@argosvix/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jissocyu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,162 @@
+# @argosvix/sdk
+
+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.
+
+> 🚧 **Pre-MVP** — backend ingest + dashboard は近日公開。 npm publish は `--tag alpha` で予定。 早期アクセスは [argosvix.com](https://argosvix.com) で waitlist 受付中。
+>
+> 設計方針:
+> - **顧客のエンドユーザー PII は送信しない**(prompt / completion 本文は記録対象外、 token 数 + cost + latency + error code のみ)
+> - **wrap idempotent**(二重 wrap しても安全、 WeakMap / WeakSet で 同一 instance を再 wrap しない)
+> - **runtime monkey-patch なし**(global を汚さず、 client 引数のみ mutate)
+
+## Supported providers
+
+| provider | hook | streaming | notes |
+|---|---|---|---|
+| **OpenAI** chat.completions | ✅ | ✅ | `chat.completions.create` |
+| **OpenAI** responses | ✅ | warn + skip(Phase B 以降)| `responses.create` |
+| **Anthropic** | ✅ | ✅ | `messages.create`(`message_start` + `message_delta` 累積)|
+| **Mistral** | ✅ | ✅ | `chat.complete` + `chat.stream` |
+| **Gemini legacy**(`@google/generative-ai`)| ✅ | ✅ | `getGenerativeModel({...}).generateContent` / `generateContentStream` |
+| **Gemini current**(`@google/genai`)| ✅ | ✅ | `client.models.generateContent` / `generateContentStream` |
+
+## Install
+
+```bash
+# alpha 段階 (= 公開後)
+npm install @argosvix/sdk@alpha openai
+```
+
+API key は [argosvix.com](https://argosvix.com) で waitlist 登録後、 launch 時に発行されます。 設定:
+
+```bash
+export ARGOSVIX_API_KEY=argosvix_live_...
+# default ingest endpoint = https://ingest.argosvix.com
+# 自前 deploy する場合 = ARGOSVIX_API_BASE で override 可能
+```
+
+## Quick start
+
+```typescript
+import OpenAI from "openai";
+import { wrap, getRecorder } from "@argosvix/sdk";
+
+const client = wrap(new OpenAI(), {
+  apiKey: process.env.ARGOSVIX_API_KEY,
+  tags: { service: "support-bot", env: "production" },
+});
+
+// Use the wrapped client exactly like the original
+const response = await client.chat.completions.create({
+  model: "gpt-5.5",
+  messages: [{ role: "user", content: "Hello" }],
+});
+
+// optional: graceful flush before process exit
+const recorder = getRecorder(client);
+if (recorder) await recorder.flush();
+```
+
+各呼び出しで自動的に記録される項目:
+
+## Short-lived runtimes(Cloudflare Workers / AWS Lambda / Vercel Edge)
+
+これらの runtime は handler が return した瞬間に outstanding fire-and-forget fetch を kill する設計です。 SDK の buffer は `bufferMaxSize` (default 100) に到達するまで auto-flush しないため、 1 リクエスト = 数回の LLM call では context exit で record が失われます。
+
+対策 = handler の `finally` で `flushClient` を await:
+
+```typescript
+import Anthropic from "@anthropic-ai/sdk";
+import { wrap, flushClient } from "@argosvix/sdk";
+
+export default {
+  async scheduled(_event, env) {
+    const client = wrap(new Anthropic({ apiKey: env.ANTHROPIC_API_KEY }), {
+      apiKey: env.ARGOSVIX_API_KEY,
+    });
+    try {
+      const res = await client.messages.create({
+        model: "claude-opus-4-1",
+        max_tokens: 200,
+        messages: [{ role: "user", content: "..." }],
+      });
+      // ...
+    } finally {
+      await flushClient(client); // 必須: backend 到達を保証
+    }
+  },
+};
+```
+
+長時間 dev server(Express / Next.js dev)や stateful Node プロセスでは不要(buffer auto-flush + process exit までは十分な時間がある)。
+
+
+- Prompt + completion token 数(camelCase の `promptTokens` / `completionTokens` で保持)
+- USD コスト(provider 別 pricing テーブル + resource-prefixed model 名 `models/gemini-2.0-flash` 対応)
+- 応答時間(ミリ秒)
+- ストリーミング = 最終 chunk の usage を取得した時点で record(consumer 完了と同期)
+- 任意タグ(`tags: { service: "X", env: "prod" }`)
+- エラー詳細(`statusCode` / `code` / `type` / `retryAfter`)
+
+**記録しない項目**: prompt 本文、 completion 本文、 system message、 tool call の引数本文。 集計に必要な metadata のみ送信し、 PII / 機密文字列を保管しない設計。
+
+## Composite client / explicit provider
+
+Auto-detect が ambiguous な場合 = `config.provider` で明示指定:
+
+```typescript
+const client = wrap(myCompositeClient, { provider: "openai" });
+```
+
+## Tags + 集計
+
+`tags` は record ごとに保存され、 backend dashboard で「`service=support-bot` の cost trend」 等の cross-dimension 集計が可能(Phase C dashboard 以降)。
+
+## Streaming
+
+```typescript
+const stream = await client.chat.completions.create({
+  model: "gpt-5.5",
+  messages: [...],
+  stream: true,
+});
+
+for await (const chunk of stream) {
+  // 通常の AsyncIterable として消費
+  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
+}
+// stream 完了時点で record が backend に POST される
+```
+
+## Examples
+
+[`examples/`](../../examples/) に 3 stack の minimum integration:
+- [`examples/nextjs-openai/`](../../examples/nextjs-openai/)= Next.js 14 App Router
+- [`examples/express-anthropic/`](../../examples/express-anthropic/)= Express + streaming + SIGTERM flush
+- [`examples/lambda-gemini/`](../../examples/lambda-gemini/)= AWS Lambda + `@google/genai` + container reuse 注意
+
+## API
+
+### `wrap<T>(client: T, config?: ArgosvixConfig): T`
+Transparently wrap an AI SDK client. Returns the same client(mutated)so the call site shape is unchanged.
+
+### `getRecorder(client: object): Recorder | null`
+Retrieve the Recorder instance associated with a wrapped client.
+
+### `flushClient(client: object): Promise<void>`
+Cloudflare Workers / Lambda 等 short-lived runtime 向け helper。 handler の finally で await すると、 SDK buffer を明示 flush + backend 到達待ちまで carry する。 失敗は console.error のみで throw しない(production の inline error 防止)。
+
+### `class Recorder`
+- `record(record: LlmCallRecord): void`
+- `flush(): Promise<LlmCallRecord[]>` — POST buffer to backend、 retry on 5xx/network、 4xx no-retry
+- `getBufferSize(): number`
+
+### `calculateCost(provider, model, promptTokens, completionTokens): number`
+Internal pricing calculator(USD)。 公開して unit-test や custom pricing で活用可能。 resource-prefixed model 名(`models/gemini-2.0-flash` 等)= terminal model 部分で lookup。
+
+### types
+`Provider` / `ArgosvixConfig` / `LlmCallRecord` / `PricingEntry`
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,24 @@
+import type { ArgosvixConfig } from "./types.js";
+import { Recorder } from "./recorder.js";
+/**
+ * Wrap an AI provider SDK client to transparently record every call.
+ *
+ * Supported: OpenAI (chat.completions + responses), Anthropic (messages),
+ * Mistral (chat.complete + chat.stream), Gemini (legacy `@google/generative-ai`
+ * + current `@google/genai`).
+ *
+ * Provider detection: constructor-name fingerprint with shape-based fallback.
+ * For composite or adapter clients, pass `config.provider` to override detection.
+ *
+ * Idempotency: wrapping the same client twice is a no-op.
+ *
+ * @example
+ * import OpenAI from "openai";
+ * import { wrap, getRecorder } from "@argosvix/sdk";
+ *
+ * const client = wrap(new OpenAI(), { apiKey: "...", tags: { service: "bot" } });
+ * const recorder = getRecorder(client);
+ */
+export declare function wrap<T extends object>(client: T, config?: ArgosvixConfig): T;
+export declare function getRecorder(client: object): Recorder | null;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAA2B,MAAM,YAAY,CAAC;AAE1E,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAKzC;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAE,cAAmB,GAAG,CAAC,CAiChF;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAE3D"}