boids-sdk 0.1.1

package/README.md

@@ -0,0 +1,74 @@
+# boids-sdk
+
+JavaScript SDK and CLI for the Boids API.
+
+## Install
+
+```bash
+npm install boids-sdk
+export BOIDS_API_KEY="..."
+```
+
+## CLI
+
+```bash
+boids agent:@iris-wei-org/my-doppelganger "Introduce yourself in one sentence."
+boids search "global launch growth agent" --limit 5
+boids run "Create a launch plan for a developer tool."
+boids agent:@iris-wei-org/my-doppelganger "Remember my name is Ada." --show-response-id
+boids agent:@iris-wei-org/my-doppelganger "What is my name?" --prev resp_...
+```
+
+`boids run` searches `/v1/market/search`, selects the first returned agent, and
+then sends your prompt to `/v1/responses`.
+
+## SDK
+
+```js
+import { Boids } from "boids-sdk";
+
+const client = new Boids();
+
+const response = await client.responses.create({
+  model: "agent:@iris-wei-org/my-doppelganger",
+  input: "Introduce yourself in one sentence.",
+});
+console.log(response);
+```
+
+Streaming:
+
+```js
+for await (const event of client.responses.create({
+  model: "agent:@iris-wei-org/my-doppelganger",
+  input: "Introduce yourself in one sentence.",
+  stream: true,
+})) {
+  console.log(event.data);
+}
+```
+
+Market search:
+
+```js
+const agents = await client.market.search({
+  query: "global launch growth agent",
+  limit: 5,
+});
+console.log(agents.data.items[0].model_name);
+```
+
+Conversation context:
+
+```js
+const first = await client.responses.create({
+  model: "agent:@iris-wei-org/my-doppelganger",
+  input: "Remember my name is Ada.",
+});
+
+const second = await client.responses.create({
+  model: "agent:@iris-wei-org/my-doppelganger",
+  input: "What is my name?",
+  previous_response_id: first.id,
+});
+```

package/bin/boids.js

