@prismshadow/mmsp 0.5.0

package/dist/zai_official/client.js

@@ -0,0 +1,420 @@
+"use strict";
+// Copyright 2025 Prism Shadow. and/or its affiliates
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZAIOfficialClient = void 0;
+const openai_1 = __importDefault(require("openai"));
+const baseClient_1 = require("../baseClient");
+const errors_1 = require("../errors");
+const types_1 = require("../types");
+const utils_1 = require("../utils");
+/**
+ * Unified client for the GLM series, named for the newest generation it serves (5.3).
+ *
+ * The wire format is shared across GLM-5.1 through 5.3; only the thinking
+ * parameter contract differs per generation, handled model-by-model.
+ */
+class ZAIOfficialClient extends baseClient_1.LLMClient {
+    /**
+     * Initialize GLM client with model and API key.
+     */
+    constructor(options) {
+        super();
+        this._model = options.model;
+        // The wrapped OpenAI SDK falls back to OPENAI_API_KEY when handed undefined, which would send
+        // an OpenAI credential to the Z.AI host, so resolve the key here and fail loudly instead.
+        const key = options.apiKey || process.env.ZAI_API_KEY;
+        if (!key) {
+            throw new Error("ZAI_API_KEY is required for ZAIOfficialClient.");
+        }
+        const url = options.baseUrl ||
+            process.env.ZAI_BASE_URL ||
+            "https://api.z.ai/api/paas/v4/";
+        this._client = new openai_1.default({
+            apiKey: key,
+            baseURL: url,
+            defaultHeaders: options.defaultHeaders,
+        });
+    }
+    /**
+     * Convert ThinkingLevel enum to GLM's thinking configuration.
+     *
+     * GLM-5.3 uses forced thinking and errors on {"type": "disabled"}, so NONE
+     * stays enabled there and degrades through the lightest reasoning effort
+     * instead (llmsdk_docs/glm5_3/docs/thinking.md).
+     */
+    _convertThinkingLevelToConfig(thinkingLevel) {
+        // Provider-hosted ids keep their own casing (e.g. SiliconFlow's zai-org/GLM-5.2),
+        // so generation detection is case-insensitive.
+        if (thinkingLevel === types_1.ThinkingLevel.NONE &&
+            !this._model.toLowerCase().includes("glm-5.3")) {
+            return { type: "disabled" };
+        }
+        return { type: "enabled", clear_thinking: false };
+    }
+    /**
+     * Convert ThinkingLevel enum to the reasoning_effort the model accepts.
+     *
+     * GLM-5.3 accepts only low/high/max and errors on anything else, so the
+     * client clamps to the closest value; NONE rides on low because 5.3 cannot
+     * disable thinking. Every earlier generation takes the vocabulary unchanged:
+     * 5.2 maps it server-side (low/medium to high, xhigh to max), and 5.1 and
+     * below accept the parameter and ignore it (verified live 2026-09-03 on
+     * Z.AI, OpenRouter and SiliconFlow), so the level is forwarded there rather
+     * than dropped. Outside 5.3 NONE disables thinking outright, which leaves no
+     * effort to send.
+     */
+    _convertThinkingLevelToReasoningEffort(thinkingLevel) {
+        const model = this._model.toLowerCase(); // provider-hosted ids keep their own casing
+        if (model.includes("glm-5.3")) {
+            const mapping = {
+                [types_1.ThinkingLevel.NONE]: "low",
+                [types_1.ThinkingLevel.LOW]: "low",
+                [types_1.ThinkingLevel.MEDIUM]: "high",
+                [types_1.ThinkingLevel.HIGH]: "high",
+                [types_1.ThinkingLevel.XHIGH]: "max",
+                [types_1.ThinkingLevel.MAX]: "max",
+            };
+            return mapping[thinkingLevel];
+        }
+        const mapping = {
+            [types_1.ThinkingLevel.LOW]: "low",
+            [types_1.ThinkingLevel.MEDIUM]: "medium",
+            [types_1.ThinkingLevel.HIGH]: "high",
+            [types_1.ThinkingLevel.XHIGH]: "xhigh",
+            [types_1.ThinkingLevel.MAX]: "max",
+        };
+        return mapping[thinkingLevel];
+    }
+    /**
+     * Convert ToolChoice to OpenAI's tool_choice format.
+     */
+    _convertToolChoice(toolChoice) {
+        if (toolChoice === "auto") {
+            return "auto";
+        }
+        else {
+            throw new errors_1.UnsupportedParameterError({
+                client: this.constructor.name,
+                parameter: "tool_choice",
+                message: 'GLM only supports "auto" for tool_choice.',
+            });
+        }
+    }
+    /**
+     * Transform universal configuration to GLM-specific configuration.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    transformUniConfigToModelConfig(config) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const glmConfig = {
+            model: this._model,
+            stream: true,
+            extra_body: { tool_stream: true },
+        };
+        if (config.max_tokens !== undefined) {
+            glmConfig.max_tokens = config.max_tokens;
+        }
+        if (config.temperature !== undefined) {
+            glmConfig.temperature = config.temperature;
+        }
+        if (config.thinking_level !== undefined) {
+            const thinkingConfig = this._convertThinkingLevelToConfig(config.thinking_level);
+            glmConfig.extra_body = {
+                ...(glmConfig.extra_body || {}),
+                thinking: thinkingConfig,
+            };
+            const reasoningEffort = this._convertThinkingLevelToReasoningEffort(config.thinking_level);
+            if (reasoningEffort !== undefined) {
+                glmConfig.reasoning_effort = reasoningEffort;
+            }
+        }
+        if (config.tools !== undefined) {
+            glmConfig.tools = config.tools.map((tool) => ({
+                type: "function",
+                function: tool,
+            }));
+        }
+        if (config.tool_choice !== undefined) {
+            glmConfig.tool_choice = this._convertToolChoice(config.tool_choice);
+        }
+        if (config.fast_mode) {
+            throw new errors_1.UnsupportedParameterError({
+                client: this.constructor.name,
+                parameter: "fast_mode",
+                message: "GLM does not support fast mode.",
+            });
+        }
+        if (config.prompt_caching !== undefined &&
+            config.prompt_caching !== types_1.PromptCaching.ENABLE) {
+            throw new errors_1.UnsupportedParameterError({
+                client: this.constructor.name,
+                parameter: "prompt_caching",
+                message: "prompt_caching must be ENABLE for GLM.",
+            });
+        }
+        return glmConfig;
+    }
+    /**
+     * Transform universal message format to OpenAI's message format.
+     */
+    transformUniMessageToModelInput(messages, _signal) {
+        // glm-5.3-flash is the natively multimodal GLM and the only one that reads image
+        // parts (https://docs.z.ai/guides/vlm/glm-5.3-flash); every other GLM answers a
+        // request carrying one with an error, so the item is refused here rather than
+        // dropped. Provider-hosted ids keep their own casing (e.g. z-ai/glm-5.3-flash),
+        // so the version match is case-insensitive.
+        const supportsImage = this._model.toLowerCase().includes("glm-5.3-flash");
+        const openaiMessages = [];
+        for (const msg of messages) {
+            const contentParts = [];
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const toolCalls = [];
+            let thinking = "";
+            const thinkingFields = new Set();
+            for (const item of msg.content_items) {
+                if (item.type === "text.done") {
+                    contentParts.push({ type: "text", text: item.text });
+                }
+                else if (item.type === "image_url.done") {
+                    if (!supportsImage) {
+                        throw new Error(`GLM ${this._model} does not support image inputs.`);
+                    }
+                    contentParts.push({
+                        type: "image_url",
+                        image_url: { url: item.image_url },
+                    });
+                }
+                else if (item.type === "thinking.done") {
+                    thinking += item.thinking;
+                    thinkingFields.add(item.fidelity?.reasoning_field);
+                }
+                else if (item.type === "tool_call.done") {
+                    toolCalls.push({
+                        id: item.tool_call_id,
+                        type: "function",
+                        function: {
+                            name: item.name,
+                            arguments: JSON.stringify(item.arguments, null, 0),
+                        },
+                    });
+                }
+                else if (item.type === "tool_result.done") {
+                    if (!item.tool_call_id) {
+                        throw new Error("tool_call_id is required for tool result.");
+                    }
+                    // Chat Completions lets a tool message carry text only, and a server that
+                    // validates the schema rejects the whole request over an image part in one.
+                    // The images ride in the user message that follows the turn's tool messages,
+                    // the one place every OpenAI-compatible server reads them.
+                    if (item.images && item.images.length > 0) {
+                        if (!supportsImage) {
+                            throw new Error(`GLM ${this._model} does not support images in tool results.`);
+                        }
+                        for (const imageUrl of item.images) {
+                            contentParts.push({
+                                type: "image_url",
+                                image_url: { url: imageUrl },
+                            });
+                        }
+                    }
+                    // the plain string is the only content shape the Chat Completion schema
+                    // documents for a tool message
+                    openaiMessages.push({
+                        role: "tool",
+                        tool_call_id: item.tool_call_id,
+                        content: item.text,
+                    });
+                }
+                else {
+                    throw new Error(`Unknown item type: ${item.type}`);
+                }
+            }
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const message = { role: msg.role };
+            if (contentParts.length > 0) {
+                message.content = contentParts;
+            }
+            if (toolCalls.length > 0) {
+                message.tool_calls = toolCalls;
+            }
+            if (thinking) {
+                // send thinking back through the exact field the upstream produced (recorded
+                // in the item fidelity); servers may reject the spelling they did not emit
+                if (thinkingFields.size === 1 &&
+                    thinkingFields.has("reasoning_content")) {
+                    message.reasoning_content = thinking;
+                }
+                else if (thinkingFields.size === 1 &&
+                    thinkingFields.has("reasoning")) {
+                    message.reasoning = thinking;
+                }
+                else {
+                    message.reasoning_content = thinking; // vLLM & siliconflow compatibility
+                    message.reasoning = thinking; // openrouter compatibility
+                }
+            }
+            if (Object.keys(message).length > 1) {
+                openaiMessages.push(message);
+            }
+        }
+        return openaiMessages;
+    }
+    /**
+     * Transform one GLM streaming chunk into a universal event.
+     *
+     * Chat Completions gives an item no identity, so each delta's item_id is the wire field
+     * that carried it: an item runs until a delta arrives from another field, or names the next
+     * tool call.
+     */
+    transformModelOutputToUniEvent(modelOutput) {
+        let eventType = "delta";
+        const contentItems = [];
+        let usageMetadata = null;
+        let finishReason = null;
+        // gateways inject content-free heartbeat chunks on long generations, whose
+        // choices arrive as undefined rather than an empty list
+        if (modelOutput.choices?.length) {
+            const choice = modelOutput.choices[0];
+            const delta = choice?.delta;
+            // the thinking field name differs by server: vLLM & siliconflow use
+            // reasoning_content while openrouter uses reasoning; record the wire
+            // field that carried each delta so a replay can reproduce exactly the
+            // field the upstream produced. The reasoning goes before the content
+            // because a chunk may end the reasoning and begin the answer.
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const reasoningContent = delta?.reasoning_content;
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const reasoning = delta?.reasoning;
+            if (reasoningContent && reasoning) {
+                // ambiguous origin: record no reasoning_field so a replay sends both fields back
+                contentItems.push({
+                    type: "thinking.delta",
+                    thinking: reasoningContent,
+                    fidelity: { item_id: "reasoning_content" },
+                });
+            }
+            else if (reasoningContent) {
+                contentItems.push({
+                    type: "thinking.delta",
+                    thinking: reasoningContent,
+                    fidelity: {
+                        item_id: "reasoning_content",
+                        reasoning_field: "reasoning_content",
+                    },
+                });
+            }
+            else if (reasoning) {
+                contentItems.push({
+                    type: "thinking.delta",
+                    thinking: reasoning,
+                    fidelity: { item_id: "reasoning", reasoning_field: "reasoning" },
+                });
+            }
+            if (delta?.content) {
+                contentItems.push({
+                    type: "text.delta",
+                    text: delta.content,
+                    fidelity: { item_id: "content" },
+                });
+            }
+            if (delta?.tool_calls) {
+                for (const toolCall of delta.tool_calls) {
+                    contentItems.push({
+                        type: "tool_call.delta",
+                        name: toolCall.function?.name || "",
+                        arguments: toolCall.function?.arguments || "",
+                        tool_call_id: toolCall.id || "",
+                        fidelity: { item_id: "tool_calls" },
+                    });
+                }
+            }
+            if (choice?.finish_reason) {
+                eventType = "stop";
+                const finishReasonMapping = {
+                    stop: "stop",
+                    length: "length",
+                    tool_calls: "tool_call",
+                    content_filter: "stop",
+                };
+                finishReason = finishReasonMapping[choice.finish_reason] || "unknown";
+            }
+        }
+        if (modelOutput.usage) {
+            eventType = "stop";
+            const cachedTokens = modelOutput.usage.prompt_tokens_details?.cached_tokens || null;
+            const reasoningTokens = modelOutput.usage.completion_tokens_details?.reasoning_tokens || null;
+            const promptTokens = cachedTokens !== null
+                ? modelOutput.usage.prompt_tokens - cachedTokens
+                : modelOutput.usage.prompt_tokens;
+            const responseTokens = reasoningTokens !== null
+                ? modelOutput.usage.completion_tokens - reasoningTokens
+                : modelOutput.usage.completion_tokens;
+            usageMetadata = {
+                cached_tokens: cachedTokens,
+                prompt_tokens: promptTokens,
+                thoughts_tokens: reasoningTokens,
+                response_tokens: responseTokens,
+            };
+            usageMetadata = (0, utils_1.fixOpenrouterUsageMetadata)(usageMetadata, this._client.baseURL);
+        }
+        return {
+            role: "assistant",
+            event_type: eventType,
+            content_items: contentItems,
+            usage_metadata: usageMetadata,
+            finish_reason: finishReason,
+        };
+    }
+    /**
+     * Stream generate using GLM SDK with unified conversion methods.
+     */
+    async *_streamingResponseInternal(options) {
+        const glmConfig = this.transformUniConfigToModelConfig(options.config);
+        const glmMessages = this.transformUniMessageToModelInput(options.messages, options.signal);
+        if (options.config.system_prompt) {
+            glmMessages.unshift({
+                role: "system",
+                content: options.config.system_prompt,
+            });
+        }
+        const params = {
+            ...glmConfig,
+            messages: glmMessages,
+            stream: true,
+        };
+        const stream = await this._client.chat.completions.create(params, {
+            signal: options.signal,
+        });
+        for await (const chunk of stream) {
+            yield this.transformModelOutputToUniEvent(chunk);
+        }
+    }
+    /**
+     * List the model ids the configured endpoint serves.
+     *
+     * @returns The model ids, in the order the endpoint returned them.
+     */
+    async listModels() {
+        const models = [];
+        for await (const model of this._client.models.list()) {
+            models.push(model.id);
+        }
+        return models;
+    }
+}
+exports.ZAIOfficialClient = ZAIOfficialClient;

