Unified LLM API

Unified LLM API (MMSP)

@prismshadow/mmsp — MMSP, the Model Message Stream Protocol, formerly @prismshadow/agenthub — is a unified TypeScript client for model APIs: one message format and one streaming grammar for text, image generation, speech synthesis and embeddings, behind one entry point.

npm install @prismshadow/mmsp

The main entry point is AutoLLMClient:

import { AutoLLMClient } from "@prismshadow/mmsp";

const client = new AutoLLMClient({ model: "<model_id>", apiKey: "<key>", baseUrl: "<url>", clientType: "<type>" });

apiKey, baseUrl and clientType are optional (see Routing and credentials); defaultHeaders adds request headers. The package also exports listSupportedModels (the model registry), normalizeLegacyMessages, the ThinkingLevel / PromptCaching enums, the message and event types, and the error classes (see Errors).

Before you start

If the user's message only invokes this skill (e.g. "use unified-llm-api skill") without a concrete task, ask the user what they want to build. Do not write code until the requirement is clear.

Important prerequisite — set the key up first, then develop. When the script is an AI app you are building for the user, have them add the model API key in this agent's key vault (gear icon on its card, Agents page → settings → key vault tab) before you start, so the credential is in your shell environment. If the app stores its own model config, keep its Penguin data root inside the CWD workspace (--root ./penguin_data), never ~/.penguin. Model ids can come from the penguin CLI catalog and the id table below.

Check for a usable API key before writing code — the client needs one for whichever provider you target:

env | grep -oE "(DEEPSEEK|OPENAI|ANTHROPIC|GEMINI|ZAI|MOONSHOT|MINIMAX)_API_KEY" || echo none

Vault keys also appear in your Vault Keys section. Only two sources count as a usable key: a vault-injected environment variable (the check above), or — when the app stores its own model config — a key already configured in the app's own data root (penguin config model list --root <data_dir>). Keys living in the global ~/.penguin or any other .penguin directory do not count — a bare penguin config model list (no --root) reads the global store, because the CLI defaults to the global root unless --root is given, so a key showing up there proves nothing for your script and must never be used or copied.

If neither counted source yields a usable key, stop immediately and ask the user to configure one — do not write code, and do not keep calling tools to retry: ask them to add one in the agent's key vault (gear icon on the agent's card, Agents page → settings → key vault tab); vault values reach your shell environment on the next task. Re-checking the environment or the vault in a loop just wastes turns — one clear check, then hand back to the user.

Keep model API keys project-local: for an app that stores its own model config, write the key into the project under the working directory with the penguin CLI, always passing --root <data_dir> for a directory inside the current working directory (penguin config model add --root ./penguin_data --provider <group> --model-id <id> --api-key <key>) — without --root it writes to the global ~/.penguin/data instead. --provider is required alongside --model-id: a model entry is the (provider, model_id) pair and the group is never inferred (use custom for an endpoint outside the built-in groups). Otherwise rely on vault-injected environment variables. Never read, copy or fall back to model keys stored in the user's global ~/.penguin directory — that config belongs to the person running Penguin, not to your script.

Model IDs

Use exact model ids. If an id is not in the table below and the user has not given one, ask the user to confirm the exact id before writing code. Official ids route on their own; every gateway id needs an explicit clientType (see Routing and credentials).

The image endpoint dropped its preview suffix: gemini-3.1-flash-image-preview is deprecated, use gemini-3.1-flash-image.

glm-5.3-flash is the one GLM model that reads images: zai-official sends an image_url.done item as an image_url part, in a prompt and in a tool result alike (an HTTP(S) URL and a base64 data URL both pass through), and matches the version case-insensitively, so the gateway spellings z-ai/glm-5.3-flash and zai-org/GLM-5.3-Flash count too. Every other GLM id refuses an image rather than dropping it (GLM <id> does not support image inputs.), glm-5v-turbo included.

Gateway model lists can be queried online:

curl https://openrouter.ai/api/v1/models
curl --request GET --url https://api.siliconflow.cn/v1/models --header 'Authorization: Bearer <token>'

Supported-model registry

listSupportedModels(currency?) returns the models MMSP curates, so ids, endpoints, modalities, context windows and prices can be read from the package instead of being hardcoded:

import { listSupportedModels } from "@prismshadow/mmsp";

for (const m of listSupportedModels()) {
  console.log(m.model, m.base_url, m.client, m.context_window, m.pricing?.prompt_tokens);
}

