@bandito-ai/sdk 0.1.7

package/README.md

@@ -0,0 +1,162 @@
+# Bandito JavaScript SDK
+
+Zero-latency LLM routing via contextual bandits. `pull()` runs Thompson Sampling locally in <1ms via WASM — no network call on the hot path.
+
+## Install
+
+```bash
+pnpm add @bandito-ai/sdk
+```
+
+Requires Node.js 18+. The [Bandito CLI](../../cli/README.md) is a separate binary for account setup, bandit management, and grading:
+
+```bash
+brew install bandito-ai/tap/bandito   # or: cargo install --path cli
+bandito signup
+```
+
+## Quickstart
+
+```typescript
+import { connect, pull, update, close } from "@bandito-ai/sdk";
+
+await connect();
+
+// Pick the best model+prompt for this query (<1ms, WASM math)
+const result = pull("my-chatbot", { query: userMessage });
+
+// Call the winning LLM
+const response = await openai.chat.completions.create({
+  model: result.model,  // e.g. "gpt-4o"
+  messages: [
+    { role: "system", content: result.prompt },
+    { role: "user", content: userMessage },
+  ],
+});
+
+// Report what happened
+update(result, {
+  queryText: userMessage,
+  response: response.choices[0].message.content,
+  inputTokens: response.usage.prompt_tokens,
+  outputTokens: response.usage.completion_tokens,
+});
+
+await close();
+```
+
+Latency is auto-measured between `pull()` and `update()`. Cost is auto-calculated from token counts. Override either by passing `latency` or `cost` explicitly.
+
+## Usage Patterns
+
+**Module-level singleton** (simplest):
+
+```typescript
+import { connect, pull, update, close } from "@bandito-ai/sdk";
+await connect({ apiKey: "bnd_..." });
+const result = pull("my-chatbot");
+```
+
+**Explicit client** (recommended for servers):
+
+```typescript
+import { BanditoClient } from "@bandito-ai/sdk";
+
+const client = new BanditoClient({ apiKey: "bnd_..." });
+await client.connect();
+const result = client.pull("my-chatbot");
+await client.close();
+```
+
+## API Reference
+
+### `connect(options?)`
+
+Bootstrap: authenticate, fetch bandit state, load WASM engine, flush pending events. **Async.**
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `apiKey` | `BANDITO_API_KEY` env / config file | API key |
+| `baseUrl` | `https://bandito-api.onrender.com` | Cloud API endpoint |
+| `storePath` | `~/.bandito/events.db` | SQLite file for crash-safe event durability |
+| `dataStorage` | `"local"` | `"local"` keeps text on your machine; `"cloud"` sends it to the server |
+
+### `pull(banditName, options?) -> PullResult`
+
+Pick the best arm. Pure WASM math, <1ms, no network. **Synchronous.**
+
+**Returns** a `PullResult`:
+- `.model` — model name (e.g. `"gpt-4o"`)
+- `.prompt` — system prompt text
+- `.provider` — model provider (e.g. `"openai"`)
+- `.eventId` — UUID linking pull → update → grade
+- `.arm` — full `Arm` object
+- `.scores` — `Map<number, number>` arm scores (for debugging)
+
+Pass `exclude: [armId]` to skip a failing arm (circuit breaker pattern).
+
+### `update(pullResult, options?)`
+
+Report event data. Writes to local SQLite immediately, flushes to cloud in background. **Synchronous.**
+
+| Option | Description |
+|--------|-------------|
+| `queryText` | The user's query |
+| `response` | LLM response (string or object) |
+| `reward` | Immediate reward (0.0–1.0) |
+| `cost` | Cost in dollars (auto-calculated from tokens if omitted) |
+| `latency` | Latency in ms (auto-calculated from pull timing if omitted) |
+| `inputTokens` | Input token count |
+| `outputTokens` | Output token count |
+| `segment` | `Record<string, string>` segment tags |
+| `failed` | Mark as failed LLM call (defaults reward to 0.0) |
+
+### `grade(eventId, grade)`
+
+Submit a human grade (0.0–1.0) for a previous event. **Async.** Use the [TUI](../../cli/README.md#tui-grading-workbench) for bulk grading.
+
+### `sync()`
+
+Refresh bandit state from cloud. **Async.** Called automatically via background heartbeat.
+
+### `close()`
+
+Flush remaining events and shut down background interval. **Async.**
+
+## How It Works
+
+The SDK loads the Rust WASM engine during `connect()`. On `pull()`:
+
+1. Sample from the posterior via Thompson Sampling
+2. Build feature vectors per arm (model + prompt one-hot, query length, latency)
+3. Score each arm, return the winner
+
+All Bayesian updates happen server-side. The SDK refreshes via periodic heartbeat.
+
+**Crash safety** — events go to local SQLite (WAL mode) before any network call. Pending events retry on next `connect()`.
+
+**Fail-safe** — if the cloud is unreachable, the SDK keeps routing with last-known-good weights. Your app never breaks.
+
+## Configuration
+
+Shared `~/.bandito/config.toml` (created by `bandito signup` or `bandito config`):
+
+```toml
+api_key = "bnd_..."
+base_url = "https://bandito-api.onrender.com"
+data_storage = "local"
+```
+
+Environment variables `BANDITO_API_KEY`, `BANDITO_BASE_URL`, `BANDITO_DATA_STORAGE` override the file.
+
+## Development
+
+```bash
+# Build WASM engine
+cd engine && wasm-pack build --target nodejs --out-dir pkg --features wasm
+
+# Install and test
+cd sdks/javascript && pnpm install
+pnpm test    # 41 tests
+pnpm build   # CJS + ESM via tsup
+```

package/dist/index.d.mts

@@ -0,0 +1,145 @@
+/**
+ * SDK types: Arm, PullResult, and internal cache structures.
+ */
+/** An arm returned to the user after pull(). Immutable. */
+interface Arm {
+    readonly armId: number;
+    readonly modelName: string;
+    readonly modelProvider: string;
+    readonly systemPrompt: string;
+    readonly isPromptTemplated: boolean;
+    /** Convenience alias for modelName. */
+    readonly model: string;
+    /** Convenience alias for systemPrompt. */
+    readonly prompt: string;
+}
+/** Returned by pull(), passed to update(). Immutable. */
+interface PullResult {
+    readonly arm: Arm;
+    readonly eventId: string;
+    readonly banditId: number;
+    readonly banditName: string;
+    readonly scores: Readonly<Record<number, number>>;
+    /** Convenience reach-through to arm.modelName. */
+    readonly model: string;
+    /** Convenience reach-through to arm.systemPrompt. */
+    readonly prompt: string;
+    /** @internal perf timestamp */
+    readonly _pullTime: number;
+}
+
+/**
+ * BanditoClient — main orchestrator for the JS/TS SDK.
+ *
+ * Mirrors the Python SDK's sync-first design:
+ * - pull() is synchronous (WASM math, <1ms)
+ * - connect(), grade(), sync(), close() are async (HTTP I/O)
+ * - update() is synchronous (SQLite write + fire-and-forget flush)
+ */
+
+interface ClientOptions {
+    apiKey?: string;
+    baseUrl?: string;
+    storePath?: string;
+    dataStorage?: string;
+}
+interface PullOptions {
+    query?: string;
+    exclude?: number[];
+}
+interface UpdateOptions {
+    queryText?: string;
+    response?: string | Record<string, unknown>;
+    reward?: number;
+    cost?: number;
+    latency?: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    segment?: Record<string, string>;
+    failed?: boolean;
+}
+declare class BanditoClient {
+    private apiKey;
+    private baseUrl;
+    private storePath;
+    private dataStorageArg;
+    private dataStorage;
+    private http;
+    private store;
+    private engines;
+    private bandits;
+    private connected;
+    private flushInterval;
+    private flushInProgress;
+    private deadUuids;
+    private retryCounts;
+    constructor(options?: ClientOptions);
+    /**
+     * Bootstrap: authenticate and hydrate in-memory state from cloud.
+     *
+     * Resolves config from: constructor args → env vars → ~/.bandito/config.toml.
+     * Initializes WASM, creates HTTP client, SQLite store, fetches full state.
+     */
+    connect(): Promise<void>;
+    /**
+     * Local Thompson Sampling decision. Synchronous, <1ms, no network.
+     */
+    pull(banditName: string, options?: PullOptions): PullResult;
+    /**
+     * Record an LLM call outcome. Writes to SQLite first (crash-safe),
+     * then fires off a non-blocking flush to cloud.
+     */
+    update(pullResult: PullResult, options?: UpdateOptions): void;
+    /**
+     * Send a human grade for an existing event. Async (HTTP).
+     */
+    grade(eventId: string, grade: number): Promise<void>;
+    /**
+     * Explicit state refresh from cloud.
+     */
+    sync(): Promise<void>;
+    /**
+     * Shut down: clear interval, flush remaining events, close connections.
+     */
+    close(): Promise<void>;
+    private ensureConnected;
+    private applySync;
+    private flushPending;
+}
+
+/**
+ * Bandito SDK — contextual bandit optimization for LLM selection.
+ *
+ * Recommended (explicit client):
+ *   import { BanditoClient } from 'bandito';
+ *
+ *   const client = new BanditoClient({ apiKey: 'bnd_...' });
+ *   await client.connect();
+ *   const result = client.pull('my-chatbot', { query: userMessage });
+ *   // ... call LLM with result.model, result.prompt ...
+ *   client.update(result, { response: response.text });
+ *   await client.close();
+ *
+ * Module-level singleton (convenience):
+ *   import { connect, pull, update, close } from 'bandito';
+ *
+ *   await connect({ apiKey: 'bnd_...' });
+ *   const result = pull('my-chatbot', { query: userMessage });
+ *   update(result, { response: response.text });
+ *   await close();
+ */
+
+/** Connect to the Bandito cloud and hydrate local state. */
+declare function connect(options?: ClientOptions): Promise<void>;
+/** Local Thompson Sampling decision. <1ms, no network. */
+declare function pull(banditName: string, options?: PullOptions): PullResult;
+/** Record an LLM call outcome (writes to SQLite, fire-and-forget flush). */
+declare function update(pullResult: PullResult, options?: UpdateOptions): void;
+/** Send a human grade for an existing event. */
+declare function grade(eventId: string, gradeValue: number): Promise<void>;
+/** Explicit state refresh from cloud. */
+declare function sync(): Promise<void>;
+/** Shut down: flush events, close connections. */
+declare function close(): Promise<void>;
+
+export { type Arm, BanditoClient, type ClientOptions, type PullOptions, type PullResult, type UpdateOptions, close, connect, grade, pull, sync, update };

package/dist/index.d.ts

@@ -0,0 +1,145 @@
+/**
+ * SDK types: Arm, PullResult, and internal cache structures.
+ */
+/** An arm returned to the user after pull(). Immutable. */
+interface Arm {
+    readonly armId: number;
+    readonly modelName: string;
+    readonly modelProvider: string;
+    readonly systemPrompt: string;
+    readonly isPromptTemplated: boolean;
+    /** Convenience alias for modelName. */
+    readonly model: string;
+    /** Convenience alias for systemPrompt. */
+    readonly prompt: string;
+}
+/** Returned by pull(), passed to update(). Immutable. */
+interface PullResult {
+    readonly arm: Arm;
+    readonly eventId: string;
+    readonly banditId: number;
+    readonly banditName: string;
+    readonly scores: Readonly<Record<number, number>>;
+    /** Convenience reach-through to arm.modelName. */
+    readonly model: string;
+    /** Convenience reach-through to arm.systemPrompt. */
+    readonly prompt: string;
+    /** @internal perf timestamp */
+    readonly _pullTime: number;
+}
+
+/**
+ * BanditoClient — main orchestrator for the JS/TS SDK.
+ *
+ * Mirrors the Python SDK's sync-first design:
+ * - pull() is synchronous (WASM math, <1ms)
+ * - connect(), grade(), sync(), close() are async (HTTP I/O)
+ * - update() is synchronous (SQLite write + fire-and-forget flush)
+ */
+
+interface ClientOptions {
+    apiKey?: string;
+    baseUrl?: string;
+    storePath?: string;
+    dataStorage?: string;
+}
+interface PullOptions {
+    query?: string;
+    exclude?: number[];
+}
+interface UpdateOptions {
+    queryText?: string;
+    response?: string | Record<string, unknown>;
+    reward?: number;
+    cost?: number;
+    latency?: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    segment?: Record<string, string>;
+    failed?: boolean;
+}
+declare class BanditoClient {
+    private apiKey;
+    private baseUrl;
+    private storePath;
+    private dataStorageArg;
+    private dataStorage;
+    private http;
+    private store;
+    private engines;
+    private bandits;
+    private connected;
+    private flushInterval;
+    private flushInProgress;
+    private deadUuids;
+    private retryCounts;
+    constructor(options?: ClientOptions);
+    /**
+     * Bootstrap: authenticate and hydrate in-memory state from cloud.
+     *
+     * Resolves config from: constructor args → env vars → ~/.bandito/config.toml.
+     * Initializes WASM, creates HTTP client, SQLite store, fetches full state.
+     */
+    connect(): Promise<void>;
+    /**
+     * Local Thompson Sampling decision. Synchronous, <1ms, no network.
+     */
+    pull(banditName: string, options?: PullOptions): PullResult;
+    /**
+     * Record an LLM call outcome. Writes to SQLite first (crash-safe),
+     * then fires off a non-blocking flush to cloud.
+     */
+    update(pullResult: PullResult, options?: UpdateOptions): void;
+    /**
+     * Send a human grade for an existing event. Async (HTTP).
+     */
+    grade(eventId: string, grade: number): Promise<void>;
+    /**
+     * Explicit state refresh from cloud.
+     */
+    sync(): Promise<void>;
+    /**
+     * Shut down: clear interval, flush remaining events, close connections.
+     */
+    close(): Promise<void>;
+    private ensureConnected;
+    private applySync;
+    private flushPending;
+}
+
+/**
+ * Bandito SDK — contextual bandit optimization for LLM selection.
+ *
+ * Recommended (explicit client):
+ *   import { BanditoClient } from 'bandito';
+ *
+ *   const client = new BanditoClient({ apiKey: 'bnd_...' });
+ *   await client.connect();
+ *   const result = client.pull('my-chatbot', { query: userMessage });
+ *   // ... call LLM with result.model, result.prompt ...
+ *   client.update(result, { response: response.text });
+ *   await client.close();
+ *
+ * Module-level singleton (convenience):
+ *   import { connect, pull, update, close } from 'bandito';
+ *
+ *   await connect({ apiKey: 'bnd_...' });
+ *   const result = pull('my-chatbot', { query: userMessage });
+ *   update(result, { response: response.text });
+ *   await close();
+ */
+
+/** Connect to the Bandito cloud and hydrate local state. */
+declare function connect(options?: ClientOptions): Promise<void>;
+/** Local Thompson Sampling decision. <1ms, no network. */
+declare function pull(banditName: string, options?: PullOptions): PullResult;
+/** Record an LLM call outcome (writes to SQLite, fire-and-forget flush). */
+declare function update(pullResult: PullResult, options?: UpdateOptions): void;
+/** Send a human grade for an existing event. */
+declare function grade(eventId: string, gradeValue: number): Promise<void>;
+/** Explicit state refresh from cloud. */
+declare function sync(): Promise<void>;
+/** Shut down: flush events, close connections. */
+declare function close(): Promise<void>;
+
+export { type Arm, BanditoClient, type ClientOptions, type PullOptions, type PullResult, type UpdateOptions, close, connect, grade, pull, sync, update };