@combycode/llm-sdk 1.0.0-rc.0

package/dist/helpers/observer.d.ts

@@ -0,0 +1,36 @@
+/** createObserver — agent-scoped reactive subscription.
+ *
+ *      createObserver(agent, 'onRunComplete', reactor);
+ *
+ *  The reactor is either a plain async function `(ctx) => void` or an
+ *  AgentOptions object describing an observer agent. When it's an agent
+ *  config, the helper internally builds an AgentLoop with the supplied
+ *  tools; on every fired event it converts the ctx to a prompt and runs
+ *  `observer.complete(prompt)` — the observer's tools execute the side
+ *  effects, the reply text is discarded.
+ *
+ *  Hooks are pulled from `coreRegistry.get().hooks`. Events fire fire-
+ *  and-forget; an in-flight reaction never blocks the next event. */
+import type { AgentLoop } from '../agent/loop';
+import type { RunCompleteContext, RunErrorContext, RunStartContext, StepCompleteContext, StepStartContext, ToolCallCompleteContext, ToolCallErrorContext, ToolCallStartContext } from '../bus/hook-map';
+import { type CreateAgentOptions } from './agent';
+/** Agent-scoped event names — hook-map entries that carry `agentId`. */
+export type AgentEventName = 'onRunStart' | 'onRunComplete' | 'onRunError' | 'onStepStart' | 'onStepComplete' | 'onToolCallStart' | 'onToolCallComplete' | 'onToolCallError';
+interface AgentEventCtxMap {
+    onRunStart: RunStartContext;
+    onRunComplete: RunCompleteContext;
+    onRunError: RunErrorContext;
+    onStepStart: StepStartContext;
+    onStepComplete: StepCompleteContext;
+    onToolCallStart: ToolCallStartContext;
+    onToolCallComplete: ToolCallCompleteContext;
+    onToolCallError: ToolCallErrorContext;
+}
+export type ObserverReactor<E extends AgentEventName> = ((ctx: AgentEventCtxMap[E]) => void | Promise<void>) | ObserverAgentReactor<E>;
+export interface ObserverAgentReactor<E extends AgentEventName> extends CreateAgentOptions {
+    /** Convert the event ctx into the prompt text fed to the observer agent.
+     *  Defaults to a JSON dump of ctx. */
+    prompt?: (ctx: AgentEventCtxMap[E]) => string | Promise<string>;
+}
+export declare function createObserver<E extends AgentEventName>(agent: AgentLoop, event: E, reactor: ObserverReactor<E>): () => void;
+export {};

package/dist/helpers/one-shot.d.ts