@@ -0,0 +1,433 @@
+#!/usr/bin/env node
+import { Boids, DEFAULT_BASE_URL, extractText } from "../src/index.js";
+
+const env = process.env;
+
+async function main(argv) {
+  if (looksLikeShortcut(argv)) {
+    return runShortcut(argv);
+  }
+
+  const command = argv.shift();
+
+  if (!command || command === "-h" || command === "--help") {
+    usage();
+    return 0;
+  }
+
+  if (command === "ask") {
+    const options = parseOptions(argv);
+    const model = requireModel(options.model);
+    const input = options._.join(" ");
+    if (!input) {
+      throw new Error("Missing input text.");
+    }
+
+    const client = makeClient(options);
+    const result = client.responses.create({
+      model,
+      input,
+      stream: options.stream ?? true,
+      previous_response_id: options.previousResponseId,
+    });
+    await printResult(result, Boolean(options.json), {
+      showResponseId: Boolean(options.showResponseId),
+    });
+    return 0;
+  }
+
+  if (command === "search") {
+    const options = parseOptions(argv, { envModel: false });
+    const query = options.query ?? options._.join(" ");
+    if (!query) {
+      throw new Error("Missing search query.");
+    }
+
+    const client = makeClient(options);
+    const result = await client.market.search({
+      query,
+      limit: Number(options.limit ?? 5),
+    });
+    printSearchResult(result, Boolean(options.json));
+    return 0;
+  }
+
+  if (command === "run" || command === "auto") {
+    const options = parseOptions(argv, { envModel: false });
+    const input = options.input ?? options._.join(" ");
+    if (!input) {
+      throw new Error("Missing input text.");
+    }
+
+    const client = makeClient(options);
+    const result = await runWithBestAgent(client, {
+      input,
+      searchQuery: options.searchQuery ?? input,
+      limit: Number(options.limit ?? 1),
+      stream: options.stream ?? true,
+      previousResponseId: options.previousResponseId,
+      showAgent: !options.quietAgent && !options.json,
+    });
+    await printResult(result, Boolean(options.json), {
+      showResponseId: Boolean(options.showResponseId),
+    });
+    return 0;
+  }
+
+  if (command === "responses" && argv[0] === "create") {
+    argv.shift();
+    const options = parseOptions(argv);
+    const model = requireModel(options.model);
+    const input = options.input ?? options._.join(" ");
+    if (!input) {
+      throw new Error("Missing --input or input text.");
+    }
+
+    const client = makeClient(options);
+    const result = client.responses.create({
+      model,
+      input,
+      stream: Boolean(options.stream),
+      previous_response_id: options.previousResponseId,
+    });
+    await printResult(result, Boolean(options.json), {
+      showResponseId: Boolean(options.showResponseId),
+    });
+    return 0;
+  }
+
+  throw new Error(`Unknown command: ${command}`);
+}
+
+async function runShortcut(argv) {
+  const options = parseOptions(argv, { envModel: false });
+  const model = options.model ?? options._.shift();
+  const input = options.input ?? options._.join(" ");
+
+  if (!model) {
+    throw new Error("Missing agent model.");
+  }
+  if (!input) {
+    throw new Error("Missing input text.");
+  }
+
+  const client = makeClient(options);
+  const result = client.responses.create({
+    model,
+    input,
+    stream: options.stream ?? true,
+    previous_response_id: options.previousResponseId,
+  });
+  await printResult(result, Boolean(options.json), {
+    showResponseId: Boolean(options.showResponseId),
+  });
+  return 0;
+}
+
+function makeClient(options) {
+  return new Boids({
+    apiKey: options.apiKey ?? env.BOIDS_API_KEY,
+    baseURL: options.baseUrl ?? DEFAULT_BASE_URL,
+  });
+}
+
+async function runWithBestAgent(client, options) {
+  const searchResult = await client.market.search({
+    query: options.searchQuery,
+    limit: options.limit,
+  });
+  const item = marketItems(searchResult)[0];
+  if (!item) {
+    throw new Error(`No agents found for: ${options.searchQuery}`);
+  }
+
+  const model = agentModel(item);
+  if (!model) {
+    throw new Error("Best market result did not include a usable model.");
+  }
+
+  if (options.showAgent) {
+    const title = item.title ?? item.id ?? model;
+    console.error(`Selected agent: ${title} (${model})`);
+  }
+
+  return client.responses.create({
+    model,
+    input: options.input,
+    stream: options.stream,
+    previous_response_id: options.previousResponseId,
+  });
+}
+
+function printSearchResult(result, asJSON) {
+  if (asJSON) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  const items = marketItems(result);
+  if (items.length === 0) {
+    console.log("No agents found.");
+    return;
+  }
+
+  items.forEach((item, index) => {
+    const title = item.title ?? item.id ?? "Untitled agent";
+    const model = agentModel(item) ?? "unknown";
+    console.log(`${index + 1}. ${title}`);
+    console.log(`   model: ${model}`);
+    if (item.description) {
+      console.log(`   ${item.description}`);
+    }
+  });
+}
+
+function marketItems(result) {
+  const items = result?.data?.items;
+  return Array.isArray(items) ? items.filter((item) => item && typeof item === "object") : [];
+}
+
+function agentModel(item) {
+  if (typeof item.model_name === "string" && item.model_name.startsWith("agent:")) {
+    return item.model_name;
+  }
+
+  const agentId = item.agent_id ?? item.id;
+  if (typeof agentId === "string" && agentId) {
+    return `agent:${agentId}`;
+  }
+
+  if (typeof item.model_name === "string" && item.model_name) {
+    return item.model_name;
+  }
+
+  return undefined;
+}
+
+async function printResult(result, asJSON, { showResponseId = false } = {}) {
+  if (isAsyncIterable(result)) {
+    let wroteText = false;
+    let fallbackText;
+    let responseId;
+
+    for await (const event of result) {
+      if (event.event?.endsWith(".completed")) {
+        fallbackText = extractText(event.data);
+        responseId = extractResponseId(event.data);
+      }
+
+      if (asJSON) {
+        console.log(JSON.stringify(event));
+        continue;
+      }
+
+      const delta = extractDelta(event.data);
+      if (delta !== undefined) {
+        process.stdout.write(delta);
+        wroteText = true;
+        continue;
+      }
+
+    }
+
+    if (wroteText) {
+      process.stdout.write("\n");
+    } else if (fallbackText) {
+      console.log(fallbackText);
+    }
+    if (showResponseId && responseId) {
+      console.error(`Response ID: ${responseId}`);
+    }
+    return;
+  }
+
+  const value = await result;
+  if (asJSON) {
+    console.log(JSON.stringify(value, null, 2));
+    if (showResponseId) {
+      printResponseId(value);
+    }
+    return;
+  }
+
+  const text = extractText(value);
+  console.log(text ?? JSON.stringify(value, null, 2));
+  if (showResponseId) {
+    printResponseId(value);
+  }
+}
+
+function parseOptions(args, { envModel = true } = {}) {
+  const options = { _: [] };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (arg === "--stream") {
+      options.stream = true;
+    } else if (arg === "--no-stream") {
+      options.stream = false;
+    } else if (arg === "--json") {
+      options.json = true;
+    } else if (arg === "--show-response-id") {
+      options.showResponseId = true;
+    } else if (arg === "--quiet-agent") {
+      options.quietAgent = true;
+    } else if (arg === "--show-agent") {
+      options.quietAgent = false;
+    } else if (arg === "-m" || arg === "--model") {
+      options.model = args[++index];
+    } else if (arg === "-i" || arg === "--input") {
+      options.input = args[++index];
+    } else if (arg === "-q" || arg === "--query") {
+      options.query = args[++index];
+    } else if (arg === "--search-query") {
+      options.searchQuery = args[++index];
+    } else if (arg === "--limit") {
+      options.limit = args[++index];
+    } else if (arg === "--previous-response-id" || arg === "--prev") {
+      options.previousResponseId = args[++index];
+    } else if (arg === "--api-key") {
+      options.apiKey = args[++index];
+    } else if (arg === "--base-url") {
+      options.baseUrl = args[++index];
+    } else if (arg.startsWith("--model=")) {
+      options.model = arg.slice("--model=".length);
+    } else if (arg.startsWith("--input=")) {
+      options.input = arg.slice("--input=".length);
+    } else if (arg.startsWith("--query=")) {
+      options.query = arg.slice("--query=".length);
+    } else if (arg.startsWith("--search-query=")) {
+      options.searchQuery = arg.slice("--search-query=".length);
+    } else if (arg.startsWith("--limit=")) {
+      options.limit = arg.slice("--limit=".length);
+    } else if (arg.startsWith("--previous-response-id=")) {
+      options.previousResponseId = arg.slice("--previous-response-id=".length);
+    } else if (arg.startsWith("--prev=")) {
+      options.previousResponseId = arg.slice("--prev=".length);
+    } else if (arg.startsWith("--api-key=")) {
+      options.apiKey = arg.slice("--api-key=".length);
+    } else if (arg.startsWith("--base-url=")) {
+      options.baseUrl = arg.slice("--base-url=".length);
+    } else {
+      options._.push(arg);
+    }
+  }
+
+  if (envModel) {
+    options.model ??= env.BOIDS_MODEL;
+  }
+  return options;
+}
+
+function requireModel(model) {
+  if (model) {
+    return model;
+  }
+  throw new Error("Missing --model or BOIDS_MODEL.");
+}
+
+function isAsyncIterable(value) {
+  return value && typeof value[Symbol.asyncIterator] === "function";
+}
+
+function extractDelta(value) {
+  if (value && typeof value === "object" && typeof value.delta === "string") {
+    return value.delta;
+  }
+  return undefined;
+}
+
+function extractResponseId(value) {
+  if (value && typeof value === "object" && typeof value.id === "string") {
+    return value.id;
+  }
+  return undefined;
+}
+
+function printResponseId(value) {
+  const responseId = extractResponseId(value);
+  if (responseId) {
+    console.error(`Response ID: ${responseId}`);
+  }
+}
+
+function looksLikeShortcut(args) {
+  const first = firstPositional(args);
+  return first !== undefined && !["ask", "responses", "search", "run", "auto"].includes(first);
+}
+
+function firstPositional(args) {
+  let skipNext = false;
+  const optionsWithValues = new Set([
+    "--api-key",
+    "--base-url",
+    "--model",
+    "-m",
+    "--input",
+    "-i",
+    "--query",
+    "-q",
+    "--search-query",
+    "--limit",
+    "--previous-response-id",
+    "--prev",
+  ]);
+
+  for (const arg of args) {
+    if (skipNext) {
+      skipNext = false;
+      continue;
+    }
+
+    if (optionsWithValues.has(arg)) {
+      skipNext = true;
+      continue;
+    }
+
+    if (
+      arg.startsWith("--api-key=") ||
+      arg.startsWith("--base-url=") ||
+      arg.startsWith("--model=") ||
+      arg.startsWith("--input=") ||
+      arg.startsWith("--query=") ||
+      arg.startsWith("--search-query=") ||
+      arg.startsWith("--limit=") ||
+      arg.startsWith("--previous-response-id=") ||
+      arg.startsWith("--prev=")
+    ) {
+      continue;
+    }
+
+    if (arg.startsWith("-")) {
+      continue;
+    }
+
+    return arg;
+  }
+
+  return undefined;
+}
+
+function usage() {
+  console.log(`Usage:
+  boids <agent-model> <input>
+  boids search <query> [--limit 5]
+  boids run <input> [--search-query <query>] [--prev <response-id>]
+  boids ask --model <model> [--no-stream] <input>
+  boids responses create --model <model> --input <input> [--stream] [--prev <response-id>]
+
+Environment:
+  BOIDS_API_KEY   Required API key
+  BOIDS_MODEL     Optional default model`);
+}
+
+main(process.argv.slice(2)).then(
+  (code) => {
+    process.exitCode = code;
+  },
+  (error) => {
+    console.error(error.message);
+    process.exitCode = 1;
+  },
+);

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "boids-sdk",
+  "version": "0.1.1",
+  "description": "JavaScript SDK and CLI for the Boids Responses API",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    }
+  },
+  "bin": {
+    "boids": "./bin/boids.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/NevaMind-AI/boids-sdk.git",
+    "directory": "js"
+  },
+  "homepage": "https://github.com/NevaMind-AI/boids-sdk#readme",
+  "bugs": {
+    "url": "https://github.com/NevaMind-AI/boids-sdk/issues"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "package.json"
+  ],
+  "scripts": {
+    "check": "node --check src/index.js && node --check bin/boids.js"
+  },
+  "keywords": [
+    "boids",
+    "sdk",
+    "cli",
+    "responses"
+  ]
+}

