@combycode/llm-sdk

A unified, pluggable AI SDK for accessing the LLMs of every major provider — Anthropic, OpenAI, Google, xAI, and OpenRouter — through one API.

• One API, every provider. Switch model or provider without rewriting calls.
• Pluggable. Opt-in subsystems: a model catalog, cost tracking + budgets, rate-limit-aware queueing, tools/agents, and an OpenAI-compatible server.
• Unified model catalog — normalised slug names (anthropic/claude-haiku-4.5), model:tier selectors, capability-based select(), tiered pricing, and cost tracking.
• Cross-environment. The same code runs on Node, Bun, and the browser. Zero runtime dependencies, ESM.

Install

npm install @combycode/llm-sdk      # or: bun add @combycode/llm-sdk

Requires Node ≥ 18 or Bun ≥ 1.1.

Quickstart

Simplest path — a callable provider id

import { complete } from '@combycode/llm-sdk';

const r = await complete({
  model: 'anthropic/claude-haiku-4-5', // provider/model, sent verbatim
  apiKey: process.env.ANTHROPIC_API_KEY,
  prompt: 'Say hello in one word.',
});
console.log(r.text);

Unified names + capability selection

createEngine() registers a default engine that the helpers use automatically — you only pass engine explicitly when you run more than one.

import { complete, createEngine, select } from '@combycode/llm-sdk';

createEngine({ catalog: 'defaults', apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! } });

// Normalised slug → translated to the provider's callable id via the catalog.
await complete({ model: 'anthropic/claude-haiku-4.5', prompt: 'Hi' });

// Pick the cheapest model matching a capability query.
const best = select('type:chat; vision; cheap'); // -> "provider/slug"
await complete({ model: best!, prompt: 'Hi' });

Streaming

import { createLLM } from '@combycode/llm-sdk';

const llm = createLLM({ model: 'openai/gpt-5.4-nano', apiKey: process.env.OPENAI_API_KEY });
for await (const ev of llm.stream('Count to 5.')) {
  if (ev.type === 'text') process.stdout.write(ev.text);
}

Documentation

Full guide pages covering all export groups:

• docs/guide/ -- index of all guide pages
  • Network Engine
  • LLM Client + complete / stream
  • Agent Loop + delegate / chain / consolidate
  • Tools (defineTool)
  • Tokens + Embeddings
  • Cost Tracking + estimate()
  • Observability / Telemetry
  • Media / Files / Batch
  • MCP (Model Context Protocol)
  • Context Guard + Permissions + Persistence + Cache
  • OpenAI-Compatible Server
  • Agent Patterns
  • Moderation
  • Retrieval (RAG)
  • Approval and Checkpoints
  • Realtime (Live)

MCP subsystem design: docs/design/mcp.md

Development

bun install
bun test          # unit tests
bun run typecheck # tsc --noEmit
bun run lint      # biome
bun run build     # dist/ (node + browser builds + types)

License

MIT