@bandito-ai/sdk 0.1.7

package/dist/index.js

@@ -0,0 +1,640 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  BanditoClient: () => BanditoClient,
+  close: () => close,
+  connect: () => connect,
+  grade: () => grade,
+  pull: () => pull,
+  sync: () => sync,
+  update: () => update
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client.ts
+var import_node_crypto = require("crypto");
+var fs2 = __toESM(require("fs"));
+var path2 = __toESM(require("path"));
+var os2 = __toESM(require("os"));
+var import_node_perf_hooks = require("perf_hooks");
+
+// src/engine.ts
+var wasmModule = null;
+async function initWasm() {
+  if (wasmModule) return;
+  wasmModule = await import("../wasm/bandito_engine");
+}
+function createEngine(banditJson) {
+  if (!wasmModule) {
+    throw new Error("WASM not initialized \u2014 call initWasm() first");
+  }
+  return new wasmModule.BanditEngine(banditJson);
+}
+function updateEngine(engine, banditJson) {
+  engine.updateFromSync(banditJson);
+}
+
+// src/models.ts
+function createArm(data) {
+  const arm = {
+    armId: data.arm_id,
+    modelName: data.model_name,
+    modelProvider: data.model_provider,
+    systemPrompt: data.system_prompt,
+    isPromptTemplated: data.is_prompt_templated ?? false,
+    get model() {
+      return this.modelName;
+    },
+    get prompt() {
+      return this.systemPrompt;
+    }
+  };
+  return Object.freeze(arm);
+}
+function createPullResult(data) {
+  const result = {
+    arm: data.arm,
+    eventId: data.eventId,
+    banditId: data.banditId,
+    banditName: data.banditName,
+    scores: Object.freeze({ ...data.scores }),
+    get model() {
+      return this.arm.modelName;
+    },
+    get prompt() {
+      return this.arm.systemPrompt;
+    },
+    _pullTime: data.pullTime
+  };
+  return Object.freeze(result);
+}
+
+// src/config.ts
+var fs = __toESM(require("fs"));
+var path = __toESM(require("path"));
+var os = __toESM(require("os"));
+var import_smol_toml = require("smol-toml");
+var DEFAULT_BASE_URL = "https://bandito-api.onrender.com";
+var CONFIG_DIR = path.join(os.homedir(), ".bandito");
+var CONFIG_FILE = path.join(CONFIG_DIR, "config.toml");
+function loadConfig() {
+  const config = {
+    apiKey: null,
+    baseUrl: DEFAULT_BASE_URL,
+    dataStorage: "local"
+  };
+  if (fs.existsSync(CONFIG_FILE)) {
+    try {
+      const content = fs.readFileSync(CONFIG_FILE, "utf-8");
+      const data = (0, import_smol_toml.parse)(content);
+      if (data.api_key) config.apiKey = data.api_key;
+      if (data.base_url) config.baseUrl = data.base_url;
+      if (data.data_storage) config.dataStorage = data.data_storage;
+    } catch {
+    }
+  }
+  const envKey = process.env.BANDITO_API_KEY;
+  if (envKey) config.apiKey = envKey;
+  const envUrl = process.env.BANDITO_BASE_URL;
+  if (envUrl) config.baseUrl = envUrl;
+  const envStorage = process.env.BANDITO_DATA_STORAGE;
+  if (envStorage) config.dataStorage = envStorage;
+  return config;
+}
+
+// src/http.ts
+var MAX_RETRIES = 3;
+var RETRY_BACKOFF_BASE = 500;
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isRetryable(status) {
+  return status >= 500;
+}
+var BanditoHTTP = class {
+  baseUrl;
+  apiKey;
+  timeout;
+  constructor(baseUrl, apiKey, timeout = 1e4) {
+    this.baseUrl = `${baseUrl.replace(/\/$/, "")}/api/v1`;
+    this.apiKey = apiKey;
+    this.timeout = timeout;
+  }
+  async request(method, path3, body) {
+    let lastError = null;
+    for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this.timeout);
+      try {
+        const resp = await fetch(`${this.baseUrl}${path3}`, {
+          method,
+          headers: {
+            "X-API-Key": this.apiKey,
+            "Content-Type": "application/json"
+          },
+          body: body != null ? JSON.stringify(body) : void 0,
+          signal: controller.signal
+        });
+        clearTimeout(timer);
+        if (!resp.ok) {
+          const text = await resp.text().catch(() => "");
+          if (!isRetryable(resp.status) || attempt === MAX_RETRIES - 1) {
+            throw new Error(
+              `HTTP ${resp.status} on ${method} ${path3}: ${text}`
+            );
+          }
+          lastError = new Error(
+            `HTTP ${resp.status} on ${method} ${path3}: ${text}`
+          );
+        } else {
+          return await resp.json();
+        }
+      } catch (err) {
+        clearTimeout(timer);
+        lastError = err;
+        const isNetworkOrTimeout = err.name === "AbortError" || err.name === "TypeError";
+        if (!isNetworkOrTimeout && attempt < MAX_RETRIES - 1) {
+          throw err;
+        }
+        if (attempt === MAX_RETRIES - 1) {
+          throw err;
+        }
+      }
+      const delay = RETRY_BACKOFF_BASE * 2 ** attempt;
+      await sleep(delay);
+    }
+    throw lastError;
+  }
+  /** POST /sync/connect — SDK bootstrap. */
+  async connect() {
+    return this.request("POST", "/sync/connect");
+  }
+  /** POST /sync/heartbeat — periodic state refresh. */
+  async heartbeat() {
+    return this.request("POST", "/sync/heartbeat", {});
+  }
+  /** POST /events — batch event ingestion. */
+  async ingestEvents(events) {
+    return this.request("POST", "/events", { events });
+  }
+  /** PATCH /events/{uuid}/grade — submit human grade. */
+  async submitGrade(eventUuid, grade2) {
+    return this.request("PATCH", `/events/${eventUuid}/grade`, {
+      grade: grade2,
+      is_graded: true
+    });
+  }
+};
+
+// src/store.ts
+var import_better_sqlite3 = __toESM(require("better-sqlite3"));
+var SCHEMA = `
+CREATE TABLE IF NOT EXISTS events (
+    local_event_uuid TEXT PRIMARY KEY,
+    bandit_id        INTEGER NOT NULL,
+    arm_id           INTEGER NOT NULL,
+    payload          TEXT NOT NULL,
+    status           TEXT NOT NULL DEFAULT 'pending',
+    created_at       REAL NOT NULL,
+    human_reward     REAL,
+    graded_at        REAL
+);
+CREATE INDEX IF NOT EXISTS idx_events_status ON events(status);
+`;
+var MIGRATION_GRADING = [
+  "ALTER TABLE events ADD COLUMN human_reward REAL",
+  "ALTER TABLE events ADD COLUMN graded_at REAL"
+];
+var EventStore = class {
+  db;
+  pushStmt;
+  pendingStmt;
+  constructor(dbPath = ":memory:") {
+    this.db = new import_better_sqlite3.default(dbPath);
+    this.db.pragma("journal_mode = WAL");
+    this.db.pragma("busy_timeout = 5000");
+    this.db.pragma("synchronous = NORMAL");
+    this.db.exec(SCHEMA);
+    this.migrate();
+    this.pushStmt = this.db.prepare(
+      `INSERT OR IGNORE INTO events
+       (local_event_uuid, bandit_id, arm_id, payload, status, created_at)
+       VALUES (?, ?, ?, ?, 'pending', ?)`
+    );
+    this.pendingStmt = this.db.prepare(
+      `SELECT payload FROM events WHERE status = 'pending'
+       ORDER BY created_at ASC LIMIT ?`
+    );
+  }
+  /** Insert a pending event. */
+  push(event) {
+    this.pushStmt.run(
+      event.local_event_uuid,
+      event.bandit_id,
+      event.arm_id,
+      JSON.stringify(event),
+      Date.now() / 1e3
+    );
+  }
+  /** Return up to `limit` pending events (oldest first). */
+  pending(limit = 50) {
+    const rows = this.pendingStmt.all(limit);
+    return rows.map((row) => JSON.parse(row.payload));
+  }
+  /** Mark events as successfully flushed to cloud. */
+  markFlushed(uuids) {
+    if (uuids.length === 0) return;
+    const placeholders = uuids.map(() => "?").join(",");
+    this.db.prepare(
+      `UPDATE events SET status = 'flushed'
+         WHERE local_event_uuid IN (${placeholders})`
+    ).run(...uuids);
+  }
+  /** Record a human grade locally. */
+  markGraded(uuid, reward) {
+    this.db.prepare(
+      `UPDATE events SET human_reward = ?, graded_at = ?
+         WHERE local_event_uuid = ?`
+    ).run(reward, Date.now() / 1e3, uuid);
+  }
+  /** Close the database connection. */
+  close() {
+    this.db.close();
+  }
+  migrate() {
+    for (const stmt of MIGRATION_GRADING) {
+      try {
+        this.db.exec(stmt);
+      } catch {
+      }
+    }
+  }
+};
+
+// src/worker.ts
+var TEXT_FIELDS = ["query_text", "response"];
+var METADATA_FIELDS = ["model_name", "model_provider"];
+function prepareCloudPayload(events, includeText) {
+  return events.map((event) => {
+    const copy = { ...event };
+    for (const field of METADATA_FIELDS) {
+      delete copy[field];
+    }
+    if (!includeText) {
+      for (const field of TEXT_FIELDS) {
+        delete copy[field];
+      }
+    }
+    return copy;
+  });
+}
+
+// src/client.ts
+var DEFAULT_STORE_PATH = path2.join(os2.homedir(), ".bandito", "events.db");
+var MAX_EVENT_RETRIES = 5;
+var BanditoClient = class {
+  apiKey;
+  baseUrl;
+  storePath;
+  dataStorageArg;
+  dataStorage;
+  http = null;
+  store = null;
+  engines = /* @__PURE__ */ new Map();
+  bandits = /* @__PURE__ */ new Map();
+  connected = false;
+  flushInterval = null;
+  flushInProgress = false;
+  deadUuids = /* @__PURE__ */ new Set();
+  retryCounts = /* @__PURE__ */ new Map();
+  constructor(options = {}) {
+    this.apiKey = options.apiKey;
+    this.baseUrl = options.baseUrl;
+    this.storePath = options.storePath;
+    this.dataStorageArg = options.dataStorage;
+    this.dataStorage = options.dataStorage ?? "local";
+  }
+  /**
+   * 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.
+   */
+  async connect() {
+    if (this.connected) {
+      await this.close();
+    }
+    await initWasm();
+    const config = loadConfig();
+    const apiKey = this.apiKey ?? config.apiKey;
+    if (!apiKey) {
+      throw new Error(
+        "apiKey required \u2014 pass it to constructor, set BANDITO_API_KEY, or run `bandito signup`"
+      );
+    }
+    const baseUrl = this.baseUrl ?? config.baseUrl;
+    if (!this.dataStorageArg) {
+      this.dataStorage = config.dataStorage;
+    }
+    this.http = new BanditoHTTP(baseUrl, apiKey);
+    const storePath = this.storePath ?? DEFAULT_STORE_PATH;
+    if (storePath !== ":memory:") {
+      const dir = path2.dirname(storePath);
+      if (!fs2.existsSync(dir)) {
+        fs2.mkdirSync(dir, { recursive: true });
+      }
+    }
+    this.store = new EventStore(storePath);
+    try {
+      const data = await this.http.connect();
+      this.applySync(data);
+      this.deadUuids.clear();
+      this.retryCounts.clear();
+      await this.flushPending();
+      this.flushInterval = setInterval(() => {
+        this.flushPending().catch(() => {
+        });
+      }, 3e4);
+      this.connected = true;
+    } catch (err) {
+      this.store?.close();
+      this.store = null;
+      this.http = null;
+      throw err;
+    }
+  }
+  /**
+   * Local Thompson Sampling decision. Synchronous, <1ms, no network.
+   */
+  pull(banditName, options = {}) {
+    this.ensureConnected();
+    const cache = this.bandits.get(banditName);
+    if (!cache) {
+      const available = [...this.bandits.keys()];
+      throw new Error(
+        `Unknown bandit '${banditName}'. Available: [${available.join(", ")}]`
+      );
+    }
+    if (cache.arms.length === 0) {
+      throw new Error(`Bandit '${banditName}' has no active arms`);
+    }
+    const engine = this.engines.get(banditName);
+    const queryLength = options.query?.length ?? void 0;
+    const excludeIds = options.exclude ? Int32Array.from(options.exclude) : void 0;
+    const resultJson = engine.pull(queryLength, excludeIds);
+    const raw = JSON.parse(resultJson);
+    const winnerArm = cache.arms.find((a) => a.armId === raw.arm_id);
+    if (!winnerArm) {
+      throw new Error(
+        `Engine selected arm ${raw.arm_id} but it's not in active arm cache for "${banditName}". This is likely a bug \u2014 please report it at https://github.com/bandito-ai/bandito/issues`
+      );
+    }
+    return createPullResult({
+      arm: winnerArm,
+      eventId: (0, import_node_crypto.randomUUID)(),
+      banditId: cache.banditId,
+      banditName,
+      scores: raw.scores,
+      pullTime: import_node_perf_hooks.performance.now()
+    });
+  }
+  /**
+   * Record an LLM call outcome. Writes to SQLite first (crash-safe),
+   * then fires off a non-blocking flush to cloud.
+   */
+  update(pullResult, options = {}) {
+    this.ensureConnected();
+    let reward = options.reward;
+    if (options.failed && reward == null) {
+      reward = 0;
+    }
+    let latency = options.latency;
+    if (latency == null && pullResult._pullTime > 0) {
+      latency = import_node_perf_hooks.performance.now() - pullResult._pullTime;
+    }
+    const event = {
+      local_event_uuid: pullResult.eventId,
+      bandit_id: pullResult.banditId,
+      arm_id: pullResult.arm.armId,
+      model_name: pullResult.arm.modelName,
+      model_provider: pullResult.arm.modelProvider
+    };
+    if (options.queryText != null) {
+      event.query_text = options.queryText;
+    }
+    if (options.response != null) {
+      event.response = typeof options.response === "string" ? { response: options.response } : options.response;
+    }
+    if (reward != null) {
+      event.early_reward = reward;
+    }
+    if (options.cost != null) {
+      event.cost = options.cost;
+    }
+    if (latency != null) {
+      event.latency = latency;
+    }
+    if (options.inputTokens != null) {
+      event.input_tokens = options.inputTokens;
+    }
+    if (options.outputTokens != null) {
+      event.output_tokens = options.outputTokens;
+    }
+    if (options.segment != null) {
+      event.segment = options.segment;
+    }
+    if (options.failed) {
+      event.run_error = true;
+    }
+    this.store.push(event);
+    this.flushPending().catch(() => {
+    });
+  }
+  /**
+   * Send a human grade for an existing event. Async (HTTP).
+   */
+  async grade(eventId, grade2) {
+    this.ensureConnected();
+    await this.http.submitGrade(eventId, grade2);
+  }
+  /**
+   * Explicit state refresh from cloud.
+   */
+  async sync() {
+    this.ensureConnected();
+    const data = await this.http.heartbeat();
+    const prevBandits = new Map(this.bandits);
+    const prevEngines = new Map(this.engines);
+    try {
+      this.applySync(data);
+    } catch (err) {
+      this.bandits = prevBandits;
+      this.engines = prevEngines;
+      console.warn("[bandito] Sync response malformed \u2014 keeping last-known-good state", err);
+    }
+  }
+  /**
+   * Shut down: clear interval, flush remaining events, close connections.
+   */
+  async close() {
+    if (this.flushInterval) {
+      clearInterval(this.flushInterval);
+      this.flushInterval = null;
+    }
+    if (this.store && this.http) {
+      await this.flushPending();
+    }
+    this.store?.close();
+    this.store = null;
+    this.http = null;
+    this.engines.clear();
+    this.bandits.clear();
+    this.connected = false;
+  }
+  // --- Internal ---
+  ensureConnected() {
+    if (!this.connected) {
+      throw new Error("Not connected \u2014 call connect() first");
+    }
+  }
+  applySync(data) {
+    const banditsData = data.bandits ?? [];
+    const newBandits = /* @__PURE__ */ new Map();
+    const newEngines = /* @__PURE__ */ new Map();
+    for (const b of banditsData) {
+      const arms = b.arms ?? [];
+      if (arms.length === 0) continue;
+      const activeArms = arms.filter((a) => a.is_active).map((a) => createArm(a));
+      const name = b.name;
+      const cache = {
+        banditId: Number(b.bandit_id),
+        name,
+        arms: activeArms,
+        armWire: arms,
+        optimizationMode: b.optimization_mode ?? "base",
+        avgLatencyLastN: b.avg_latency_last_n,
+        budget: b.budget,
+        totalCost: b.total_cost
+      };
+      newBandits.set(name, cache);
+      const existingEngine = this.engines.get(name);
+      const banditJson = JSON.stringify(b);
+      if (existingEngine) {
+        updateEngine(existingEngine, banditJson);
+        newEngines.set(name, existingEngine);
+      } else {
+        newEngines.set(name, createEngine(banditJson));
+      }
+    }
+    this.bandits = newBandits;
+    this.engines = newEngines;
+  }
+  async flushPending() {
+    if (this.flushInProgress || !this.store || !this.http) return;
+    this.flushInProgress = true;
+    try {
+      const pending = this.store.pending();
+      if (pending.length === 0) return;
+      const alive = this.deadUuids.size > 0 ? pending.filter((e) => !this.deadUuids.has(e.local_event_uuid)) : pending;
+      if (alive.length === 0) return;
+      const payload = prepareCloudPayload(
+        alive,
+        this.dataStorage !== "local"
+      );
+      const result = await this.http.ingestEvents(payload);
+      const errors = result.errors ?? [];
+      const erroredUuids = new Set(
+        errors.map((e) => e.local_event_uuid).filter(Boolean)
+      );
+      for (const uid of erroredUuids) {
+        const count = (this.retryCounts.get(uid) ?? 0) + 1;
+        this.retryCounts.set(uid, count);
+        if (count >= MAX_EVENT_RETRIES) {
+          this.deadUuids.add(uid);
+        }
+      }
+      const flushedUuids = alive.map((e) => e.local_event_uuid).filter((uid) => !erroredUuids.has(uid));
+      if (flushedUuids.length > 0 && this.store) {
+        this.store.markFlushed(flushedUuids);
+      }
+    } catch (err) {
+      console.warn("[bandito] Event flush failed \u2014 will retry", err);
+    } finally {
+      this.flushInProgress = false;
+    }
+  }
+};
+
+// src/index.ts
+var _client = null;
+function getClient() {
+  if (!_client) {
+    throw new Error("Not connected \u2014 call connect() first");
+  }
+  return _client;
+}
+async function connect(options = {}) {
+  if (_client) {
+    await _client.close();
+  }
+  _client = new BanditoClient(options);
+  await _client.connect();
+}
+function pull(banditName, options) {
+  return getClient().pull(banditName, options);
+}
+function update(pullResult, options) {
+  getClient().update(pullResult, options);
+}
+async function grade(eventId, gradeValue) {
+  await getClient().grade(eventId, gradeValue);
+}
+async function sync() {
+  await getClient().sync();
+}
+async function close() {
+  if (_client) {
+    await _client.close();
+    _client = null;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BanditoClient,
+  close,
+  connect,
+  grade,
+  pull,
+  sync,
+  update
+});
+//# sourceMappingURL=index.js.map