@wrongstack/providers 0.1.1 → 0.1.3

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Provider, Capabilities, Request, Response, StreamEvent, ProviderError, TextBlock, Message, Tool, ModelsRegistry, StopReason, ContentBlock, Logger, ProviderFactory, ProviderConfig } from '@wrongstack/core';
+import { Provider, Capabilities, Request, Response, StreamEvent, ProviderError, TextBlock, Message, Tool, WireFamily, ProviderFactory, Usage, StopReason, ModelsRegistry, ContentBlock, Logger, ProviderConfig } from '@wrongstack/core';
 
 /**
  * Minimal Server-Sent Events parser for HTTP streaming responses.
@@ -203,6 +203,157 @@ declare class GoogleProvider extends WireAdapter {
     private buildGenConfig;
 }
 
+/**
+ * Declarative wire-format definition. Sufficient to add a new HTTP+SSE
+ * provider without subclassing `WireAdapter` — the boilerplate (HTTP errors,
+ * abort wiring, SSE body parsing) is shared.
+ *
+ * The shape covers the variation that actually matters between providers:
+ *   - URL template (path, query)
+ *   - Auth headers (x-api-key, Authorization, etc.)
+ *   - Request body (field names, system-prompt placement, tool format)
+ *   - SSE event translation (one wire event → 0+ canonical events)
+ *
+ * Anything more exotic (non-SSE streams, multipart bodies, OAuth flows) still
+ * needs a hand-written subclass — those cases are too varied to template.
+ *
+ * `S` is provider-internal state threaded across SSE events for one stream:
+ * accumulating partial tool-call JSON, tracking block kinds, carrying the
+ * model id forward from `message_start`, etc. Each `stream()` call gets a
+ * fresh `S` via `createStreamState`.
+ */
+interface WireFormatConfig<S = Record<string, unknown>> {
+    /** Provider id (matches catalog id when the provider is in models.dev). */
+    id: string;
+    /** Wire family — used by the registry's factory list. */
+    family: WireFamily;
+    capabilities: Capabilities;
+    /** Used when the user doesn't override via config.baseUrl. */
+    defaultBaseUrl: string;
+    /** Build the HTTPS endpoint. Receives the (possibly user-overridden) base URL. */
+    buildUrl(baseUrl: string, req: Request): string;
+    /** Per-request headers. Default `content-type`/`accept` are provided already. */
+    buildHeaders(apiKey: string, req: Request): Record<string, string>;
+    /** Map a canonical Request onto the provider's body shape. */
+    buildBody(req: Request): Record<string, unknown>;
+    /** Construct fresh per-stream state. Called once per `stream()` call. */
+    createStreamState(fallbackModel: string): S;
+    /**
+     * Translate one SSE event into 0+ canonical events. Mutating `state` is
+     * expected — providers carry per-stream accumulators (partial tool JSON,
+     * current model id, usage) here.
+     */
+    parseStreamEvent(msg: SSEMessage, state: S): StreamEvent[];
+    /**
+     * Optional: yield any final events after the upstream stream closes
+     * (e.g. emit a synthetic `message_stop` when the wire format ends with
+     * `[DONE]` instead of an explicit terminator).
+     */
+    finalizeStream?(state: S): StreamEvent[];
+    /** Optional override; defaults to the shared HTTP error parser. */
+    normalizeError?(status: number, body: string): ProviderError;
+}
+/**
+ * Concrete Provider built from a declarative config. Extends WireAdapter to
+ * inherit the canonical HTTP + abort + error machinery.
+ */
+declare class WireFormatProvider<S = Record<string, unknown>> extends WireAdapter {
+    readonly id: string;
+    readonly capabilities: Capabilities;
+    private readonly cfg;
+    constructor(cfg: WireFormatConfig<S>, opts: {
+        apiKey: string;
+        baseUrl?: string;
+        fetchImpl?: typeof fetch;
+    });
+    protected buildUrl(req: Request): string;
+    protected buildHeaders(req: Request): Record<string, string>;
+    protected buildBody(req: Request): Record<string, unknown>;
+    protected parseStream(body: Parameters<typeof parseSSE>[0], fallbackModel: string): AsyncIterable<StreamEvent>;
+    protected translateError(status: number, body: string): ProviderError;
+    private runStream;
+}
+/**
+ * Identity helper that gives authors type checking on the config literal.
+ * Use at module level:
+ *
+ *   export const myProvider = defineWireFormat({
+ *     id: 'mistral',
+ *     family: 'openai-compatible',
+ *     capabilities: { ... },
+ *     ...
+ *   });
+ */
+declare function defineWireFormat<S = Record<string, unknown>>(cfg: WireFormatConfig<S>): WireFormatConfig<S>;
+interface WireFactoryOptions {
+    /**
+     * Optional config-time override of the API key. When omitted, the factory
+     * reads `cfg.apiKey` (passed in at create time by the registry / config
+     * loader). Setting this here is useful in tests.
+     */
+    apiKey?: string;
+    /** Override the base URL at factory build time. */
+    baseUrl?: string;
+}
+/**
+ * Build a `ProviderFactory` from a declarative wire-format. Plug into
+ * `ProviderRegistry.register(...)` or use in `buildProviderFactoriesFromRegistry`
+ * for catalog-driven discovery.
+ */
+declare function createWireFormatFactory(cfg: WireFormatConfig, opts?: WireFactoryOptions): ProviderFactory;
+
+interface MistralStreamState {
+    model: string;
+    started: boolean;
+    toolCalls: Map<number, {
+        id?: string;
+        name?: string;
+        partial: string;
+        emittedStart: boolean;
+    }>;
+}
+declare const mistralWireFormat: WireFormatConfig<MistralStreamState>;
+
+type BlockKind = 'text' | 'tool_use' | 'unknown';
+interface AnthropicStreamState {
+    model: string;
+    usage: Usage;
+    stopReason: StopReason;
+    started: boolean;
+    blocks: Map<number, {
+        kind: BlockKind;
+        id?: string;
+        name?: string;
+        partial: string;
+    }>;
+}
+declare const anthropicWireFormat: WireFormatConfig<AnthropicStreamState>;
+
+interface OpenAIStreamState {
+    model: string;
+    usage: Usage;
+    stopReason: StopReason;
+    started: boolean;
+    textOpen: boolean;
+    toolByIndex: Map<number, {
+        id: string;
+        name: string;
+        argBuf: string;
+    }>;
+    finalEmitted: boolean;
+}
+declare const openaiWireFormat: WireFormatConfig<OpenAIStreamState>;
+
+interface GoogleStreamState {
+    model: string;
+    usage: Usage;
+    stopReason: StopReason;
+    started: boolean;
+    sawFunctionCall: boolean;
+    finalEmitted: boolean;
+}
+declare const googleWireFormat: WireFormatConfig<GoogleStreamState>;
+
 /**
  * Resolve capabilities for a (provider, model) pair using the family default
  * as a baseline and overlaying per-model facts from the ModelsRegistry.
@@ -308,4 +459,4 @@ declare function buildProviderFactoriesFromRegistry(opts: BuildFactoriesOptions)
  */
 declare function makeProviderFromConfig(id: string, cfg: ProviderConfig): Provider;
 
