@argosvix/sdk 0.1.1 → 0.1.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.
Files changed (3) hide show
  1. package/CHANGELOG.md +20 -0
  2. package/README.md +53 -52
  3. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -4,6 +4,25 @@ All notable changes to `@argosvix/sdk` are documented in this file.
4
4
  The format is loosely based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
5
5
  and the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6
6
 
7
+ ## [0.1.2] - 2026-05-22
8
+
9
+ Documentation-only release that aligns the npm README with global SaaS norms.
10
+
11
+ ### Changed
12
+ - README is now fully English. The prior version mixed Japanese and English in
13
+ the same sections, which is unusual for a globally distributed npm package
14
+ and weakened the first-impression signal on the npm registry page. Japanese
15
+ speakers can read the same content (and more) at https://argosvix.com which
16
+ ships JA / EN locales.
17
+
18
+ ### Added
19
+ - Listed the new `examples/workers-anthropic/` integration alongside the
20
+ existing Next.js / Express / Lambda examples.
21
+
22
+ ### Notes
23
+ - No SDK code changes. The compiled `dist/` output is byte-identical to
24
+ v0.1.1 except for the bundled README inside the tarball.
25
+
7
26
  ## [0.1.1] - 2026-05-21
8
27
 
9
28
  Patch release that hardens short-lived runtime delivery and matches the SDK's
@@ -68,5 +87,6 @@ Initial public release on npm under the `alpha` dist-tag.
68
87
  only the ones you actually use.
69
88
  - License: MIT.
70
89
 
90
+ [0.1.2]: https://www.npmjs.com/package/@argosvix/sdk/v/0.1.2
71
91
  [0.1.1]: https://www.npmjs.com/package/@argosvix/sdk/v/0.1.1
72
92
  [0.1.0]: https://www.npmjs.com/package/@argosvix/sdk/v/0.1.0
package/README.md CHANGED
@@ -1,42 +1,42 @@
1
1
  # @argosvix/sdk
2
2
 
3
- Transparent observability wrapper for AI provider SDKs. Wrap a single line of code and get cost / latency / token / error records for every LLM call across OpenAI, Anthropic, Gemini, and Mistral.
3
+ Transparent observability wrapper for AI provider SDKs. Wrap a single line of code and get cost, latency, token, and error records for every LLM call across OpenAI, Anthropic, Gemini, and Mistral.
4
4
 
5
- > 🟢 **Alpha released** — backend ingest (`ingest.argosvix.com`) と dashboard (`dashboard.argosvix.com`) は稼働中。 npm に `@argosvix/sdk@alpha` で公開済。 dogfood / ベータ提供期間として無料プランのみで運用しており、 サインアップから API キー発行までブラウザだけで完了します。 詳細な変更履歴は [`CHANGELOG.md`](./CHANGELOG.md) を参照。
5
+ > 🟢 **Alpha released** — backend ingest (`ingest.argosvix.com`) and dashboard (`dashboard.argosvix.com`) are live. Published on npm as `@argosvix/sdk@alpha`. We operate as a Free-only plan during the current beta phase; the entire sign-up to API-key flow runs in the browser. See [`CHANGELOG.md`](./CHANGELOG.md) for the full change log.
6
6
  >
7
- > 設計方針:
8
- > - **顧客のエンドユーザー PII は送信しない**(prompt / completion 本文は記録対象外、 token 数 + cost + latency + error code のみ)
9
- > - **wrap idempotent**(二重 wrap しても安全、 WeakMap / WeakSet で 同一 instance を再 wrap しない)
10
- > - **runtime monkey-patch なし**(global を汚さず、 client 引数のみ mutate)
7
+ > Design principles:
8
+ > - **No end-user PII is sent.** Prompt and completion bodies are never recorded; only token counts, cost, latency, and error codes leave your process.
9
+ > - **Idempotent wrap.** Wrapping the same client twice is a no-op; we track instances via WeakMap / WeakSet.
10
+ > - **No global monkey-patching.** Only the client argument you pass in is mutated; the global namespace is untouched.
11
11
 
12
12
  ## Supported providers