@@ -0,0 +1,86 @@
+/** One-shot complete() — single-call helper that hides the ceremony.
+ *
+ *    const reply = await complete({
+ *      provider: 'anthropic',
+ *      model: 'claude-haiku-4-5',
+ *      apiKey,
+ *      system: 'Reply in one sentence.',
+ *      prompt: 'What is TypeScript?',
+ *      maxTokens: 60,
+ *    });
+ *    // reply: { text, usage, finishReason, raw }
+ *
+ *  When `tools` is supplied, the helper internally builds an AgentLoop and
+ *  runs the multi-step tool loop. Without tools, it goes through plain
+ *  LLMClient.complete. Either way the helper destroys its created client
+ *  before returning so callers don't leak. */
+import type { AgentTool } from '../agent/types';
+import type { LLMClientConfig } from '../llm/client-config';
+import type { AudioOptions } from '../llm/types/audio';
+import type { ContentPart, Message } from '../llm/types/messages';
+import type { CompletionResponse } from '../llm/types/response';
+import type { ProviderName } from '../llm/types/provider';
+import type { ServiceTier } from '../llm/types/tiers';
+import type { BuiltinTool } from '../llm/types/tools';
+import type { EngineHandle } from './engine';
+import type { EstimateBound } from './estimate-types';
+export interface CompleteOptions {
+    /** Model string. Bare (e.g. `claude-haiku-4-5` — pair with `provider`) or
+     *  namespaced (e.g. `anthropic/claude-haiku-4-5`). */
+    model: string;
+    /** Required when `model` is bare. */
+    provider?: ProviderName;
+    /** Optional — falls back to `engine.apiKeys[provider]`. */
+    apiKey?: string;
+    /** Per-call system prompt. */
+    system?: string;
+    /** Either a string (becomes user message) OR an explicit messages array. */
+    prompt: string | ContentPart[] | Message[];
+    /** Inline media / file parts to append to the user message. Each entry may be:
+     *    - a string path or `http(s)://` URL → auto-loaded as an image part
+     *    - a `Uint8Array`                    → auto-loaded as an image part
+     *    - a `ContentPart`                   → used as-is
+     *  Sugar over `prompt: [...{role:'user', content:[...attachments, {type:'text', text}]}]`. */
+    attachments?: Array<string | Uint8Array | ContentPart>;
+    /** Tools — if any are passed, the helper runs an AgentLoop. Executable tools
+     *  (from `defineTool`) AND bare builtin tools (`{type:'web_search'}` /
+     *  `{type:'code_interpreter'}` …) are both accepted; builtins run server-side
+     *  so they need no client executor. */
+    tools?: Array<AgentTool | BuiltinTool>;
+    /** Generation control. */
+    maxTokens?: number;
+    temperature?: number;
+    structured?: {
+        schema: Record<string, unknown>;
+        name?: string;
+    };
+    /** Output audio controls (voice/format) for audio-capable models. */
+    audio?: AudioOptions;
+    /** Which output modalities to return. Default ['text']; add 'audio' for a spoken
+     *  reply (surfaced as a media part on `response.media`). */
+    outputModalities?: Array<'text' | 'audio'>;
+    /** Service tier for this call. Also settable as a `model:tier` suffix (e.g.
+     *  `anthropic/claude-opus-4.8:priority`); an explicit value here wins. */
+    serviceTier?: ServiceTier;
+    /** Optional engine to use. Falls back to coreRegistry default. */
+    engine?: EngineHandle;
+    /** Provider-specific request options (e.g. `{ openrouter: { models: [...] } }`). */
+    providerOptions?: Record<string, unknown>;
+    /** Extra LLMClient options. */
+    client?: Partial<Omit<LLMClientConfig, 'provider' | 'model' | 'apiKey'>>;
+    /** When set, `estimate()` runs BEFORE the request is sent. If the cost for
+     *  `budgetBound` exceeds this limit, throws `BudgetExceededError` and never
+     *  calls the provider.  OFF by default (no behavior change when absent). */
+    maxCostUsd?: number;
+    /** Which estimate bound to compare against `maxCostUsd`.
+     *  Default: `'expected'`.  Use `'high'` for conservative worst-case gating. */
+    budgetBound?: EstimateBound;
+}
+export interface CompleteResult<T = unknown> {
+    text: string;
+    /** Auto-parsed JSON result. Present iff `opts.structured.schema` was set;
+     *  otherwise `undefined`. The generic on `complete<T>(...)` types this. */
+    parsed?: T;
+    response: CompletionResponse;
+}
+export declare function complete<T = unknown>(opts: CompleteOptions): Promise<CompleteResult<T>>;

package/dist/helpers/parallel.d.ts

@@ -0,0 +1,16 @@
+/** parallel — fan-out a single input across N steps and collect their
+ *  outputs in order. Companion to `chain` (sequential).
+ *
+ *  Each step is either a `complete()` config with `prompt(input)` or a
+ *  plain async function. Optional `onStep` fires per-completion (in
+ *  whichever order they finish). */
+import type { ChainStep } from './chain';
+export interface ParallelOptions {
+    /** Fires once per step as it completes (NOT necessarily in step order). */
+    onStep?: (info: {
+        index: number;
+        name?: string;
+        output: string;
+    }) => void;
+}
+export declare function parallel(steps: ChainStep[], options?: ParallelOptions): (input: string) => Promise<string[]>;

package/dist/helpers/realtime.d.ts