-export { AnthropicProvider, type AnthropicProviderOptions, type BuildFactoriesOptions, type CompatibilityQuirks, type ConvertOptions, GoogleProvider, type GoogleProviderOptions, type OpenAIChoice, type OpenAICompatibleOptions, OpenAICompatibleProvider, type OpenAIMessage, OpenAIProvider, type OpenAIProviderOptions, type OpenAIToolCall, WireAdapter, buildProviderFactoriesFromRegistry, capabilitiesFor, contentFromAnthropic, contentFromOpenAI, makeProviderFromConfig, messagesToOpenAI, normalizeAnthropic, normalizeOpenAI, parseProviderHttpError, toolsToAnthropic, toolsToOpenAI };
+export { AnthropicProvider, type AnthropicProviderOptions, type BuildFactoriesOptions, type CompatibilityQuirks, type ConvertOptions, GoogleProvider, type GoogleProviderOptions, type OpenAIChoice, type OpenAICompatibleOptions, OpenAICompatibleProvider, type OpenAIMessage, OpenAIProvider, type OpenAIProviderOptions, type OpenAIToolCall, WireAdapter, type WireFactoryOptions, type WireFormatConfig, WireFormatProvider, anthropicWireFormat, buildProviderFactoriesFromRegistry, capabilitiesFor, contentFromAnthropic, contentFromOpenAI, createWireFormatFactory, defineWireFormat, googleWireFormat, makeProviderFromConfig, messagesToOpenAI, mistralWireFormat, normalizeAnthropic, normalizeOpenAI, openaiWireFormat, parseProviderHttpError, toolsToAnthropic, toolsToOpenAI };