13
13
 
14
- | provider | hook | streaming | notes |
14
+ | Provider | Hook | Streaming | Notes |
15
15
  |---|---|---|---|
16
16
  | **OpenAI** chat.completions | ✅ | ✅ | `chat.completions.create` |
17
- | **OpenAI** responses | ✅ | warn + skip(Phase B 以降)| `responses.create` |
18
- | **Anthropic** | ✅ | ✅ | `messages.create`(`message_start` + `message_delta` 累積)|
17
+ | **OpenAI** responses | ✅ | warn + skip (planned) | `responses.create` |
18
+ | **Anthropic** | ✅ | ✅ | `messages.create` (accumulates `message_start` + `message_delta`) |
19
19
  | **Mistral** | ✅ | ✅ | `chat.complete` + `chat.stream` |
20
- | **Gemini legacy**(`@google/generative-ai`)| ✅ | ✅ | `getGenerativeModel({...}).generateContent` / `generateContentStream` |
21
- | **Gemini current**(`@google/genai`)| ✅ | ✅ | `client.models.generateContent` / `generateContentStream` |
20
+ | **Gemini legacy** (`@google/generative-ai`) | ✅ | ✅ | `getGenerativeModel({...}).generateContent` / `generateContentStream` |
21
+ | **Gemini current** (`@google/genai`) | ✅ | ✅ | `client.models.generateContent` / `generateContentStream` |
22
22
 
23
23
  ## Install
24
24
 
25
25
  ```bash
26
26
  npm install @argosvix/sdk@alpha openai
27
- # Anthropic / Gemini / Mistral を使う場合は対応する SDK も併せて install
27
+ # Also install the SDKs for any other providers you use (Anthropic, Gemini, Mistral).
28
28
  ```
29
29
 
30
- API キー取得手順(2026-05 時点、 dogfood / ベータ運用):
30
+ ### Obtain an API key
31
31
 
32
- 1. <https://dashboard.argosvix.com/ja/signup> でメールアドレスとパスワードを登録
33
- 2. 受信した認証メール内のリンクを開く
34
- 3. 認証完了画面で `argosvix_live_…` 形式の API キーが**一度だけ**表示されます。 安全な場所に保管してください
32
+ 1. Sign up at <https://dashboard.argosvix.com/en/signup> with an email address and password.
33
+ 2. Open the verification link sent to your inbox.
34
+ 3. The verification screen displays your API key (`argosvix_live_…`) **once**. Copy and store it safely — it cannot be retrieved later (rotation will be available in a future release).
35
35
 
36
36
  ```bash
37
37
  export ARGOSVIX_API_KEY=argosvix_live_...
38
- # default ingest endpoint = https://ingest.argosvix.com
39
- # 自前 deploy する場合 = ARGOSVIX_API_BASE で override 可能
38
+ # Default ingest endpoint = https://ingest.argosvix.com
39
+ # Override with ARGOSVIX_API_BASE if you self-host the backend.
40
40
  ```
41
41
 
42
42
  ## Quick start
@@ -50,24 +50,33 @@ const client = wrap(new OpenAI(), {
50
50
  tags: { service: "support-bot", env: "production" },
51
51
  });
52
52
 
53
- // Use the wrapped client exactly like the original
53
+ // Use the wrapped client exactly like the original.
54
54
  const response = await client.chat.completions.create({
55
55
  model: "gpt-5.5",
56
56
  messages: [{ role: "user", content: "Hello" }],
57
57
  });
58
58
 
59
- // optional: graceful flush before process exit
59
+ // Optional: graceful flush before process exit.
60
60
  const recorder = getRecorder(client);
61
61
  if (recorder) await recorder.flush();
