@molecule/api-ai-zhipu 1.0.0 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md ADDED
@@ -0,0 +1,185 @@
1
+ <!--
2
+ AUTO-GENERATED — DO NOT EDIT THIS FILE.
3
+ Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
4
+ Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
5
+ To change this document, edit the module-level JSDoc in src/index.ts.
6
+ Generated: 2026-08-26T19:42:20.290Z
7
+ -->
8
+
9
+ # @molecule/api-ai-zhipu
10
+
11
+ > **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
12
+ > It is written to be read by coding agents as much as by people, and is generated from this
13
+ > package's source — edit `src/index.ts` JSDoc, not this file.
14
+
15
+ Zhipu GLM AI provider for molecule.dev.
16
+
17
+ ## Type
18
+
19
+ `provider`
20
+
21
+ ## Installation
22
+
23
+ ```bash
24
+ npm install @molecule/api-ai-zhipu @molecule/api-ai @molecule/api-bond @molecule/api-i18n @molecule/api-secrets
25
+ ```
26
+
27
+ ## API
28
+
29
+ ### Interfaces
30
+
31
+ #### `ProcessEnv`
32
+
33
+ Process Env interface.
34
+
35
+ ```typescript
36
+ interface ProcessEnv {
37
+ ZHIPU_API_KEY: string
38
+ /** Base URL override (for credential brokers / gateways / US OpenAI-compatible hosts). */
39
+ ZHIPU_BASE_URL?: string
40
+ /** Chat-completions path override (see {@link ZhipuConfig.completionsPath}). */
41
+ ZHIPU_COMPLETIONS_PATH?: string
42
+ }
43
+ ```
44
+
45
+ #### `ZhipuConfig`
46
+
47
+ Configuration for Zhipu.
48
+
49
+ ```typescript
50
+ interface ZhipuConfig {
51
+ /** Called on each rate-limited/overloaded upstream response, before any retry sleep. */
52
+ onRateLimit?: AiRateLimitCallback
53
+ /** API key. Defaults to ZHIPU_API_KEY env var. */
54
+ apiKey?: string
55
+ /** Default model. Defaults to 'glm-5.3'. */
56
+ defaultModel?: string
57
+ /** Maximum tokens for completions. */
58
+ maxTokens?: number
59
+ /** Base URL override (for proxies). Defaults to 'https://open.bigmodel.cn/api/paas'. */
60
+ baseUrl?: string
61
+ /**
62
+ * Chat-completions path appended to {@link baseUrl}. Defaults to
63
+ * `/v4/chat/completions` (Zhipu-native). Set to `/chat/completions` when the
64
+ * GLM open weights are served from a US OpenAI-compatible host (DeepInfra:
65
+ * baseUrl='https://api.deepinfra.com/v1/openai').
66
+ */
67
+ completionsPath?: string
68
+ /**
69
+ * Catalog-id → upstream-model-id map, applied to the outbound request only, so
70
+ * a US host (DeepInfra) receives its namespaced id (`zai-org/GLM-5.2`) while
71
+ * pricing/cost/display keep the canonical catalog id (`glm-5.2`).
72
+ */
73
+ modelMap?: Record<string, string>
74
+ }
75
+ ```
76
+
77
+ ### Functions
78
+
79
+ #### `createProvider(config)`
80
+
81
+ Creates a Zhipu GLM AI provider instance.
82
+
83
+ ```typescript
84
+ function createProvider(config?: ZhipuConfig): AIProvider
85
+ ```
86
+
87
+ - `config` — Zhipu-specific configuration (API key, model, max tokens, base URL).
88
+
89
+ **Returns:** An `AIProvider` backed by the Zhipu Chat Completions API.
90
+
91
+ ### Constants
92
+
93
+ #### `aiZhipuSecretDefinitions`
94
+
95
+ Secret definitions required by the Zhipu AI bond.
96
+
97
+ ```typescript
98
+ const aiZhipuSecretDefinitions: SecretDefinition[]
99
+ ```
100
+
101
+ #### `provider`
102
+
103
+ The provider implementation.
104
+
105
+ ```typescript
106
+ const provider: AIProvider
107
+ ```
108
+
109
+ ## Core Interface
110
+
111
+ Implements `@molecule/api-ai` interface.
112
+
113
+ ## Bond Wiring
114
+
115
+ Setup function to register this provider with the bond system:
116
+
117
+ ```typescript
118
+ import { bond } from '@molecule/api-bond'
119
+ import { provider } from '@molecule/api-ai-zhipu'
120
+
121
+ export function setupAiZhipu(): void {
122
+ bond('ai', 'zhipu', provider)
123
+ }
124
+ ```
125
+
126
+ ## Injection Notes
127
+
128
+ ### Requirements
129
+
130
+ Peer dependencies:
131
+
132
+ - `@molecule/api-ai` ^1.0.1
133
+ - `@molecule/api-bond` ^1.0.1
134
+ - `@molecule/api-i18n` ^1.0.1
135
+ - `@molecule/api-secrets` ^1.0.1
136
+
137
+ ### Environment Variables
138
+
139
+ - `ZHIPU_API_KEY` _(required)_ — Zhipu AI API key
140
+ - Setup: Create an API key in the Zhipu AI (BigModel) user center.
141
+ - Get it here: [https://open.bigmodel.cn/usercenter/apikeys](https://open.bigmodel.cn/usercenter/apikeys)
142
+
143
+ ### Runtime Dependencies
144
+
145
+ - `@molecule/api-ai`
146
+ - `@molecule/api-bond`
147
+ - `@molecule/api-i18n`
148
+ - `@molecule/api-secrets`
149
+
150
+ Config: `ZHIPU_API_KEY` (SERVER-side only) plus an optional default model id/base URL.
151
+
152
+ **Missing `ZHIPU_API_KEY` fails fast**: the provider throws naming the exact env var on first
153
+ use (the exported `provider` is a lazy proxy, so this fires on the first `chat()` call, not at
154
+ bond/module-load time) — it never silently sends an empty key.
155
+
156
+ **Error message disambiguation**: a plain 400 that ISN'T a context-length error (bad param,
157
+ malformed tool schema) gets its own non-retryable message distinct from the generic
158
+ "AI service error. Please try again." used for retryable failures.
159
+
160
+ ## E2E Tests
161
+
162
+ Integration checklist — drive the real UI (live preview, no mocks), adapt
163
+ each item to this app's actual chat/AI screens, and check every box off one
164
+ by one. A box you can't check is an integration bug to fix — not a skip. The
165
+ sandbox HAS an AI provider bonded, so the flow runs live end-to-end; AI
166
+ output is NON-DETERMINISTIC, so assert on STRUCTURE/behavior, not exact text:
167
+
168
+ - [ ] A message sent through the real chat UI comes back as a RELEVANT AI
169
+ reply — not an echo of the prompt, a hardcoded stub, or an empty bubble.
170
+ Ask something with a checkable answer (e.g. "What is 2 + 2?") and confirm
171
+ the response actually contains it ("4"), proving a live model answered.
172
+ - [ ] If the app streams, tokens render INCREMENTALLY — text grows word by
173
+ word in the UI, not one final blob dumped after a long frozen spinner. (A
174
+ streamed `chat()` yields `text` chunks then a final `done`; a single late
175
+ blob means the reply was awaited whole and streaming is broken.)
176
+ - [ ] Multi-turn CONTEXT is preserved: a follow-up that refers back to the
177
+ previous turn (e.g. after "2 + 2", ask "now double that" -> understood as 8) works — proving the full `messages` history is sent, not just the last
178
+ line.
179
+ - [ ] A provider failure (bad/missing key, rate limit, timeout) surfaces as
180
+ a graceful in-UI error message, NOT a crash, blank screen, a spinner that
181
+ never resolves, or an unhandled 500. Force one and watch the UI recover.
182
+ - [ ] The provider key + the provider call are SERVER-side only: the key
183
+ never reaches the browser (check the network tab, the JS bundle, and page
184
+ globals), and no route proxies arbitrary prompts to the model without auth
185
+ - a token cap — an open AI endpoint is an unbounded bill and abuse vector.
@@ -1 +1 @@
1
- {"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,UAAU,EAOX,MAAM,kBAAkB,CAAA;AASzB,OAAO,cAAc,CAAA;AAErB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAilB7C;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,UAAU,CAE/D"}
1
+ {"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,UAAU,EAOX,MAAM,kBAAkB,CAAA;AASzB,OAAO,cAAc,CAAA;AAErB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAmlB7C;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,UAAU,CAE/D"}
package/dist/provider.js CHANGED
@@ -15,8 +15,10 @@ import './secrets.js';
15
15
  /**
16
16
  * Fallback: map thinking budget tokens to a Zhipu reasoning_effort level when
17
17
  * the caller didn't resolve a native value from the model catalog. Note
18
- * `reasoning_effort` is only honored on glm-5.2+ (values minimal | none | low |
19
- * medium | high | xhigh | max; low/medium coerce to high, xhigh to max) —
18
+ * `reasoning_effort` is only honored on glm-5.2+ (glm-5.2 takes minimal | none |
19
+ * low | medium | high | xhigh | max, where low/medium coerce to high and xhigh
20
+ * to max; glm-5.3 narrows this to low | high | max and can no longer disable
21
+ * reasoning at all — both accept the `'high'`/`'low'` this returns) —
20
22
  * callers should prefer passing `thinking.effort`; older GLM models only
21
23
  * support thinking on/off and should not receive a thinking param at all.
22
24
  *
@@ -42,7 +44,7 @@ class ZhipuAIProvider {
42
44
  onRateLimit;
43
45
  constructor(config = {}) {
44
46
  this.apiKey = config.apiKey ?? process.env.ZHIPU_API_KEY ?? '';
45
- this.defaultModel = config.defaultModel ?? 'glm-5.2';
47
+ this.defaultModel = config.defaultModel ?? 'glm-5.3';
46
48
  this.maxTokens = config.maxTokens ?? 4096;
47
49
  this.baseUrl = config.baseUrl ?? process.env.ZHIPU_BASE_URL ?? 'https://api.z.ai/api/paas';
48
50
  this.completionsPath =
package/dist/types.d.ts CHANGED
@@ -12,7 +12,7 @@ export interface ZhipuConfig {
12
12
  onRateLimit?: AiRateLimitCallback;
13
13
  /** API key. Defaults to ZHIPU_API_KEY env var. */