@@ -0,0 +1,25 @@
+/** createRealtime — open a unified realtime/live session using the current
+ *  EngineHandle (engine.connect transport + engine.apiKeys). Resolves a default
+ *  per-provider RealtimeProviderAdapter (openai/google). Mirrors createLLM. */
+import type { AudioOptions } from '../llm/types/audio';
+import type { RealtimeModality, RealtimeSession } from '../llm/realtime/types';
+import type { ProviderName } from '../llm/types/provider';
+import type { EngineHandle } from './engine';
+export interface CreateRealtimeOptions {
+    /** Model string. Bare (`gpt-realtime` — pair with `provider`) or namespaced
+     *  (`openai/gpt-realtime`). */
+    model: string;
+    /** Required when `model` is bare. Ignored when namespaced. */
+    provider?: ProviderName;
+    /** Falls back to `engine.apiKeys[provider]` when omitted. */
+    apiKey?: string;
+    modalities?: RealtimeModality[];
+    /** Output audio controls (voice/format). `audio.voice` accepts a provider voice
+     *  id or a unified alias. Takes precedence over the legacy `voice` field. */
+    audio?: AudioOptions;
+    /** @deprecated use `audio.voice`. */
+    voice?: string;
+    instructions?: string;
+    engine?: EngineHandle;
+}
+export declare function createRealtime(opts: CreateRealtimeOptions): RealtimeSession;

package/dist/helpers/route.d.ts

@@ -0,0 +1,29 @@
+/** route() — provider routing with fallback.
+ *
+ *  V2 (client-side): try each model in order; on a *retryable* failure
+ *  (classified ErrorKind) fall over to the next; on a non-retryable failure
+ *  (auth, invalid_request, content_filter, …) fail fast — another model won't
+ *  fix a fundamentally bad request. Works across providers.
+ *
+ *  V1 (openrouter passthrough): when every model is openrouter, send ONE request
+ *  with a `models` array and let OpenRouter route server-side (one round-trip;
+ *  `response.model` reports who served). */
+import type { ErrorKind } from '../network/errors';
+import { type CompleteOptions, type CompleteResult } from './one-shot';
+export interface RouteOptions extends Omit<CompleteOptions, 'model' | 'provider'> {
+    /** Ordered candidate models — "provider/model" (namespaced) preferred. */
+    models: string[];
+    /** Override which ErrorKinds trigger fallback. */
+    fallbackOn?: ErrorKind[];
+}
+export interface RouteAttempt {
+    model: string;
+    error?: string;
+    kind?: ErrorKind;
+}
+export interface RouteResult<T = unknown> extends CompleteResult<T> {
+    /** The candidate model whose request produced this result. */
+    servedBy: string;
+    attempts: RouteAttempt[];
+}
+export declare function route<T = unknown>(opts: RouteOptions): Promise<RouteResult<T>>;

package/dist/helpers/select-model.d.ts

@@ -0,0 +1,41 @@
+/** select() — pick a model by capabilities/features via a tiny tag DSL, returning
+ *  a `provider/slug` string you can feed straight to complete({ model }).
+ *
+ *  Query: a `;`-separated string OR an array of clauses. Clause grammar:
+ *    key:value      exact          e.g. type:chat, search:yes, status:stable
+ *    key            → key:yes      e.g. search, vision, reasoning
+ *    key > N        key ≥ N        e.g. context > 200k   (inclusive)
+ *    key < N        key ≤ N        e.g. price < 1        (inclusive)
+ *    N parses k/M suffixes (200k → 200000). Custom tags expand first.
+ *
+ *  Availability-aware: only considers providers with a configured API key.
+ *  Ranks cheapest-first (tiebreak: newest version); select() returns the single
+ *  best, selectModels() the ranked list. Thresholds + custom tags are overridable. */
+import type { ModelInfo } from '../plugins/model-catalog/catalog';
+import type { ProviderName } from '../llm/types/provider';
+import { type EngineHandle } from './engine';
+export interface SelectPrefs {
+    /** Named cutoffs (overridable). */
+    thresholds?: Partial<typeof DEFAULT_THRESHOLDS>;
+    /** Custom tag → DSL expansion, e.g. `{ cheap: 'price < 1', coding: 'type:code; tools' }`. */
+    tags?: Record<string, string>;
+}
+export interface SelectOptions {
+    engine?: EngineHandle;
+    /** Restrict to one provider. */
+    provider?: ProviderName;
+    /** Price tier to evaluate `price` against (default: standard/flat). */
+    tier?: string;
+    prefs?: SelectPrefs;
+}
+declare const DEFAULT_THRESHOLDS: {
+    'price.low': number;
+    'price.mid': number;
+    'context.small': number;
+    'context.large': number;
+};
+/** All matching models, ranked cheapest-first (tiebreak: newest version). */
+export declare function selectModels(query: string | string[], opts?: SelectOptions): ModelInfo[];
+/** The single best match as a `provider/slug` string (feedable to complete), or null. */
+export declare function select(query: string | string[], opts?: SelectOptions): string | null;
+export {};