62
62
  ```
63
63
 
64
- 各呼び出しで自動的に記録される項目:
64
+ Each call automatically records:
65
65
 
66
- ## Short-lived runtimes(Cloudflare Workers / AWS Lambda / Vercel Edge)
66
+ - Prompt and completion token counts (`promptTokens` / `completionTokens`, camelCase).
67
+ - USD cost, computed from the bundled per-provider pricing table. Resource-prefixed model names such as `models/gemini-2.0-flash` are normalized to their terminal model name.
68
+ - Latency in milliseconds.
69
+ - Streaming responses produce a record once the final usage chunk is observed (synced with consumer completion).
70
+ - Arbitrary tags (`tags: { service: "X", env: "prod" }`).
71
+ - Structured error details (`statusCode`, `code`, `type`, `retryAfter`).
67
72
 
68
- これらの runtime は handler が return した瞬間に outstanding fire-and-forget fetch を kill する設計です。 SDK の buffer は `bufferMaxSize` (default 100) に到達するまで auto-flush しないため、 1 リクエスト = 数回の LLM call では context exit で record が失われます。
73
+ **Not recorded:** prompt bodies, completion bodies, system messages, or tool-call argument bodies. Only the metadata required for aggregation is sent — no PII or confidential strings are stored.
69
74
 
70
- 対策 = handler の `finally` で `flushClient` を await:
75
+ ## Short-lived runtimes (Cloudflare Workers / AWS Lambda / Vercel Edge)
76
+
77
+ These runtimes kill any outstanding fire-and-forget `fetch` the moment the handler returns. The SDK normally buffers records in memory and flushes them only when `bufferMaxSize` is reached (default 100), so a single request with a few LLM calls would lose its records on context exit.
78
+
79
+ Mitigation: await `flushClient(client)` in the handler's `finally` block.
71
80
 
72
81
  ```typescript
73
82
  import Anthropic from "@anthropic-ai/sdk";
@@ -86,35 +95,25 @@ export default {
86
95
  });
87
96
  // ...
88
97
  } finally {
89
- await flushClient(client); // 必須: backend 到達を保証
98
+ await flushClient(client); // Required: guarantees backend delivery before exit.
90
99
  }
91
100
  },
92
101
  };
93
102
  ```
94
103
 
95
- 長時間 dev server(Express / Next.js dev)や stateful Node プロセスでは不要(buffer auto-flush + process exit までは十分な時間がある)。
96
-
97
-
98
- - Prompt + completion token 数(camelCase の `promptTokens` / `completionTokens` で保持)
99
- - USD コスト(provider 別 pricing テーブル + resource-prefixed model 名 `models/gemini-2.0-flash` 対応)
100
- - 応答時間(ミリ秒)
101
- - ストリーミング = 最終 chunk の usage を取得した時点で record(consumer 完了と同期)
102
- - 任意タグ(`tags: { service: "X", env: "prod" }`)
103
- - エラー詳細(`statusCode` / `code` / `type` / `retryAfter`)
104
-
105
- **記録しない項目**: prompt 本文、 completion 本文、 system message、 tool call の引数本文。 集計に必要な metadata のみ送信し、 PII / 機密文字列を保管しない設計。
104
+ Long-running Node processes (Express, Next.js dev server, classic servers) do not need this — the buffer auto-flushes well before process exit.
106
105
 
107
106
  ## Composite client / explicit provider
108
107
 
109
- Auto-detect が ambiguous な場合 = `config.provider` で明示指定:
108
+ When auto-detection is ambiguous (e.g. for composite or adapter clients), set `config.provider` explicitly:
110
109
 
111
110
  ```typescript
112
111
  const client = wrap(myCompositeClient, { provider: "openai" });
113
112
  ```
114
113
 
115
- ## Tags + 集計
114
+ ## Tags + aggregation
116
115
 
117
- `tags` は record ごとに保存され、 backend dashboard で「`service=support-bot` の cost trend」 等の cross-dimension 集計が可能(Phase C dashboard 以降)。
116
+ Tags are persisted per record. The backend dashboard supports cross-dimension aggregation such as "cost trend for `service=support-bot`" (Phase C dashboard and beyond).
118
117
 
119
118
  ## Streaming
120
119
 
@@ -126,40 +125,42 @@ const stream = await client.chat.completions.create({
126
125
  });
127
126
 
128
127
  for await (const chunk of stream) {
129
- // 通常の AsyncIterable として消費
128
+ // Consume as a normal AsyncIterable.
130
129
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
131
130
  }
132
- // stream 完了時点で record が backend に POST される
131
+ // A record is POSTed to the backend once the stream completes.
133
132
  ```