package/dist/zai_official/index.d.ts

@@ -0,0 +1,2 @@
+export { ZAIOfficialClient } from "./client";
+//# sourceMappingURL=index.d.ts.map

package/dist/zai_official/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/zai_official/index.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC"}

package/dist/zai_official/index.js

@@ -0,0 +1,18 @@
+"use strict";
+// Copyright 2025 Prism Shadow. and/or its affiliates
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZAIOfficialClient = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "ZAIOfficialClient", { enumerable: true, get: function () { return client_1.ZAIOfficialClient; } });

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@prismshadow/mmsp",
+  "version": "0.5.0",
+  "description": "MMSP, the Model Message Stream Protocol: one message format and one streaming grammar for every model provider, in Python and TypeScript.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": "./dist/index.js",
+    "./integration/tracer": "./dist/integration/tracer.js",
+    "./integration/playground": "./dist/integration/playground.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint src --ext .ts",
+    "start": "node dist/index.js",
+    "test": "NODE_OPTIONS=--experimental-vm-modules jest --verbose",
+    "tracer": "tsx examples/tracerExample.ts",
+    "playground": "tsx examples/playgroundExample.ts"
+  },
+  "dependencies": {
+    "@anthropic-ai/bedrock-sdk": "^0.26.4",
+    "@anthropic-ai/sdk": "^0.81.0",
+    "@google/genai": "^2.24.0",
+    "express": "^4.18.2",
+    "openai": "^6.33.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "@types/express": "^4.17.21",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^25.0.10",
+    "@types/supertest": "^7.2.0",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "eslint": "^9.0.0",
+    "gaxios": "^7.1.3",
+    "jest": "^30.2.0",
+    "supertest": "^7.2.2",
+    "ts-jest": "^29.4.6",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  },
+  "directories": {
+    "example": "examples",
+    "test": "tests"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Prism-Shadow/model-message-stream-protocol.git"
+  },
+  "keywords": [
+    "mmsp",
+    "llm",
+    "stream",
+    "gemini",
+    "claude",
+    "gpt"
+  ],
+  "author": "PrismShadow",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/Prism-Shadow/model-message-stream-protocol/issues"
+  },
+  "homepage": "https://github.com/Prism-Shadow/model-message-stream-protocol#readme"
+}