@agentskit/adapters 0.7.0 → 0.9.1

package/dist/index.d.cts

@@ -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,203 @@ 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 the OpenAI-compatibility endpoint.
+ * Default models: `command-r-plus`, `command-r`, `command-light`.
+ */
+declare const cohere: (config: OpenAICompatibleConfig) => _agentskit_core.AdapterFactory;
+
+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 LPU.
+ * Known for very low first-token latency.
+ */
+declare const groq: (config: OpenAICompatibleConfig) => _agentskit_core.AdapterFactory;
+
+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 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 +469,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 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 RetryOptions, type RouterCandidate, type RouterOptions, type RouterPolicy, type TogetherConfig, type VLLMConfig, type VercelAIConfig, anthropic, chunkText, cohere, createAdapter, createEnsembleAdapter, createFallbackAdapter, createOpenAICompatibleEmbedder, createRouter, deepseek, deepseekEmbedder, fetchWithRetry, fireworks, gemini, geminiEmbedder, generic, grok, grokEmbedder, groq, huggingface, inMemorySink, kimi, kimiEmbedder, langchain, langgraph, llamacpp, lmstudio, mistral, mockAdapter, ollama, ollamaEmbedder, openai, openaiEmbedder, openrouter, recordingAdapter, replayAdapter, simulateStream, together, vercelAI, vllm };

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,203 @@ 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 the OpenAI-compatibility endpoint.
+ * Default models: `command-r-plus`, `command-r`, `command-light`.
+ */
+declare const cohere: (config: OpenAICompatibleConfig) => _agentskit_core.AdapterFactory;
+
+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 LPU.
+ * Known for very low first-token latency.
+ */
+declare const groq: (config: OpenAICompatibleConfig) => _agentskit_core.AdapterFactory;
+
+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 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 +469,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 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 RetryOptions, type RouterCandidate, type RouterOptions, type RouterPolicy, type TogetherConfig, type VLLMConfig, type VercelAIConfig, anthropic, chunkText, cohere, createAdapter, createEnsembleAdapter, createFallbackAdapter, createOpenAICompatibleEmbedder, createRouter, deepseek, deepseekEmbedder, fetchWithRetry, fireworks, gemini, geminiEmbedder, generic, grok, grokEmbedder, groq, huggingface, inMemorySink, kimi, kimiEmbedder, langchain, langgraph, llamacpp, lmstudio, mistral, mockAdapter, ollama, ollamaEmbedder, openai, openaiEmbedder, openrouter, recordingAdapter, replayAdapter, simulateStream, together, vercelAI, vllm };