@odla-ai/ai 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,991 @@
+/** Every provider odla-ai can route to. Apps should not branch on this for
+ *  portability, but it is carried on responses/events for observability. */
+type ProviderId = "anthropic" | "openai" | "google";
+interface TextBlock {
+    type: "text";
+    text: string;
+    /** Anthropic prompt-caching marker. Other providers ignore it. */
+    cacheControl?: {
+        type: "ephemeral";
+    };
+}
+type ImageMediaType = "image/jpeg" | "image/png" | "image/gif" | "image/webp";
+type ImageSource = {
+    type: "base64";
+    mediaType: ImageMediaType;
+    data: string;
+} | {
+    type: "url";
+    url: string;
+};
+interface ImageBlock {
+    type: "image";
+    source: ImageSource;
+}
+type AudioMediaType = "audio/wav" | "audio/mp3" | "audio/mpeg" | "audio/ogg" | "audio/flac" | "audio/aac" | "audio/webm";
+type AudioSource = {
+    type: "base64";
+    mediaType: AudioMediaType;
+    data: string;
+} | {
+    type: "url";
+    url: string;
+};
+/** Audio input. Supported by OpenAI (audio models) and Google (Gemini); NOT by
+ *  Anthropic — a request carrying an AudioBlock to a Claude model is rejected up
+ *  front by capability validation, never sent. */
+interface AudioBlock {
+    type: "audio";
+    source: AudioSource;
+}
+type DocumentSource = {
+    type: "base64";
+    mediaType: "application/pdf";
+    data: string;
+} | {
+    type: "url";
+    url: string;
+};
+/** A document (PDF) input. Supported by Anthropic and Google. */
+interface DocumentBlock {
+    type: "document";
+    source: DocumentSource;
+}
+interface ToolUseBlock {
+    type: "tool_use";
+    /** Correlates a `tool_result` with this call. Translated from OpenAI's
+     *  `tool_calls[].id` by the openai adapter. */
+    id: string;
+    name: string;
+    /** Already-parsed object. OpenAI's JSON-string `arguments` is parsed before it
+     *  reaches this shape — callers never JSON.parse a tool's arguments. */
+    input: Record<string, unknown>;
+}
+interface ToolResultBlock {
+    type: "tool_result";
+    toolUseId: string;
+    /** String for plain-text results (most tools); a content-block array for tools
+     *  that return structured / multi-modal content. */
+    content: string | OracleContentBlock[];
+    isError?: boolean;
+}
+interface ThinkingBlock {
+    type: "thinking";
+    /** Extended-thinking text (Anthropic). Empty when `display` is omitted. */
+    thinking: string;
+    signature?: string;
+}
+type OracleContentBlock = TextBlock | ImageBlock | AudioBlock | DocumentBlock | ToolUseBlock | ToolResultBlock | ThinkingBlock;
+type OracleRole = "user" | "assistant";
+interface OracleMessage {
+    role: OracleRole;
+    /** A plain string (shorthand for a single TextBlock) or an explicit array for
+     *  multi-modal / tool turns. */
+    content: string | OracleContentBlock[];
+}
+interface OracleTool {
+    name: string;
+    description: string;
+    /** JSON Schema for the tool's arguments. */
+    inputSchema: Record<string, unknown>;
+}
+/** How the model may use tools this turn. `{ type: "tool", name }` forces one
+ *  specific tool — the mechanism behind `extract<T>()`. */
+type ToolChoice = "auto" | "any" | "none" | {
+    type: "tool";
+    name: string;
+};
+/** Whether the model reasons before answering. Maps to Anthropic adaptive
+ *  thinking; emulated or ignored on providers without a native equivalent. */
+type ThinkingMode = "off" | "adaptive";
+/** Reasoning/spend depth. Maps to Anthropic `output_config.effort`; the openai
+ *  and google adapters map it to their nearest reasoning-effort knob. */
+type Effort = "low" | "medium" | "high" | "xhigh" | "max";
+/** Constrain the response to valid JSON matching a schema (structured output). */
+interface ResponseFormat {
+    type: "json_schema";
+    name?: string;
+    schema: Record<string, unknown>;
+}
+interface OracleRequest {
+    /** Canonical model id from the catalog; resolved to a provider + native id. */
+    model: string;
+    /** System prompt. Top-level for Anthropic/Google; the openai adapter folds it
+     *  into a leading system message. */
+    system?: string | TextBlock[];
+    messages: OracleMessage[];
+    tools?: OracleTool[];
+    toolChoice?: ToolChoice;
+    maxTokens: number;
+    temperature?: number;
+    stopSequences?: string[];
+    /** Reasoning mode. Only applied on models whose capabilities allow it. */
+    thinking?: ThinkingMode;
+    /** Reasoning/spend depth. Only applied on models whose capabilities allow it. */
+    effort?: Effort;
+    responseFormat?: ResponseFormat;
+    /** Enable the provider's server-side web-search tool for this request. */
+    webSearch?: boolean;
+    /** Provider-specific escape hatch, passed through opaquely. Using it gives up
+     *  portability across providers. */
+    providerExtras?: Record<string, unknown>;
+}
+interface OracleUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cacheCreationTokens?: number;
+    cacheReadTokens?: number;
+}
+declare function emptyUsage(): OracleUsage;
+/** Accumulate `more` into `into`, in place. Cache fields sum when present. */
+declare function addUsage(into: OracleUsage, more: OracleUsage): void;
+type OracleStopReason = "end_turn" | "max_tokens" | "stop_sequence" | "tool_use" | "pause_turn" | "refusal" | "error";
+interface OracleResponse {
+    id: string;
+    model: string;
+    /** The provider that actually answered — for observability, not branching. */
+    provider: ProviderId;
+    role: "assistant";
+    content: OracleContentBlock[];
+    stopReason: OracleStopReason;
+    usage: OracleUsage;
+}
+/** A discriminated union of SSE events with the same vocabulary regardless of
+ *  provider. The anthropic adapter passes these through nearly 1:1; the openai
+ *  and google adapters map their native streams onto this shape. */
+type OracleEvent = MessageStartEvent | ContentBlockStartEvent | ContentBlockDeltaEvent | ContentBlockStopEvent | MessageDeltaEvent | MessageStopEvent | OracleErrorEvent;
+interface MessageStartEvent {
+    type: "message_start";
+    message: {
+        id: string;
+        model: string;
+        provider: ProviderId;
+        role: "assistant";
+        content: [];
+        usage: OracleUsage;
+    };
+}
+interface ContentBlockStartEvent {
+    type: "content_block_start";
+    index: number;
+    contentBlock: OracleContentBlock;
+}
+type ContentBlockDelta = {
+    type: "text_delta";
+    text: string;
+} | {
+    type: "thinking_delta";
+    thinking: string;
+} | {
+    type: "input_json_delta";
+    partialJson: string;
+};
+interface ContentBlockDeltaEvent {
+    type: "content_block_delta";
+    index: number;
+    delta: ContentBlockDelta;
+}
+interface ContentBlockStopEvent {
+    type: "content_block_stop";
+    index: number;
+}
+interface MessageDeltaEvent {
+    type: "message_delta";
+    delta: {
+        stopReason?: OracleStopReason;
+    };
+    usage: OracleUsage;
+}
+interface MessageStopEvent {
+    type: "message_stop";
+}
+interface OracleErrorEvent {
+    type: "error";
+    error: OracleErrorShape;
+}
+/** The closed taxonomy of normalized error codes carried by every OdlaAIError
+ *  and by the streaming `error` event. */
+type OracleErrorType = "invalid_request" | "auth" | "rate_limit" | "context_window" | "tool_input_invalid" | "capability_unsupported" | "config" | "provider_error";
+/** The plain-data error shape used inside the streaming `error` event. */
+interface OracleErrorShape {
+    code: OracleErrorType;
+    message: string;
+    /** HTTP status from the upstream provider, when applicable. */
+    providerStatus?: number;
+    /** Seconds until a retry might succeed (rate limit / overload). */
+    retryAfter?: number;
+}
+/** Base class for every error odla-ai throws. Carries a stable string `code`
+ *  (the odla ecosystem convention — see odla-db's AuthError/RuleError) so
+ *  callers branch on `err.code`, never on message text. */
+declare class OdlaAIError extends Error {
+    readonly code: OracleErrorType;
+    readonly providerStatus?: number;
+    readonly retryAfter?: number;
+    constructor(code: OracleErrorType, message: string, opts?: {
+        providerStatus?: number;
+        retryAfter?: number;
+        cause?: unknown;
+    });
+    toShape(): OracleErrorShape;
+}
+/** A provider/model is not configured — e.g. no API key for its provider, or an
+ *  unknown canonical model id. The library analog of odla-db's 501 gating. */
+declare class ConfigError extends OdlaAIError {
+    constructor(message: string);
+}
+/** Authentication with the provider failed (bad/missing key). */
+declare class AuthError extends OdlaAIError {
+    constructor(message: string, opts?: {
+        providerStatus?: number;
+        cause?: unknown;
+    });
+}
+/** The provider rate-limited or is overloaded; check `retryAfter`. */
+declare class RateLimitError extends OdlaAIError {
+    constructor(message: string, opts?: {
+        providerStatus?: number;
+        retryAfter?: number;
+        cause?: unknown;
+    });
+}
+/** The request asked a model to do something it cannot — audio to Claude, tools
+ *  to a text-only model, web search where unsupported, etc. Raised before any
+ *  network call by `validateRequest`. */
+declare class CapabilityError extends OdlaAIError {
+    constructor(message: string);
+}
+/** The request exceeded the model's context window. */
+declare class ContextWindowError extends OdlaAIError {
+    constructor(message: string, opts?: {
+        providerStatus?: number;
+        cause?: unknown;
+    });
+}
+/** The request was malformed / rejected as invalid by the provider. */
+declare class InvalidRequestError extends OdlaAIError {
+    constructor(message: string, opts?: {
+        providerStatus?: number;
+        cause?: unknown;
+    });
+}
+/** Any other upstream provider failure (5xx, transport, unexpected shape). */
+declare class ProviderError extends OdlaAIError {
+    constructor(message: string, opts?: {
+        providerStatus?: number;
+        cause?: unknown;
+    });
+}
+declare function isTextBlock(b: OracleContentBlock): b is TextBlock;
+declare function isImageBlock(b: OracleContentBlock): b is ImageBlock;
+declare function isAudioBlock(b: OracleContentBlock): b is AudioBlock;
+declare function isDocumentBlock(b: OracleContentBlock): b is DocumentBlock;
+declare function isToolUseBlock(b: OracleContentBlock): b is ToolUseBlock;
+declare function isToolResultBlock(b: OracleContentBlock): b is ToolResultBlock;
+declare function isThinkingBlock(b: OracleContentBlock): b is ThinkingBlock;
+/** Normalize a message's `content` (string shorthand or block array) to blocks. */
+declare function blocksOf(content: string | OracleContentBlock[]): OracleContentBlock[];
+/** Concatenate the text of every TextBlock. Image/audio/tool/thinking ignored. */
+declare function extractText(content: OracleContentBlock[]): string;
+/** Collect every tool_use block from response or message content. */
+declare function extractToolUses(content: OracleContentBlock[]): ToolUseBlock[];
+
+/** The kind of model — chat/multimodal is the v1 focus; the others are modeled
+ *  so embeddings, transcription, TTS, and image generation slot in later. */
+type ModelKind = "chat" | "embed" | "transcribe" | "tts" | "image";
+interface Capabilities {
+    kind: ModelKind;
+    /** Accepts text input. */
+    textIn: boolean;
+    /** Accepts image input (ImageBlock). */
+    imageIn: boolean;
+    /** Accepts audio input (AudioBlock). */
+    audioIn: boolean;
+    /** Accepts document/PDF input (DocumentBlock). */
+    documentIn: boolean;
+    /** Supports tool / function calling. */
+    toolUse: boolean;
+    /** Supports a native reasoning/thinking mode. */
+    thinking: boolean;
+    /** Supports an effort/reasoning-depth knob. */
+    effort: boolean;
+    /** Supports streaming responses. */
+    streaming: boolean;
+    /** Supports constrained JSON / structured output. */
+    structuredOutput: boolean;
+    /** Supports a provider server-side web-search tool. */
+    webSearch: boolean;
+}
+/** A catalog entry: a canonical model id mapped to a provider, that provider's
+ *  native model id, and what the model can do. */
+interface ModelSpec {
+    /** Canonical id used across odla-ai (e.g. "claude-opus-4-8", "gpt-5"). */
+    id: string;
+    provider: ProviderId;
+    /** The id passed to the provider SDK. Often equal to `id`. */
+    nativeId: string;
+    capabilities: Capabilities;
+    contextWindow?: number;
+    maxOutput?: number;
+}
+/** Sensible chat/multimodal defaults; per-model tables override what differs. */
+declare function chatCapabilities(overrides?: Partial<Capabilities>): Capabilities;
+/**
+ * Validate a request against a model's capabilities. Throws CapabilityError on
+ * the first violation. Runs before any provider call — the single choke point
+ * that turns "audio to Claude" from an opaque upstream 400 into a clear error.
+ */
+declare function validateRequest(spec: ModelSpec, req: OracleRequest): void;
+
+declare const ANTHROPIC_MODELS: ModelSpec[];
+
+declare const OPENAI_MODELS: ModelSpec[];
+
+declare const GOOGLE_MODELS: ModelSpec[];
+
+/** Canonical id → spec. */
+type Catalog = Record<string, ModelSpec>;
+/** The built-in catalog across Anthropic, OpenAI, and Google. */
+declare const DEFAULT_CATALOG: Catalog;
+/** Merge extra specs over a base catalog (later entries win by id). */
+declare function buildCatalog(base: Catalog, extra?: ModelSpec[]): Catalog;
+/** Look up a model, throwing a ConfigError (with the known ids) if unknown. */
+declare function resolveModel(catalog: Catalog, id: string): ModelSpec;
+/** List every provider the catalog can route to. */
+declare function providersInCatalog(catalog: Catalog): ProviderId[];
+
+interface Provider {
+    readonly id: ProviderId;
+    /** One assistant turn. Server-side tools (e.g. web search) are resolved
+     *  internally; the returned response is final for this turn (its stopReason is
+     *  never "pause_turn"). Client-side tool calls return with stopReason
+     *  "tool_use" for the agent loop to handle. */
+    create(spec: ModelSpec, req: OracleRequest): Promise<OracleResponse>;
+    /** The same turn as an async stream of normalized OracleEvents. */
+    stream(spec: ModelSpec, req: OracleRequest): AsyncIterable<OracleEvent>;
+}
+/** Constructs a provider adapter bound to a resolved API key. */
+type ProviderFactory = (apiKey: string) => Provider;
+
+/** Static per-provider keys. */
+type KeyMap = Partial<Record<ProviderId, string>>;
+/** Dynamic key lookup — return undefined to signal "no key for this provider". */
+type KeyResolver = (provider: ProviderId) => string | undefined | Promise<string | undefined>;
+interface KeyOptions {
+    keys?: KeyMap;
+    /** Consulted first; falls back to `keys` when it returns undefined. */
+    resolveKey?: KeyResolver;
+}
+/** Best-effort key-shape check (used by smoke/diagnostics, never for gating —
+ *  formats drift). */
+declare function looksLikeKey(provider: ProviderId, key: string): boolean;
+/** Redact anything that looks like a provider secret from a string (logs/errors). */
+declare function redact(text: string): string;
+
+interface InitOptions {
+    /** Static per-provider API keys (BYO). */
+    keys?: KeyMap;
+    /** Dynamic per-provider key lookup (multi-tenant / per-call). Consulted first. */
+    resolveKey?: KeyResolver;
+    /** Model used when a call omits `model`. */
+    defaultModel?: string;
+    /** Override / extend the built-in model catalog. */
+    catalog?: Catalog;
+    /** Inject provider adapters directly (tests, custom transports). When present
+     *  for a provider, it is used verbatim and no key is required. */
+    providers?: Partial<Record<ProviderId, Provider>>;
+}
+/** Any turn's input — a canonical request with `model` optional (defaultModel fills). */
+type ChatInput = Omit<OracleRequest, "model"> & {
+    model?: string;
+};
+interface ExtractTool {
+    name: string;
+    description?: string;
+    /** JSON Schema for the forced tool's arguments. */
+    parameters: Record<string, unknown>;
+}
+/** A forced structured extraction: schema in, validated object out. */
+interface ExtractCall {
+    model?: string;
+    system?: string | TextBlock[];
+    user: string | OracleContentBlock[];
+    tool: ExtractTool;
+    maxTokens?: number;
+}
+/** A web-search-enabled call: the model searches and returns prose. */
+interface SearchCall {
+    model?: string;
+    system?: string | TextBlock[];
+    user: string | OracleContentBlock[];
+    maxTokens?: number;
+}
+interface Ai {
+    /** The active model catalog. */
+    readonly catalog: Catalog;
+    /** One assistant turn (non-streaming). */
+    chat(input: ChatInput): Promise<OracleResponse>;
+    /** One assistant turn as a stream of normalized OracleEvents. */
+    stream(input: ChatInput): AsyncIterable<OracleEvent>;
+    /** Forced single-tool extraction → validated object. */
+    extract<T = unknown>(c: ExtractCall): Promise<{
+        value: T;
+        usage: OracleUsage;
+    }>;
+    /** Web-search-grounded prose answer. */
+    search(c: SearchCall): Promise<{
+        text: string;
+        usage: OracleUsage;
+    }>;
+}
+/** The minimal inference surface the agent loop and eval harness depend on. */
+type Inference = Pick<Ai, "chat" | "stream" | "catalog">;
+declare function init(opts?: InitOptions): Ai;
+
+/** Generate the `llms.txt` context document for a given model catalog. */
+declare function generateLlmsTxt(catalog?: Catalog): string;
+
+declare function getProvider(id: ProviderId, apiKey: string): Promise<Provider>;
+/** Test seam: register a provider instance directly (used to inject mocks). */
+declare function registerProvider(id: ProviderId, apiKey: string, provider: Provider): void;
+/** Test seam: clear the adapter cache. */
+declare function clearProviderCache(): void;
+
+/** Map any provider error to an OdlaAIError, returning it (does not throw).
+ *  Re-returns an OdlaAIError unchanged (already normalized). */
+declare function normalizeError(err: unknown, provider: ProviderId): OdlaAIError;
+
+type TaintLabel = "web_untrusted" | "operator_pasted_untrusted" | "llm_inherited" | `tool_untrusted:${string}`;
+type TaintSet = Set<TaintLabel>;
+declare function taint(...labels: TaintLabel[]): TaintSet;
+/** Raised when a tool's taint allowlist doesn't cover the conversation's taint. */
+declare class TaintError extends OdlaAIError {
+    constructor(message: string);
+}
+/**
+ * Throw unless every label currently on the conversation is in the sink's
+ * allowlist. `llm_inherited` is intentionally excludable: a tool that lists it as
+ * *not* accepted is one where model-derived instructions must never reach the
+ * sink (the classic injected-instruction propagation case).
+ */
+declare function assertSinkAcceptsTaint(sink: string, allowed: TaintLabel[], actual: TaintSet): void;
+
+/** What a tool returns after running. */
+interface ToolOutput {
+    content: string | OracleContentBlock[];
+    isError?: boolean;
+}
+/** Context handed to a tool handler when it runs. */
+interface ToolContext {
+    /** The taint currently on the conversation feeding this call. */
+    taint: TaintSet;
+    /** Optional cancellation signal, threaded from the run. */
+    signal?: AbortSignal;
+}
+type ToolHandler = (input: Record<string, unknown>, ctx: ToolContext) => Promise<ToolOutput> | ToolOutput;
+interface ToolDef {
+    name: string;
+    description: string;
+    /** JSON Schema for the tool arguments. */
+    inputSchema: Record<string, unknown>;
+    /** Local executor. Omit for provider server tools resolved inside the adapter. */
+    handler?: ToolHandler;
+    /** Taint labels this tool's output introduces into the conversation. */
+    outputTaint?: TaintLabel[];
+    /** If set, the tool only runs when the conversation taint ⊆ this allowlist. */
+    acceptsTaint?: TaintLabel[];
+}
+/** Project a ToolDef to the wire-level OracleTool the model sees. */
+declare function toOracleTool(t: ToolDef): OracleTool;
+
+interface Skill {
+    /** Skill name — used as the heading for its instructions in the system prompt. */
+    name: string;
+    /** Guidance appended to the persona's system prompt (when/how to use the tools). */
+    instructions?: string;
+    /** The tools this skill contributes to the agent. */
+    tools: ToolDef[];
+}
+interface ComposedPersona {
+    system: string | undefined;
+    tools: ToolDef[];
+}
+/** Merge a persona's own tools/system with its attached skills: skill tools are
+ *  appended to the tool list, and each skill's instructions become a titled
+ *  section of the system prompt. Order is preserved (persona first, then skills). */
+declare function composeSkills(system: string | undefined, tools: ToolDef[] | undefined, skills: Skill[] | undefined): ComposedPersona;
+
+interface MemoryScope {
+    /** Messages to prepend before this run's input. */
+    load(): Promise<OracleMessage[]> | OracleMessage[];
+    /** Persist the messages produced during this run (excludes what load() returned). */
+    append(messages: OracleMessage[]): Promise<void> | void;
+}
+/** A simple process-lifetime memory scope. */
+declare class InMemoryScope implements MemoryScope {
+    private messages;
+    load(): OracleMessage[];
+    append(messages: OracleMessage[]): void;
+    clear(): void;
+}
+
+interface Persona {
+    /** Human-readable role name (e.g. "researcher", "triager"). */
+    name: string;
+    /** Canonical model id the persona runs on. */
+    model: string;
+    /** System prompt defining the persona's behavior. */
+    system?: string;
+    /** Tools the persona may call. Handlers run locally; handler-less tools are
+     *  provider server tools. */
+    tools?: ToolDef[];
+    /** Skills to attach — each contributes tools + instructions to the persona. */
+    skills?: Skill[];
+    /** Enable the provider's web-search server tool for this persona. */
+    webSearch?: boolean;
+    /** Max model turns before the loop stops (default 8). */
+    maxSteps?: number;
+    /** Reasoning depth (applied only where the model supports it). */
+    effort?: Effort;
+    /** Reasoning mode (applied only where the model supports it). */
+    thinking?: ThinkingMode;
+    temperature?: number;
+    /** Max output tokens per model turn (default 4096). */
+    maxTokens?: number;
+    /** Persistent memory scope loaded before, and appended after, each run. */
+    memory?: MemoryScope;
+}
+
+/** One resolved tool call within a run. */
+interface ToolCallRecord {
+    toolUse: ToolUseBlock;
+    output: ToolOutput;
+}
+interface AgentRunInput {
+    /** A single user turn (convenience). */
+    input?: string | OracleContentBlock[];
+    /** Or an explicit list of messages (takes precedence when both are given). */
+    messages?: OracleMessage[];
+    signal?: AbortSignal;
+}
+type StoppedReason = "end_turn" | "max_steps" | "refusal";
+interface AgentRun {
+    /** Concatenated text of the final assistant turn. */
+    finalText: string;
+    /** The last assistant response. */
+    response: OracleResponse;
+    /** The full conversation (loaded memory + input + assistant/tool turns). */
+    messages: OracleMessage[];
+    /** Accumulated usage across every model turn. */
+    usage: OracleUsage;
+    /** Number of model turns taken. */
+    steps: number;
+    /** Every tool call executed, in order. */
+    toolCalls: ToolCallRecord[];
+    stoppedReason: StoppedReason;
+}
+declare function runAgent(inference: Inference, persona: Persona, input: AgentRunInput): Promise<AgentRun>;
+
+/** One evaluation case — an input plus whatever the grader needs to judge it. */
+interface EvalCase {
+    name?: string;
+    /** A user turn (string / blocks) or an explicit conversation (message array). */
+    input: string | OracleContentBlock[] | OracleMessage[];
+    /** Grader-specific expectation (exact string, JSON subset, rubric text, …). */
+    expected?: unknown;
+    meta?: Record<string, unknown>;
+}
+interface GradeContext {
+    case: EvalCase;
+    /** The system-under-test's final text output. */
+    output: string;
+    /** The final model response. */
+    response: OracleResponse;
+}
+interface GradeResult {
+    pass: boolean;
+    /** 0..1 when a grader scores rather than passes/fails. */
+    score?: number;
+    reason?: string;
+}
+type Grader = (ctx: GradeContext) => Promise<GradeResult> | GradeResult;
+
+interface EvalResult {
+    case: EvalCase;
+    output: string;
+    grade: GradeResult;
+    response: OracleResponse;
+    usage: OracleUsage;
+}
+interface EvalReport {
+    total: number;
+    passed: number;
+    failed: number;
+    passRate: number;
+    results: EvalResult[];
+    usage: OracleUsage;
+}
+interface EvaluateOptions {
+    inference: Inference;
+    cases: EvalCase[];
+    grader: Grader;
+    /** Run each case through this persona (agent loop). Mutually exclusive with model. */
+    persona?: Persona;
+    /** Or run each case as a single chat with this model + system. */
+    model?: string;
+    system?: string;
+    maxTokens?: number;
+    /** Max cases run concurrently (default 5). */
+    concurrency?: number;
+}
+declare function evaluate(opts: EvaluateOptions): Promise<EvalReport>;
+
+/** Pass when trimmed output equals `case.expected` (stringified). */
+declare function exactMatch(): Grader;
+/** Pass when output contains `case.expected` (case-insensitive by default). */
+declare function includes(opts?: {
+    caseInsensitive?: boolean;
+}): Grader;
+/** Pass when output parses as JSON and contains every key/value in
+ *  `case.expected` (a recursive subset match). */
+declare function structuredMatch(): Grader;
+/** Grade open-ended output with a judge model. `case.expected` is the rubric.
+ *  The judge is asked to return a strict JSON verdict which is tolerantly parsed. */
+declare function llmJudge(opts: {
+    inference: Inference;
+    model: string;
+    extraGuidance?: string;
+}): Grader;
+
+/** Entity namespaces odla-ai owns in odla-db (all non-`$`, so no platform clash). */
+declare const NS: {
+    readonly conversation: "agent_conversation";
+    readonly message: "agent_message";
+    readonly run: "agent_run";
+};
+/** Serialized odla-db schema (POST to `/app/:id/schema` as `{ schema: AGENT_SCHEMA }`). */
+declare const AGENT_SCHEMA: {
+    readonly entities: {
+        readonly agent_conversation: {
+            readonly attrs: {
+                readonly key: {
+                    readonly type: "string";
+                    readonly unique: true;
+                    readonly indexed: true;
+                    readonly optional: false;
+                };
+                readonly sessionId: {
+                    readonly type: "string";
+                    readonly unique: false;
+                    readonly indexed: true;
+                    readonly optional: false;
+                };
+                readonly title: {
+                    readonly type: "string";
+                    readonly unique: false;
+                    readonly indexed: false;
+                    readonly optional: true;
+                };
+                readonly createdAt: {
+                    readonly type: "date";
+                    readonly unique: false;
+                    readonly indexed: true;
+                    readonly optional: false;
+                };
+                readonly updatedAt: {
+                    readonly type: "date";
+                    readonly unique: false;
+                    readonly indexed: true;
+                    readonly optional: false;
+                };
+            };
+        };
+        readonly agent_message: {
+            readonly attrs: {
+                readonly key: {
+                    readonly type: "string";
+                    readonly unique: true;
+                    readonly indexed: true;
+                    readonly optional: false;
+                };
+                readonly sessionId: {
+                    readonly type: "string";
+                    readonly unique: false;
+                    readonly indexed: true;
+                    readonly optional: false;
+                };
+                readonly seq: {
+                    readonly type: "number";
+                    readonly unique: false;
+                    readonly indexed: true;
+                    readonly optional: false;
+                };
+                readonly role: {
+                    readonly type: "string";
+                    readonly unique: false;
+                    readonly indexed: false;
+                    readonly optional: false;
+                };
+                readonly content: {
+                    readonly type: "string";
+                    readonly unique: false;
+                    readonly indexed: false;
+                    readonly optional: false;
+                };
+                readonly createdAt: {
+                    readonly type: "date";
+                    readonly unique: false;
+                    readonly indexed: true;
+                    readonly optional: false;
+                };
+            };
+        };
+        readonly agent_run: {
+            readonly attrs: {
+                readonly key: {
+                    readonly type: "string";
+                    readonly unique: true;
+                    readonly indexed: true;
+                    readonly optional: false;
+                };
+                readonly sessionId: {
+                    readonly type: "string";
+                    readonly unique: false;
+                    readonly indexed: true;
+                    readonly optional: false;
+                };
+                readonly persona: {
+                    readonly type: "string";
+                    readonly unique: false;
+                    readonly indexed: false;
+                    readonly optional: true;
+                };
+                readonly status: {
+                    readonly type: "string";
+                    readonly unique: false;
+                    readonly indexed: true;
+                    readonly optional: false;
+                };
+                readonly steps: {
+                    readonly type: "number";
+                    readonly unique: false;
+                    readonly indexed: false;
+                    readonly optional: false;
+                };
+                readonly inputTokens: {
+                    readonly type: "number";
+                    readonly unique: false;
+                    readonly indexed: false;
+                    readonly optional: false;
+                };
+                readonly outputTokens: {
+                    readonly type: "number";
+                    readonly unique: false;
+                    readonly indexed: false;
+                    readonly optional: false;
+                };
+                readonly finalText: {
+                    readonly type: "string";
+                    readonly unique: false;
+                    readonly indexed: false;
+                    readonly optional: true;
+                };
+                readonly trace: {
+                    readonly type: "json";
+                    readonly unique: false;
+                    readonly indexed: false;
+                    readonly optional: false;
+                };
+                readonly createdAt: {
+                    readonly type: "date";
+                    readonly unique: false;
+                    readonly indexed: true;
+                    readonly optional: false;
+                };
+            };
+        };
+    };
+    readonly links: {};
+};
+
+type OdlaScalar = string | number | boolean | null;
+interface OdlaLookup {
+    ns: string;
+    attr: string;
+    value: OdlaScalar;
+}
+/** Entity reference: a raw id, or a natural-key `Lookup` for idempotent upsert. */
+type OdlaEntityRef = string | OdlaLookup;
+/** The odla-db transaction op union (subset we emit). */
+type OdlaOp = {
+    t: "update";
+    ns: string;
+    id: OdlaEntityRef;
+    attrs: Record<string, unknown>;
+} | {
+    t: "merge";
+    ns: string;
+    id: OdlaEntityRef;
+    attrs: Record<string, unknown>;
+} | {
+    t: "delete";
+    ns: string;
+    id: OdlaEntityRef;
+} | {
+    t: "link";
+    ns: string;
+    id: OdlaEntityRef;
+    label: string;
+    target: OdlaEntityRef;
+} | {
+    t: "unlink";
+    ns: string;
+    id: OdlaEntityRef;
+    label: string;
+    target: OdlaEntityRef;
+};
+/** An InstaQL-style query object, e.g. `{ ns: { $: { where, order, limit } } }`. */
+type OdlaQuery = Record<string, unknown>;
+/** The subset of the odla-db Admin client odla-ai uses. */
+interface OdlaDbClient {
+    /** Apply ops atomically; a stable `mutationId` gives exactly-once replay. */
+    transact(ops: OdlaOp[], opts?: {
+        mutationId?: string;
+    }): Promise<number>;
+    /** Run an InstaQL query; returns namespace → rows. */
+    query(query: OdlaQuery): Promise<Record<string, Record<string, unknown>[]>>;
+    /** Read one of this app's secrets by name (app-key credential; read-only). */
+    secrets: {
+        get(name: string): Promise<string>;
+    };
+}
+
+interface OdlaDbMemoryOptions {
+    db: OdlaDbClient;
+    /** Groups a conversation's turns; stable across runs to accumulate history. */
+    sessionId: string;
+    /** Optional human-readable title stored on the conversation node. */
+    title?: string;
+    /** Override entity namespaces (default NS.message / NS.conversation). */
+    namespaces?: {
+        message?: string;
+        conversation?: string;
+    };
+}
+declare class OdlaDbMemory implements MemoryScope {
+    private readonly db;
+    private readonly sessionId;
+    private readonly title;
+    private readonly msgNs;
+    private readonly convNs;
+    private loadedCount;
+    constructor(opts: OdlaDbMemoryOptions);
+    load(): Promise<OracleMessage[]>;
+    append(messages: OracleMessage[]): Promise<void>;
+}
+
+interface PersistRunOptions {
+    db: OdlaDbClient;
+    /** Groups runs (typically the same session as the memory scope). */
+    sessionId: string;
+    personaName?: string;
+    /** Stable id for exactly-once persistence; defaults to `${sessionId}:${now}`. */
+    runId?: string;
+    namespace?: string;
+}
+/** Write a run trace; returns the record key. */
+declare function persistRun(run: AgentRun, opts: PersistRunOptions): Promise<string>;
+interface QueryRunsOptions {
+    db: OdlaDbClient;
+    sessionId: string;
+    limit?: number;
+    namespace?: string;
+}
+/** Read persisted runs for a session, newest first. */
+declare function queryRuns(opts: QueryRunsOptions): Promise<Record<string, unknown>[]>;
+
+/** Default secret name per provider. */
+declare const DEFAULT_SECRET_NAMES: Record<ProviderId, string>;
+interface OdlaDbKeyResolverOptions {
+    /** Map a provider to its secret name (default `<provider>_api_key`). Use this
+     *  to scope per-end-user keys, e.g. `(p) => \`${p}_api_key__${userSub}\``. */
+    secretName?: (provider: ProviderId) => string;
+    /** Cache resolved keys in memory (default true). */
+    cache?: boolean;
+}
+/** Build a KeyResolver that reads provider keys from odla-db secrets. A missing
+ *  secret resolves to `undefined` (→ that provider is simply unavailable, and
+ *  odla-ai throws its own ConfigError) rather than surfacing odla-db's 404. */
+declare function odlaDbKeyResolver(db: OdlaDbClient, opts?: OdlaDbKeyResolverOptions): KeyResolver;
+
+type FetchLike = typeof fetch;
+interface ProvisionContext {
+    /** The odla-db worker URL — always human-supplied, never hardcoded. */
+    endpoint: string;
+    /** Operator `ADMIN_SECRET` or an `odla_dev_...` developer token (owns the app). */
+    token: string;
+    fetch?: FetchLike;
+}
+/** Create an app (owned by the token's developer). Returns its id. */
+declare function createApp(ctx: ProvisionContext, opts?: {
+    appId?: string;
+    name?: string;
+}): Promise<string>;
+/** Mint a per-app `odla_sk_...` key (shown once). */
+declare function mintAppKey(ctx: ProvisionContext, appId: string): Promise<string>;
+/** Push odla-ai's agent memory/run schema (authenticated with the app key). */
+declare function pushAgentSchema(ctx: {
+    endpoint: string;
+    fetch?: FetchLike;
+}, appId: string, appKey: string): Promise<void>;
+/** Store a named secret (operator/dev token). Value must be a non-`$` string. */
+declare function putSecret(ctx: ProvisionContext, appId: string, name: string, value: string): Promise<void>;
+interface ProvisionAgentAppOptions extends ProvisionContext {
+    appId?: string;
+    appName?: string;
+    /** Provider keys to store as odla-db secrets (read later via odlaDbKeyResolver). */
+    providerKeys?: Partial<Record<ProviderId, string>>;
+    /** Map a provider to its secret name (default `<provider>_api_key`). */
+    secretName?: (provider: ProviderId) => string;
+    /** Push the agent schema (default true). */
+    pushSchema?: boolean;
+}
+interface ProvisionedApp {
+    appId: string;
+    /** The minted `odla_sk_...` app key — pass as `adminToken` to `@odla-ai/db`'s init. */
+    appKey: string;
+}
+/** One call to stand up an agent app: create → mint key → push schema → store
+ *  provider keys as secrets. Returns the appId + app key for the runtime client. */
+declare function provisionAgentApp(opts: ProvisionAgentAppOptions): Promise<ProvisionedApp>;
+
+interface EntityCrudSkillOptions {
+    /** The injected odla-db client (from @odla-ai/db's init). */
+    db: OdlaDbClient;
+    /** Entity namespace, e.g. "todos". */
+    entity: string;
+    /** JSON-Schema `properties` for the create/update fields (e.g. { text: { type: "string" }, done: { type: "boolean" } }). */
+    fields: Record<string, unknown>;
+    /** Field names required to create (default: none). */
+    required?: string[];
+    /** Skill name (default `${entity} management`). */
+    name?: string;
+    /** Extra instructions appended to the generated guidance. */
+    instructions?: string;
+    /** Singular noun for tool names (default: `entity` with a trailing "s" stripped). */
+    singular?: string;
+    /** Plural noun for the list tool (default: `entity`). */
+    plural?: string;
+    /** Input field carrying the entity id in update/delete (default "id"). */
+    idField?: string;
+    /** Generate a new id on create (default crypto.randomUUID). */
+    genId?: () => string;
+    /** Attr stamped with Date.now() on create; pass false to disable (default "createdAt"). */
+    stampCreatedAt?: string | false;
+    /** Default ordering for the list tool (default { createdAt: "asc" }). */
+    order?: Record<string, "asc" | "desc">;
+}
+/** Build a CRUD Skill for one odla-db entity. */
+declare function entityCrudSkill(opts: EntityCrudSkillOptions): Skill;
+
+export { AGENT_SCHEMA, ANTHROPIC_MODELS, type AgentRun, type AgentRunInput, type Ai, type AudioBlock, type AudioMediaType, type AudioSource, AuthError, type Capabilities, CapabilityError, type Catalog, type ChatInput, type ComposedPersona, ConfigError, type ContentBlockDelta, type ContentBlockDeltaEvent, type ContentBlockStartEvent, type ContentBlockStopEvent, ContextWindowError, DEFAULT_CATALOG, DEFAULT_SECRET_NAMES, type DocumentBlock, type DocumentSource, type Effort, type EntityCrudSkillOptions, type EvalCase, type EvalReport, type EvalResult, type EvaluateOptions, type ExtractCall, type ExtractTool, GOOGLE_MODELS, type GradeContext, type GradeResult, type Grader, type ImageBlock, type ImageMediaType, type ImageSource, InMemoryScope, type Inference, type InitOptions, InvalidRequestError, type KeyMap, type KeyOptions, type KeyResolver, type MemoryScope, type MessageDeltaEvent, type MessageStartEvent, type MessageStopEvent, type ModelKind, type ModelSpec, NS, OPENAI_MODELS, OdlaAIError, type OdlaDbClient, type OdlaDbKeyResolverOptions, OdlaDbMemory, type OdlaDbMemoryOptions, type OdlaEntityRef, type OdlaLookup, type OdlaOp, type OdlaQuery, type OdlaScalar, type OracleContentBlock, type OracleErrorEvent, type OracleErrorShape, type OracleErrorType, type OracleEvent, type OracleMessage, type OracleRequest, type OracleResponse, type OracleRole, type OracleStopReason, type OracleTool, type OracleUsage, type PersistRunOptions, type Persona, type Provider, ProviderError, type ProviderFactory, type ProviderId, type ProvisionAgentAppOptions, type ProvisionContext, type ProvisionedApp, type QueryRunsOptions, RateLimitError, type ResponseFormat, type SearchCall, type Skill, type StoppedReason, TaintError, type TaintLabel, type TaintSet, type TextBlock, type ThinkingBlock, type ThinkingMode, type ToolCallRecord, type ToolChoice, type ToolContext, type ToolDef, type ToolHandler, type ToolOutput, type ToolResultBlock, type ToolUseBlock, addUsage, assertSinkAcceptsTaint, blocksOf, buildCatalog, chatCapabilities, clearProviderCache, composeSkills, createApp, emptyUsage, entityCrudSkill, evaluate, exactMatch, extractText, extractToolUses, generateLlmsTxt, getProvider, includes, init, isAudioBlock, isDocumentBlock, isImageBlock, isTextBlock, isThinkingBlock, isToolResultBlock, isToolUseBlock, llmJudge, looksLikeKey, mintAppKey, normalizeError, odlaDbKeyResolver, persistRun, providersInCatalog, provisionAgentApp, pushAgentSchema, putSecret, queryRuns, redact, registerProvider, resolveModel, runAgent, structuredMatch, taint, toOracleTool, validateRequest };