package/src/index.d.ts

@@ -0,0 +1,50 @@
+export interface BoidsOptions {
+  apiKey?: string;
+  baseURL?: string;
+  fetch?: typeof fetch;
+  headers?: Record<string, string>;
+}
+
+export interface ResponseCreateParams {
+  model: string;
+  input: unknown;
+  stream?: boolean;
+  previous_response_id?: string;
+  [key: string]: unknown;
+}
+
+export interface ResponseEvent {
+  event?: string;
+  data: unknown;
+  raw: string;
+}
+
+export interface MarketSearchParams {
+  query: string;
+  limit?: number;
+  [key: string]: unknown;
+}
+
+export class BoidsError extends Error {}
+
+export class BoidsAPIError extends BoidsError {
+  status: number;
+  body: string;
+}
+
+export class Boids {
+  constructor(options?: BoidsOptions);
+  responses: {
+    create(params: ResponseCreateParams): Promise<unknown> | AsyncIterable<ResponseEvent>;
+  };
+  market: {
+    search(params: MarketSearchParams | string): Promise<unknown>;
+  };
+  createResponse(params: ResponseCreateParams): Promise<unknown> | AsyncIterable<ResponseEvent>;
+  searchMarket(params: MarketSearchParams | string): Promise<unknown>;
+}
+
+export function parseSSE(response: Response): AsyncIterable<ResponseEvent>;
+export function extractText(value: unknown): string | undefined;
+
+export const DEFAULT_BASE_URL: string;

