combined-ai 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,773 @@
+/**
+ * Core, provider-agnostic contract shared by every AI provider in the package.
+ *
+ * Everything else (additional providers, provider selection, multi-provider
+ * combinations) builds on these types.
+ */
+type Role = "user" | "assistant";
+/** A text segment of a message's content. */
+type TextPart = {
+    type: "text";
+    text: string;
+};
+/**
+ * Where binary media (an image or document) comes from — either inline
+ * base64-encoded bytes (with their MIME type) or a URL the provider fetches.
+ * For a `url` source, `mediaType` is optional but some providers need it (e.g.
+ * Gemini's file references), so set it when known.
+ */
+type MediaSource = {
+    kind: "base64";
+    mediaType: string;
+    data: string;
+} | {
+    kind: "url";
+    url: string;
+    mediaType?: string;
+};
+/** An image input (PNG/JPEG/WebP/GIF, per the provider's support). */
+type ImagePart = {
+    type: "image";
+    source: MediaSource;
+};
+/** A document input, e.g. a PDF (`source.mediaType` should be `"application/pdf"`). */
+type FilePart = {
+    type: "file";
+    source: MediaSource;
+    /** Optional file name (used by OpenAI's file input). */
+    filename?: string;
+};
+/**
+ * A tool call the model made, as it appears in an **assistant** message's content
+ * when you replay the conversation. Build these from the {@link ToolCall}s a prior
+ * `complete()` returned, append them as the assistant turn, then send the matching
+ * {@link ToolResultPart}s in the next user message.
+ */
+type ToolUsePart = {
+    type: "tool_use";
+    /** The id the provider assigned to the call; echo it on the matching result. */
+    id?: string;
+    name: string;
+    /** The arguments the model passed (a parsed object). */
+    input: Record<string, unknown>;
+};
+/**
+ * A tool's result, placed in a **user** message's content to feed it back to the
+ * model. Carry both `toolUseId` (Anthropic/OpenAI match the call by id) and `name`
+ * (Gemini matches by function name) when you have them.
+ */
+type ToolResultPart = {
+    type: "tool_result";
+    /** The id of the {@link ToolUsePart}/{@link ToolCall} this answers. */
+    toolUseId?: string;
+    /** The tool's name — required for Gemini, which matches results by name. */
+    name?: string;
+    /** The tool's output as text. */
+    content: string;
+    /** Mark the call as having errored (the model is told the tool failed). */
+    isError?: boolean;
+};
+/**
+ * One part of a structured message content: text, an image, a file/document, or a
+ * tool call / tool result (for replaying a tool-use conversation). Widening
+ * {@link Message.content} from `string` to `string | ContentPart[]` was the one
+ * breaking change; adding members here is additive.
+ *
+ * Provider support varies (e.g. OpenAI's Chat Completions has no URL file
+ * source); each provider's content mapper handles what its API supports and
+ * throws a clear error otherwise.
+ */
+type ContentPart = TextPart | ImagePart | FilePart | ToolUsePart | ToolResultPart;
+type Message = {
+    role: Role;
+    /**
+     * The message body. A bare `string` is shorthand for a single text part, so
+     * existing string callers keep working unchanged; pass `ContentPart[]` for
+     * structured (e.g. future multimodal) content.
+     */
+    content: string | ContentPart[];
+};
+/**
+ * Constrain the model's output to a JSON Schema (structured output). The schema
+ * is a plain JSON Schema object — no Zod/runtime dependency. Each provider maps
+ * it onto its own native mechanism (Anthropic `output_config.format`, OpenAI
+ * `response_format`, Gemini `responseSchema`).
+ *
+ * **For one schema to work across all three providers** (driven by the strictest
+ * rules), keep it simple: every `object` sets `additionalProperties: false`, and
+ * every property is listed in `required` with a single non-null `type`. Avoid
+ * optional and nullable fields — OpenAI's strict mode requires every property in
+ * `required`, and Gemini expresses nullability with `nullable: true` rather than a
+ * `["string", "null"]` union or an `anyOf` with a null member, so null-unions are
+ * **not** portable (they're passed through untranslated and Gemini will reject
+ * them). Also avoid recursive schemas, numeric/length constraints
+ * (`minimum`/`maxLength`/…), and `$ref` (Gemini ignores most JSON Schema keywords
+ * beyond types/enum/format). Provider-specific schemas can of course use more —
+ * these constraints are only for a single schema shared across providers.
+ */
+type ResponseFormat = {
+    type: "json_schema";
+    /** A JSON Schema object describing the desired output shape. */
+    schema: Record<string, unknown>;
+    /**
+     * Schema name. OpenAI requires one (must match `^[a-zA-Z0-9_-]+$`); defaulted
+     * when omitted. Ignored by Anthropic and Gemini.
+     */
+    name?: string;
+};
+/**
+ * A tool the model may call. `parameters` is a JSON Schema describing the tool's
+ * input (the same cross-provider schema guidance as {@link ResponseFormat} applies).
+ */
+type ToolDefinition = {
+    name: string;
+    description?: string;
+    parameters: Record<string, unknown>;
+};
+/**
+ * How the model should use the supplied tools:
+ * - `"auto"` — the model decides whether to call a tool (the default when tools
+ *   are present);
+ * - `"any"` — the model must call some tool;
+ * - `"none"` — the model must not call a tool;
+ * - `{ name }` — the model must call that specific tool.
+ */
+type ToolChoice = "auto" | "any" | "none" | {
+    name: string;
+};
+/**
+ * A tool call the model requested, surfaced on {@link CompletionResult.toolCalls}.
+ * `input` is the parsed arguments object (OpenAI's JSON-string arguments are
+ * parsed for you; Anthropic/Gemini already return an object).
+ */
+type ToolCall = {
+    /** Provider-assigned id (always on Anthropic/OpenAI; newer Gemini models). */
+    id?: string;
+    name: string;
+    input: Record<string, unknown>;
+};
+type CompletionRequest = {
+    messages: Message[];
+    /** Optional system prompt applied to the whole request. */
+    system?: string;
+    /** Override the provider's default model. */
+    model?: string;
+    /** Override the provider's default output-token cap. */
+    maxTokens?: number;
+    /**
+     * Constrain the output to a JSON Schema. The model returns JSON in `text`, and
+     * `complete()` also surfaces the parsed value on {@link CompletionResult.parsed}.
+     */
+    responseFormat?: ResponseFormat;
+    /**
+     * Tools the model may call. When the model calls one, `complete()` returns the
+     * calls on {@link CompletionResult.toolCalls} (and `finishReason: "tool_use"`);
+     * you run them and feed results back as {@link ToolResultPart}s in the next
+     * message. Surfaced by `complete()` only — `stream()` yields text deltas and
+     * does not report tool calls.
+     */
+    tools?: ToolDefinition[];
+    /** Constrain whether/which tool the model calls. Defaults to provider behavior (`"auto"`). */
+    toolChoice?: ToolChoice;
+    /**
+     * Abort the request (and, for `stream()`, the in-flight read) when this signal
+     * fires. For a timeout, pass `AbortSignal.timeout(ms)`. An aborted request
+     * rejects with a transport `ProviderError` whose `cause` is the abort reason.
+     */
+    signal?: AbortSignal;
+};
+/**
+ * Normalized, provider-agnostic stop reason. The provider's exact value is
+ * preserved separately on {@link CompletionResult.rawFinishReason}.
+ *
+ * - `"stop"` — the model finished on its own.
+ * - `"length"` — output was truncated at the token cap (likely an empty `text`
+ *   when the cap was spent on thinking tokens; see the Gemini note in CLAUDE.md).
+ * - `"content_filter"` — the model refused or output was blocked by a safety
+ *   filter.
+ * - `"tool_use"` — the model stopped to call a tool; see
+ *   {@link CompletionResult.toolCalls}.
+ * - `"other"` — any other or unrecognized reason.
+ */
+type FinishReason = "stop" | "length" | "content_filter" | "tool_use" | "other";
+/**
+ * Token usage for a single completion. `totalTokens` is the provider's own total
+ * when it reports one (Gemini's includes thinking tokens, so it can exceed
+ * input + output), otherwise `inputTokens + outputTokens`.
+ */
+type Usage = {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+};
+type CompletionResult = {
+    text: string;
+    /** The model that actually produced the response. */
+    model: string;
+    /**
+     * Normalized stop reason, or `undefined` if the provider returned none.
+     * Lets callers distinguish a real empty answer from a truncated/refused one
+     * instead of seeing a bare `text: ""`.
+     */
+    finishReason?: FinishReason;
+    /** The provider's exact stop-reason string, verbatim (before normalization). */
+    rawFinishReason?: string;
+    /**
+     * The refusal message when the model explicitly declined (currently OpenAI's
+     * `message.refusal`). When set, `finishReason` is `"content_filter"`.
+     */
+    refusal?: string;
+    /** Token usage for this completion, or `undefined` if the provider reported none. */
+    usage?: Usage;
+    /**
+     * The parsed structured output, set only when {@link CompletionRequest.responseFormat}
+     * was given and `text` parsed as JSON. `undefined` if no schema was requested
+     * or the output wasn't valid JSON (e.g. truncated at the token cap). The raw
+     * JSON is always in `text`. Typed `unknown` — cast to your schema's type.
+     */
+    parsed?: unknown;
+    /**
+     * The tool calls the model requested, set only when it called at least one tool
+     * (then `finishReason` is `"tool_use"`). Run them and feed results back as
+     * {@link ToolResultPart}s. `complete()`-only.
+     */
+    toolCalls?: ToolCall[];
+};
+type Provider = {
+    readonly name: string;
+    /** Run a single completion and return the full text. */
+    complete(request: CompletionRequest): Promise<CompletionResult>;
+    /** Run a single completion, yielding text deltas as they arrive. */
+    stream(request: CompletionRequest): AsyncIterable<string>;
+};
+
+/**
+ * Public types for the **combine** feature — multiple providers cooperating on
+ * one prompt via a selectable strategy. The strategy implementations live in
+ * sibling files (e.g. `consensus.ts`); the public entry point is
+ * {@link ProviderRegistry.combine}.
+ */
+
+/** The cooperation strategies the registry knows how to run. */
+declare const STRATEGY_NAMES: readonly ["consensus", "pipeline", "ensemble", "broadcast"];
+type StrategyName = (typeof STRATEGY_NAMES)[number];
+/**
+ * One participant in a combine. A bare provider name uses that provider's
+ * configured default model; the object form overrides the model and/or maxTokens
+ * for this participant only — letting one combine mix cheap drafters with a strong
+ * synthesizer, or run the same provider twice with different models.
+ */
+type ParticipantSpec = ProviderName | {
+    /** Which configured provider to run this participant on (validated by the registry). */
+    provider: ProviderName;
+    /** Model for this participant. Falls back to `request.model`, then the provider default. */
+    model?: string;
+    /** maxTokens for this participant. Falls back to `request.maxTokens`. */
+    maxTokens?: number;
+    /**
+     * Unique id for this participant in results/events/usage and for `synthesizer`.
+     * Defaults to the provider name, or `<provider>-<model>` when `model` is set.
+     * Required (must be set explicitly) only to disambiguate two participants that
+     * would otherwise resolve to the same id (e.g. the same provider+model twice).
+     */
+    label?: string;
+};
+/**
+ * The fields every combine strategy's request shares: the underlying
+ * {@link CompletionRequest} (messages, model, maxTokens, system, signal, …) plus
+ * the roster of participants. The per-strategy request types
+ * ({@link ConsensusRequest}, {@link PipelineRequest}, {@link EnsembleRequest},
+ * {@link BroadcastRequest}) extend this with only the options that strategy uses.
+ */
+type CombineRequestBase = CompletionRequest & {
+    /**
+     * Who participates. A bare provider name uses its configured default model; the
+     * object form ({@link ParticipantSpec}) overrides model/maxTokens per participant.
+     * Resolved to a unique id each (see {@link ParticipantSpec.label}); validated by
+     * the registry.
+     */
+    participants: ParticipantSpec[];
+};
+/**
+ * Request for the `consensus` strategy (draft → critique → synthesize). Call
+ * {@link ProviderRegistry.consensus} directly, or pass `strategy: "consensus"`
+ * (the default) to {@link ProviderRegistry.combine}.
+ */
+type ConsensusRequest = CombineRequestBase & {
+    /**
+     * Which participant writes the final synthesized answer, referenced by its
+     * **id** (see {@link ParticipantSpec.label}). Defaults to the first participant.
+     */
+    synthesizer?: string;
+    /**
+     * Whether drafts are attributed to their provider in the text shown to the
+     * other providers. `"anonymized"` (default) shows `Answer A`/`Answer B`/… to
+     * neutralize brand and self-preference bias; `"attributed"` shows participant
+     * ids. The returned {@link ConsensusResult} always keeps ids regardless.
+     */
+    attribution?: "attributed" | "anonymized";
+    /**
+     * Minimum number of participants that must successfully produce a draft for a
+     * consensus run to proceed. Defaults to 2. A single-provider combine always
+     * degrades to a plain completion regardless of this value.
+     */
+    minParticipants?: number;
+};
+/**
+ * Request for the `pipeline` strategy (sequential refinement). Call
+ * {@link ProviderRegistry.pipeline} directly, or pass `strategy: "pipeline"` to
+ * {@link ProviderRegistry.combine}. No strategy-specific options — participant
+ * order is the conveyor order.
+ */
+type PipelineRequest = CombineRequestBase;
+/**
+ * Request for the `ensemble` strategy (multi-model vote on structured output).
+ * Call {@link ProviderRegistry.ensemble} directly, or pass `strategy: "ensemble"`
+ * to {@link ProviderRegistry.combine}. `responseFormat` is **required** (every
+ * participant answers under this schema, and the field-wise vote needs an
+ * object-root schema).
+ */
+type EnsembleRequest = CombineRequestBase & {
+    responseFormat: ResponseFormat;
+};
+/**
+ * Request for the `broadcast` strategy (fan-out, no combine). Call
+ * {@link ProviderRegistry.broadcast} directly, or pass `strategy: "broadcast"` to
+ * {@link ProviderRegistry.combine}. No strategy-specific options.
+ */
+type BroadcastRequest = CombineRequestBase;
+/**
+ * The broad request accepted by the strategy-dispatching
+ * {@link ProviderRegistry.combine}: {@link CombineRequestBase} plus every
+ * strategy's options and the `strategy` selector. Today only consensus adds
+ * options, so this is {@link ConsensusRequest} plus `strategy` (each strategy
+ * reads only the options it uses; `responseFormat` stays optional here, inherited
+ * from {@link CompletionRequest}). Prefer a per-strategy method
+ * ({@link ProviderRegistry.consensus} etc.) when the strategy is known at the
+ * call site — they take the precise {@link ConsensusRequest}/… type and return
+ * the concrete result without narrowing.
+ */
+type CombineRequest = ConsensusRequest & {
+    /** Cooperation strategy. Defaults to `"consensus"`. */
+    strategy?: StrategyName;
+};
+/**
+ * The outcome of one participant in one phase — either its result or its failure.
+ * `id` is the participant's unique id (see {@link ParticipantSpec.label}); `provider`
+ * is the actual provider it ran on (these differ when a model override gives the
+ * participant a `<provider>-<model>` id, or two participants share one provider).
+ * A failure's `error` is typically a `ProviderError` (carrying `status`/`kind`/
+ * `code`); narrow with `instanceof ProviderError` to read those fields.
+ */
+type ParticipantOutcome = {
+    id: string;
+    provider: ProviderName;
+    status: "ok";
+    result: CompletionResult;
+} | {
+    id: string;
+    provider: ProviderName;
+    status: "failed";
+    error: Error;
+};
+/**
+ * Aggregated token usage across all the model calls a combine made — the true
+ * cost of a run, which is several times one completion (a default 3-way
+ * consensus is ~8 calls: 3 drafts + 3 critiques + synthesis + sanitize).
+ * `undefined` if no participating provider reported usage.
+ */
+type CombineUsage = {
+    /** Total usage summed across every call the combine made. */
+    total: Usage;
+    /** Usage per participant id, summed across all of that participant's calls. */
+    byParticipant: Partial<Record<string, Usage>>;
+};
+/** The result of the `consensus` strategy (draft → critique → synthesize). */
+type ConsensusResult = {
+    /** The final synthesized answer. */
+    text: string;
+    strategy: "consensus";
+    /** The id of the participant that wrote the final answer (may be a fallback if the chosen one failed). */
+    synthesizer: string;
+    /** The model the synthesizer actually used. */
+    model: string;
+    /** Phase 1 drafts, in participant order (includes any failures). */
+    drafts: ParticipantOutcome[];
+    /** Phase 2 critiques, in surviving-participant order (includes any failures). */
+    critiques: ParticipantOutcome[];
+    /** Aggregated token usage across every call, or `undefined` if none was reported. */
+    usage?: CombineUsage;
+};
+/** The result of the `pipeline` strategy (sequential refinement). */
+type PipelineResult = {
+    /** The final answer — the output of the last stage that produced one. */
+    text: string;
+    strategy: "pipeline";
+    /** The id of the participant that produced the final answer (the last advancing stage). */
+    finalParticipant: string;
+    /** The model that produced the final answer. */
+    model: string;
+    /** Every stage in pipeline (participant) order, including any failures. */
+    stages: ParticipantOutcome[];
+    /** Aggregated token usage across every stage, or `undefined` if none was reported. */
+    usage?: CombineUsage;
+};
+/**
+ * How strongly the ensemble participants agreed on the merged object — the
+ * confidence signal a multi-model vote gives you that a single model can't.
+ */
+type EnsembleAgreement = {
+    /** Mean of the per-field agreement scores (0–1), or 1 for an empty object. */
+    overall: number;
+    /**
+     * Per-field agreement: the fraction of the merged responses that voted for the
+     * field's merged value (0–1). The denominator is **all** the valid responses,
+     * not just the ones that returned the field — so a field most models omitted
+     * scores low. 1 means every model returned the field and agreed on its value; a
+     * low value flags either disagreement or sparse coverage.
+     */
+    byField: Record<string, number>;
+};
+/**
+ * The result of the `ensemble` strategy (each participant returns the same typed
+ * object; the objects are merged field-wise by majority vote — with no LLM
+ * synthesis — so every merged value is one a model actually returned).
+ */
+type EnsembleResult = {
+    /** The merged object serialized as JSON (the same content as `merged`). */
+    text: string;
+    strategy: "ensemble";
+    /** The merged typed object. Cast to your schema's type. */
+    merged: Record<string, unknown>;
+    /** How strongly the participants agreed, overall and per field. */
+    agreement: EnsembleAgreement;
+    /** Each participant's structured response, in participant order (includes failures). */
+    responses: ParticipantOutcome[];
+    /** Aggregated token usage across every participant call, or `undefined` if none was reported. */
+    usage?: CombineUsage;
+};
+/**
+ * The result of the `broadcast` strategy (fan-out to every participant in
+ * parallel, no cooperation). There is no single combined answer — hence no
+ * `text` field — just every participant's raw response. Narrow on
+ * `result.strategy` to reach `responses`.
+ */
+type BroadcastResult = {
+    strategy: "broadcast";
+    /** Each participant's raw completion, in participant order (includes failures). */
+    responses: ParticipantOutcome[];
+    /** Aggregated token usage across every participant call, or `undefined` if none was reported. */
+    usage?: CombineUsage;
+};
+/**
+ * The result of a combine, discriminated on `strategy`. Narrow on
+ * `result.strategy` to reach the strategy-specific artifacts. Note that
+ * `BroadcastResult` has no `text` (it returns every raw response, not one answer).
+ */
+type CombineResult = ConsensusResult | PipelineResult | EnsembleResult | BroadcastResult;
+/**
+ * Maps a strategy name to its request type — e.g. `StrategyRequest<"ensemble">`
+ * is {@link EnsembleRequest}. A utility for callers writing code generic over the
+ * strategy.
+ */
+type StrategyRequest<S extends StrategyName> = {
+    consensus: ConsensusRequest;
+    pipeline: PipelineRequest;
+    ensemble: EnsembleRequest;
+    broadcast: BroadcastRequest;
+}[S];
+/**
+ * Maps a strategy name to its concrete result type — e.g.
+ * `ResultFor<"ensemble">` is {@link EnsembleResult}. A utility for callers
+ * writing code generic over the strategy.
+ */
+type ResultFor<S extends StrategyName> = Extract<CombineResult, {
+    strategy: S;
+}>;
+/**
+ * A progress event emitted while a combine runs. For `consensus`, `phase` marks
+ * a phase boundary and `draft`/`critique` fire as each participant's call settles
+ * (in completion order, which may differ from participant order). For `pipeline`,
+ * a `stage` event fires as each stage settles (in conveyor order). For `ensemble`
+ * and `broadcast`, a `response` event fires as each participant settles (in
+ * completion order, which may differ from participant order). The final answer is
+ * the resolved {@link CombineResult}, so there is no terminal event.
+ */
+type CombineEvent = {
+    type: "phase";
+    phase: "drafting" | "critiquing" | "synthesizing";
+} | {
+    type: "draft";
+    id: string;
+    provider: ProviderName;
+    status: "ok" | "failed";
+} | {
+    type: "critique";
+    id: string;
+    provider: ProviderName;
+    status: "ok" | "failed";
+} | {
+    /** A `pipeline` stage settled. `index` is its 0-based position in the conveyor. */
+    type: "stage";
+    id: string;
+    provider: ProviderName;
+    status: "ok" | "failed";
+    index: number;
+} | {
+    /** A participant settled in an `ensemble` or `broadcast` run. */
+    type: "response";
+    id: string;
+    provider: ProviderName;
+    status: "ok" | "failed";
+};
+type CombineOptions = {
+    /**
+     * Called with progress events as the combine runs. Errors thrown from the
+     * handler are swallowed so a progress listener can never break the run.
+     */
+    onEvent?: (event: CombineEvent) => void;
+};
+
+/**
+ * HTTP transport for the providers: a `fetch` wrapper that turns network
+ * failures into typed errors, plus bounded retry/backoff on routine retryable
+ * statuses. The error *vocabulary* (`ProviderError`, `apiError`) lives in
+ * `./errors`; this module is about how a request is made.
+ */
+
+/** Tuning for {@link requestWithRetry}'s bounded exponential backoff. */
+type RetryOptions = {
+    /**
+     * How many times to retry after the initial attempt on a retryable status
+     * (429/503/529). `0` disables retry. Defaults to {@link DEFAULT_MAX_RETRIES}.
+     */
+    maxRetries?: number;
+    /**
+     * Base backoff in ms; the nth retry waits `baseDelayMs * 2 ** n` (capped at
+     * {@link MAX_BACKOFF_MS}), unless the response carries a `Retry-After` header.
+     * Defaults to {@link DEFAULT_BASE_DELAY_MS}.
+     */
+    baseDelayMs?: number;
+};
+
+/**
+ * Anthropic (Claude) provider, talking to the Messages API directly over
+ * `fetch` — no SDK dependency.
+ */
+
+type AnthropicProviderOptions = {
+    apiKey: string;
+    /** Defaults to {@link DEFAULT_MODEL}. */
+    model?: string;
+    /** Defaults to `https://api.anthropic.com`. */
+    baseUrl?: string;
+    /** Bounded retry/backoff on 429/503/529. Defaults applied when omitted. */
+    retry?: RetryOptions;
+};
+
+/**
+ * Google Gemini provider, talking to the Generative Language API directly over
+ * `fetch` — no SDK dependency.
+ */
+
+type GoogleProviderOptions = {
+    apiKey: string;
+    /** Defaults to {@link DEFAULT_MODEL}. */
+    model?: string;
+    /** Defaults to `https://generativelanguage.googleapis.com`. */
+    baseUrl?: string;
+    /** Bounded retry/backoff on 429/503/529. Defaults applied when omitted. */
+    retry?: RetryOptions;
+};
+
+/**
+ * OpenAI provider, talking to the Chat Completions API directly over `fetch` —
+ * no SDK dependency.
+ */
+
+type OpenAIProviderOptions = {
+    apiKey: string;
+    /** Defaults to {@link DEFAULT_MODEL}. */
+    model?: string;
+    /** Defaults to `https://api.openai.com`. */
+    baseUrl?: string;
+    /**
+     * Extra headers merged into (and able to override) every request's headers —
+     * for an OpenAI-compatible gateway's auth/routing (e.g. OpenRouter's
+     * `HTTP-Referer`/`X-Title`) or a proxy. Use lowercase header names.
+     */
+    headers?: Record<string, string>;
+    /** Bounded retry/backoff on 429/503/529. Defaults applied when omitted. */
+    retry?: RetryOptions;
+};
+
+/**
+ * Provider registry — the package's single point of access to its providers.
+ *
+ * You configure the registry with the providers you want (and their API keys);
+ * the library constructs the built-in providers by name and hands one back via
+ * {@link ProviderRegistry.select}. Consumers never import the provider classes
+ * directly. It never reads env vars — keys are always passed in the config.
+ */
+
+/**
+ * An OpenAI Chat Completions–compatible endpoint registered under a custom name.
+ * The library reuses its OpenAI provider against your `baseUrl`, so any service
+ * that speaks the Chat Completions wire format works — OpenRouter, Together,
+ * Groq, Ollama, a local server, etc.
+ */
+type OpenAICompatibleConfig = {
+    kind: "openai-compatible";
+    apiKey: string;
+    /**
+     * Base URL of the endpoint, **excluding** the `/v1/chat/completions` path the
+     * provider appends (e.g. `https://api.groq.com/openai`, `http://localhost:11434`).
+     */
+    baseUrl: string;
+    /**
+     * The model id to send. Required — unlike the built-ins there is no sensible
+     * default for a third-party endpoint. `request.model` (or combine's `model`)
+     * still overrides it per call.
+     */
+    model: string;
+    /** Extra headers merged into every request (e.g. OpenRouter's `HTTP-Referer`/`X-Title`). */
+    headers?: Record<string, string>;
+    /** Bounded retry/backoff on 429/503/529. Defaults applied when omitted. */
+    retry?: RetryOptions;
+};
+/**
+ * A provider you implement yourself (anything satisfying {@link Provider}),
+ * registered under a custom name. The escape hatch for an API the library
+ * doesn't speak natively, or for wrapping a built-in with instrumentation.
+ */
+type CustomProviderInstance = {
+    kind: "provider";
+    provider: Provider;
+};
+/** How a custom (non-built-in) provider is registered. */
+type CustomProviderConfig = OpenAICompatibleConfig | CustomProviderInstance;
+/** The names the library constructs as built-in providers (the single source of truth). */
+declare const BUILT_IN_NAMES: readonly ["anthropic", "openai", "google"];
+/** The provider names the library constructs from its own config. */
+type BuiltInProviderName = (typeof BUILT_IN_NAMES)[number];
+/** Per-provider configuration. Include a provider's key to register it. */
+type ProviderRegistryConfig = {
+    anthropic?: AnthropicProviderOptions;
+    openai?: OpenAIProviderOptions;
+    google?: GoogleProviderOptions;
+    /**
+     * Extra providers registered under names you choose — an OpenAI-compatible
+     * gateway/local endpoint or a {@link Provider} you bring yourself. Each name
+     * must not collide with a built-in.
+     */
+    custom?: Record<string, CustomProviderConfig>;
+};
+/**
+ * A configured provider's name: the three built-ins, or any custom name you
+ * registered. The `string & Record<never, never>` intersection keeps editor
+ * autocomplete for the built-in literals while still accepting an arbitrary
+ * custom string.
+ */
+type ProviderName = BuiltInProviderName | (string & Record<never, never>);
+declare class ProviderRegistry {
+    #private;
+    /**
+     * Construct the providers present in `config`. A provider is registered only
+     * if its entry is supplied; the rest are left out.
+     */
+    constructor(config: ProviderRegistryConfig);
+    /**
+     * Return the provider registered under `name`. Throws a clear error listing
+     * the configured names if that provider was not configured.
+     */
+    select(name: ProviderName): Provider;
+    /**
+     * Combine several configured providers to cooperate on one prompt, dispatching
+     * on `request.strategy` (defaults to `"consensus"`).
+     *
+     * Generic over the strategy: `S` is inferred from the `strategy` field, so a
+     * **literal** `strategy` at the call site makes the return that strategy's
+     * concrete result (e.g. `strategy: "ensemble"` → `EnsembleResult`) — the caller
+     * does **not** narrow a union. When `strategy` is only known at runtime, `S`
+     * widens to {@link StrategyName} and the return is the full
+     * {@link CombineResult} union to narrow.
+     *
+     * The request stays the broad {@link CombineRequest} here; for compile-time
+     * enforcement of a strategy's specific options (e.g. `responseFormat` required
+     * for ensemble) call the per-strategy method ({@link ProviderRegistry.consensus},
+     * {@link ProviderRegistry.pipeline}, {@link ProviderRegistry.ensemble},
+     * {@link ProviderRegistry.broadcast}), which takes that strategy's request type.
+     */
+    combine<S extends StrategyName = "consensus">(request: Omit<CombineRequest, "strategy"> & {
+        strategy?: S;
+    }, options?: CombineOptions): Promise<ResultFor<S>>;
+    /**
+     * Run the `consensus` strategy (draft → critique → synthesize) over the
+     * configured participants. Strategy-specific: `synthesizer` (defaults to the
+     * first participant), `attribution`, `minParticipants` (default 2).
+     */
+    consensus(request: ConsensusRequest, options?: CombineOptions): Promise<ConsensusResult>;
+    /**
+     * Run the `pipeline` strategy (sequential refinement) — participants refine a
+     * running answer in roster order; the last advancing stage wins.
+     */
+    pipeline(request: PipelineRequest, options?: CombineOptions): Promise<PipelineResult>;
+    /**
+     * Run the `ensemble` strategy (multi-model vote on structured output) — every
+     * participant answers under `request.responseFormat`; the typed objects are
+     * merged field-wise by majority vote with a per-field agreement score.
+     */
+    ensemble(request: EnsembleRequest, options?: CombineOptions): Promise<EnsembleResult>;
+    /**
+     * Run the `broadcast` strategy (fan-out, no combine) — every participant
+     * answers the raw prompt in parallel; all raw responses are returned.
+     */
+    broadcast(request: BroadcastRequest, options?: CombineOptions): Promise<BroadcastResult>;
+    /** Whether a provider is configured under `name`. */
+    has(name: string): boolean;
+    /** The names of all configured providers. */
+    names(): ProviderName[];
+}
+
+/**
+ * Typed provider errors. Every provider throws a {@link ProviderError} so
+ * consumers can branch on `err.status` / `err.kind` / `err.code` instead of
+ * regex-matching a message string.
+ */
+
+/**
+ * Whether the failure happened after the provider responded (`"api"` — an
+ * HTTP error status, so `status` is set) or before any response arrived
+ * (`"transport"` — a network/DNS failure or an aborted request, so `status` is
+ * undefined). Branch on this to tell "the provider said no" from "we never
+ * reached the provider".
+ */
+type ProviderErrorKind = "api" | "transport";
+type ProviderErrorInit = {
+    provider: ProviderName;
+    kind: ProviderErrorKind;
+    status?: number;
+    code?: string;
+    type?: string;
+    body?: string;
+    cause?: unknown;
+};
+/** An error from a provider call, carrying enough structure to handle it programmatically. */
+declare class ProviderError extends Error {
+    readonly name = "ProviderError";
+    /** Which provider produced the failure. */
+    readonly provider: ProviderName;
+    /** Transport failure (no response) vs API failure (error response). */
+    readonly kind: ProviderErrorKind;
+    /** HTTP status for `kind: "api"`; `undefined` for transport failures. */
+    readonly status?: number;
+    /** Machine-readable code parsed from the error body, where the provider sends one. */
+    readonly code?: string;
+    /** Error category parsed from the body (Anthropic/OpenAI `type`, Gemini `status`). */
+    readonly type?: string;
+    /** The raw response body, for `kind: "api"`. */
+    readonly body?: string;
+    constructor(message: string, init: ProviderErrorInit);
+}
+
+export { type AnthropicProviderOptions, type BroadcastRequest, type BroadcastResult, type BuiltInProviderName, type CombineEvent, type CombineOptions, type CombineRequest, type CombineRequestBase, type CombineResult, type CombineUsage, type CompletionRequest, type CompletionResult, type ConsensusRequest, type ConsensusResult, type ContentPart, type CustomProviderConfig, type CustomProviderInstance, type EnsembleAgreement, type EnsembleRequest, type EnsembleResult, type FilePart, type FinishReason, type GoogleProviderOptions, type ImagePart, type MediaSource, type Message, type OpenAICompatibleConfig, type OpenAIProviderOptions, type ParticipantOutcome, type ParticipantSpec, type PipelineRequest, type PipelineResult, type Provider, ProviderError, type ProviderErrorKind, type ProviderName, ProviderRegistry, type ProviderRegistryConfig, type ResponseFormat, type ResultFor, type RetryOptions, type Role, type StrategyName, type StrategyRequest, type TextPart, type ToolCall, type ToolChoice, type ToolDefinition, type ToolResultPart, type ToolUsePart, type Usage };