package/dist/helpers/server.d.ts

@@ -0,0 +1,32 @@
+/** createServer — convenience helper that builds an OaiServer with engine
+ *  wiring (shared HookBus + ResponseStore-backed Persistence).
+ *
+ *  When `agents` is supplied, the helper auto-builds an `agentLoader` that
+ *  constructs an AgentLoop per request and a `conversationLoader` backed
+ *  by `createCollection<HistorySnapshot>('server-conversations')` so chat
+ *  history survives across requests + restarts. The raw `agentLoader` /
+ *  `conversationLoader` slots remain available for advanced cases. */
+import type { AgentTool } from '../agent/types';
+import type { AgentLoop } from '../agent/loop';
+import { OaiServer, type OaiServerConfig } from '../server/server';
+import { type CreateAgentOptions } from './agent';
+import type { EngineHandle } from './engine';
+export interface ServerAgentSpec extends CreateAgentOptions {
+    /** Pre-built AgentLoop. When set, the same instance is reused for every
+     *  request — best for single-tenant stateful agents. */
+    agent?: AgentLoop;
+    /** Internal tools (executable on the server, hidden from the client). */
+    internalTools?: AgentTool[];
+    /** When false, client-supplied tools in the OAI request are dropped. Default true. */
+    allowExternalTools?: boolean;
+}
+export interface CreateServerOptions extends Omit<OaiServerConfig, 'hooks' | 'responseStorePersistence'> {
+    /** High-level agent registration. Each entry becomes a server model with
+     *  a per-request AgentLoop built from the spec, plus per-(userId,
+     *  conversationId) history backed by `engine.persistence`. */
+    agents?: Record<string, ServerAgentSpec>;
+    engine?: EngineHandle;
+    hooks?: OaiServerConfig['hooks'];
+    responseStorePersistence?: OaiServerConfig['responseStorePersistence'];
+}
+export declare function createServer(opts?: CreateServerOptions): OaiServer;

package/dist/helpers/transcribe.d.ts

@@ -0,0 +1,36 @@
+/** transcribe() — speech-to-text, unified across providers.
+ *
+ *  Two provider shapes:
+ *    - openai: a dedicated /v1/audio/transcriptions multipart endpoint
+ *      (gpt-4o-transcribe / whisper). Routed to OpenAITranscriptionAdapter.
+ *    - generateContent providers (google, …): transcription is just a normal
+ *      completion with the audio attached, so reuse complete(). */
+import type { AudioInput } from '../llm/types/audio';
+import type { ProviderName } from '../llm/types/provider';
+import type { EngineHandle } from './engine';
+export interface TranscribeOptions {
+    model: string;
+    provider?: ProviderName;
+    apiKey?: string;
+    /** Audio source: a file path, raw bytes, or an AudioInput (with explicit
+     *  mimeType for raw/stream audio). */
+    audio: string | Uint8Array | AudioInput;
+    /** Optional language hint (BCP-47, e.g. "en"). */
+    language?: string;
+    /** Prompt used for generateContent-style providers (ignored by openai). */
+    prompt?: string;
+    /** Caller-supplied audio duration in seconds.  Used to price OpenAI
+     *  transcription calls (the API does not return duration).  When omitted,
+     *  the helper tries to parse duration from a WAV header; other formats
+     *  emit an honest zero with a note. */
+    audioDurationSeconds?: number;
+    engine?: EngineHandle;
+}
+export interface TranscribeResult {
+    text: string;
+}
+export declare function transcribe(opts: TranscribeOptions): Promise<TranscribeResult>;
+/** WAV PCM duration from raw bytes — pure arithmetic, cross-env.
+ *  Reads sample-rate (bytes 24-27) and data-chunk size from the RIFF header.
+ *  Returns undefined for non-WAV or malformed data. */
+export declare function deriveWavDuration(bytes: Uint8Array, mimeType: string): number | undefined;