@agentskit/adapters 0.4.0 → 0.5.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _agentskit_core from '@agentskit/core';
-import { AdapterRequest, StreamChunk, AdapterFactory } from '@agentskit/core';
+import { AdapterRequest, StreamChunk, AdapterFactory, StreamSource, EmbedFn } from '@agentskit/core';
 
 interface CreateAdapterConfig {
     send: (request: AdapterRequest) => Promise<ReadableStream | Response>;
@@ -14,11 +14,75 @@ declare function createAdapter(config: CreateAdapterConfig): AdapterFactory;
 
 declare function generic(config: GenericAdapterConfig): AdapterFactory;
 
+/**
+ * Retry knobs for adapter fetches. Tunable per call to createStreamSource.
+ *
+ * Default behavior:
+ *   - 3 attempts total (1 initial + 2 retries)
+ *   - exponential backoff: 500ms, 1000ms, 2000ms ... (capped at maxDelayMs)
+ *   - full jitter on each delay
+ *   - retry on HTTP 408, 429, 500, 502, 503, 504
+ *   - retry on network errors (fetch throws)
+ *   - DO NOT retry on 4xx other than 408/429 (those are bad requests / auth)
+ *   - retries only the initial fetch — never mid-stream
+ *   - respects Retry-After header when present
+ */
+interface RetryOptions {
+    maxAttempts?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    jitter?: boolean;
+    retryOn?: (info: {
+        error?: unknown;
+        response?: Response;
+        attempt: number;
+    }) => boolean;
+    /** Hook for tests + logging. Called after every failed attempt. */
+    onRetry?: (info: {
+        attempt: number;
+        delayMs: number;
+        reason: string;
+    }) => void;
+    /** Sleep override for tests. Defaults to setTimeout. */
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Run a fetch with retries on transient failures. Returns the final
+ * Response (whether successful or not — caller decides), or throws if
+ * the AbortSignal fires or all attempts fail with a thrown error.
+ */
+declare function fetchWithRetry(doFetch: (signal: AbortSignal) => Promise<Response>, signal: AbortSignal, retryOpt?: RetryOptions): Promise<Response>;
+/**
+ * Chunk-splitter that turns one large string into N streamable text chunks.
+ * Useful when a provider returns the full response in one shot and you
+ * want to feed it to a UI that expects streaming.
+ *
+ * Default splits by whitespace boundaries with a target chunk size of ~32
+ * characters.
+ */
+declare function chunkText(text: string, targetSize?: number): string[];
+/**
+ * Build a StreamSource from a non-streaming fetch. The adapter is
+ * auto-completing: it fetches once, then yields the text as a sequence
+ * of chunks so UIs see the same streaming shape they'd see from a
+ * native streaming provider.
+ *
+ * Use this when you're wiring a provider that only has a non-streaming
+ * endpoint but you want consumers (useChat, the runtime) to get
+ * identical ergonomics.
+ */
+declare function simulateStream(doFetch: (signal: AbortSignal) => Promise<Response>, extractText: (response: Response) => Promise<string>, errorLabel: string, options?: {
+    chunkSize?: number;
+    delayMs?: number;
+    retry?: RetryOptions;
+}): StreamSource;
+
 interface AnthropicConfig {
     apiKey: string;
     model: string;
     baseUrl?: string;
     maxTokens?: number;
+    retry?: RetryOptions;
 }
 declare function anthropic(config: AnthropicConfig): AdapterFactory;
 
@@ -26,6 +90,7 @@ interface OpenAIConfig {
     apiKey: string;
     model: string;
     baseUrl?: string;
+    retry?: RetryOptions;
 }
 declare function openai(config: OpenAIConfig): AdapterFactory;
 
@@ -33,6 +98,7 @@ interface GeminiConfig {
     apiKey: string;
     model: string;
     baseUrl?: string;
+    retry?: RetryOptions;
 }
 declare function gemini(config: GeminiConfig): AdapterFactory;
 
@@ -46,6 +112,7 @@ declare const grok: (config: OpenAICompatibleConfig) => _agentskit_core.AdapterF
 interface OllamaConfig {
     model: string;
     baseUrl?: string;
+    retry?: RetryOptions;
 }
 declare function ollama(config: OllamaConfig): AdapterFactory;
 
@@ -74,7 +141,127 @@ declare function langgraph(config: LangGraphConfig): AdapterFactory;
 interface VercelAIConfig {
     api: string;
     headers?: Record<string, string>;
+    retry?: RetryOptions;
 }
 declare function vercelAI(config: VercelAIConfig): AdapterFactory;
 
-export { type AnthropicConfig, type CreateAdapterConfig, type DeepSeekConfig, type GeminiConfig, type GenericAdapterConfig, type GrokConfig, type KimiConfig, type LangChainConfig, type LangGraphConfig, type OllamaConfig, type OpenAIConfig, type VercelAIConfig, anthropic, createAdapter, deepseek, gemini, generic, grok, kimi, langchain, langgraph, ollama, openai, vercelAI };
+type MockResponse = StreamChunk[] | ((request: AdapterRequest) => StreamChunk[]);
+interface MockAdapterOptions {
+    /**
+     * Static chunks, a request-aware function, or a sequence of responses
+     * (the i-th call returns the i-th item, looping when exhausted).
+     */
+    response: MockResponse | MockResponse[];
+    /** ms between yielded chunks. Default 0 (synchronous). */
+    delayMs?: number;
+    /** Track every request the adapter received. Useful for assertions. */
+    history?: AdapterRequest[];
+}
+/**
+ * A deterministic adapter for tests, demos, and dry-run experiments.
+ *
+ * Conforms to ADR 0001 — Adapter contract:
+ * - createSource is pure (A1) — no work until stream() runs
+ * - Always emits a terminal chunk (A3)
+ * - abort() is safe (A6)
+ * - Does not mutate input messages (A7)
+ *
+ * Examples:
+ *
+ *   // Static
+ *   const adapter = mockAdapter({
+ *     response: [
+ *       { type: 'text', content: 'Hello!' },
+ *       { type: 'done' },
+ *     ],
+ *   })
+ *
+ *   // Request-aware
+ *   const adapter = mockAdapter({
+ *     response: req => {
+ *       const last = req.messages[req.messages.length - 1]?.content ?? ''
+ *       return [
+ *         { type: 'text', content: 'Echo: ' + last },
+ *         { type: 'done' },
+ *       ]
+ *     },
+ *   })
+ *
+ *   // Sequenced — different output each call
+ *   const adapter = mockAdapter({
+ *     response: [
+ *       [{ type: 'text', content: 'first' }, { type: 'done' }],
+ *       [{ type: 'text', content: 'second' }, { type: 'done' }],
+ *     ],
+ *   })
+ */
+declare function mockAdapter(options: MockAdapterOptions): AdapterFactory;
+interface RecordedTurn {
+    /** ISO timestamp when this turn was recorded. */
+    recordedAt: string;
+    /** The request that produced this turn. */
+    request: AdapterRequest;
+    /** Every chunk yielded by the wrapped adapter. */
+    chunks: StreamChunk[];
+}
+type RecordingFixture = RecordedTurn[];
+interface RecordingSink {
+    push(turn: RecordedTurn): void | Promise<void>;
+}
+/**
+ * Wrap a real adapter so every turn is captured to a sink. Use this in
+ * dev to build up a fixture, then replay with replayAdapter() in tests.
+ */
+declare function recordingAdapter(inner: AdapterFactory, sink: RecordingSink): AdapterFactory;
+/**
+ * In-memory recording sink — useful for tests and ephemeral capture.
+ */
+declare function inMemorySink(): RecordingSink & {
+    fixture: RecordingFixture;
+};
+/**
+ * Replay an adapter from a recorded fixture. Each turn maps 1:1 to a
+ * recorded entry by index — call N replays fixture[N % fixture.length].
+ */
+declare function replayAdapter(fixture: RecordingFixture): AdapterFactory;
+
+interface OpenAIEmbedderConfig {
+    apiKey: string;
+    model?: string;
+    baseUrl?: string;
+}
+declare function openaiEmbedder(config: OpenAIEmbedderConfig): EmbedFn;
+
+interface GeminiEmbedderConfig {
+    apiKey: string;
+    model?: string;
+    baseUrl?: string;
+}
+declare function geminiEmbedder(config: GeminiEmbedderConfig): EmbedFn;
+
+interface OllamaEmbedderConfig {
+    model?: string;
+    baseUrl?: string;
+}
+declare function ollamaEmbedder(config: OllamaEmbedderConfig): EmbedFn;
+
+interface OpenAICompatibleEmbedderConfig {
+    apiKey: string;
+    model: string;
+    baseUrl?: string;
+}
+declare function createOpenAICompatibleEmbedder(provider: string, defaultBaseUrl: string): (config: OpenAICompatibleEmbedderConfig) => EmbedFn;
+
+interface DeepSeekEmbedderConfig extends OpenAICompatibleEmbedderConfig {
+}
+declare const deepseekEmbedder: (config: OpenAICompatibleEmbedderConfig) => _agentskit_core.EmbedFn;
+
+interface GrokEmbedderConfig extends OpenAICompatibleEmbedderConfig {
+}
+declare const grokEmbedder: (config: OpenAICompatibleEmbedderConfig) => _agentskit_core.EmbedFn;
+
+interface KimiEmbedderConfig extends OpenAICompatibleEmbedderConfig {
+}
+declare const kimiEmbedder: (config: OpenAICompatibleEmbedderConfig) => _agentskit_core.EmbedFn;
+
+export { type AnthropicConfig, type CreateAdapterConfig, type DeepSeekConfig, type DeepSeekEmbedderConfig, type GeminiConfig, type GeminiEmbedderConfig, type GenericAdapterConfig, type GrokConfig, type GrokEmbedderConfig, type KimiConfig, type KimiEmbedderConfig, type LangChainConfig, type LangGraphConfig, type MockAdapterOptions, type MockResponse, type OllamaConfig, type OllamaEmbedderConfig, type OpenAICompatibleEmbedderConfig, type OpenAIConfig, type OpenAIEmbedderConfig, type RecordedTurn, type RecordingFixture, type RecordingSink, type RetryOptions, type VercelAIConfig, anthropic, chunkText, createAdapter, createOpenAICompatibleEmbedder, deepseek, deepseekEmbedder, fetchWithRetry, gemini, geminiEmbedder, generic, grok, grokEmbedder, inMemorySink, kimi, kimiEmbedder, langchain, langgraph, mockAdapter, ollama, ollamaEmbedder, openai, openaiEmbedder, recordingAdapter, replayAdapter, simulateStream, vercelAI };