@molecule/api-ai-moonshot 1.0.0 → 1.0.1

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.
Files changed (2) hide show
  1. package/README.md +195 -0
  2. package/package.json +14 -8
package/README.md ADDED
@@ -0,0 +1,195 @@
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-04T01:47:34.665Z
7
+ -->
8
+
9
+ # @molecule/api-ai-moonshot
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
+ Moonshot (Kimi) AI provider for molecule.dev.
16
+
17
+ ## Type
18
+
19
+ `provider`
20
+
21
+ ## Installation
22
+
23
+ ```bash
24
+ npm install @molecule/api-ai-moonshot @molecule/api-ai @molecule/api-bond @molecule/api-i18n @molecule/api-secrets
25
+ ```
26
+
27
+ ## API
28
+
29
+ ### Interfaces
30
+
31
+ #### `MoonshotConfig`
32
+
33
+ Configuration for Moonshot.
34
+
35
+ ```typescript
36
+ interface MoonshotConfig {
37
+ /** API key. Defaults to MOONSHOT_API_KEY env var. */
38
+ apiKey?: string
39
+ /** Default model. Defaults to 'kimi-k3'. */
40
+ defaultModel?: string
41
+ /** Maximum tokens for completions. */
42
+ maxTokens?: number
43
+ /** Base URL override (for proxies). Defaults to 'https://api.moonshot.cn'. */
44
+ baseUrl?: string
45
+ /**
46
+ * Chat-completions path appended to {@link baseUrl}. Defaults to
47
+ * `/v1/chat/completions` (Moonshot-direct puts the version in the path). Set
48
+ * this when the same open-weight model is served by a US OpenAI-compatible
49
+ * host whose version prefix lives in the base URL instead — e.g. DeepInfra:
50
+ * `baseUrl='https://api.deepinfra.com/v1/openai'` + `completionsPath='/chat/completions'`.
51
+ */
52
+ completionsPath?: string
53
+ /**
54
+ * Optional catalog-id → upstream-model-id map, applied to the outbound request
55
+ * ONLY. Lets a US OpenAI-compatible host (DeepInfra) receive its namespaced id
56
+ * (`moonshotai/Kimi-K3`) while the rest of the platform — pricing, cost
57
+ * ceilings, display — keeps using the canonical catalog id (`kimi-k3`). An id
58
+ * not in the map passes through unchanged.
59
+ */
60
+ modelMap?: Record<string, string>
61
+ /** Called on each rate-limited/overloaded upstream response, before any retry sleep. */
62
+ onRateLimit?: AiRateLimitCallback
63
+ }
64
+ ```
65
+
66
+ #### `ProcessEnv`
67
+
68
+ Process Env interface.
69
+
70
+ ```typescript
71
+ interface ProcessEnv {
72
+ MOONSHOT_API_KEY: string
73
+ /** Base URL override (for credential brokers / gateways / US OpenAI-compatible hosts). */
74
+ MOONSHOT_BASE_URL?: string
75
+ /** Chat-completions path override (see {@link MoonshotConfig.completionsPath}). */
76
+ MOONSHOT_COMPLETIONS_PATH?: string
77
+ }
78
+ ```
79
+
80
+ ### Functions
81
+
82
+ #### `createProvider(config)`
83
+
84
+ Creates a Moonshot (Kimi) AI provider instance.
85
+
86
+ ```typescript
87
+ function createProvider(config?: MoonshotConfig): AIProvider
88
+ ```
89
+
90
+ - `config` — Moonshot-specific configuration (API key, model, max tokens, base URL).
91
+
92
+ **Returns:** An `AIProvider` backed by the Moonshot Chat Completions API.
93
+
94
+ ### Constants
95
+
96
+ #### `aiMoonshotSecretDefinitions`
97
+
98
+ Secret definitions required by the Moonshot AI bond.
99
+
100
+ ```typescript
101
+ const aiMoonshotSecretDefinitions: SecretDefinition[]
102
+ ```
103
+
104
+ #### `provider`
105
+
106
+ The provider implementation.
107
+
108
+ ```typescript
109
+ const provider: AIProvider
110
+ ```
111
+
112
+ ## Core Interface
113
+
114
+ Implements `@molecule/api-ai` interface.
115
+
116
+ ## Bond Wiring
117
+
118
+ Setup function to register this provider with the bond system:
119
+
120
+ ```typescript
121
+ import { bond } from '@molecule/api-bond'
122
+ import { provider } from '@molecule/api-ai-moonshot'
123
+
124
+ export function setupAiMoonshot(): void {
125
+ bond('ai', 'moonshot', provider)
126
+ }
127
+ ```
128
+
129
+ ## Injection Notes
130
+
131
+ ### Requirements
132
+
133
+ Peer dependencies:
134
+
135
+ - `@molecule/api-ai` ^1.0.1
136
+ - `@molecule/api-bond` ^1.0.1
137
+ - `@molecule/api-i18n` ^1.0.1
138
+ - `@molecule/api-secrets` ^1.0.1
139
+
140
+ ### Environment Variables
141
+
142
+ - `MOONSHOT_API_KEY` _(required)_ — Moonshot API key
143
+ - Setup: Create an API key in the Moonshot AI console.
144
+ - Get it here: [https://platform.moonshot.ai/console/api-keys](https://platform.moonshot.ai/console/api-keys)
145
+ - Example: `sk-...`
146
+
147
+ ### Runtime Dependencies
148
+
149
+ - `@molecule/api-ai`
150
+ - `@molecule/api-bond`
151
+ - `@molecule/api-i18n`
152
+ - `@molecule/api-secrets`
153
+
154
+ Config: `MOONSHOT_API_KEY` (SERVER-side only) plus an optional default model id/base URL.
155
+
156
+ **Missing `MOONSHOT_API_KEY` fails fast**: the provider throws naming the exact env var on
157
+ first use (the exported `provider` is a lazy proxy, so this fires on the first `chat()` call,
158
+ not at bond/module-load time) — it never silently sends an empty key.
159
+
160
+ **Error message disambiguation**: a plain 400 that ISN'T a context-length error (bad param,
161
+ malformed tool schema) gets its own non-retryable message distinct from the generic
162
+ "AI service error. Please try again." used for retryable failures.
163
+
164
+ **Reasoning effort** (`KIMI_REASONING_EFFORT`, optional): when a call doesn't pass
165
+ `params.thinking`, the provider reads this env var — `disabled` (default) fully disables
166
+ thinking (fastest, least accurate); `minimal` | `low` | `medium` | `high` set the API's
167
+ `reasoning_effort`. Note: on kimi-k2.6 even `minimal` produces ~1000 chars of reasoning
168
+ per turn (~5x slower than `disabled`, but more reliable for complex multi-step tasks).
169
+
170
+ ## E2E Tests
171
+
172
+ Integration checklist — drive the real UI (live preview, no mocks), adapt
173
+ each item to this app's actual chat/AI screens, and check every box off one
174
+ by one. A box you can't check is an integration bug to fix — not a skip. The
175
+ sandbox HAS an AI provider bonded, so the flow runs live end-to-end; AI
176
+ output is NON-DETERMINISTIC, so assert on STRUCTURE/behavior, not exact text:
177
+
178
+ - [ ] A message sent through the real chat UI comes back as a RELEVANT AI
179
+ reply — not an echo of the prompt, a hardcoded stub, or an empty bubble.
180
+ Ask something with a checkable answer (e.g. "What is 2 + 2?") and confirm
181
+ the response actually contains it ("4"), proving a live model answered.
182
+ - [ ] If the app streams, tokens render INCREMENTALLY — text grows word by
183
+ word in the UI, not one final blob dumped after a long frozen spinner. (A
184
+ streamed `chat()` yields `text` chunks then a final `done`; a single late
185
+ blob means the reply was awaited whole and streaming is broken.)
186
+ - [ ] Multi-turn CONTEXT is preserved: a follow-up that refers back to the
187
+ 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
188
+ line.
189
+ - [ ] A provider failure (bad/missing key, rate limit, timeout) surfaces as
190
+ a graceful in-UI error message, NOT a crash, blank screen, a spinner that
191
+ never resolves, or an unhandled 500. Force one and watch the UI recover.
192
+ - [ ] The provider key + the provider call are SERVER-side only: the key
193
+ never reaches the browser (check the network tab, the JS bundle, and page
194
+ globals), and no route proxies arbitrary prompts to the model without auth
195
+ - a token cap — an open AI endpoint is an unbounded bill and abuse vector.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@molecule/api-ai-moonshot",
3
- "version": "1.0.0",
3
+ "version": "1.0.1",
4
4
  "description": "Moonshot (Kimi) 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
  "kimi"
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/moonshot"
34
+ },
29
35
  "devDependencies": {
30
- "@molecule/api-ai": "1.0.0",
31
- "@molecule/api-bond": "1.0.0",
36
+ "@molecule/api-ai": "1.0.1",
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": {