@broberg/ai-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1146 @@
+import { z } from 'zod';
+
+/** How a call reaches the model. `http` = provider REST API; `subprocess` = local
+ *  `claude -p` CLI (Max plan, costUsd 0). */
+type Transport = "http" | "subprocess";
+/** Named capability tier. Resolves to a (provider, model, transport) triple via
+ *  the tier map, overridable per call. */
+type Tier = "fast" | "smart" | "powerful" | "cheap" | "vision" | "embedding";
+/** The concrete routing target a Tier (or a per-call override) resolves to. */
+interface TierSpec {
+    provider: string;
+    model: string;
+    transport: Transport;
+}
+/** High-level capability a call exercises. Mirrors the capability layer (F5). */
+type Capability = "chat" | "vision" | "translate" | "image" | "embedding" | "transcribe" | "mockup" | "design" | "extract" | "classify" | "rerank";
+type Role = "system" | "user" | "assistant" | "tool";
+/** A piece of message content. Text everywhere; image parts feed vision. */
+type ContentPart = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    image: string | Uint8Array;
+    mimeType?: string;
+};
+interface Message {
+    role: Role;
+    content: string | ContentPart[];
+    /** Set on assistant messages that called tools. */
+    toolCalls?: ToolCall[];
+    /** Set on `tool` role messages — which call this result answers. */
+    toolCallId?: string;
+}
+/** SDK-level tool definition. Adapters convert this to each provider's format
+ *  (F4.5). `parameters` is a JSON Schema object. */
+interface Tool {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}
+/** A model's request to invoke a tool, normalized across providers (F4.5). */
+interface ToolCall {
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+}
+/** Per-call usage. Fields mirror the upmetrics `agent_runs` schema 1:1 so the
+ *  upmetricsSink (F3.7) forwards without re-mapping. `costUsd` is 0 for
+ *  subprocess (Max plan); `subprocess:true` lets dashboards split free vs paid. */
+interface Usage {
+    provider: string;
+    model: string;
+    tier?: Tier;
+    transport: Transport;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+    costUsd: number;
+    toolCalls?: {
+        name: string;
+        count: number;
+        errorCount?: number;
+    }[];
+    latencyMs: number;
+    capability: Capability;
+    purpose?: string;
+    ts: string;
+    subprocess?: true;
+}
+/** A cost reporter. Fans `Usage` out to Upmetrics / Discord / sqlite / etc.
+ *  Implementations must never throw into the caller (F3.3). */
+interface CostSink {
+    record(usage: Usage): void | Promise<void>;
+}
+/** Pre-flight budget ceilings, enforced before a call fires (F3.2). */
+interface BudgetConfig {
+    /** Reject a single call whose estimated cost exceeds this many USD. */
+    perCallUsd?: number;
+    /** Reject once cumulative spend on this client instance exceeds this many USD. */
+    rollingUsd?: number;
+}
+/** Per-call options shared by every capability: which tier, optional routing
+ *  override, optional fallback chain, and a free-text purpose for cost reports. */
+interface CallOptions {
+    tier?: Tier;
+    /** Override any part of the resolved TierSpec for this call only. */
+    override?: Partial<TierSpec>;
+    /** Ordered fallbacks tried if the primary route errors (inventory finding:
+     *  cms/trail/sanne/xrt81 all hand-roll this — make it first-class). */
+    fallback?: (Tier | TierSpec)[];
+    purpose?: string;
+}
+interface ChatRequest {
+    messages: Message[];
+    spec: TierSpec;
+    tools?: Tool[];
+    maxTokens?: number;
+    temperature?: number;
+}
+interface ChatResult {
+    text: string;
+    toolCalls?: ToolCall[];
+    usage: Usage;
+}
+interface ImageRequest {
+    prompt: string;
+    spec: TierSpec;
+    width?: number;
+    height?: number;
+}
+interface ImageResult {
+    url: string;
+    usage: Usage;
+}
+interface EmbeddingRequest {
+    input: string[];
+    spec: TierSpec;
+}
+interface EmbeddingResult {
+    vectors: number[][];
+    usage: Usage;
+}
+interface TranscribeRequest {
+    /** Raw audio bytes (the client resolves a URL to bytes before calling). */
+    audio: Uint8Array;
+    language?: string;
+    spec: TierSpec;
+}
+interface TranscribeResult {
+    text: string;
+    usage: Usage;
+}
+/** The thin contract every provider implements (F4). A provider need only
+ *  support the capabilities it offers — `chat` is the baseline; vision/image/
+ *  embedding are optional and absence is a typed capability gap. */
+interface ProviderAdapter {
+    readonly name: string;
+    /** Every capability is optional — an adapter implements only what it supports
+     *  (e.g. fal does image only). The client guards each call and throws a clear
+     *  "provider X does not support Y" when a capability is absent. */
+    chat?(req: ChatRequest): Promise<ChatResult>;
+    vision?(req: ChatRequest): Promise<ChatResult>;
+    image?(req: ImageRequest): Promise<ImageResult>;
+    embedding?(req: EmbeddingRequest): Promise<EmbeddingResult>;
+    transcribe?(req: TranscribeRequest): Promise<TranscribeResult>;
+}
+interface TranslateResult {
+    text: string;
+    usage: Usage;
+}
+
+interface MockupInput {
+    description: string;
+    constraints?: string;
+    tier?: Tier;
+    purpose?: string;
+}
+interface MockupResult {
+    html: string;
+    usage: Usage;
+}
+interface DesignInput {
+    /** Screenshot URL or raw bytes to iterate on. */
+    screenshot: string | Uint8Array;
+    instructions: string;
+    tier?: Tier;
+    purpose?: string;
+}
+interface DesignResult {
+    html: string;
+    usage: Usage;
+}
+interface ExtractInput<T> {
+    text: string;
+    /** Zod schema the extracted data must satisfy. */
+    schema: z.ZodType<T>;
+    instructions?: string;
+    tier?: Tier;
+    purpose?: string;
+}
+interface ExtractResult<T> {
+    data: T;
+    usage: Usage;
+}
+interface ClassifyInput {
+    text: string;
+    labels: string[];
+    tier?: Tier;
+    purpose?: string;
+}
+interface ClassifyResult {
+    label: string;
+    confidence: number;
+    usage: Usage;
+}
+interface RerankInput {
+    query: string;
+    items: string[];
+    tier?: Tier;
+    purpose?: string;
+}
+interface RerankResult {
+    ranked: {
+        item: string;
+        score: number;
+    }[];
+    usage: Usage;
+}
+interface Contracts {
+    mockup(input: MockupInput): Promise<MockupResult>;
+    design(input: DesignInput): Promise<DesignResult>;
+    extract<T>(input: ExtractInput<T>): Promise<ExtractResult<T>>;
+    classify(input: ClassifyInput): Promise<ClassifyResult>;
+    rerank(input: RerankInput): Promise<RerankResult>;
+}
+
+declare const tierSpecSchema: z.ZodObject<{
+    provider: z.ZodString;
+    model: z.ZodString;
+    transport: z.ZodEnum<["http", "subprocess"]>;
+}, "strip", z.ZodTypeAny, {
+    provider: string;
+    model: string;
+    transport: "http" | "subprocess";
+}, {
+    provider: string;
+    model: string;
+    transport: "http" | "subprocess";
+}>;
+declare const toolSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    parameters: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}, {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}>;
+declare const messageSchema: z.ZodObject<{
+    role: z.ZodEnum<["system", "user", "assistant", "tool"]>;
+    content: z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"text">;
+        text: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        text: string;
+        type: "text";
+    }, {
+        text: string;
+        type: "text";
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"image">;
+        image: z.ZodUnion<[z.ZodString, z.ZodType<Uint8Array<ArrayBuffer>, z.ZodTypeDef, Uint8Array<ArrayBuffer>>]>;
+        mimeType: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        image: string | Uint8Array<ArrayBuffer>;
+        type: "image";
+        mimeType?: string | undefined;
+    }, {
+        image: string | Uint8Array<ArrayBuffer>;
+        type: "image";
+        mimeType?: string | undefined;
+    }>]>, "many">]>;
+    toolCalls: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        arguments: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        name: string;
+        arguments: Record<string, unknown>;
+    }, {
+        id: string;
+        name: string;
+        arguments: Record<string, unknown>;
+    }>, "many">>;
+    toolCallId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string | ({
+        text: string;
+        type: "text";
+    } | {
+        image: string | Uint8Array<ArrayBuffer>;
+        type: "image";
+        mimeType?: string | undefined;
+    })[];
+    toolCalls?: {
+        id: string;
+        name: string;
+        arguments: Record<string, unknown>;
+    }[] | undefined;
+    toolCallId?: string | undefined;
+}, {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string | ({
+        text: string;
+        type: "text";
+    } | {
+        image: string | Uint8Array<ArrayBuffer>;
+        type: "image";
+        mimeType?: string | undefined;
+    })[];
+    toolCalls?: {
+        id: string;
+        name: string;
+        arguments: Record<string, unknown>;
+    }[] | undefined;
+    toolCallId?: string | undefined;
+}>;
+declare const chatInputSchema: z.ZodObject<{
+    tier: z.ZodOptional<z.ZodEnum<["fast", "smart", "powerful", "cheap", "vision", "embedding"]>>;
+    override: z.ZodOptional<z.ZodObject<{
+        provider: z.ZodOptional<z.ZodString>;
+        model: z.ZodOptional<z.ZodString>;
+        transport: z.ZodOptional<z.ZodEnum<["http", "subprocess"]>>;
+    }, "strip", z.ZodTypeAny, {
+        provider?: string | undefined;
+        model?: string | undefined;
+        transport?: "http" | "subprocess" | undefined;
+    }, {
+        provider?: string | undefined;
+        model?: string | undefined;
+        transport?: "http" | "subprocess" | undefined;
+    }>>;
+    fallback: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodEnum<["fast", "smart", "powerful", "cheap", "vision", "embedding"]>, z.ZodObject<{
+        provider: z.ZodString;
+        model: z.ZodString;
+        transport: z.ZodEnum<["http", "subprocess"]>;
+    }, "strip", z.ZodTypeAny, {
+        provider: string;
+        model: string;
+        transport: "http" | "subprocess";
+    }, {
+        provider: string;
+        model: string;
+        transport: "http" | "subprocess";
+    }>]>, "many">>;
+    purpose: z.ZodOptional<z.ZodString>;
+    prompt: z.ZodOptional<z.ZodString>;
+    messages: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        role: z.ZodEnum<["system", "user", "assistant", "tool"]>;
+        content: z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"text">;
+            text: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            text: string;
+            type: "text";
+        }, {
+            text: string;
+            type: "text";
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"image">;
+            image: z.ZodUnion<[z.ZodString, z.ZodType<Uint8Array<ArrayBuffer>, z.ZodTypeDef, Uint8Array<ArrayBuffer>>]>;
+            mimeType: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            image: string | Uint8Array<ArrayBuffer>;
+            type: "image";
+            mimeType?: string | undefined;
+        }, {
+            image: string | Uint8Array<ArrayBuffer>;
+            type: "image";
+            mimeType?: string | undefined;
+        }>]>, "many">]>;
+        toolCalls: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            arguments: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        }, "strip", z.ZodTypeAny, {
+            id: string;
+            name: string;
+            arguments: Record<string, unknown>;
+        }, {
+            id: string;
+            name: string;
+            arguments: Record<string, unknown>;
+        }>, "many">>;
+        toolCallId: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        role: "system" | "user" | "assistant" | "tool";
+        content: string | ({
+            text: string;
+            type: "text";
+        } | {
+            image: string | Uint8Array<ArrayBuffer>;
+            type: "image";
+            mimeType?: string | undefined;
+        })[];
+        toolCalls?: {
+            id: string;
+            name: string;
+            arguments: Record<string, unknown>;
+        }[] | undefined;
+        toolCallId?: string | undefined;
+    }, {
+        role: "system" | "user" | "assistant" | "tool";
+        content: string | ({
+            text: string;
+            type: "text";
+        } | {
+            image: string | Uint8Array<ArrayBuffer>;
+            type: "image";
+            mimeType?: string | undefined;
+        })[];
+        toolCalls?: {
+            id: string;
+            name: string;
+            arguments: Record<string, unknown>;
+        }[] | undefined;
+        toolCallId?: string | undefined;
+    }>, "many">>;
+    system: z.ZodOptional<z.ZodString>;
+    tools: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        parameters: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    }, {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    }>, "many">>;
+    maxTokens: z.ZodOptional<z.ZodNumber>;
+    temperature: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    system?: string | undefined;
+    prompt?: string | undefined;
+    messages?: {
+        role: "system" | "user" | "assistant" | "tool";
+        content: string | ({
+            text: string;
+            type: "text";
+        } | {
+            image: string | Uint8Array<ArrayBuffer>;
+            type: "image";
+            mimeType?: string | undefined;
+        })[];
+        toolCalls?: {
+            id: string;
+            name: string;
+            arguments: Record<string, unknown>;
+        }[] | undefined;
+        toolCallId?: string | undefined;
+    }[] | undefined;
+    tools?: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    }[] | undefined;
+    temperature?: number | undefined;
+    maxTokens?: number | undefined;
+    tier?: "fast" | "smart" | "powerful" | "cheap" | "vision" | "embedding" | undefined;
+    override?: {
+        provider?: string | undefined;
+        model?: string | undefined;
+        transport?: "http" | "subprocess" | undefined;
+    } | undefined;
+    fallback?: ("fast" | "smart" | "powerful" | "cheap" | "vision" | "embedding" | {
+        provider: string;
+        model: string;
+        transport: "http" | "subprocess";
+    })[] | undefined;
+    purpose?: string | undefined;
+}, {
+    system?: string | undefined;
+    prompt?: string | undefined;
+    messages?: {
+        role: "system" | "user" | "assistant" | "tool";
+        content: string | ({
+            text: string;
+            type: "text";
+        } | {
+            image: string | Uint8Array<ArrayBuffer>;
+            type: "image";
+            mimeType?: string | undefined;
+        })[];
+        toolCalls?: {
+            id: string;
+            name: string;
+            arguments: Record<string, unknown>;
+        }[] | undefined;
+        toolCallId?: string | undefined;
+    }[] | undefined;
+    tools?: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    }[] | undefined;
+    temperature?: number | undefined;
+    maxTokens?: number | undefined;
+    tier?: "fast" | "smart" | "powerful" | "cheap" | "vision" | "embedding" | undefined;
+    override?: {
+        provider?: string | undefined;
+        model?: string | undefined;
+        transport?: "http" | "subprocess" | undefined;
+    } | undefined;
+    fallback?: ("fast" | "smart" | "powerful" | "cheap" | "vision" | "embedding" | {
+        provider: string;
+        model: string;
+        transport: "http" | "subprocess";
+    })[] | undefined;
+    purpose?: string | undefined;
+}>;
+declare const visionInputSchema: z.ZodObject<{
+    tier: z.ZodOptional<z.ZodEnum<["fast", "smart", "powerful", "cheap", "vision", "embedding"]>>;
+    override: z.ZodOptional<z.ZodObject<{
+        provider: z.ZodOptional<z.ZodString>;
+        model: z.ZodOptional<z.ZodString>;
+        transport: z.ZodOptional<z.ZodEnum<["http", "subprocess"]>>;
+    }, "strip", z.ZodTypeAny, {
+        provider?: string | undefined;
+        model?: string | undefined;
+        transport?: "http" | "subprocess" | undefined;
+    }, {
+        provider?: string | undefined;
+        model?: string | undefined;
+        transport?: "http" | "subprocess" | undefined;
+    }>>;
+    fallback: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodEnum<["fast", "smart", "powerful", "cheap", "vision", "embedding"]>, z.ZodObject<{
+        provider: z.ZodString;
+        model: z.ZodString;
+        transport: z.ZodEnum<["http", "subprocess"]>;
+    }, "strip", z.ZodTypeAny, {
+        provider: string;
+        model: string;
+        transport: "http" | "subprocess";
+    }, {
+        provider: string;
+        model: string;
+        transport: "http" | "subprocess";
+    }>]>, "many">>;
+    purpose: z.ZodOptional<z.ZodString>;
+    image: z.ZodUnion<[z.ZodString, z.ZodType<Uint8Array<ArrayBuffer>, z.ZodTypeDef, Uint8Array<ArrayBuffer>>]>;
+    prompt: z.ZodString;
+    mimeType: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    image: string | Uint8Array<ArrayBuffer>;
+    prompt: string;
+    mimeType?: string | undefined;
+    tier?: "fast" | "smart" | "powerful" | "cheap" | "vision" | "embedding" | undefined;
+    override?: {
+        provider?: string | undefined;
+        model?: string | undefined;
+        transport?: "http" | "subprocess" | undefined;
+    } | undefined;
+    fallback?: ("fast" | "smart" | "powerful" | "cheap" | "vision" | "embedding" | {
+        provider: string;
+        model: string;
+        transport: "http" | "subprocess";
+    })[] | undefined;
+    purpose?: string | undefined;
+}, {
+    image: string | Uint8Array<ArrayBuffer>;
+    prompt: string;
+    mimeType?: string | undefined;
+    tier?: "fast" | "smart" | "powerful" | "cheap" | "vision" | "embedding" | undefined;
+    override?: {
+        provider?: string | undefined;
+        model?: string | undefined;
+        transport?: "http" | "subprocess" | undefined;
+    } | undefined;
+    fallback?: ("fast" | "smart" | "powerful" | "cheap" | "vision" | "embedding" | {
+        provider: string;
+        model: string;
+        transport: "http" | "subprocess";
+    })[] | undefined;
+    purpose?: string | undefined;
+}>;
+declare const translateInputSchema: z.ZodObject<{
+    tier: z.ZodOptional<z.ZodEnum<["fast", "smart", "powerful", "cheap", "vision", "embedding"]>>;
+    override: z.ZodOptional<z.ZodObject<{
+        provider: z.ZodOptional<z.ZodString>;
+        model: z.ZodOptional<z.ZodString>;
+        transport: z.ZodOptional<z.ZodEnum<["http", "subprocess"]>>;
+    }, "strip", z.ZodTypeAny, {
+        provider?: string | undefined;
+        model?: string | undefined;
+        transport?: "http" | "subprocess" | undefined;
+    }, {
+        provider?: string | undefined;
+        model?: string | undefined;
+        transport?: "http" | "subprocess" | undefined;
+    }>>;
+    fallback: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodEnum<["fast", "smart", "powerful", "cheap", "vision", "embedding"]>, z.ZodObject<{
+        provider: z.ZodString;
+        model: z.ZodString;
+        transport: z.ZodEnum<["http", "subprocess"]>;
+    }, "strip", z.ZodTypeAny, {
+        provider: string;
+        model: string;
+        transport: "http" | "subprocess";
+    }, {
+        provider: string;
+        model: string;
+        transport: "http" | "subprocess";
+    }>]>, "many">>;
+    purpose: z.ZodOptional<z.ZodString>;
+    text: z.ZodString;
+    to: z.ZodString;
+    from: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    text: string;
+    to: string;
+    tier?: "fast" | "smart" | "powerful" | "cheap" | "vision" | "embedding" | undefined;
+    override?: {
+        provider?: string | undefined;
+        model?: string | undefined;
+        transport?: "http" | "subprocess" | undefined;
+    } | undefined;
+    fallback?: ("fast" | "smart" | "powerful" | "cheap" | "vision" | "embedding" | {
+        provider: string;
+        model: string;
+        transport: "http" | "subprocess";
+    })[] | undefined;
+    purpose?: string | undefined;
+    from?: string | undefined;
+}, {
+    text: string;
+    to: string;
+    tier?: "fast" | "smart" | "powerful" | "cheap" | "vision" | "embedding" | undefined;
+    override?: {
+        provider?: string | undefined;
+        model?: string | undefined;
+        transport?: "http" | "subprocess" | undefined;
+    } | undefined;
+    fallback?: ("fast" | "smart" | "powerful" | "cheap" | "vision" | "embedding" | {
+        provider: string;
+        model: string;
+        transport: "http" | "subprocess";
+    })[] | undefined;
+    purpose?: string | undefined;
+    from?: string | undefined;
+}>;
+declare const imageInputSchema: z.ZodObject<{
+    tier: z.ZodOptional<z.ZodEnum<["fast", "smart", "powerful", "cheap", "vision", "embedding"]>>;
+    override: z.ZodOptional<z.ZodObject<{
+        provider: z.ZodOptional<z.ZodString>;
+        model: z.ZodOptional<z.ZodString>;
+        transport: z.ZodOptional<z.ZodEnum<["http", "subprocess"]>>;
+    }, "strip", z.ZodTypeAny, {
+        provider?: string | undefined;
+        model?: string | undefined;
+        transport?: "http" | "subprocess" | undefined;
+    }, {
+        provider?: string | undefined;
+        model?: string | undefined;
+        transport?: "http" | "subprocess" | undefined;
+    }>>;
+    fallback: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodEnum<["fast", "smart", "powerful", "cheap", "vision", "embedding"]>, z.ZodObject<{
+        provider: z.ZodString;
+        model: z.ZodString;
+        transport: z.ZodEnum<["http", "subprocess"]>;
+    }, "strip", z.ZodTypeAny, {
+        provider: string;
+        model: string;
+        transport: "http" | "subprocess";
+    }, {
+        provider: string;
+        model: string;
+        transport: "http" | "subprocess";
+    }>]>, "many">>;
+    purpose: z.ZodOptional<z.ZodString>;
+    prompt: z.ZodString;
+    width: z.ZodOptional<z.ZodNumber>;
+    height: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    prompt: string;
+    tier?: "fast" | "smart" | "powerful" | "cheap" | "vision" | "embedding" | undefined;
+    override?: {
+        provider?: string | undefined;
+        model?: string | undefined;
+        transport?: "http" | "subprocess" | undefined;
+    } | undefined;
+    fallback?: ("fast" | "smart" | "powerful" | "cheap" | "vision" | "embedding" | {
+        provider: string;
+        model: string;
+        transport: "http" | "subprocess";
+    })[] | undefined;
+    purpose?: string | undefined;
+    width?: number | undefined;
+    height?: number | undefined;
+}, {
+    prompt: string;
+    tier?: "fast" | "smart" | "powerful" | "cheap" | "vision" | "embedding" | undefined;
+    override?: {
+        provider?: string | undefined;
+        model?: string | undefined;
+        transport?: "http" | "subprocess" | undefined;
+    } | undefined;
+    fallback?: ("fast" | "smart" | "powerful" | "cheap" | "vision" | "embedding" | {
+        provider: string;
+        model: string;
+        transport: "http" | "subprocess";
+    })[] | undefined;
+    purpose?: string | undefined;
+    width?: number | undefined;
+    height?: number | undefined;
+}>;
+declare const embeddingInputSchema: z.ZodObject<{
+    tier: z.ZodOptional<z.ZodEnum<["fast", "smart", "powerful", "cheap", "vision", "embedding"]>>;
+    override: z.ZodOptional<z.ZodObject<{
+        provider: z.ZodOptional<z.ZodString>;
+        model: z.ZodOptional<z.ZodString>;
+        transport: z.ZodOptional<z.ZodEnum<["http", "subprocess"]>>;
+    }, "strip", z.ZodTypeAny, {
+        provider?: string | undefined;
+        model?: string | undefined;
+        transport?: "http" | "subprocess" | undefined;
+    }, {
+        provider?: string | undefined;
+        model?: string | undefined;
+        transport?: "http" | "subprocess" | undefined;
+    }>>;
+    fallback: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodEnum<["fast", "smart", "powerful", "cheap", "vision", "embedding"]>, z.ZodObject<{
+        provider: z.ZodString;
+        model: z.ZodString;
+        transport: z.ZodEnum<["http", "subprocess"]>;
+    }, "strip", z.ZodTypeAny, {
+        provider: string;
+        model: string;
+        transport: "http" | "subprocess";
+    }, {
+        provider: string;
+        model: string;
+        transport: "http" | "subprocess";
+    }>]>, "many">>;
+    purpose: z.ZodOptional<z.ZodString>;
+    text: z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>;
+}, "strip", z.ZodTypeAny, {
+    text: string | string[];
+    tier?: "fast" | "smart" | "powerful" | "cheap" | "vision" | "embedding" | undefined;
+    override?: {
+        provider?: string | undefined;
+        model?: string | undefined;
+        transport?: "http" | "subprocess" | undefined;
+    } | undefined;
+    fallback?: ("fast" | "smart" | "powerful" | "cheap" | "vision" | "embedding" | {
+        provider: string;
+        model: string;
+        transport: "http" | "subprocess";
+    })[] | undefined;
+    purpose?: string | undefined;
+}, {
+    text: string | string[];
+    tier?: "fast" | "smart" | "powerful" | "cheap" | "vision" | "embedding" | undefined;
+    override?: {
+        provider?: string | undefined;
+        model?: string | undefined;
+        transport?: "http" | "subprocess" | undefined;
+    } | undefined;
+    fallback?: ("fast" | "smart" | "powerful" | "cheap" | "vision" | "embedding" | {
+        provider: string;
+        model: string;
+        transport: "http" | "subprocess";
+    })[] | undefined;
+    purpose?: string | undefined;
+}>;
+declare const transcribeInputSchema: z.ZodObject<{
+    tier: z.ZodOptional<z.ZodEnum<["fast", "smart", "powerful", "cheap", "vision", "embedding"]>>;
+    override: z.ZodOptional<z.ZodObject<{
+        provider: z.ZodOptional<z.ZodString>;
+        model: z.ZodOptional<z.ZodString>;
+        transport: z.ZodOptional<z.ZodEnum<["http", "subprocess"]>>;
+    }, "strip", z.ZodTypeAny, {
+        provider?: string | undefined;
+        model?: string | undefined;
+        transport?: "http" | "subprocess" | undefined;
+    }, {
+        provider?: string | undefined;
+        model?: string | undefined;
+        transport?: "http" | "subprocess" | undefined;
+    }>>;
+    fallback: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodEnum<["fast", "smart", "powerful", "cheap", "vision", "embedding"]>, z.ZodObject<{
+        provider: z.ZodString;
+        model: z.ZodString;
+        transport: z.ZodEnum<["http", "subprocess"]>;
+    }, "strip", z.ZodTypeAny, {
+        provider: string;
+        model: string;
+        transport: "http" | "subprocess";
+    }, {
+        provider: string;
+        model: string;
+        transport: "http" | "subprocess";
+    }>]>, "many">>;
+    purpose: z.ZodOptional<z.ZodString>;
+    /** Audio URL or raw bytes. */
+    audio: z.ZodUnion<[z.ZodString, z.ZodType<Uint8Array<ArrayBuffer>, z.ZodTypeDef, Uint8Array<ArrayBuffer>>]>;
+    language: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    audio: string | Uint8Array<ArrayBuffer>;
+    language?: string | undefined;
+    tier?: "fast" | "smart" | "powerful" | "cheap" | "vision" | "embedding" | undefined;
+    override?: {
+        provider?: string | undefined;
+        model?: string | undefined;
+        transport?: "http" | "subprocess" | undefined;
+    } | undefined;
+    fallback?: ("fast" | "smart" | "powerful" | "cheap" | "vision" | "embedding" | {
+        provider: string;
+        model: string;
+        transport: "http" | "subprocess";
+    })[] | undefined;
+    purpose?: string | undefined;
+}, {
+    audio: string | Uint8Array<ArrayBuffer>;
+    language?: string | undefined;
+    tier?: "fast" | "smart" | "powerful" | "cheap" | "vision" | "embedding" | undefined;
+    override?: {
+        provider?: string | undefined;
+        model?: string | undefined;
+        transport?: "http" | "subprocess" | undefined;
+    } | undefined;
+    fallback?: ("fast" | "smart" | "powerful" | "cheap" | "vision" | "embedding" | {
+        provider: string;
+        model: string;
+        transport: "http" | "subprocess";
+    })[] | undefined;
+    purpose?: string | undefined;
+}>;
+declare const aiConfigSchema: z.ZodObject<{
+    defaults: z.ZodOptional<z.ZodRecord<z.ZodEnum<["fast", "smart", "powerful", "cheap", "vision", "embedding"]>, z.ZodObject<{
+        provider: z.ZodString;
+        model: z.ZodString;
+        transport: z.ZodEnum<["http", "subprocess"]>;
+    }, "strip", z.ZodTypeAny, {
+        provider: string;
+        model: string;
+        transport: "http" | "subprocess";
+    }, {
+        provider: string;
+        model: string;
+        transport: "http" | "subprocess";
+    }>>>;
+    providers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<ProviderAdapter, z.ZodTypeDef, ProviderAdapter>>>;
+    costSink: z.ZodOptional<z.ZodType<CostSink, z.ZodTypeDef, CostSink>>;
+    budget: z.ZodOptional<z.ZodObject<{
+        perCallUsd: z.ZodOptional<z.ZodNumber>;
+        rollingUsd: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        perCallUsd?: number | undefined;
+        rollingUsd?: number | undefined;
+    }, {
+        perCallUsd?: number | undefined;
+        rollingUsd?: number | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    defaults?: Partial<Record<"fast" | "smart" | "powerful" | "cheap" | "vision" | "embedding", {
+        provider: string;
+        model: string;
+        transport: "http" | "subprocess";
+    }>> | undefined;
+    providers?: Record<string, ProviderAdapter> | undefined;
+    costSink?: CostSink | undefined;
+    budget?: {
+        perCallUsd?: number | undefined;
+        rollingUsd?: number | undefined;
+    } | undefined;
+}, {
+    defaults?: Partial<Record<"fast" | "smart" | "powerful" | "cheap" | "vision" | "embedding", {
+        provider: string;
+        model: string;
+        transport: "http" | "subprocess";
+    }>> | undefined;
+    providers?: Record<string, ProviderAdapter> | undefined;
+    costSink?: CostSink | undefined;
+    budget?: {
+        perCallUsd?: number | undefined;
+        rollingUsd?: number | undefined;
+    } | undefined;
+}>;
+type ChatInput = z.infer<typeof chatInputSchema>;
+type VisionInput = z.infer<typeof visionInputSchema>;
+type TranslateInput = z.infer<typeof translateInputSchema>;
+type ImageInput = z.infer<typeof imageInputSchema>;
+type EmbeddingInput = z.infer<typeof embeddingInputSchema>;
+type TranscribeInput = z.infer<typeof transcribeInputSchema>;
+type AiConfig = z.infer<typeof aiConfigSchema>;
+/** The public facade. Defined here because it depends on the derived inputs. */
+interface AiClient {
+    chat(input: ChatInput): Promise<ChatResult>;
+    vision(input: VisionInput): Promise<ChatResult>;
+    translate(input: TranslateInput): Promise<TranslateResult>;
+    image(input: ImageInput): Promise<ImageResult>;
+    embedding(input: EmbeddingInput): Promise<EmbeddingResult>;
+    transcribe(input: TranscribeInput): Promise<TranscribeResult>;
+    /** Prompt-contract capabilities (F5.5) layered on chat/vision. */
+    contracts: Contracts;
+}
+
+declare function createAI(config?: AiConfig): AiClient;
+
+/** Pull the first JSON value out of a model reply (tolerates ```json fences + prose). */
+declare function parseJsonLoose(text: string): unknown;
+type ChatVision = Pick<AiClient, "chat" | "vision">;
+declare function makeContracts(client: ChatVision): Contracts;
+
+/** Convert SDK tools to a provider's request format. */
+declare function toProviderTools(tools: Tool[], provider: string): unknown;
+/** Parse a single provider-shaped tool call back into the SDK ToolCall shape. */
+declare function fromProviderToolCall(raw: unknown, provider: string): ToolCall;
+
+declare function anthropicAdapter(config?: {
+    apiKey?: string;
+    baseUrl?: string;
+    anthropicVersion?: string;
+}): ProviderAdapter;
+
+declare function openaiAdapter(config?: {
+    apiKey?: string;
+    baseUrl?: string;
+    fetch?: typeof fetch;
+}): ProviderAdapter;
+
+declare function geminiAdapter(config?: {
+    apiKey?: string;
+    baseUrl?: string;
+}): ProviderAdapter;
+
+declare function deepinfraAdapter(config?: {
+    apiKey?: string;
+    baseUrl?: string;
+}): ProviderAdapter;
+
+declare function openrouterAdapter(config?: {
+    apiKey?: string;
+    baseUrl?: string;
+    referer?: string;
+    title?: string;
+}): ProviderAdapter;
+
+interface FalAdapterConfig {
+    apiKey?: string;
+    /** "sync" (default — fal.run, fast models) or "queue" (queue.fal.run, polled). */
+    mode?: "sync" | "queue";
+    syncBaseUrl?: string;
+    queueBaseUrl?: string;
+    pollIntervalMs?: number;
+    timeoutMs?: number;
+    fetch?: typeof fetch;
+}
+declare function falAdapter(config?: FalAdapterConfig): ProviderAdapter;
+
+interface OpenAICompatibleConfig {
+    /** Provider name recorded on Usage (e.g. "openai", "deepinfra", "openrouter"). */
+    name: string;
+    /** Chat completions base, e.g. "https://api.openai.com/v1". */
+    baseUrl: string;
+    /** Resolved at call time if omitted (env var per provider). */
+    apiKey?: string;
+    /** Extra headers (e.g. OpenRouter's HTTP-Referer / X-Title). */
+    extraHeaders?: Record<string, string>;
+}
+declare function makeOpenAICompatibleAdapter(config: OpenAICompatibleConfig): ProviderAdapter;
+
+declare const defaultProviders: Record<string, ProviderAdapter>;
+
+/** Anthropic adapter stub (HTTP path). */
+declare const anthropicApiAdapter: ProviderAdapter;
+/** Anthropic adapter stub (subprocess / `claude -p` path). */
+declare const anthropicSubprocessAdapter: ProviderAdapter;
+/** OpenAI adapter stub — covers the embedding default tier + a chat fallback. */
+declare const openaiStubAdapter: ProviderAdapter;
+/** fal.ai adapter stub — image generation (real one in fal.ts, F5.3). */
+declare const falStubAdapter: ProviderAdapter;
+/** Stub provider registry — deterministic, no network. Used by tests via
+ *  createAI({ providers: stubProviders }). The real default registry (registry.ts)
+ *  wires the live adapters. */
+declare const stubProviders: Record<string, ProviderAdapter>;
+
+declare const VERSION: "0.1.0";
+declare const SDK_TAG: "@broberg/ai-sdk@0.1.0";
+
+/** Built-in defaults. Every entry is overridable via AiConfig.defaults or a
+ *  per-call override. Model IDs are current at scaffold time; callers pin their
+ *  own via config. `cheap` routes through the local `claude -p` subprocess
+ *  (Max plan → costUsd 0); everything else is HTTP. */
+declare const DEFAULT_TIER_MAP: Record<Tier, TierSpec>;
+/**
+ * Resolve a Tier to a concrete TierSpec.
+ *
+ * Merge order (later wins): DEFAULT_TIER_MAP < configMap < override.
+ * - `configMap` is the client-level AiConfig.defaults (per-tier full specs).
+ * - `override` is a per-call Partial<TierSpec> — only the fields it sets win.
+ */
+declare function resolveTier(tier: Tier, override?: Partial<TierSpec>, configMap?: Partial<Record<Tier, TierSpec>>): TierSpec;
+
+/**
+ * Cost in USD for a call. cache-read/creation tokens are priced separately when
+ * the pricing entry defines rates for them; otherwise they fall back to the
+ * input rate (read) / are ignored (creation). Unknown model → 0.
+ */
+declare function computeCost(provider: string, model: string, inputTokens: number, outputTokens: number, cacheReadTokens?: number, cacheCreationTokens?: number): number;
+/** Build a Usage with cost computed from the pricing table. Adapters call this
+ *  after a successful provider call; latencyMs/ts/capability are stamped by the
+ *  client (call-context owner), so they default to 0/""/the passed capability. */
+declare function freshUsage(args: {
+    provider: string;
+    model: string;
+    transport: Transport;
+    capability: Capability;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens?: number;
+    cacheCreationTokens?: number;
+    subprocess?: boolean;
+}): Usage;
+
+declare class BudgetExceededError extends Error {
+    readonly kind: "per-call" | "rolling";
+    readonly limit: number;
+    readonly spent: number;
+    readonly requested: number;
+    constructor(kind: "per-call" | "rolling", limit: number, spent: number, requested: number);
+}
+declare class BudgetGuard {
+    private readonly config;
+    private spentUsd;
+    constructor(config: BudgetConfig);
+    /** Throws BudgetExceededError if `requested` would breach the per-call ceiling
+     *  or push the rolling total past its ceiling. Call before firing the request. */
+    check(requested: number): void;
+    /** Add an actual cost to the running total (after a successful call). */
+    record(actual: number): void;
+    get totalSpent(): number;
+}
+
+/** A sink that does nothing. The default when no costSink is configured. */
+declare const noopSink: CostSink;
+
+/** Fan a Usage out to several sinks. Uses allSettled so one failing sink never
+ *  prevents the others from recording (and never propagates to the caller). */
+declare function multiSink(sinks: CostSink[]): CostSink;
+
+interface UpmetricsSinkConfig {
+    /** Ingest base URL, e.g. https://upmetrics.org */
+    baseUrl: string;
+    /** Per-project api_key → sent as the X-Upmetrics-Key header. */
+    apiKey: string;
+    /** Consumer name dashboards group by (e.g. "cms", "trail", "xrt81") — NOT the
+     *  capability. */
+    agentName: string;
+    /** Defaults to "chatbot" ("embedding" auto-selected for embedding calls). */
+    agentKind?: string;
+    /** When true, guarantees no prompt/response content is ever sent (the sink
+     *  sends none regardless — Usage carries no excerpts — so this is belt-and-
+     *  suspenders for GDPR-health projects). */
+    complianceMode?: boolean;
+    /** Injectable fetch for testing; defaults to global fetch. */
+    fetch?: typeof fetch;
+    /** Optional error hook (errors are otherwise swallowed silently). */
+    onError?: (err: unknown) => void;
+}
+declare function upmetricsSink(config: UpmetricsSinkConfig): CostSink;
+
+interface DiscordSinkConfig {
+    webhookUrl: string;
+    /** Skip posting paid calls below this USD threshold (anti-spam). Subprocess
+     *  (Max-plan free) calls always post so the "free" feed stays visible.
+     *  Default 0 → post everything. */
+    minUsd?: number;
+    fetch?: typeof fetch;
+    onError?: (err: unknown) => void;
+}
+declare function discordSink(config: DiscordSinkConfig): CostSink;
+
+interface SqliteSinkConfig {
+    /** Path to the SQLite file, e.g. "./ai-cost.db" (or ":memory:"). */
+    dbPath: string;
+}
+declare function sqliteSink(config: SqliteSinkConfig): CostSink;
+interface CostSummary {
+    totalUsd: number;
+    byProvider: Record<string, number>;
+    byCapability: Record<string, number>;
+}
+/** Aggregate the recorded spend from a sqliteSink DB. */
+declare function getCostSummary(dbPath: string): CostSummary;
+
+interface PricingEntry {
+    /** USD per 1M input tokens. */
+    inputPer1M: number;
+    /** USD per 1M output tokens. */
+    outputPer1M: number;
+    /** USD per 1M cache-read tokens (falls back to input rate if unset). */
+    cacheReadPer1M?: number;
+    /** USD per 1M cache-write/creation tokens (falls back to input rate if unset). */
+    cacheWritePer1M?: number;
+    /** Pricing snapshot version (date or tag) so stale entries are detectable. */
+    version: string;
+}
+declare function getPrice(provider: string, model: string): PricingEntry | undefined;
+
+interface TransportRequest {
+    /** Resolved routing for this call (transport field selects the path). */
+    spec: TierSpec;
+    /** HTTP details — required when spec.transport === "http". The adapter has
+     *  already built the provider-specific URL/headers/body. */
+    http?: {
+        url: string;
+        method?: string;
+        headers?: Record<string, string>;
+        body?: unknown;
+    };
+    /** Subprocess details — required when spec.transport === "subprocess". */
+    subprocess?: {
+        prompt: string;
+        systemPrompt?: string;
+    };
+}
+/** HTTP transport result — raw, unparsed. The adapter reads text + token usage
+ *  out of `json` (shapes differ per provider). */
+interface HttpResponse {
+    ok: boolean;
+    status: number;
+    json: unknown;
+}
+/** Subprocess transport result — already normalized from the `claude -p` JSON.
+ *  costUsd is always 0 (Max plan is not a metered charge); subprocess flags it. */
+interface SubprocessResponse {
+    text: string;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+    costUsd: 0;
+    subprocess: true;
+}
+type TransportResponse = HttpResponse | SubprocessResponse;
+
+declare function httpTransport(req: TransportRequest): Promise<HttpResponse>;
+
+/** Pure parser for the `claude -p --output-format json` stdout. Exported so it
+ *  can be unit-tested without spawning the binary. costUsd is pinned to 0. */
+declare function parseClaudeCliJson(raw: string): SubprocessResponse;
+declare function subprocessTransport(req: TransportRequest): Promise<SubprocessResponse>;
+
+export { type AiClient, type AiConfig, type BudgetConfig, BudgetExceededError, BudgetGuard, type CallOptions, type Capability, type ChatInput, type ChatRequest, type ChatResult, type ClassifyInput, type ClassifyResult, type ContentPart, type Contracts, type CostSink, type CostSummary, DEFAULT_TIER_MAP, type DesignInput, type DesignResult, type DiscordSinkConfig, type EmbeddingInput, type EmbeddingRequest, type EmbeddingResult, type ExtractInput, type ExtractResult, type FalAdapterConfig, type HttpResponse, type ImageInput, type ImageRequest, type ImageResult, type Message, type MockupInput, type MockupResult, type OpenAICompatibleConfig, type PricingEntry, type ProviderAdapter, type RerankInput, type RerankResult, type Role, SDK_TAG, type SqliteSinkConfig, type SubprocessResponse, type Tier, type TierSpec, type Tool, type ToolCall, type TranscribeInput, type TranscribeRequest, type TranscribeResult, type TranslateInput, type TranslateResult, type Transport, type TransportRequest, type TransportResponse, type UpmetricsSinkConfig, type Usage, VERSION, type VisionInput, aiConfigSchema, anthropicAdapter, anthropicApiAdapter, anthropicSubprocessAdapter, chatInputSchema, computeCost, createAI, deepinfraAdapter, defaultProviders, discordSink, embeddingInputSchema, falAdapter, falStubAdapter, freshUsage, fromProviderToolCall, geminiAdapter, getCostSummary, getPrice, httpTransport, imageInputSchema, makeContracts, makeOpenAICompatibleAdapter, messageSchema, multiSink, noopSink, openaiAdapter, openaiStubAdapter, openrouterAdapter, parseClaudeCliJson, parseJsonLoose, resolveTier, sqliteSink, stubProviders, subprocessTransport, tierSpecSchema, toProviderTools, toolSchema, translateInputSchema, upmetricsSink, visionInputSchema };