Mmsp Dev

MMSP Development Workflow

Adding or updating model support follows the stages below, in order. Where a stage says stop and ask, pause and ask the user; do not continue until the issue is resolved, and never fill the gap yourself.

Directory map

llmsdk_docs/<model_version>/      Official docs snapshot, one folder per model generation (README.md + docs/)
api_captures/<protocol>/          Git-ignored raw API captures: request payloads + stream events
src_py/mmsp/<client_type>/        Python client, one folder per client type: <vendor>_official/ or <protocol>/
src_py/mmsp/auto_client.py        Creates the client a client_type names; a model id's family names its official client
src_ts/src/<client_type>/         TypeScript client, mirrors the Python folder
src_ts/src/autoClient.ts          TypeScript routing, mirrors auto_client.py
src_py/tests/test_client.py       Parameterized e2e tests (env-gated AVAILABLE_MODELS)
src_ts/tests/client.test.ts       Same for TypeScript
changelog/unreleased/             Where unshipped changes go; renamed to the version at release
changelog/<version>/              Release summary (README.md) plus one detail file per entry
changelog/README.md               The entry format: metadata block, body rules, bilingual pairing
CHANGELOG.md                      One brief line per release linking into changelog/
src_py/mmsp/integration/          The playground and the tracer pages, mirrored in src_ts/src/integration/
site/                             The Astro site at mmsp.penguin.ooo
.agents/skills/mmsp-dev/kill-ai-slop/   Vendored AI-slop guide and scanner for the UI work below
<name>.zh.md                      Chinese counterpart, required for every file in changelog/

Stage 1 — Sync official docs into llmsdk_docs/

• Sources must be the model vendor's official documentation site (e.g. docs.anthropic.com, platform.openai.com, ai.google.dev). Never use third-party mirrors, blog posts, or model memory.
• Save the snapshot under llmsdk_docs/<model_version>/ following the existing folder conventions, and list the folder in llmsdk_docs/README.md. Running this workflow is the explicit request that the repository rule against editing llmsdk_docs/ asks for.
• When the fetched docs differ from an existing snapshot, the new official docs win: update the old files in place.
• The snapshot must be complete enough to implement from: request/response schemas, streaming event sequence, thinking output, tool calling, usage fields, and error responses.
• Stop and ask if the official URL is uncertain or a page cannot be fetched. The user can paste the content manually.

Stage 2 — Capture a live API exchange into api_captures/

• Gate: the provider's API key environment variable must be set and usable. Use the same environment variables and base URLs as src_py/tests/test_client.py (AVAILABLE_MODELS gating and _create_client). Stop and ask the user to supply the key if it is missing; the workflow must not continue without it.
• Using the provider's official SDK, or raw HTTP exactly as documented, run one streaming tool-call request with thinking enabled, then send the tool result back so the capture also shows how assistant turns are re-sent.
• Save the complete exchange unmodified under api_captures/<protocol>/ (git-ignored), e.g. round1.request.json plus round1.stream.jsonl with every raw stream event in order. Never save credentials.
• When something in the exchange will not serialize to JSON (binary payloads, SDK objects holding non-JSON values), save its str() form and analyze from that. Keep the container parseable: wrap the text in a JSON object so the .jsonl stays one JSON value per line ({"unserializable_str": "<str(event)>"}, keeping the event in stream order), or put the whole exchange in a sibling .txt when nothing about it serializes. A str() capture is still the authoritative record of what the API returned. Never drop the event, hand-edit it into valid JSON, or fall back to the docs because serialization failed.
• Stop and ask on any API error (invalid key, insufficient quota, rate limit). Do not mock the response or continue from docs alone.
• The capture is the primary implementation reference and outranks the docs: where they disagree, implement what the API actually returned.
• Then probe the replay, because the capture only shows what the API sends, not what it needs back. Re-send the assistant turn repeatedly, each time with one candidate field removed — the reasoning item's id, its content, the whole reasoning item, each field you were tempted to keep — and record which removals the API still accepts with the model's behavior intact. That result, not the shape of the response, decides what Stage 3 stores. Save the probe outcomes next to the capture.

Stage 3 — Implement the Python and TypeScript clients

