@cetusai/sdk 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes to `@songlines/sdk` are documented here.
+
+This project adheres to [Semantic Versioning](https://semver.org/).
+
+---
+
+## [0.2.0] — Unreleased
+
+### Added
+- `evaluateGuardrail(params)` — real-time policy evaluation via the Songlines Gateway API
+- `SonglinesClient.evaluateGuardrail()` — synchronous guardrail check before sending to an LLM
+- `GuardrailResult` type with `decision`, `violations`, `modifiedInput`, and `latencyMs`
+- `GuardrailViolation` type with `policyId`, `policyName`, `action`, `reason`, and `field`
+- `GuardrailBlockedError` — thrown when a guardrail returns `decision: "block"` and `throwOnBlock: true`
+- Tests for allow, block, modify, and multiple-violation scenarios
+
+---
+
+## [0.1.0] — 2026-06-23
+
+### Added
+- `SonglinesClient` with `trackAIRequest()`, `flush()`, and `shutdown()`
+- `wrapOpenAI()` — transparent proxy for the OpenAI SDK
+- `wrapAnthropic()` — transparent proxy for the Anthropic SDK
+- `BatchQueue` — async batching with configurable `batchSize` and `flushIntervalMs`
+- Exponential backoff retry with jitter (`withRetry()`)
+- Built-in cost estimation for 14+ models (`estimateCost()`, `getModelRates()`)
+- Zero-dependency UUID v4 generator
+- 9 typed error classes surfaced via `onError` callback
+- Dual ESM + CJS build with TypeScript declarations
+- 76 unit tests across 5 test files

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cetus AI Pty Ltd
+
+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,409 @@
+# @songlines/sdk
+
+Official TypeScript/JavaScript SDK for **Songlines Control** — AI observability, cost attribution, and governance for enterprise workloads.
+
+[![npm version](https://img.shields.io/npm/v/@songlines/sdk)](https://www.npmjs.com/package/@songlines/sdk)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green)](LICENSE)
+
+---
+
+## Features
+
+- **Zero runtime dependencies** in the core ingest path — no supply chain risk, no version conflicts
+- **Fire-and-forget** — `trackAIRequest()` never blocks or slows down your AI calls
+- **Automatic batching** — events are queued and flushed in configurable batches
+- **Exponential backoff** — failed flushes are retried automatically with jitter
+- **OpenAI & Anthropic wrappers** — one-line instrumentation with `wrapOpenAI()` / `wrapAnthropic()`
+- **Prompt-safe by design** — prompt content is never captured or transmitted
+- **Dual ESM + CJS** — works in Node.js, edge runtimes, and bundlers
+- **Full TypeScript types** — end-to-end type safety with declaration maps
+
+---
+
+## Installation
+
+```bash
+npm install @songlines/sdk
+# or
+pnpm add @songlines/sdk
+# or
+yarn add @songlines/sdk
+```
+
+---
+
+## Quick Start
+
+### Manual tracking
+
+```typescript
+import { SonglinesClient } from "@songlines/sdk";
+
+const songlines = new SonglinesClient({
+  apiKey: process.env.SONGLINES_API_KEY!,
+});
+
+// After your AI call completes:
+await songlines.trackAIRequest({
+  model: "gpt-4o",
+  provider: "openai",
+  workflow: "invoice-processor",
+  inputTokens: 1200,
+  outputTokens: 400,
+  latencyMs: 1840,
+  status: "success",
+});
+
+// Flush on graceful shutdown
+process.on("SIGTERM", async () => {
+  await songlines.shutdown();
+  process.exit(0);
+});
+```
+
+### OpenAI wrapper (recommended)
+
+```typescript
+import OpenAI from "openai";
+import { SonglinesClient, wrapOpenAI } from "@songlines/sdk";
+
+const openai = wrapOpenAI(new OpenAI(), new SonglinesClient({
+  apiKey: process.env.SONGLINES_API_KEY!,
+}), {
+  workflow: "customer-support",
+  environment: "production",
+});
+
+// All calls are automatically tracked — no code changes needed
+const response = await openai.chat.completions.create({
+  model: "gpt-4o",
+  messages: [{ role: "user", content: "Hello" }],
+});
+```
+
+### Anthropic wrapper
+
+```typescript
+import Anthropic from "@anthropic-ai/sdk";
+import { SonglinesClient, wrapAnthropic } from "@songlines/sdk";
+
+const anthropic = wrapAnthropic(new Anthropic(), new SonglinesClient({
+  apiKey: process.env.SONGLINES_API_KEY!,
+}), {
+  workflow: "document-review",
+});
+
+const message = await anthropic.messages.create({
+  model: "claude-3-5-sonnet-20241022",
+  max_tokens: 1024,
+  messages: [{ role: "user", content: "Summarise this document." }],
+});
+```
+
+---
+
+## Configuration
+
+```typescript
+const songlines = new SonglinesClient({
+  // Required
+  apiKey: process.env.SONGLINES_API_KEY!,
+
+  // Optional — defaults shown
+  baseUrl: "https://api.songlinesai.com",  // Override for on-premises deployments
+  environment: "production",               // "production" | "staging" | "development" | "test"
+  batchSize: 10,                           // Flush after N events (1–100)
+  flushIntervalMs: 5000,                   // Flush every N ms (100–60000)
+  timeout: 10000,                          // HTTP request timeout in ms
+  retries: 3,                              // Retry attempts on network failure (0–10)
+  debug: false,                            // Log SDK internals to console.debug
+
+  // Error callback — called when events are dropped after all retries
+  onError: (error) => {
+    console.error("[Songlines SDK]", error.code, error.message);
+  },
+});
+```
+
+---
+
+## API Reference
+
+### `SonglinesClient`
+
+#### `trackAIRequest(params)`
+
+Records an AI request event. Returns immediately — the event is queued and sent asynchronously.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `model` | `string` | Yes | Model identifier (e.g. `"gpt-4o"`, `"claude-3-5-sonnet-20241022"`) |
+| `provider` | `string` | No | Provider name (e.g. `"openai"`, `"anthropic"`, `"azure"`) |
+| `workflow` | `string` | No | Logical workflow or feature name for cost attribution |
+| `step` | `string` | No | Step within a multi-step workflow |
+| `agentId` | `string` | No | Agent identifier for multi-agent systems |
+| `user` | `string` | No | End-user identifier (hashed/anonymised) |
+| `inputTokens` | `number` | No | Prompt token count |
+| `outputTokens` | `number` | No | Completion token count |
+| `latencyMs` | `number` | No | End-to-end latency in milliseconds |
+| `cost` | `number` | No | Actual cost in USD (auto-estimated if omitted) |
+| `status` | `RequestStatus` | No | `"success"` \| `"error"` \| `"blocked"` \| `"pending"` (default: `"success"`) |
+| `requestId` | `string` | No | Idempotency key (UUID auto-generated if omitted) |
+| `timestamp` | `Date` | No | Event timestamp (current time if omitted) |
+
+#### `flush()`
+
+Forces immediate delivery of all queued events. Resolves when the flush completes.
+
+```typescript
+await songlines.flush();
+```
+
+#### `shutdown()`
+
+Flushes remaining events and stops the background timer. Call during graceful shutdown.
+
+```typescript
+await songlines.shutdown();
+```
+
+---
+
+### `wrapOpenAI(client, songlinesClient, options?)`
+
+Returns a transparent proxy of the OpenAI client that automatically calls `trackAIRequest()` after every `chat.completions.create()` call.
+
+**Options** (`WrapOptions`):
+
+| Option | Type | Description |
+|---|---|---|
+| `workflow` | `string` | Workflow tag applied to all calls via this wrapper |
+| `step` | `string` | Step tag applied to all calls |
+| `agentId` | `string` | Agent identifier |
+| `user` | `string` | End-user identifier |
+
+**Behaviour:**
+- Token counts are read from `response.usage` automatically
+- Latency is measured from call start to response received
+- On API error, `status: "error"` is recorded and the error is re-thrown
+- Streaming calls (`stream: true`) are tracked with `inputTokens: 0, outputTokens: 0` — token counts are not available from the stream
+- Prompt content is never captured
+
+---
+
+### `wrapAnthropic(client, songlinesClient, options?)`
+
+Returns a transparent proxy of the Anthropic client that automatically calls `trackAIRequest()` after every `messages.create()` call.
+
+Behaviour is identical to `wrapOpenAI()` — token counts from `response.usage.input_tokens` / `response.usage.output_tokens`, latency measured end-to-end, errors recorded and re-thrown.
+
+---
+
+### Cost Estimation
+
+If `cost` is not provided to `trackAIRequest()`, the SDK estimates it from the model name and token counts using a built-in rate table. The table is updated with each SDK release.
+
+```typescript
+import { estimateCost, getModelRates } from "@songlines/sdk";
+
+// Estimate cost for a specific call
+const cost = estimateCost({
+  model: "gpt-4o",
+  inputTokens: 1000,
+  outputTokens: 500,
+});
+// → 0.00750 (USD)
+
+// Inspect the full rate table
+const rates = getModelRates();
+// → { "gpt-4o": { input: 2.50, output: 10.00 }, ... }
+```
+
+**Supported models (built-in rates):**
+
+| Model | Input ($/M tokens) | Output ($/M tokens) |
+|---|---|---|
+| gpt-4o | $2.50 | $10.00 |
+| gpt-4o-mini | $0.15 | $0.60 |
+| gpt-4-turbo | $10.00 | $30.00 |
+| gpt-3.5-turbo | $0.50 | $1.50 |
+| o1 | $15.00 | $60.00 |
+| o1-mini | $3.00 | $12.00 |
+| o3-mini | $1.10 | $4.40 |
+| claude-3-5-sonnet | $3.00 | $15.00 |
+| claude-3-5-haiku | $0.80 | $4.00 |
+| claude-3-opus | $15.00 | $75.00 |
+| gemini-1.5-pro | $1.25 | $5.00 |
+| gemini-1.5-flash | $0.075 | $0.30 |
+| Unknown models | $1.00 | $3.00 |
+
+---
+
+## Error Handling
+
+The SDK never throws. All errors are surfaced via the `onError` callback.
+
+```typescript
+import {
+  InvalidApiKeyError,
+  NetworkError,
+  RateLimitedError,
+  ServerError,
+  QueueOverflowError,
+  PartialFailureError,
+} from "@songlines/sdk";
+
+const songlines = new SonglinesClient({
+  apiKey: process.env.SONGLINES_API_KEY!,
+  onError: (error) => {
+    if (error instanceof InvalidApiKeyError) {
+      // API key is invalid — alert immediately
+      alertOps("Invalid Songlines API key");
+    } else if (error instanceof RateLimitedError) {
+      // Back off — error.retryAfterMs is available if the server sent Retry-After
+      console.warn(`Rate limited. Retry after ${error.retryAfterMs}ms`);
+    } else if (error instanceof QueueOverflowError) {
+      // Events were dropped — queue is full
+      metrics.increment("songlines.events.dropped", error.droppedCount);
+    } else if (error instanceof NetworkError) {
+      // Transient network failure after all retries exhausted
+      metrics.increment("songlines.flush.failed");
+    }
+  },
+});
+```
+
+---
+
+## Framework Examples
+
+### Express.js middleware
+
+```typescript
+import express from "express";
+import OpenAI from "openai";
+import { SonglinesClient, wrapOpenAI } from "@songlines/sdk";
+
+const songlines = new SonglinesClient({ apiKey: process.env.SONGLINES_API_KEY! });
+const openai = wrapOpenAI(new OpenAI(), songlines);
+
+const app = express();
+
+app.post("/chat", async (req, res) => {
+  const { message, userId } = req.body;
+
+  const response = await openai.chat.completions.create({
+    model: "gpt-4o",
+    messages: [{ role: "user", content: message }],
+    // Songlines metadata passed via options at wrap time
+  });
+
+  res.json({ reply: response.choices[0]?.message.content });
+});
+
+process.on("SIGTERM", async () => {
+  await songlines.shutdown();
+  process.exit(0);
+});
+```
+
+### Next.js API route
+
+```typescript
+// app/api/chat/route.ts
+import { SonglinesClient, wrapOpenAI } from "@songlines/sdk";
+import OpenAI from "openai";
+
+// Instantiate once per cold start
+const songlines = new SonglinesClient({ apiKey: process.env.SONGLINES_API_KEY! });
+const openai = wrapOpenAI(new OpenAI(), songlines, { workflow: "chat" });
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+  const response = await openai.chat.completions.create({ model: "gpt-4o", messages });
+  return Response.json(response);
+}
+```
+
+### LangChain callback
+
+```typescript
+import { SonglinesClient } from "@songlines/sdk";
+import { ChatOpenAI } from "@langchain/openai";
+
+const songlines = new SonglinesClient({ apiKey: process.env.SONGLINES_API_KEY! });
+
+const llm = new ChatOpenAI({ model: "gpt-4o" });
+
+// After each LangChain call, track manually:
+const result = await llm.invoke("Hello");
+await songlines.trackAIRequest({
+  model: "gpt-4o",
+  provider: "openai",
+  workflow: "langchain-agent",
+  inputTokens: result.usage_metadata?.input_tokens,
+  outputTokens: result.usage_metadata?.output_tokens,
+});
+```
+
+---
+
+## Privacy & Security
+
+**Prompt content is never captured.** The `wrapOpenAI()` and `wrapAnthropic()` proxies read only:
+- `response.usage` (token counts)
+- `response.model` (model name)
+- Request start/end timestamps (latency)
+
+The message content, system prompts, and completion text are never accessed, stored, or transmitted by the SDK. This is a hard architectural boundary, not a configuration option.
+
+**API key security:**
+- Always load from environment variables — never hardcode
+- The API key is sent only in the `Authorization: Bearer` header over HTTPS
+- The SDK does not log the API key, even in `debug` mode
+
+---
+
+## Batching & Performance
+
+The SDK uses an in-memory queue with automatic batching to minimise API calls:
+
+```
+trackAIRequest() → queue.push() → [returns immediately]
+                                       ↓
+                              [batch reaches batchSize]
+                              [OR flushIntervalMs elapses]
+                                       ↓
+                              POST /api/ingest (batch)
+                              [retry with backoff on failure]
+```
+
+**Default behaviour:**
+- Events are batched up to 10 at a time
+- A partial batch is flushed every 5 seconds
+- Failed flushes are retried 3 times with exponential backoff (500ms base, 2× multiplier, ±20% jitter)
+- Events that fail all retries are dropped and reported via `onError`
+- The queue holds up to 1,000 events; overflow events are dropped and reported
+
+**Memory impact:** Each event is approximately 200–400 bytes. At the default queue cap of 1,000 events, the maximum memory footprint is approximately 400 KB.
+
+---
+
+## Changelog
+
+### 0.1.0 (2026-06-23)
+- Initial release
+- `SonglinesClient` with `trackAIRequest()`, `flush()`, `shutdown()`
+- `wrapOpenAI()` proxy wrapper
+- `wrapAnthropic()` proxy wrapper
+- Built-in cost estimation for 14+ models
+- Exponential backoff retry with jitter
+- Dual ESM + CJS build
+- Full TypeScript declarations
+
+---
+
+## License
+
+MIT © Cetus AI Pty Ltd