indusagi 0.12.32 → 0.12.33

package/dist/types/llmgateway/connectors/google.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Google Generative AI connector (Gemini family).
+ *
+ * Speaks Google's native `streamGenerateContent` dialect rather than the
+ * OpenAI Chat Completions shape, so this connector owns its own streaming loop
+ * instead of delegating to {@link streamOpenAICompatibleChat}. The request body
+ * is assembled from the shared {@link toGoogleContents} /
+ * {@link toGoogleSystemInstruction} / {@link toGoogleTools} mappers plus a
+ * `generationConfig` block; the SSE response is decoded with the foundation's
+ * {@link sseEvents} framer and the resulting deltas are folded into a single
+ * {@link Reply} by {@link foldReply}.
+ *
+ * Wire shape (re-derived from Google's public Generative Language REST docs):
+ *
+ *   POST {baseUrl}/v1beta/models/{model.id}:streamGenerateContent?alt=sse
+ *   x-goog-api-key: <key>
+ *   { contents, systemInstruction?, tools?, generationConfig: { ... } }
+ *
+ *   data: {"candidates":[{"content":{"parts":[{"text":"..."}]},
+ *           "finishReason":"STOP"}],"usageMetadata":{...}}
+ *
+ * Serves the `google` provider's `google-generative` cards:
+ * `gemini-2.5-pro` and `gemini-2.5-flash`.
+ */
+import type { CredentialResolver, Connector } from "../contract";
+/** Dependencies injected into the connector factory. */
+interface GoogleConnectorDeps {
+    /** Resolve the API key for a provider, honoring an explicit override. */
+    readonly resolveSecret: CredentialResolver["resolve"];
+}
+/**
+ * Build a {@link Connector} for Google Generative AI.
+ *
+ * The API key is resolved lazily, on the first iteration of {@link stream}, via
+ * the injected `resolveSecret`. A missing key surfaces as an `auth`
+ * {@link GatewayError} carried on a terminal `error` emission, keeping the
+ * channel non-throwing like every other connector.
+ */
+export declare function creategoogleConnector(deps: GoogleConnectorDeps): Connector;
+export {};

package/dist/types/llmgateway/connectors/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Connector registry.
+ *
+ * One {@link Connector} instance per {@link ApiKind} wire dialect, each built
+ * from its factory and wired to the real environment-backed credential
+ * resolver. The registry is the gateway's routing table: given a card's `api`,
+ * {@link connectorForApi} returns the connector that speaks that dialect.
+ *
+ * Every connector factory takes the same dependency bag (`{ resolveSecret }`),
+ * so they are all constructed uniformly here with {@link resolveSecret} from the
+ * credentials module.
+ */
+import type { ApiKind, Connector } from "../contract";
+/**
+ * The complete routing table: every {@link ApiKind} mapped to a live
+ * {@link Connector}. Total over `ApiKind`, so {@link connectorForApi} can never
+ * miss a known dialect.
+ */
+export declare const CONNECTOR_REGISTRY: Readonly<Record<ApiKind, Connector>>;
+/**
+ * Resolve the connector that speaks a given wire dialect.
+ *
+ * The registry is total over {@link ApiKind}, so this always returns a
+ * connector for any statically-valid `api`.
+ */
+export declare function connectorForApi(api: ApiKind): Connector;

package/dist/types/llmgateway/connectors/kimi.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Kimi (Moonshot AI) connector.
+ *
+ * Moonshot's Kimi models are served over the OpenAI Chat Completions dialect,
+ * so this connector is a thin adapter: it resolves the Moonshot bearer key,
+ * points the request at `{baseUrl}/chat/completions`, and hands every byte of
+ * wire work — request assembly, SSE decoding, chunk→emission translation — to
+ * the shared {@link streamOpenAICompatibleChat} streamer. Nothing about the
+ * stream parsing is re-implemented here.
+ *
+ * Serves: catalog cards whose `api` is `kimi-openai-compatible` (provider
+ * `kimi`), e.g. `kimi-k2`. The bearer key comes from `MOONSHOT_API_KEY` (or
+ * `KIMI_API_KEY`), or a per-call `options.apiKey` override.
+ */
+import type { Connector, CredentialResolver } from "../contract";
+/** Dependencies this connector pulls from the gateway runtime. */
+export interface KimiDeps {
+    /** Resolves the Moonshot bearer key, honoring a per-call override. */
+    readonly resolveSecret: CredentialResolver["resolve"];
+}
+/**
+ * Build a Kimi (Moonshot) {@link Connector}.
+ *
+ * The lone dependency is the credential resolver (typically
+ * `environmentCredentialResolver.resolve`), injected so the connector stays
+ * free of ambient environment access and is trivial to fake in tests.
+ */
+export declare function createkimiConnector(deps: KimiDeps): Connector;

package/dist/types/llmgateway/connectors/mock.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Mock connector.
+ *
+ * A deterministic, network-free dialect used by the gateway smoke test. It
+ * never opens a socket and never reads a credential — it replays one of two
+ * fixed transcripts chosen from the {@link Conversation}:
+ *   - When the caller offers the `echo` tool and this is the first turn, it
+ *     streams "Hello"/" world", a scripted `echo` tool call, usage, and a
+ *     `tool_calls` stop — exercising the gateway's tool-call streaming.
+ *   - Otherwise (no `echo` offered, or a continuation turn that already carries a
+ *     tool result), it streams a prose answer and a `complete` stop, so a driving
+ *     agent loop converges instead of re-requesting the tool forever.
+ * Each path ends with a terminal `done` carrying the fully folded {@link Reply}.
+ *
+ * Serves: the catalog's `mock` provider card (`mock-1`, api `mock`).
+ * `options.signal` short-circuits the replay with an `aborted` reply so
+ * cancellation stays honest.
+ */
+import type { Connector, CredentialResolver } from "../contract";
+/** Dependencies the gateway injects into the mock connector. */
+export interface MockDeps {
+    /**
+     * Credential resolver. The mock dialect needs no secret, so this is accepted
+     * purely to keep the factory shape uniform with the live connectors; it is
+     * never invoked.
+     */
+    readonly resolveSecret: CredentialResolver["resolve"];
+}
+/**
+ * Build the mock {@link Connector}.
+ *
+ * Mirrors the live connector factories' shape — it accepts the credential
+ * resolver — but the deterministic transcript means no secret is ever read and
+ * no network call is ever made. The happy path is the only path, so there is no
+ * gateway error to surface.
+ */
+export declare function createmockConnector(deps: MockDeps): Connector;

package/dist/types/llmgateway/connectors/nvidia.d.ts

@@ -0,0 +1,27 @@
+/**
+ * NVIDIA NIM connector.
+ *
+ * Serves the `nvidia-openai-compatible` cards in the catalog — currently
+ * `nvidia/llama-3.1-nemotron-70b-instruct` — against the hosted NIM gateway at
+ * `https://integrate.api.nvidia.com/v1`. NVIDIA speaks the OpenAI Chat
+ * Completions dialect, so this connector is a thin adapter: it resolves the
+ * bearer credential, points the shared {@link streamOpenAICompatibleChat}
+ * streamer at the right endpoint with the right headers, and — for reasoning
+ * cards — opts into NVIDIA's thinking trace via the provider-specific
+ * `chat_template_kwargs.thinking` body field. All wire work (request assembly,
+ * SSE decoding, chunk→emission translation) is owned by the shared streamer.
+ */
+import type { Connector, CredentialResolver } from "../contract";
+/** Dependencies the NVIDIA connector pulls from the gateway runtime. */
+export interface NvidiaConnectorDeps {
+    /** Resolves the NVIDIA bearer key, honoring a per-call override. */
+    readonly resolveSecret: CredentialResolver["resolve"];
+}
+/**
+ * Build an NVIDIA NIM {@link Connector}.
+ *
+ * The lone dependency is the credential resolver (typically
+ * `environmentCredentialResolver.resolve`), injected so the connector stays
+ * free of ambient environment access and is trivial to fake under test.
+ */
+export declare function createnvidiaConnector(deps: NvidiaConnectorDeps): Connector;

package/dist/types/llmgateway/connectors/ollama.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Ollama connector (local inference daemon).
+ *
+ * Ollama exposes a chat endpoint that accepts OpenAI-style messages and tool
+ * definitions but answers in newline-delimited JSON rather than SSE. Because of
+ * that framing difference this connector cannot ride the shared
+ * {@link streamOpenAICompatibleChat} streamer — it owns its own loop, decoding
+ * the body with the foundation's {@link ndjsonLines} reader and folding the
+ * deltas into a {@link Reply} via {@link foldReply}.
+ *
+ * Wire shape (re-derived from Ollama's public `/api/chat` docs):
+ *
+ *   POST {baseUrl||http://localhost:11434}/api/chat
+ *   { model, messages, tools?, stream: true, options? }
+ *
+ *   {"message":{"content":"par"},"done":false}
+ *   {"message":{"content":"tial"},"done":false}
+ *   {"message":{"role":"assistant","content":"",
+ *     "tool_calls":[{"function":{"name":"f","arguments":{"a":1}}}]},"done":false}
+ *   {"message":{"content":""},"done":true,"done_reason":"stop",
+ *     "prompt_eval_count":11,"eval_count":42}
+ *
+ * Serves the single `ollama` card in the catalog: `llama3.1:8b`. Pricing is
+ * zero (it runs on the caller's own hardware), and the daemon is unauthenticated
+ * by default, so the resolved secret is sent as a bearer token only when one is
+ * actually present (handy for reverse-proxied deployments that do gate access).
+ */
+import type { Connector, CredentialResolver } from "../contract";
+/** Dependencies injected into the connector factory. */
+interface OllamaConnectorDeps {
+    /** Resolve the (optional) bearer secret, honoring a per-call override. */
+    readonly resolveSecret: CredentialResolver["resolve"];
+}
+/**
+ * Build a {@link Connector} for the Ollama local inference daemon.
+ *
+ * `stream()` resolves the optional bearer secret lazily on first iteration,
+ * POSTs the chat request, then walks the NDJSON body line by line, translating
+ * each into neutral {@link Emission}s and closing with a terminal `done`
+ * carrying the folded {@link Reply}. Any failure is delivered as a terminal
+ * `error` emission so the channel never throws. `complete()` simply drains that
+ * same channel, keeping both entry points on one code path.
+ */
+export declare function createollamaConnector(deps: OllamaConnectorDeps): Connector;
+export {};

package/dist/types/llmgateway/connectors/openai-chat.d.ts

@@ -0,0 +1,25 @@
+/**
+ * OpenAI Chat Completions connector.
+ *
+ * Serves the `openai-completions` cards in the catalog — `gpt-4o` and
+ * `gpt-4o-mini` — by speaking the canonical OpenAI `/chat/completions` dialect.
+ * It is a thin wrapper: all request assembly, SSE decoding, and chunk→emission
+ * translation live in the shared {@link streamOpenAICompatibleChat} streamer.
+ * This module's only jobs are resolving the bearer credential, pointing the
+ * streamer at the right URL with the right headers, and exposing the
+ * {@link Connector} surface.
+ */
+import type { Connector, CredentialResolver } from "../contract";
+/** Dependencies this connector needs from the gateway runtime. */
+export interface OpenAIChatDeps {
+    /** Resolves the OpenAI bearer key (honoring a per-call override). */
+    readonly resolveSecret: CredentialResolver["resolve"];
+}
+/**
+ * Build an OpenAI Chat Completions {@link Connector}.
+ *
+ * The single dependency is the credential resolver (typically
+ * `environmentCredentialResolver.resolve`), injected so the connector stays
+ * free of ambient environment access and is trivial to fake in tests.
+ */
+export declare function createopenaichatConnector(deps: OpenAIChatDeps): Connector;

package/dist/types/llmgateway/connectors/openai-responses.d.ts

@@ -0,0 +1,49 @@
+/**
+ * OpenAI Responses connector.
+ *
+ * Speaks the OpenAI **Responses** dialect (`POST /v1/responses`), which the
+ * o-series reasoning models (`o3`, `o4-mini`) expose. Unlike the Chat
+ * Completions dialect, the Responses stream is a sequence of *typed* server
+ * events — each SSE payload is a JSON object whose `type` field names a discrete
+ * lifecycle step (`response.output_text.delta`, `response.completed`, …) rather
+ * than an opaque chat chunk. Because of that distinct shape this connector runs
+ * its own decode loop instead of delegating to the shared Chat Completions
+ * streamer.
+ *
+ * Wire shape (re-derived from OpenAI's public Responses docs):
+ *
+ *   POST {baseUrl||https://api.openai.com/v1}/responses
+ *   Authorization: Bearer <key>
+ *   { "model": "...", "input": [...], "tools": [...], "stream": true,
+ *     "reasoning": { "effort": "medium" } }
+ *
+ *   event: response.output_text.delta
+ *   data: {"type":"response.output_text.delta","delta":"Hel"}
+ *
+ *   event: response.output_item.added
+ *   data: {"type":"response.output_item.added",
+ *          "item":{"type":"function_call","name":"f","call_id":"call_x"}}
+ *
+ *   event: response.function_call_arguments.delta
+ *   data: {"type":"response.function_call_arguments.delta",
+ *          "item_id":"...","delta":"{\"a"}
+ *
+ *   event: response.completed
+ *   data: {"type":"response.completed",
+ *          "response":{"status":"completed","usage":{...}}}
+ */
+import type { Connector, CredentialResolver } from "../contract";
+/** Injected dependencies — only credential resolution is required. */
+export interface OpenAiResponsesDeps {
+    /** Resolves the bearer key, honoring a per-call override first. */
+    readonly resolveSecret: CredentialResolver["resolve"];
+}
+/**
+ * Build an OpenAI Responses {@link Connector}.
+ *
+ * Serves the reasoning-capable o-series cards whose `api` is `openai-responses`
+ * — `o3` and `o4-mini` in the catalog. The bearer key is resolved lazily on
+ * each call through the injected {@link CredentialResolver.resolve}, honoring a
+ * per-invocation `options.apiKey` override.
+ */
+export declare function createopenairesponsesConnector(deps: OpenAiResponsesDeps): Connector;

package/dist/types/llmgateway/contract/connector.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The connector contract.
+ *
+ * A {@link Connector} is one provider dialect's implementation: given a {@link ModelCard}, a
+ * {@link Conversation}, and {@link StreamOptions}, it either streams
+ * {@link Emission}s ({@link Connector.stream}) or resolves a single
+ * {@link Reply} ({@link Connector.complete}).
+ */
+import type { ApiKind, ModelCard } from "./model-card";
+import type { Conversation } from "./conversation";
+import type { StreamOptions } from "./options";
+import type { Channel } from "./emission";
+import type { Reply } from "./reply";
+import type { ProviderId } from "./model-card";
+/** One provider-dialect implementation of the gateway protocol. */
+export interface Connector {
+    /** Stable identifier for this connector instance. */
+    readonly id: string;
+    /** The wire dialect this connector speaks. */
+    readonly api: ApiKind;
+    /** Open a streaming invocation, yielding incremental emissions. */
+    stream(model: ModelCard, conversation: Conversation, options: StreamOptions): Channel;
+    /** Run a one-shot invocation and resolve the assembled reply. */
+    complete(model: ModelCard, conversation: Conversation, options: StreamOptions): Promise<Reply>;
+}
+/**
+ * Resolves a provider credential, optionally honoring a caller-supplied
+ * override before falling back to environment/cloud detection.
+ */
+export interface CredentialResolver {
+    resolve(provider: ProviderId, override?: string): Promise<string | undefined>;
+}

package/dist/types/llmgateway/contract/conversation.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The canonical conversation model.
+ *
+ * A {@link Conversation} is the provider-neutral request payload: a system
+ * preamble, an ordered list of {@link Turn}s, and the {@link ToolDescriptor}s
+ * the model is allowed to call. Connectors translate this into each provider's
+ * native wire shape.
+ */
+/** A JSON Schema object describing a tool's parameters. Kept structurally open. */
+export type JsonSchema = Record<string, unknown>;
+/** A free-form text segment authored by a user, assistant, or tool. */
+export interface TextBlock {
+    readonly kind: "text";
+    readonly text: string;
+}
+/**
+ * A reasoning / chain-of-thought segment. `signature` carries an opaque
+ * provider token used to replay verified reasoning back to the model.
+ */
+export interface ThinkingBlock {
+    readonly kind: "thinking";
+    readonly text: string;
+    readonly signature?: string;
+}
+/** A request from the assistant to invoke a named tool with structured input. */
+export interface ToolCallBlock {
+    readonly kind: "tool_call";
+    readonly id: string;
+    readonly name: string;
+    readonly input: unknown;
+}
+/** The outcome of running a tool, paired back to its originating call by `callId`. */
+export interface ToolResultBlock {
+    readonly kind: "tool_result";
+    readonly callId: string;
+    readonly output: unknown;
+    readonly isError?: boolean;
+}
+/** Inline binary media, carried as base64 with an explicit IANA media type. */
+export interface ImageBlock {
+    readonly kind: "image";
+    readonly mediaType: string;
+    readonly dataBase64: string;
+}
+/**
+ * An indus-original block representing a shell or MCP command intent the
+ * assistant wants to execute. Unlike {@link ToolCallBlock}, this is a
+ * lower-level shell-style instruction (program + argv) rather than a
+ * structured tool invocation.
+ */
+export interface CommandBlock {
+    readonly kind: "command";
+    readonly command: string;
+    readonly args?: readonly string[];
+}
+/** The tagged union of every content fragment that can appear inside a turn. */
+export type Block = TextBlock | ThinkingBlock | ToolCallBlock | ToolResultBlock | ImageBlock | CommandBlock;
+/** A turn authored by the human/caller side of the conversation. */
+export interface UserTurn {
+    readonly role: "user";
+    readonly blocks: readonly Block[];
+}
+/** A turn authored by the model. */
+export interface AssistantTurn {
+    readonly role: "assistant";
+    readonly blocks: readonly Block[];
+}
+/** A turn carrying tool results back into the conversation. */
+export interface ToolTurn {
+    readonly role: "tool";
+    readonly blocks: readonly Block[];
+}
+/** One conversational message, discriminated by `role`. */
+export type Turn = UserTurn | AssistantTurn | ToolTurn;
+/** Declares a tool the model may call, with JSON-Schema-typed parameters. */
+export interface ToolDescriptor {
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: JsonSchema;
+}
+/** A complete provider-neutral request payload. */
+export interface Conversation {
+    readonly system?: string;
+    readonly turns: readonly Turn[];
+    readonly tools?: readonly ToolDescriptor[];
+}

package/dist/types/llmgateway/contract/emission.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The streaming protocol.
+ *
+ * A connector's streaming call yields a {@link Channel} of {@link Emission}s —
+ * incremental deltas followed by a single terminal `done` (success) or
+ * `error` (failure).
+ */
+import type { Reply, StopReason, Usage } from "./reply";
+import type { GatewayError } from "./errors";
+/** Incremental assistant prose. */
+export interface TextEmission {
+    readonly kind: "text";
+    readonly delta: string;
+}
+/** Incremental reasoning / chain-of-thought text. */
+export interface ThinkingEmission {
+    readonly kind: "thinking";
+    readonly delta: string;
+}
+/** Announces the beginning of a tool call, before its arguments stream in. */
+export interface ToolCallStartEmission {
+    readonly kind: "tool_call_start";
+    readonly id: string;
+    readonly name: string;
+}
+/** A fragment of a tool call's argument JSON, keyed to its call `id`. */
+export interface ToolCallDeltaEmission {
+    readonly kind: "tool_call_delta";
+    readonly id: string;
+    readonly argsDelta: string;
+}
+/** Carries token accounting, typically near the end of a stream. */
+export interface UsageEmission {
+    readonly kind: "usage";
+    readonly usage: Usage;
+}
+/** Reports the model's stop reason. */
+export interface StopEmission {
+    readonly kind: "stop";
+    readonly stop: StopReason;
+}
+/** Terminal success: the fully assembled response. */
+export interface DoneEmission {
+    readonly kind: "done";
+    readonly reply: Reply;
+}
+/** Terminal failure: a normalized gateway error. */
+export interface ErrorEmission {
+    readonly kind: "error";
+    readonly error: GatewayError;
+}
+/** The tagged union of every streaming event a {@link Channel} can yield. */
+export type Emission = TextEmission | ThinkingEmission | ToolCallStartEmission | ToolCallDeltaEmission | UsageEmission | StopEmission | DoneEmission | ErrorEmission;
+/** An async stream of {@link Emission}s, consumed with `for await`. */
+export type Channel = AsyncIterable<Emission>;

package/dist/types/llmgateway/contract/errors.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Gateway error model.
+ *
+ * Every failure surfaced by a connector is normalized into a {@link GatewayError}
+ * whose `kind` discriminates the failure class, so callers can branch on it
+ * without string-matching messages.
+ */
+/** The class of failure a {@link GatewayError} represents. */
+export type GatewayErrorKind = "auth" | "rate_limit" | "http" | "transport" | "parse" | "unsupported" | "aborted";
+/** Optional context attached to a gateway error. */
+export interface GatewayErrorExtra {
+    /** HTTP status code, when the failure originated from a response. */
+    readonly status?: number;
+    /** The provider whose connector raised the error. */
+    readonly provider?: string;
+    /** The underlying error or value that triggered this one, if any. */
+    readonly cause?: unknown;
+}
+/** A normalized, discriminable error raised anywhere inside the gateway. */
+export declare class GatewayError extends Error {
+    readonly kind: GatewayErrorKind;
+    readonly status?: number;
+    readonly provider?: string;
+    constructor(kind: GatewayErrorKind, message: string, extra?: GatewayErrorExtra);
+}
+/** Construct a {@link GatewayError}. Convenience over the constructor. */
+export declare function gatewayError(kind: GatewayErrorKind, message: string, extra?: GatewayErrorExtra): GatewayError;

package/dist/types/llmgateway/contract/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Frozen type contract for the LLM gateway.
+ *
+ * Every downstream gateway module imports its vocabulary from this barrel.
+ */
+export type { ProviderId, ApiKind, Modality, CostSheet, ModelCard, } from "./model-card";
+export type { JsonSchema, TextBlock, ThinkingBlock, ToolCallBlock, ToolResultBlock, ImageBlock, CommandBlock, Block, UserTurn, AssistantTurn, ToolTurn, Turn, ToolDescriptor, Conversation, } from "./conversation";
+export type { Usage, StopReason, Reply } from "./reply";
+export type { TextEmission, ThinkingEmission, ToolCallStartEmission, ToolCallDeltaEmission, UsageEmission, StopEmission, DoneEmission, ErrorEmission, Emission, Channel, } from "./emission";
+export type { ThinkingLevel, ToolChoice, StreamOptions, } from "./options";
+export type { GatewayErrorKind, GatewayErrorExtra, } from "./errors";
+export { GatewayError, gatewayError } from "./errors";
+export type { Connector, CredentialResolver } from "./connector";

package/dist/types/llmgateway/contract/model-card.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Model-card descriptor: the static capability + pricing sheet for a single model.
+ *
+ * A `ModelCard` is pure data — it carries no
+ * behavior; connectors read it to shape their wire requests, and the pricing
+ * helpers read it to turn token counts into money.
+ */
+/**
+ * The upstream organization that owns a model. This is the *vendor* identity,
+ * independent of which HTTP dialect we speak to reach it (see {@link ApiKind}).
+ */
+export type ProviderId = "anthropic" | "openai" | "google" | "google-vertex" | "amazon" | "azure" | "nvidia" | "kimi" | "ollama" | "mock";
+/**
+ * The concrete request/response wire protocol a connector implements. Several
+ * providers share a dialect (everything OpenAI-compatible speaks
+ * `openai-completions`), and one provider can expose several dialects.
+ */
+export type ApiKind = "anthropic-messages" | "openai-completions" | "openai-responses" | "google-generative" | "google-vertex" | "amazon-bedrock" | "azure-openai" | "nvidia-openai-compatible" | "kimi-openai-compatible" | "ollama" | "mock";
+/** Kinds of content a model can accept or emit. */
+export type Modality = "text" | "image" | "audio";
+/** Per-million-token pricing. Optional tiers are absent when a model has no cache pricing. */
+export interface CostSheet {
+    readonly inputPerMTok: number;
+    readonly outputPerMTok: number;
+    readonly cacheReadPerMTok?: number;
+    readonly cacheWritePerMTok?: number;
+}
+/**
+ * Static descriptor for one model. Identified by `id` within a `provider`.
+ */
+export interface ModelCard {
+    readonly id: string;
+    readonly provider: ProviderId;
+    readonly api: ApiKind;
+    readonly displayName: string;
+    readonly baseUrl?: string;
+    readonly contextWindow: number;
+    readonly maxOutputTokens: number;
+    readonly modalities: readonly Modality[];
+    readonly reasoning: boolean;
+    readonly cost: CostSheet;
+}

package/dist/types/llmgateway/contract/options.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Per-invocation request options.
+ *
+ * These are the knobs a caller may set on a
+ * single model invocation; everything is optional so a bare `{}` is a valid
+ * "use the model's defaults" request.
+ */
+/**
+ * How much reasoning budget to grant a reasoning-capable model.
+ * `off` disables thinking entirely; the remaining levels scale the budget up.
+ */
+export type ThinkingLevel = "off" | "low" | "medium" | "high" | "max";
+/** Constrains how the model may use the declared tools on this turn. */
+export type ToolChoice = "auto" | "required" | "none";
+/** Options for a single streaming or one-shot invocation. */
+export interface StreamOptions {
+    /** Cancels the request when aborted. */
+    readonly signal?: AbortSignal;
+    /** Requested reasoning depth for reasoning-capable models. */
+    readonly thinking?: ThinkingLevel;
+    /** Hard ceiling on output tokens for this invocation. */
+    readonly maxOutputTokens?: number;
+    /** Sampling temperature. */
+    readonly temperature?: number;
+    /** Nucleus-sampling probability mass. */
+    readonly topP?: number;
+    /** Whether and how strongly the model must use a tool. */
+    readonly toolChoice?: ToolChoice;
+    /** Overrides the credential resolved from the environment. */
+    readonly apiKey?: string;
+}

package/dist/types/llmgateway/contract/reply.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The terminal, fully-materialized model response.
+ *
+ * A {@link Reply} is what a non-streaming call returns, and what a streaming
+ * channel surfaces in its final `done` emission once every delta has been
+ * folded together.
+ */
+import type { Block } from "./conversation";
+/** Token accounting for a single model response. Cache tiers are absent when unused. */
+export interface Usage {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly cacheReadTokens?: number;
+    readonly cacheWriteTokens?: number;
+}
+/**
+ * Why the model stopped producing output.
+ * - `complete`    — the model finished its turn naturally.
+ * - `tool_calls`  — the model paused to request one or more tool invocations.
+ * - `max_output`  — generation hit the output-token ceiling.
+ * - `refusal`     — the model declined to answer.
+ * - `aborted`     — the caller cancelled via an AbortSignal.
+ * - `error`       — the request failed; see the channel's error emission.
+ */
+export type StopReason = "complete" | "tool_calls" | "max_output" | "refusal" | "aborted" | "error";
+/** A complete assistant response, assembled from one model invocation. */
+export interface Reply {
+    readonly role: "assistant";
+    readonly model: string;
+    readonly blocks: readonly Block[];
+    readonly usage: Usage;
+    readonly stop: StopReason;
+}

package/dist/types/llmgateway/conversion/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Conversion layer barrel.
+ *
+ * Re-exports the pure request mappers, the emission-folding reducer, and the
+ * shared OpenAI-compatible streamer that every OpenAI-dialect connector reuses.
+ */
+export { toOpenAIChatMessages, toOpenAITools, toOpenAIToolChoice, toAnthropicRequest, toGoogleContents, toGoogleSystemInstruction, toGoogleTools, toResponsesInput, toResponsesTools, } from "./mappers";
+export { foldReply } from "./reduce";
+export { streamOpenAICompatibleChat, completeOpenAICompatibleChat, } from "./openai-compatible";
+export type { OpenAICompatibleConfig } from "./openai-compatible";