• One folder per client type, named after it: an official client per vendor (openai_official/, anthropic_official/, gemini_official/, zai_official/, moonshot_official/, deepseek_official/, minimax_official/) speaks the vendor's own API, knows every generation of the vendor's models, and reads the vendor's key from the environment; a compatible client per wire protocol (openai_responses/, openai_chat/, openai_chat_vllm_adapter/, openai_embedding/, ant_messages/, google_genai/) speaks that protocol for any endpoint. The class is named after the folder (OpenAIOfficialClient, OpenaiChatClient), and the client type is the folder name with hyphens (openai-official, openai-chat).
  • A new generation of a vendor's models goes into the vendor's official client. Diff the new protocol (capture + docs) against what the client sends today; where a generation differs, even by a single key name, tell the generations apart inside the client by explicit version ("4-6" in self._model, "gpt-6" in self._model), never by a bare substring like "claude" in model, and keep the older generations working. Never drop a generation unless the user explicitly instructs it.
  • A new vendor gets a new official client folder, a new <vendor>-official client type in auto_client.py / autoClient.ts, and a new row in the model family table there: the family is the prefix every id of the vendor's models begins with (glm-, kimi-), matched case-insensitively.
  • A new wire protocol that several vendors serve gets a compatible client folder and client type; a compatible client carries no vendor's quirks.
