@agentskit/adapters 0.7.1 → 0.10.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _agentskit_core from '@agentskit/core';
-import { AdapterRequest, StreamChunk, AdapterFactory, StreamSource, EmbedFn } from '@agentskit/core';
+import { AdapterRequest, StreamChunk, AdapterFactory, StreamSource, AdapterCapabilities, EmbedFn } from '@agentskit/core';
 
 interface CreateAdapterConfig {
     send: (request: AdapterRequest) => Promise<ReadableStream | Response>;
@@ -153,6 +153,339 @@ interface VercelAIConfig {
 }
 declare function vercelAI(config: VercelAIConfig): AdapterFactory;
 
+interface MistralConfig extends OpenAICompatibleConfig {
+}
+/**
+ * Mistral AI. Uses the OpenAI-compatible chat completions endpoint.
+ * Default models: `mistral-large-latest`, `mistral-small-latest`,
+ * `open-mistral-nemo`.
+ */
+declare const mistral: (config: OpenAICompatibleConfig) => _agentskit_core.AdapterFactory;
+
+interface CohereConfig extends OpenAICompatibleConfig {
+}
+/**
+ * Cohere Command models via Cohere's OpenAI-compatibility endpoint.
+ *
+ * - Streams tokens via SSE (OpenAI-compatible chunks).
+ * - Supports tool calls in the OpenAI `tools` shape.
+ * - Reports `usage` on the final stream chunk when the upstream model
+ *   returns it (Cohere's compatibility layer mirrors OpenAI's
+ *   `stream_options: { include_usage: true }` semantics).
+ * - Inherits auto-retry from the shared OpenAI core (`retry`).
+ *
+ * Default model: `command-r-plus`. Override via `model`.
+ */
+declare function cohere(config: Partial<CohereConfig> & {
+    apiKey: string;
+}): AdapterFactory;
+/** Alias for naming consistency with other native adapters. */
+declare const cohereAdapter: typeof cohere;
+
+interface TogetherConfig extends OpenAICompatibleConfig {
+}
+/**
+ * Together AI. OpenAI-compatible endpoint, broad open-model catalog
+ * (Llama, Qwen, DeepSeek, Mixtral, etc.).
+ */
+declare const together: (config: OpenAICompatibleConfig) => _agentskit_core.AdapterFactory;
+
+interface GroqConfig extends OpenAICompatibleConfig {
+}
+/**
+ * Groq — OpenAI-compatible endpoint serving Llama / Mixtral on LPUs.
+ * Known for very low first-token latency.
+ *
+ * Default model: `llama-3.3-70b-versatile`.
+ */
+declare function groq(config: Partial<GroqConfig> & {
+    apiKey: string;
+}): AdapterFactory;
+/** Alias for naming consistency with other native adapters. */
+declare const groqAdapter: typeof groq;
+
+interface FireworksConfig extends OpenAICompatibleConfig {
+}
+/**
+ * Fireworks AI. OpenAI-compatible endpoint with tuned open-source
+ * models and fine-tunes (Llama, DeepSeek, Qwen, etc.).
+ */
+declare const fireworks: (config: OpenAICompatibleConfig) => _agentskit_core.AdapterFactory;
+
+interface OpenRouterConfig extends OpenAICompatibleConfig {
+}
+/**
+ * OpenRouter — routes to 300+ provider models behind a single
+ * OpenAI-compatible endpoint. Pass the fully-qualified id as
+ * `model`, e.g. `anthropic/claude-sonnet-4-6`.
+ */
+declare const openrouter: (config: OpenAICompatibleConfig) => _agentskit_core.AdapterFactory;
+
+interface HuggingFaceConfig extends OpenAICompatibleConfig {
+}
+/**
+ * Hugging Face Inference Providers router. OpenAI-compatible
+ * endpoint that fans out to HF-hosted model inference providers.
+ * Pass any supported repo id as `model`, e.g.
+ * `meta-llama/Meta-Llama-3.1-8B-Instruct`.
+ */
+declare const huggingface: (config: OpenAICompatibleConfig) => _agentskit_core.AdapterFactory;
+
+interface LMStudioConfig extends OpenAICompatibleConfig {
+}
+/**
+ * LM Studio local server. Start the built-in OpenAI-compatible
+ * server in LM Studio, then point this adapter at
+ * `http://localhost:1234/v1` (the default).
+ */
+declare const lmstudio: (config: OpenAICompatibleConfig) => _agentskit_core.AdapterFactory;
+
+interface VLLMConfig extends OpenAICompatibleConfig {
+}
+/**
+ * vLLM's OpenAI-compatible serving endpoint. Defaults to
+ * `http://localhost:8000/v1` — the standard `vllm serve ...` port.
+ */
+declare const vllm: (config: OpenAICompatibleConfig) => _agentskit_core.AdapterFactory;
+
+interface LlamaCppConfig extends OpenAICompatibleConfig {
+}
+/**
+ * llama.cpp's OpenAI-compatible HTTP server (`llama-server`). Defaults
+ * to `http://localhost:8080/v1`, matching the binary's default port.
+ */
+declare const llamacpp: (config: OpenAICompatibleConfig) => _agentskit_core.AdapterFactory;
+
+interface CerebrasConfig extends OpenAICompatibleConfig {
+}
+/**
+ * Cerebras — ultra-fast inference on wafer-scale chips. OpenAI-compatible
+ * endpoint serving Llama / Qwen models with very low first-token latency.
+ *
+ * Default model: `llama-3.3-70b`.
+ */
+declare function cerebras(config: Partial<CerebrasConfig> & {
+    apiKey: string;
+}): AdapterFactory;
+declare const cerebrasAdapter: typeof cerebras;
+
+interface AzureOpenAIConfig {
+    apiKey: string;
+    /** Resource endpoint, e.g. `https://my-resource.openai.azure.com`. */
+    endpoint: string;
+    /** Deployment name (NOT the underlying model name — Azure routes by deployment). */
+    deployment: string;
+    /** Azure REST `api-version`. Defaults to `2024-10-21`. */
+    apiVersion?: string;
+    retry?: RetryOptions;
+    /** Surface usage by setting `stream_options.include_usage`. Defaults to true. */
+    includeUsage?: boolean;
+}
+declare function azureOpenAI(config: AzureOpenAIConfig): AdapterFactory;
+declare const azureOpenAIAdapter: typeof azureOpenAI;
+
+interface ReplicateConfig {
+    apiKey: string;
+    /** Replicate model id, e.g. `meta/meta-llama-3-70b-instruct`. */
+    model: string;
+    /** Optional pinned version hash (for non-official models). */
+    version?: string;
+    /** Override the prediction endpoint base. */
+    baseUrl?: string;
+    /** Map AdapterRequest → Replicate `input` object. Defaults to `{ prompt }`. */
+    toInput?: (request: AdapterRequest) => Record<string, unknown>;
+}
+declare function replicate(config: ReplicateConfig): AdapterFactory;
+declare const replicateAdapter: typeof replicate;
+
+interface BailConfig extends OpenAICompatibleConfig {
+}
+/**
+ * Alibaba Bailian (Qwen) via the DashScope OpenAI-compatibility endpoint.
+ *
+ * Supports the Qwen-2.5 / 3 chat series and Qwen-VL multimodal models. APAC
+ * users typically prefer this over OpenAI for latency + data residency.
+ *
+ * Default model: `qwen-max`.
+ */
+declare function bail(config: Partial<BailConfig> & {
+    apiKey: string;
+}): AdapterFactory;
+declare const bailAdapter: typeof bail;
+/** Alias matching Alibaba's product naming. */
+declare const qwen: typeof bail;
+
+interface VertexConfig {
+    /** GCP project id. */
+    project: string;
+    /** Region, e.g. `us-central1`. */
+    region: string;
+    /** Vertex model id, e.g. `gemini-2.5-pro`. */
+    model: string;
+    /**
+     * OAuth2 access token, or a function returning one (called per request).
+     *
+     * Use the `google-auth-library` (or `gcloud auth print-access-token`) to
+     * mint these — the adapter intentionally doesn't take that as a hard dep.
+     */
+    accessToken: string | (() => string | Promise<string>);
+    /** Override the publisher (defaults to `google`; set for partner publishers). */
+    publisher?: string;
+    retry?: RetryOptions;
+}
+declare function vertex(config: VertexConfig): AdapterFactory;
+declare const vertexAdapter: typeof vertex;
+
+interface BedrockConfig {
+    /** Bedrock model id, e.g. `anthropic.claude-3-5-sonnet-20241022-v2:0`. */
+    model: string;
+    /** AWS region (e.g. `us-east-1`). Falls back to the SDK's default credential chain. */
+    region?: string;
+    /** Override `max_tokens` (Anthropic on Bedrock requires it). Defaults to 4096. */
+    maxTokens?: number;
+    /**
+     * Override the SDK client. Mostly for tests; production code should let the
+     * adapter create the client from `region` + the SDK's default credential
+     * chain.
+     */
+    client?: BedrockRuntimeClientLike;
+}
+/**
+ * Minimal structural type for `BedrockRuntimeClient` so we don't take a hard
+ * dep on `@aws-sdk/client-bedrock-runtime`.
+ */
+interface BedrockRuntimeClientLike {
+    send(command: {
+        input: BedrockInvokeInput;
+    }): Promise<{
+        body?: AsyncIterable<{
+            chunk?: {
+                bytes?: Uint8Array;
+            };
+        }>;
+    }>;
+}
+interface BedrockInvokeInput {
+    modelId: string;
+    contentType: string;
+    accept: string;
+    body: string;
+}
+declare function bedrock(config: BedrockConfig): AdapterFactory;
+declare const bedrockAdapter: typeof bedrock;
+
+interface RouterCandidate {
+    id: string;
+    adapter: AdapterFactory;
+    /**
+     * Relative cost hint (lower wins for policy='cheapest'). Only
+     * relative values matter — use $/1M tokens or any consistent unit.
+     */
+    cost?: number;
+    /** Typical latency in ms. Lower wins for policy='fastest'. */
+    latencyMs?: number;
+    /**
+     * Capability override. Defaults to `adapter.capabilities`.
+     * Used to reject candidates missing required features
+     * (e.g. tools, multiModal).
+     */
+    capabilities?: AdapterCapabilities;
+    /** Free-form tags used by classifier routing (e.g. 'fast', 'coding'). */
+    tags?: string[];
+}
+type RouterPolicy = 'cheapest' | 'fastest' | 'capability-match' | ((input: {
+    request: AdapterRequest;
+    candidates: RouterCandidate[];
+}) => string | Promise<string>);
+interface RouterOptions {
+    candidates: RouterCandidate[];
+    /** Policy when `classify` doesn't pick a candidate. Default 'cheapest'. */
+    policy?: RouterPolicy;
+    /**
+     * Fast path: inspect the request, return a candidate id or tag(s).
+     * Return `undefined` to fall back to `policy`.
+     */
+    classify?: (request: AdapterRequest) => string | string[] | undefined;
+    /** Observability hook — fires once per decision. */
+    onRoute?: (decision: {
+        id: string;
+        reason: string;
+        request: AdapterRequest;
+    }) => void;
+}
+/**
+ * Build an AdapterFactory that picks one of N candidates per request.
+ *
+ * Resolution order:
+ *  1. `classify(request)` returns a candidate id → use it
+ *  2. `classify(request)` returns tag(s) → filter by tags, then `policy`
+ *  3. Fall back to `policy` over all capability-matched candidates
+ */
+declare function createRouter(options: RouterOptions): AdapterFactory;
+
+interface EnsembleCandidate {
+    id: string;
+    adapter: AdapterFactory;
+    /** Weight used by 'weighted-vote' aggregator. Default 1. */
+    weight?: number;
+}
+interface EnsembleBranchResult {
+    id: string;
+    text: string;
+    chunks: StreamChunk[];
+    error?: Error;
+}
+type EnsembleAggregator = 'majority-vote' | 'concat' | 'longest' | ((branches: EnsembleBranchResult[]) => string | Promise<string>);
+interface EnsembleOptions {
+    candidates: EnsembleCandidate[];
+    /** How to combine branches into the single output text. Default 'majority-vote'. */
+    aggregate?: EnsembleAggregator;
+    /** Per-candidate timeout in ms. Branches that time out are marked with an error. */
+    timeoutMs?: number;
+    /** Observability hook — fires once with every branch's result. */
+    onBranches?: (branches: EnsembleBranchResult[]) => void;
+}
+/**
+ * Build an AdapterFactory that runs the same request against N
+ * candidates in parallel, then aggregates the results into a single
+ * text output. Unlike `speculate` (which picks a winner), `ensemble`
+ * combines — majority vote, concatenation, longest, or a custom fn.
+ *
+ * The returned source emits a single `{ type: 'text' }` chunk with
+ * the aggregated output followed by `{ type: 'done' }`, so it plugs
+ * into any runtime that expects a regular streaming adapter.
+ */
+declare function createEnsembleAdapter(options: EnsembleOptions): AdapterFactory;
+
+interface FallbackOptions {
+    /**
+     * Predicate deciding whether an error from a given adapter should
+     * trigger fall-through to the next. Default: always retry the next.
+     */
+    shouldRetry?: (error: Error, index: number) => boolean;
+    /** Observability hook — fires when one adapter fails and the chain advances. */
+    onFallback?: (from: {
+        id: string;
+        index: number;
+        error: Error;
+    }) => void;
+}
+interface FallbackCandidate {
+    id: string;
+    adapter: AdapterFactory;
+}
+/**
+ * Try adapters in order. If the first fails (throws while opening, or
+ * errors mid-stream before emitting any non-done chunk), fall through
+ * to the next. As soon as a candidate produces its first real chunk,
+ * that's the committed one — we don't retroactively retry mid-stream.
+ *
+ * Errors that happen *after* committing are propagated; the caller
+ * sees a normal streaming failure, not a mysterious cross-candidate
+ * retry that could duplicate tool calls.
+ */
+declare function createFallbackAdapter(candidates: FallbackCandidate[], options?: FallbackOptions): AdapterFactory;
+
 type MockResponse = StreamChunk[] | ((request: AdapterRequest) => StreamChunk[]);
 interface MockAdapterOptions {
     /**
@@ -272,4 +605,4 @@ 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 };
+export { type AnthropicConfig, type AzureOpenAIConfig, type BailConfig, type BedrockConfig, type BedrockRuntimeClientLike, type CerebrasConfig, type CohereConfig, type CreateAdapterConfig, type DeepSeekConfig, type DeepSeekEmbedderConfig, type EnsembleAggregator, type EnsembleBranchResult, type EnsembleCandidate, type EnsembleOptions, type FallbackCandidate, type FallbackOptions, type FireworksConfig, type GeminiConfig, type GeminiEmbedderConfig, type GenericAdapterConfig, type GrokConfig, type GrokEmbedderConfig, type GroqConfig, type HuggingFaceConfig, type KimiConfig, type KimiEmbedderConfig, type LMStudioConfig, type LangChainConfig, type LangGraphConfig, type LlamaCppConfig, type MistralConfig, type MockAdapterOptions, type MockResponse, type OllamaConfig, type OllamaEmbedderConfig, type OpenAICompatibleEmbedderConfig, type OpenAIConfig, type OpenAIEmbedderConfig, type OpenRouterConfig, type RecordedTurn, type RecordingFixture, type RecordingSink, type ReplicateConfig, type RetryOptions, type RouterCandidate, type RouterOptions, type RouterPolicy, type TogetherConfig, type VLLMConfig, type VercelAIConfig, type VertexConfig, anthropic, azureOpenAI, azureOpenAIAdapter, bail, bailAdapter, bedrock, bedrockAdapter, cerebras, cerebrasAdapter, chunkText, cohere, cohereAdapter, createAdapter, createEnsembleAdapter, createFallbackAdapter, createOpenAICompatibleEmbedder, createRouter, deepseek, deepseekEmbedder, fetchWithRetry, fireworks, gemini, geminiEmbedder, generic, grok, grokEmbedder, groq, groqAdapter, huggingface, inMemorySink, kimi, kimiEmbedder, langchain, langgraph, llamacpp, lmstudio, mistral, mockAdapter, ollama, ollamaEmbedder, openai, openaiEmbedder, openrouter, qwen, recordingAdapter, replayAdapter, replicate, replicateAdapter, simulateStream, together, vercelAI, vertex, vertexAdapter, vllm };