14
14
  apiKey?: string;
15
- /** Default model. Defaults to 'glm-5.2'. */
15
+ /** Default model. Defaults to 'glm-5.3'. */
16
16
  defaultModel?: string;
17
17
  /** Maximum tokens for completions. */
18
18
  maxTokens?: number;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@molecule/api-ai-zhipu",
3
- "version": "1.0.0",
3
+ "version": "1.0.2",
4
4
  "description": "Zhipu GLM AI provider for molecule.dev",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -17,7 +17,8 @@
17
17
  }
18
18
  },
19
19
  "files": [
20
- "dist"
20
+ "dist",
21
+ "README.md"
21
22
  ],
22
23
  "keywords": [
23
24
  "molecule",
@@ -26,18 +27,23 @@
26
27
  "glm"
27
28
  ],
28
29
  "license": "Apache-2.0",
30
+ "repository": {
31
+ "type": "git",
32
+ "url": "https://github.com/molecule-dev/molecule.git",
33
+ "directory": "packages/api/bonds/ai/zhipu"
34
+ },
29
35
  "devDependencies": {
30
- "@molecule/api-ai": "1.0.0",
31
- "@molecule/api-bond": "1.0.0",
36
+ "@molecule/api-ai": "1.1.0",
37
+ "@molecule/api-bond": "1.0.1",
32
38
  "@types/node": "26.1.2",
33
39
  "typescript": "6.0.3",
34
40
  "vitest": "4.1.10"
35
41
  },
36
42
  "peerDependencies": {
37
- "@molecule/api-ai": "^1.0.0",
38
- "@molecule/api-bond": "^1.0.0",
39
- "@molecule/api-i18n": "^1.0.0",
40
- "@molecule/api-secrets": "^1.0.0"
43
+ "@molecule/api-ai": "^1.0.1",
44
+ "@molecule/api-bond": "^1.0.1",
45
+ "@molecule/api-i18n": "^1.0.1",
46
+ "@molecule/api-secrets": "^1.0.1"
41
47
  },
42
48
  "peerDependenciesMeta": {
43
49
  "@molecule/api-ai": {