• auto_client.py / autoClient.ts create the client a client_type names, from the one table of client types. Without a client_type, the family a model id begins with names its official client; an id of no known family raises and asks for one. The routing has no other rule: no substring matching on model ids, no version matching outside the official clients.
• A credential goes only where it was given for. This is the security model, and every client constructor follows it. A key passed as api_key is used as it is. A client that reads the environment's generic key (OPENAI_API_KEY for openai_official and the OpenAI-protocol compatible clients, ANTHROPIC_API_KEY for anthropic_official and ant_messages, GEMINI_API_KEY for google_genai) reads it only when the endpoint comes from the environment too (OPENAI_BASE_URL / ANTHROPIC_BASE_URL / GEMINI_BASE_URL, or the provider's own default): given a base_url and no api_key, it raises at construction instead of sending that key to another endpoint. That is resolve_credentials / resolveCredentials in utils; call it, do not reimplement it. Any other official client (deepseek_official, zai_official, moonshot_official, minimax_official, gemini_official) reads its own variable (DEEPSEEK_API_KEY, ZAI_API_KEY, MOONSHOT_API_KEY, MINIMAX_API_KEY, GEMINI_API_KEY) whatever base URL it is given, and never the generic one; without either it raises <VAR> is required for <Client>.. Hand every credential to the vendor SDK explicitly, including "none" (authToken: null in TypeScript, a cleared auth_token in Python), because the SDKs fill whatever they are not handed from their own environment variables. The offline tests in tests/env-credentials.test.ts / tests/test_env_credentials.py build every client under a controlled environment and read the credential the SDK instance holds; add a new client to them.
• Replay must be minimal, not exhaustive. A replayed assistant turn has to be accepted by the API with the model's behavior intact; it does not have to reproduce the wire item field for field. fidelity is an exception channel, not a mirror of the payload: a field earns a place there only when the Stage 2 probe shows the request fails or the model degrades without it. Provider-generated ids the API regenerates or ignores — a reasoning item id, an output-item id — stay out. Fields the API demands go in: GPT-5.5's phase, Claude's thinking signature, the exact reasoning field name a strict upstream requires.
• Never copy into fidelity what a universal field already carries — the thinking text, a tool call's name or parsed arguments. Rebuild the wire item from the universal fields instead.
• tool_call_id is not optional: always capture the provider's call id and replay it. Where the wire format carries both an item id and a call id, the call id is the one that correlates a result to its call.
• Follow the reference client; do not redesign. openai_official/ is the shape for Responses-style protocols, openai_chat/ for Chat Completions: same method order, same control flow, same names. A new client should read as a diff against its reference, because that is how it will be reviewed.
• Keep it readable top to bottom. A reader should follow one request or response straight through the file without jumping between definitions, so inlining is the default: read the SDK's attributes directly (model_output.delta, model_output.item.call_id) and keep field access, usage arithmetic, and error text where they are used. Extract a helper only for a genuinely large, self-contained block — the kind that would bury the main flow if inlined, such as fetching and decoding an image — never for a few lines. Mirror the reference client's own private methods (_convert_thinking_level_*, _convert_tool_choice) instead of inventing a layer beside them; a shim that accepts both dicts and SDK objects is never one of them, because the events are typed with the SDK's own types.
• Clients yield deltas only; the base class closes the items. transform_model_output_to_uni_event / transformModelOutputToUniEvent turns one wire event into one UniEvent whose content_items are the .delta items that event carries, in wire order, and never a .done item. _streaming_response_internal / _streamingResponseInternal builds the request, opens the stream, and yields one event per wire event: a plain loop, with no item bookkeeping, no accumulator, no argument parsing, no usage merging, and no synthesized stop. usage_metadata / finish_reason ride on stop events wherever the wire reports them — Anthropic message_start and message_delta, the Chat Completions finish and usage chunks, response.completed — merged field by field by the base; a client's stop event never ends the public stream. A wire event with nothing universal is the empty delta event: no items, null usage and finish reason. The base class hands every delta to StreamItems (stream_items.py / streamItems.ts), which sends it out as it arrives and closes each item with its .done item when the next item begins or the client's stream ends; the base then emits the one stop event or raises EmptyResponseError. Events that break the protocol raise StreamProtocolError in every mode, and the shared e2e tests check every client's stream with assert_stream_grammar / assertStreamGrammar.
• The deltas of one item are contiguous and share one fidelity.item_id. Model output is serial, so one item streams at a time and the provider's end-of-item events (content_block_stop, response.output_item.done, step.stop) are listed as no-ops: a gateway that closes its items late or out of order changes nothing. Pass the provider's own id, stringified, as fidelity.item_id: the Anthropic block index, the Responses event item_id or item.id or item.call_id (None / undefined where a gateway sends none), the Interactions step index, the Chat Completions wire field (reasoning_content, reasoning, content, tool_calls), the generateContent part kind (function_call, thought, inline_thinking, inline_data, text); embedding vectors carry none. StreamItems strips it, so it never reaches consumers, traces or histories.
• StreamItems decides where an item ends; clients never do. A delta belongs to the next item when it carries another item_id, is of another kind (an Interactions thought step going text, image, text is three items under one index), or begins an item by itself: a tool_call.delta carrying a name (every provider sends it once, on the call's first delta, so Chat Completions calls need no ids of their own), an image (inline_thinking, or inline_data with an image/* MIME type, while audio streams in chunks of one item), an embedding vector. Otherwise it continues the item streaming now: a delta without an id does, and so do a call's arguments whatever id a gateway puts on them. Fidelity sent alone under the item's id is that item's, whatever kind carries it (an Interactions thought_signature after an image thought). The per-kind table in that file — the growing field, the header fields of the first delta, how the chunks join — is the only per-kind code in the stream: the done item is the item's first delta with the growing field replaced by the join of every delta's (tool call arguments parsed) plus the item's fidelity.
• Fidelity goes out once, when it is complete. Attach it to the delta at which the client knows it whole: Anthropic's signature on its signature_delta, as a thinking.delta with empty thinking; the Responses reasoning channel / encrypted_content on an empty thinking.delta yielded at response.output_item.done, the last delta of that item; GPT's phase on an empty text.delta at response.output_item.added. StreamItems copies it onto the .done item. An identical fidelity repeated on later deltas of the same item goes out once (Chat Completions tags every reasoning delta with reasoning_field); a different one is a StreamProtocolError.
• Stream on deltas; never re-read the completed item. A tool call opens with a tool_call.delta carrying the name and call id on the item-added event and continues with argument fragments; the completion event yields nothing but the fidelity unknown until then. Never read content back from a completed item or cross-check it against what the deltas produced; response.function_call_arguments.done returns the empty delta event. Leave provider error events (response.failed, response.error, error) to the unknown-event guard rather than translating them into MMSP errors, except on Gemini Interactions: neither of its SDKs raises on the SSE error event that arrives inside an open stream, so the guard would drop the provider's failure and the stream would end as one without usage, and gemini_official raises on an error event carrying an error object instead, with the provider's code and message. minimax_official is the deliberate exception: it ignores the argument deltas and reads each call from response.output_item.done, yielding one tool_call.delta with the name, call id, and whole arguments. A client streams a call on deltas or delivers the completed item, never both, so the fragments and the complete call can never disagree.
• The message transform switches on .done types. transform_uni_message_to_model_input matches text.done, thinking.done, tool_call.done, tool_result.done, and the rest; a message never carries a .delta item, and legacy item types are converted before a client sees the messages.
• The message transform keeps the order of the content items. Whatever a turn produced — thinking, then text, then a tool call — has to leave the transform in that order. Where a protocol makes an item its own entry (a Responses reasoning / function_call, say) and the message text is collected separately, flush the collected text before appending the entry; a message appended after the items it preceded is what DeepSeek answers with "No tool output found for tool call". Anthropic Messages and Gemini keep one ordered block list per message, so appending in item order is enough; Chat Completions splits content and tool_calls into fields of one message and carries no interleaving at all.
• UniConfig keys rarely map one-to-one onto provider config keys. Stop and ask: list every non-obvious mapping and confirm it with the user before coding. Never decide silently.
• Every ThinkingLevel must stay usable on every client — never raise for a thinking level. Map each level to the closest level the model supports and degrade silently when a level has no exact equivalent (e.g. gemini_official maps NONE to MINIMAL, or to low on the models that reject minimal; moonshot_official maps NONE to low because K3 cannot disable reasoning).
• temperature and tool_choice (and other unsupported parameter values, e.g. prompt_caching) may reject with an exception, but must raise the MMSP-specific UnsupportedParameterError from errors.py / errors.ts, never a bare ValueError/Error. Keep the message wording consistent with existing clients (containing "not support").
• Implement Python and TypeScript together with identical behavior.