134
133
 
135
134
  ## Examples
136
135
 
137
- [`examples/`](../../examples/) に 3 stack の minimum integration:
138
- - [`examples/nextjs-openai/`](../../examples/nextjs-openai/)= Next.js 14 App Router
139
- - [`examples/express-anthropic/`](../../examples/express-anthropic/)= Express + streaming + SIGTERM flush
140
- - [`examples/lambda-gemini/`](../../examples/lambda-gemini/)= AWS Lambda + `@google/genai` + container reuse 注意
136
+ The [`examples/`](../../examples/) directory contains minimum-viable integrations for four stacks:
137
+
138
+ - [`examples/nextjs-openai/`](../../examples/nextjs-openai/) — Next.js 14 App Router.
139
+ - [`examples/express-anthropic/`](../../examples/express-anthropic/) — Express with streaming and SIGTERM flush.
140
+ - [`examples/lambda-gemini/`](../../examples/lambda-gemini/) — AWS Lambda with `@google/genai` (note: container-reuse semantics).
141
+ - [`examples/workers-anthropic/`](../../examples/workers-anthropic/) — Cloudflare Workers with the `flushClient` pattern.
141
142
 
142
143
  ## API
143
144
 
144
145
  ### `wrap<T>(client: T, config?: ArgosvixConfig): T`
145
- Transparently wrap an AI SDK client. Returns the same client(mutated)so the call site shape is unchanged.
146
+ Transparently wraps an AI SDK client. Returns the same client (mutated) so the call-site shape is unchanged.
146
147
 
147
148
  ### `getRecorder(client: object): Recorder | null`
148
- Retrieve the Recorder instance associated with a wrapped client.
149
+ Retrieves the `Recorder` instance associated with a wrapped client.
149
150
 
150
151
  ### `flushClient(client: object): Promise<void>`
151
- Cloudflare Workers / Lambda 等 short-lived runtime 向け helper。 handler の finally で await すると、 SDK buffer を明示 flush + backend 到達待ちまで carry する。 失敗は console.error のみで throw しない(production の inline error 防止)。
152
+ Helper for short-lived runtimes (Cloudflare Workers, AWS Lambda, Vercel Edge). Awaiting this in a `finally` block explicitly flushes the SDK buffer and waits for backend delivery. Failures are logged via `console.error` only — never thrown — to avoid breaking the host application.
152
153
 
153
154
  ### `class Recorder`
154
155
  - `record(record: LlmCallRecord): void`
155
- - `flush(): Promise<LlmCallRecord[]>` — POST buffer to backend、 retry on 5xx/network、 4xx no-retry
156
+ - `flush(): Promise<LlmCallRecord[]>` — POSTs the buffer to the backend. Retries on 5xx and network errors; 4xx errors are not retried.
156
157
  - `getBufferSize(): number`
157
158
 
158
159
  ### `calculateCost(provider, model, promptTokens, completionTokens): number`
159
- Internal pricing calculator(USD)。 公開して unit-test や custom pricing で活用可能。 resource-prefixed model 名(`models/gemini-2.0-flash` 等)= terminal model 部分で lookup。
160
+ Internal pricing calculator returning USD. Exported for unit tests and custom-pricing experimentation. Resource-prefixed model names (e.g. `models/gemini-2.0-flash`) are looked up by their terminal model name.
160
161
 
161
- ### types
162
- `Provider` / `ArgosvixConfig` / `LlmCallRecord` / `PricingEntry`
162
+ ### Types
163
+ `Provider` · `ArgosvixConfig` · `LlmCallRecord` · `PricingEntry`
163
164
 
164
165
  ## License
165
166
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@argosvix/sdk",
3
- "version": "0.1.1",
3
+ "version": "0.1.2",
4
4
  "description": "Drop-in observability wrapper for OpenAI, Anthropic, Gemini, Mistral SDK clients. One-line wrap() = cost / latency / quality records.",
5
5
  "keywords": [
6
6
  "argosvix",