• Each SupportedModel is { model, base_url, client, input_modalities, output_modalities, context_window?, pricing? }. The (model, base_url, client) triple maps straight onto the constructor: new AutoLLMClient({ model, baseUrl: base_url, clientType: client }) — client is the client type MMSP pairs with that id, gateway ids included.
• Modalities are "Text" | "Image" | "Video" | "Audio" | "Embed". Coverage includes the official vendor endpoints plus the OpenRouter and SiliconFlow gateways; context_window and pricing are omitted where the platform publishes no authoritative value.
• pricing is the list price per million tokens (a running promotion is not recorded), keyed by the usage buckets of usage_metadata: prompt_tokens (non-cached input), thoughts_tokens / response_tokens (both the output price) and optional cached_tokens (cache-hit price). Values are stored in USD; listSupportedModels("CNY") converts at 7 CNY/USD.

The registry is the curated current line-up, not the routing table: any id of a known family routes whether or not the registry lists it. For an id it omits, take the context window and price from the vendor's own page.

Routing and credentials

Client types. clientType names one client:

• Official clients speak their vendor's own API: openai-official (Responses API; text-embedding-* ids go to the Embeddings API), anthropic-official (Messages; a bedrock://<region> base URL reaches Bedrock), gemini-official (Interactions API only; a Vertex AI service-account JSON key is refused with an error naming google-genai), zai-official and moonshot-official (Chat Completions), deepseek-official and minimax-official (Responses API).
• Compatible clients speak one wire protocol for any endpoint that serves it: openai-responses, openai-chat (the bare openai is an alias), openai-chat-vllm-adapter (Chat Completions plus the served model's thinking switch), openai-embedding, ant-messages (Anthropic Messages), google-genai (Google's generateContent as the Google GenAI SDK speaks it — Vertex AI with a service-account JSON key as apiKey, the Gemini API, or a relay; gemini-generate-content is its 0.5.0 name, kept as an alias).

Routing by prefix. Without clientType (or the CLIENT_TYPE environment variable), the family the lowercased model id begins with names its official client: gpt- and text-embedding- → openai-official, claude- → anthropic-official, gemini- → gemini-official, glm- → zai-official, kimi- → moonshot-official, deepseek- → deepseek-official, minimax- → minimax-official. Any other id throws at construction: No client for model "<id>": its family is not known. Pass clientType, one of the official clients: …; compatible clients: …. An unknown client type throws Unknown client type "<type>". Pass one of the …. Routing never looks at baseUrl.

Renamed in 0.5.0. The 0.4.x vendor client types no longer exist, and a model id passed as clientType no longer works; the compatible client types are unchanged.

Gateway ids: always pass clientType. Owner-prefixed ids (openai/gpt-5.6-sol, anthropic/claude-opus-4.8, moonshotai/kimi-k3) begin with no family and throw; an id that does begin with one (deepseek-ai/DeepSeek-V4-Pro) would reach the vendor's official client aimed at the gateway.

• openai-responses on OpenRouter: https://openrouter.ai/api/v1 serves the Responses API for every model it resells and round-trips reasoning items (openai-chat works there too).
• openai-chat on Chat Completions endpoints: SiliconFlow, Fireworks AI, DashScope https://dashscope.aliyuncs.com/compatible-mode/v1, a self-hosted server (openai-chat-vllm-adapter for vLLM, to switch the served model's thinking). A self-hosted deepseek-* id needs it too, because deepseek-official posts to {baseUrl}/responses.
• ant-messages on Anthropic Messages endpoints (Anthropic, OpenRouter https://openrouter.ai/api, DeepSeek https://api.deepseek.com/anthropic, Z.AI, MiniMax); google-genai on Vertex AI or a relay that proxies Gemini's generateContent.

Credentials. The constructor's apiKey comes first, then the environment: an official client reads its vendor's pair (DEEPSEEK_, OPENAI_, ANTHROPIC_, GEMINI_, ZAI_, MOONSHOT_, MINIMAX_ + API_KEY / BASE_URL), a compatible client the pair of its protocol (OPENAI_*; ANTHROPIC_* for ant-messages, GEMINI_* for google-genai). The OpenAI-, Anthropic- and generateContent-protocol clients send an environment key only to the environment's endpoint: a baseUrl without an apiKey throws apiKey is required for <Client> with a baseUrl: OPENAI_API_KEY is not sent to another endpoint. The other clients read their own variable whatever endpoint they are given, so pass a gateway's key as apiKey every time.