package/src/index.js

@@ -0,0 +1,231 @@
+const DEFAULT_BASE_URL = "https://api.boids.so/v1";
+const USER_AGENT = "boids-sdk-js/0.1.1";
+
+export class BoidsError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "BoidsError";
+  }
+}
+
+export class BoidsAPIError extends BoidsError {
+  constructor(status, body) {
+    super(`Boids API error ${status}: ${body}`);
+    this.name = "BoidsAPIError";
+    this.status = status;
+    this.body = body;
+  }
+}
+
+export class Boids {
+  constructor(options = {}) {
+    const env = typeof process === "undefined" ? {} : process.env;
+
+    this.apiKey = options.apiKey ?? env.BOIDS_API_KEY;
+    this.baseURL = (options.baseURL ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.fetch = options.fetch ?? globalThis.fetch;
+    this.headers = options.headers ?? {};
+
+    this.responses = {
+      create: (params) => this.createResponse(params),
+    };
+    this.market = {
+      search: (params) => this.searchMarket(params),
+    };
+  }
+
+  createResponse(params = {}) {
+    const body = withoutUndefined({ ...params });
+    if (body.stream) {
+      return this.streamResponse(body);
+    }
+    return this.requestJSON("/responses", body);
+  }
+
+  async requestJSON(path, body) {
+    const response = await this.request(path, body);
+    const text = await response.text();
+    if (!text) {
+      return null;
+    }
+
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
+  }
+
+  searchMarket(params = {}) {
+    const body = typeof params === "string" ? { query: params } : { ...params };
+    body.limit ??= 5;
+    return this.requestJSON("/market/search", body);
+  }
+
+  async *streamResponse(body) {
+    const response = await this.request("/responses", { ...body, stream: true });
+    yield* parseSSE(response);
+  }
+
+  async request(path, body) {
+    if (!this.apiKey) {
+      throw new BoidsError("Missing BOIDS_API_KEY or apiKey.");
+    }
+    if (!this.fetch) {
+      throw new BoidsError("No fetch implementation available.");
+    }
+
+    const response = await this.fetch(`${this.baseURL}${path}`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        "Content-Type": "application/json",
+        Accept: "text/event-stream, application/json",
+        "User-Agent": USER_AGENT,
+        ...this.headers,
+      },
+      body: JSON.stringify(withoutUndefined(body)),
+    });
+
+    if (!response.ok) {
+      throw new BoidsAPIError(response.status, await response.text());
+    }
+
+    return response;
+  }
+}
+
+export async function* parseSSE(response) {
+  const decoder = new TextDecoder();
+  let buffer = "";
+
+  for await (const chunk of readBody(response.body)) {
+    buffer += decoder.decode(chunk, { stream: true });
+    const parts = buffer.split(/\r?\n\r?\n/);
+    buffer = parts.pop() ?? "";
+
+    for (const block of parts) {
+      const event = parseSSEBlock(block);
+      if (!event) {
+        continue;
+      }
+      if (event.raw === "[DONE]") {
+        return;
+      }
+      yield event;
+    }
+  }
+
+  buffer += decoder.decode();
+  if (buffer.trim()) {
+    const event = parseSSEBlock(buffer);
+    if (event && event.raw !== "[DONE]") {
+      yield event;
+    }
+  }
+}
+
+async function* readBody(body) {
+  if (!body) {
+    return;
+  }
+
+  if (typeof body.getReader === "function") {
+    const reader = body.getReader();
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) {
+          break;
+        }
+        if (value) {
+          yield value;
+        }
+      }
+    } finally {
+      reader.releaseLock();
+    }
+    return;
+  }
+
+  for await (const chunk of body) {
+    yield chunk;
+  }
+}
+
+function parseSSEBlock(block) {
+  const lines = block.split(/\r?\n/);
+  const dataLines = [];
+  let eventName;
+
+  for (const line of lines) {
+    if (!line || line.startsWith(":")) {
+      continue;
+    }
+
+    const index = line.indexOf(":");
+    const field = index === -1 ? line : line.slice(0, index);
+    let value = index === -1 ? "" : line.slice(index + 1);
+    if (value.startsWith(" ")) {
+      value = value.slice(1);
+    }
+
+    if (field === "event") {
+      eventName = value;
+    } else if (field === "data") {
+      dataLines.push(value);
+    }
+  }
+
+  if (dataLines.length === 0) {
+    return undefined;
+  }
+
+  const raw = dataLines.join("\n");
+  let data = raw;
+  if (raw !== "[DONE]") {
+    try {
+      data = JSON.parse(raw);
+    } catch {
+      data = raw;
+    }
+  }
+
+  return { event: eventName, data, raw };
+}
+
+export function extractText(value) {
+  if (typeof value === "string") {
+    return value;
+  }
+
+  if (Array.isArray(value)) {
+    const parts = value.map(extractText).filter(Boolean);
+    return parts.length > 0 ? parts.join("") : undefined;
+  }
+
+  if (value && typeof value === "object") {
+    for (const key of ["delta", "text", "output_text"]) {
+      if (typeof value[key] === "string") {
+        return value[key];
+      }
+    }
+
+    for (const key of ["content", "output", "message"]) {
+      const text = extractText(value[key]);
+      if (text) {
+        return text;
+      }
+    }
+  }
+
+  return undefined;
+}
+
+function withoutUndefined(value) {
+  return Object.fromEntries(
+    Object.entries(value).filter(([, item]) => item !== undefined),
+  );
+}
+
+export { DEFAULT_BASE_URL };