@molecule/api-ai-anthropic 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 +183 -0
  2. package/package.json +14 -8
package/README.md ADDED
@@ -0,0 +1,183 @@
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:28.776Z
7
+ -->
8
+
9
+ # @molecule/api-ai-anthropic
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
+ Anthropic ai-anthropic provider for molecule.dev.
16
+
17
+ ## Type
18
+
19
+ `provider`
20
+
21
+ ## Installation
22
+
23
+ ```bash
24
+ npm install @molecule/api-ai-anthropic @molecule/api-ai @molecule/api-bond @molecule/api-i18n @molecule/api-secrets
25
+ ```
26
+
27
+ ## API
28
+
29
+ ### Interfaces
30
+
31
+ #### `AnthropicConfig`
32
+
33
+ Configuration for anthropic.
34
+
35
+ ```typescript
36
+ interface AnthropicConfig {
37
+ /** API key. Defaults to ANTHROPIC_API_KEY env var. */
38
+ apiKey?: string
39
+ /** Default model. Defaults to 'claude-opus-5'. */
40
+ defaultModel?: string
41
+ /** Maximum tokens for completions. */
42
+ maxTokens?: number
43
+ /** Base URL override (for proxies). */
44
+ baseUrl?: string
45
+ /** Called on each rate-limited/overloaded upstream response, before any retry sleep. */
46
+ onRateLimit?: AiRateLimitCallback
47
+ }
48
+ ```
49
+
50
+ #### `ProcessEnv`
51
+
52
+ Process Env interface.
53
+
54
+ ```typescript
55
+ interface ProcessEnv {
56
+ ANTHROPIC_API_KEY: string
57
+ /** Base URL override (for credential brokers / gateways). */
58
+ ANTHROPIC_BASE_URL?: string
59
+ }
60
+ ```
61
+
62
+ ### Functions
63
+
64
+ #### `createProvider(config)`
65
+
66
+ Creates an Anthropic Claude AI provider instance.
67
+
68
+ ```typescript
69
+ function createProvider(config?: AnthropicConfig): AIProvider
70
+ ```
71
+
72
+ - `config` — Anthropic-specific configuration (API key, model, max tokens, base URL).
73
+
74
+ **Returns:** An `AIProvider` backed by the Anthropic Messages API.
75
+
76
+ ### Constants
77
+
78
+ #### `aiAnthropicSecretDefinitions`
79
+
80
+ Secret definitions required by the Anthropic AI bond.
81
+
82
+ ```typescript
83
+ const aiAnthropicSecretDefinitions: SecretDefinition[]
84
+ ```
85
+
86
+ #### `provider`
87
+
88
+ The provider implementation.
89
+
90
+ ```typescript
91
+ const provider: AIProvider
92
+ ```
93
+
94
+ ## Core Interface
95
+
96
+ Implements `@molecule/api-ai` interface.
97
+
98
+ ## Bond Wiring
99
+
100
+ Setup function to register this provider with the bond system:
101
+
102
+ ```typescript
103
+ import { bond } from '@molecule/api-bond'
104
+ import { provider } from '@molecule/api-ai-anthropic'
105
+
106
+ export function setupAiAnthropic(): void {
107
+ bond('ai', 'anthropic', provider)
108
+ }
109
+ ```
110
+
111
+ ## Injection Notes
112
+
113
+ ### Requirements
114
+
115
+ Peer dependencies:
116
+
117
+ - `@molecule/api-ai` ^1.0.1
118
+ - `@molecule/api-bond` ^1.0.1
119
+ - `@molecule/api-i18n` ^1.0.1
120
+ - `@molecule/api-secrets` ^1.0.1
121
+
122
+ ### Environment Variables
123
+
124
+ - `ANTHROPIC_API_KEY` _(required)_ — Anthropic API key
125
+ - Setup: Create a key in the Anthropic Console under Settings → API keys.
126
+ - Get it here: [https://console.anthropic.com/settings/keys](https://console.anthropic.com/settings/keys)
127
+ - Example: `sk-ant-api03-...`
128
+
129
+ ### Runtime Dependencies
130
+
131
+ - `@molecule/api-ai`
132
+ - `@molecule/api-bond`
133
+ - `@molecule/api-i18n`
134
+ - `@molecule/api-secrets`
135
+
136
+ Bond this as an AI provider (see `@molecule/api-ai` for the `chat()` streaming loop and the
137
+ key-server-side / never-blindly-trust-model-output rules). Config: `ANTHROPIC_API_KEY`
138
+ (SERVER-side only — never shipped to the browser) plus an optional default model id. Drive it
139
+ through the core `chat()` / `requireProvider()`, NOT the Anthropic SDK directly, so the app
140
+ stays provider-agnostic and can swap models/providers by changing only the bond.
141
+
142
+ **Missing `ANTHROPIC_API_KEY` fails fast**: the provider throws naming the exact env var on
143
+ first use (the exported `provider` is a lazy proxy, so this fires on the first `chat()` call,
144
+ not at bond/module-load time) — it never silently sends an empty key and surfaces only as a
145
+ generic 401 later.
146
+
147
+ **Error message disambiguation**: a non-OK response yields a sanitized `error` ChatEvent
148
+ (never a throw). A permanently-invalid request — a plain 400 that ISN'T a context-length
149
+ error (bad param, malformed tool schema) — gets its own non-retryable message ("AI request
150
+ was invalid — check the model and request parameters.") distinct from the generic "AI service
151
+ error. Please try again." used for retryable failures; don't retry a plain 400 as if it might
152
+ succeed on a second attempt.
153
+
154
+ ## E2E Tests
155
+
156
+ Integration checklist — drive the real UI (live preview, no mocks), adapt
157
+ each item to this app's actual chat/AI screens, and check every box off one
158
+ by one. A box you can't check is an integration bug to fix — not a skip. The
159
+ sandbox HAS an AI provider bonded, so the flow runs live end-to-end; AI
160
+ output is NON-DETERMINISTIC, so assert on STRUCTURE/behavior, not exact text:
161
+
162
+ - [ ] A message sent through the real chat UI comes back as a RELEVANT AI
163
+ reply — not an echo of the prompt, a hardcoded stub, or an empty bubble.
164
+ Ask something with a checkable answer (e.g. "What is 2 + 2?") and confirm
165
+ the response actually contains it ("4"), proving a live model answered.
166
+ - [ ] If the app streams, tokens render INCREMENTALLY — text grows word by
167
+ word in the UI, not one final blob dumped after a long frozen spinner. (A
168
+ streamed `chat()` yields `text` chunks then a final `done`; a single late
169
+ blob means the reply was awaited whole and streaming is broken.)
170
+ - [ ] Multi-turn CONTEXT is preserved: a follow-up that refers back to the
171
+ 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
172
+ line.
173
+ - [ ] A provider failure (bad/missing key, rate limit, timeout) surfaces as
174
+ a graceful in-UI error message, NOT a crash, blank screen, a spinner that
175
+ never resolves, or an unhandled 500. Force one and watch the UI recover.
176
+ - [ ] The provider key + the provider call are SERVER-side only: the key
177
+ never reaches the browser (check the network tab, the JS bundle, and page
178
+ globals), and no route proxies arbitrary prompts to the model without auth
179
+ - a token cap — an open AI endpoint is an unbounded bill and abuse vector.
180
+
181
+ ## Translations
182
+
183
+ Translation strings are provided by `@molecule/api-locales-ai-anthropic`.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@molecule/api-ai-anthropic",
3
- "version": "1.0.0",
3
+ "version": "1.0.1",
4
4
  "description": "Anthropic Claude 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",
@@ -25,18 +26,23 @@
25
26
  "anthropic"
26
27
  ],
27
28
  "license": "Apache-2.0",
29
+ "repository": {
30
+ "type": "git",
31
+ "url": "https://github.com/molecule-dev/molecule.git",
32
+ "directory": "packages/api/bonds/ai/anthropic"
33
+ },
28
34
  "devDependencies": {
29
- "@molecule/api-ai": "1.0.0",
30
- "@molecule/api-bond": "1.0.0",
35
+ "@molecule/api-ai": "1.0.1",
36
+ "@molecule/api-bond": "1.0.1",
31
37
  "@types/node": "26.1.2",
32
38
  "typescript": "6.0.3",
33
39
  "vitest": "4.1.10"
34
40
  },
35
41
  "peerDependencies": {
36
- "@molecule/api-ai": "^1.0.0",
37
- "@molecule/api-bond": "^1.0.0",
38
- "@molecule/api-i18n": "^1.0.0",
39
- "@molecule/api-secrets": "^1.0.0"
42
+ "@molecule/api-ai": "^1.0.1",
43
+ "@molecule/api-bond": "^1.0.1",
44
+ "@molecule/api-i18n": "^1.0.1",
45
+ "@molecule/api-secrets": "^1.0.1"
40
46
  },
41
47
  "peerDependenciesMeta": {
42
48
  "@molecule/api-ai": {