@reactive-agents/llm-provider 0.7.7 → 0.8.0

package/dist/index.d.ts

@@ -590,6 +590,30 @@ declare const ToolCallSchema: Schema.Struct<{
  * When the model decides to call a tool, this describes which tool and with what inputs.
  */
 type ToolCall = Schema.Schema.Type<typeof ToolCallSchema>;
+/**
+ * Log probability information for a single token.
+ * Returned by providers that support logprobs (OpenAI, Ollama).
+ *
+ * @example
+ * ```typescript
+ * const logprob: TokenLogprob = {
+ *   token: "Paris",
+ *   logprob: -0.0234,
+ *   topLogprobs: [
+ *     { token: "Paris", logprob: -0.0234 },
+ *     { token: "London", logprob: -3.89 },
+ *   ]
+ * };
+ * ```
+ */
+type TokenLogprob = {
+    readonly token: string;
+    readonly logprob: number;
+    readonly topLogprobs?: readonly {
+        token: string;
+        logprob: number;
+    }[];
+};
 /**
  * Request to the LLM for a completion.
  * Includes messages, model configuration, tool definitions, and sampling parameters.
@@ -630,6 +654,10 @@ type CompletionRequest = {
     readonly tools?: readonly ToolDefinition[];
     /** System prompt (optional, prepended to user messages) */
     readonly systemPrompt?: string;
+    /** Request log probabilities for each output token (optional) */
+    readonly logprobs?: boolean;
+    /** Number of most likely tokens to return log probabilities for (optional, 1-20) */
+    readonly topLogprobs?: number;
 };
 /**
  * Schema for LLM response.
@@ -675,6 +703,15 @@ declare const CompletionResponseSchema: Schema.Struct<{
     }>>>;
     /** Internal reasoning from thinking models (e.g. <think> blocks from qwen3, DeepSeek-R1) */
     thinking: Schema.optional<typeof Schema.String>;
+    /** Token-level log probabilities (when requested via logprobs in CompletionRequest) */
+    logprobs: Schema.optional<Schema.Array$<Schema.Struct<{
+        token: typeof Schema.String;
+        logprob: typeof Schema.Number;
+        topLogprobs: Schema.optional<Schema.Array$<Schema.Struct<{
+            token: typeof Schema.String;
+            logprob: typeof Schema.Number;
+        }>>>;
+    }>>>;
 }>;
 /**
  * LLM response to a completion request.
@@ -729,6 +766,11 @@ type StreamEvent = {
     readonly type: "usage";
     /** Final token usage for the request */
     readonly usage: TokenUsage;
+} | {
+    /** Token-level log probabilities (accumulated over the full response) */
+    readonly type: "logprobs";
+    /** Per-token logprob data */
+    readonly logprobs: readonly TokenLogprob[];
 } | {
     /** Error occurred during streaming */
     readonly type: "error";
@@ -1286,23 +1328,49 @@ declare const GeminiProviderLive: Layer.Layer<LLMService, never, LLMConfig>;
 
 declare const LiteLLMProviderLive: Layer.Layer<LLMService, never, LLMConfig>;
 
+interface ToolCallSpec {
+    name: string;
+    args: Record<string, unknown>;
+    id?: string;
+}
+type TestTurn = {
+    text: string;
+    match?: string;
+} | {
+    json: unknown;
+    match?: string;
+} | {
+    toolCall: ToolCallSpec;
+    match?: string;
+} | {
+    toolCalls: ToolCallSpec[];
+    match?: string;
+} | {
+    error: string;
+    match?: string;
+};
 /**
- * Create a deterministic test LLM service.
- * Returns responses based on pattern matching against prompt content.
+ * Create a deterministic test LLM service using a scenario of sequential turns.
+ *
+ * Turns are consumed in order. Each LLM call scans forward from the current
+ * position for the first matching turn (or unconditional turn). The last turn
+ * repeats when the scenario is exhausted, so single-turn tests need no special
+ * handling.
  *
  * Usage:
  * ```ts
- * const layer = TestLLMServiceLayer({
- *   "capital of France": "Paris",
- *   "plan": '{"goal":"test","steps":[]}',
- * });
+ * const layer = TestLLMServiceLayer([
+ *   { toolCall: { name: "web-search", args: { query: "AI news" } } },
+ *   { text: "Here is the summary..." },
+ * ]);
  * ```
  */
-declare const TestLLMService: (responses: Record<string, string>) => typeof LLMService.Service;
+declare const TestLLMService: (scenario: TestTurn[]) => typeof LLMService.Service;
 /**
- * Create a test Layer for LLMService with optional pattern-matched responses.
+ * Create a test Layer for LLMService with a deterministic turn scenario.
+ * Turns are consumed sequentially; the last turn repeats when exhausted.
  */
-declare const TestLLMServiceLayer: (responses?: Record<string, string>) => Layer.Layer<LLMService, never, never>;
+declare const TestLLMServiceLayer: (scenario?: TestTurn[]) => Layer.Layer<LLMService, never, never>;
 
 /**
  * Estimate token count for messages.
@@ -1422,7 +1490,7 @@ declare function getProviderDefaultModel(provider: string): string | undefined;
  * Create the LLM provider layer for a specific provider.
  * Uses env vars for configuration by default.
  */
-declare const createLLMProviderLayer: (provider?: "anthropic" | "openai" | "ollama" | "gemini" | "litellm" | "test", testResponses?: Record<string, string>, model?: string, modelParams?: {
+declare const createLLMProviderLayer: (provider?: "anthropic" | "openai" | "ollama" | "gemini" | "litellm" | "test", testScenario?: TestTurn[], model?: string, modelParams?: {
     thinking?: boolean;
     temperature?: number;
     maxTokens?: number;
@@ -1476,4 +1544,119 @@ interface CircuitBreaker {
  */
 declare const makeCircuitBreaker: (config?: Partial<CircuitBreakerConfig>) => CircuitBreaker;
 
-export { AnthropicProviderLive, type CacheControl, CacheControlSchema, type CacheableContentBlock, type CircuitBreaker, type CircuitBreakerConfig, type CompletionRequest, type CompletionResponse, CompletionResponseSchema, type ComplexityAnalysis, ComplexityAnalysisSchema, type ContentBlock, DefaultEmbeddingConfig, type EmbeddingCache, type EmbeddingConfig, EmbeddingConfigSchema, GeminiProviderLive, ImageContentBlockSchema, type ImageSource, ImageSourceSchema, LLMConfig, LLMConfigFromEnv, LLMContextOverflowError, LLMError, type LLMErrors, type LLMMessage, LLMParseError, type LLMProvider, LLMProviderType, LLMRateLimitError, LLMService, LLMTimeoutError, LiteLLMProviderLive, LocalProviderLive, type ModelConfig, ModelConfigSchema, type ModelPresetName, ModelPresets, OpenAIProviderLive, PROVIDER_DEFAULT_MODELS, type Plan, PlanSchema, PromptManager, PromptManagerLive, type ReActAction, ReActActionSchema, type Reflection, ReflectionSchema, type StopReason, StopReasonSchema, type StrategySelection, StrategySelectionSchema, type StreamEvent, type StructuredCompletionRequest, type StructuredOutputCapabilities, TestLLMService, TestLLMServiceLayer, TextContentBlockSchema, type ThoughtEvaluation, ThoughtEvaluationSchema, type TokenUsage, TokenUsageSchema, type ToolCall, ToolCallSchema, type ToolDefinition, ToolDefinitionSchema, ToolResultContentBlockSchema, ToolUseContentBlockSchema, type TruncationStrategy, calculateCost, createLLMProviderLayer, createLLMProviderLayerWithConfig, defaultCircuitBreakerConfig, estimateTokenCount, getProviderDefaultModel, llmConfigFromEnv, makeCacheable, makeCircuitBreaker, makeEmbeddingCache, retryPolicy };
+/**
+ * Configuration for the FallbackChain graceful degradation strategy.
+ *
+ * Specifies ordered lists of fallback providers and models, along with
+ * the error threshold that triggers switching to the next provider.
+ *
+ * @example
+ * ```typescript
+ * const config: FallbackConfig = {
+ *   providers: ["anthropic", "openai", "gemini"],
+ *   models: ["claude-sonnet-4-20250514", "claude-haiku-3-20250520"],
+ *   errorThreshold: 3,
+ * };
+ * ```
+ */
+interface FallbackConfig {
+    /** Ordered list of provider names to try in sequence. */
+    readonly providers: string[];
+    /** Ordered list of model names to try within the same provider. */
+    readonly models?: string[];
+    /** Consecutive errors on a provider before switching to next. Default: 3 */
+    readonly errorThreshold?: number;
+}
+/**
+ * FallbackChain manages graceful degradation when LLM providers or models fail.
+ *
+ * Tracks consecutive errors per provider and automatically switches to the next
+ * provider when the error threshold is exceeded. On rate limits (429), falls back
+ * to a cheaper model within the same provider.
+ *
+ * Use case: Deploy with Anthropic as primary, OpenAI as secondary, Gemini as
+ * fallback. If Claude API goes down, automatically route to GPT. If quota exceeded,
+ * switch from claude-sonnet to claude-haiku to reduce cost/load.
+ *
+ * @example
+ * ```typescript
+ * const chain = new FallbackChain({
+ *   providers: ["anthropic", "openai"],
+ *   models: ["claude-sonnet-4-20250514", "claude-haiku-3-20250520"],
+ *   errorThreshold: 3,
+ * });
+ *
+ * // Record errors
+ * chain.recordError("anthropic");
+ * chain.recordError("anthropic");
+ * chain.recordError("anthropic"); // threshold met, switch to openai
+ *
+ * console.log(chain.currentProvider()); // "openai"
+ *
+ * // Record rate limit, fall back to cheaper model
+ * chain.recordRateLimit("openai");
+ * console.log(chain.currentModel()); // "claude-haiku-3-20250520"
+ *
+ * // Successful call resets error count
+ * chain.recordSuccess("openai");
+ *
+ * // Check if more fallbacks available
+ * if (!chain.hasFallback()) {
+ *   console.log("All providers exhausted!");
+ * }
+ * ```
+ */
+declare class FallbackChain {
+    private readonly config;
+    /** Error count per provider. */
+    private readonly errorCounts;
+    /** Current index in the providers list. */
+    private currentProviderIndex;
+    /** Current index in the models list. */
+    private currentModelIndex;
+    /** Threshold for switching to next provider. */
+    private readonly threshold;
+    constructor(config: FallbackConfig);
+    /**
+     * Record an error for the given provider.
+     * Increments the error count and switches to the next provider if threshold is met.
+     *
+     * @param provider - Provider name that errored
+     */
+    recordError(provider: string): void;
+    /**
+     * Record a rate limit error (429) for the given provider.
+     * Falls back to the next model in the chain.
+     *
+     * @param _provider - Provider name that was rate limited (parameter name _ to indicate unused)
+     */
+    recordRateLimit(_provider: string): void;
+    /**
+     * Record a successful call for the given provider.
+     * Resets the error count for that provider.
+     *
+     * @param provider - Provider name that succeeded
+     */
+    recordSuccess(provider: string): void;
+    /**
+     * Get the currently active provider.
+     *
+     * @returns Name of the provider to use
+     */
+    currentProvider(): string;
+    /**
+     * Get the currently active model.
+     * Returns undefined if no models are configured.
+     *
+     * @returns Name of the model to use, or undefined if no models configured
+     */
+    currentModel(): string | undefined;
+    /**
+     * Check if there are more fallbacks available (provider or model).
+     *
+     * @returns true if there are unused fallback providers or models, false if all exhausted
+     */
+    hasFallback(): boolean;
+}
+
+export { AnthropicProviderLive, type CacheControl, CacheControlSchema, type CacheableContentBlock, type CircuitBreaker, type CircuitBreakerConfig, type CompletionRequest, type CompletionResponse, CompletionResponseSchema, type ComplexityAnalysis, ComplexityAnalysisSchema, type ContentBlock, DefaultEmbeddingConfig, type EmbeddingCache, type EmbeddingConfig, EmbeddingConfigSchema, FallbackChain, type FallbackConfig, GeminiProviderLive, ImageContentBlockSchema, type ImageSource, ImageSourceSchema, LLMConfig, LLMConfigFromEnv, LLMContextOverflowError, LLMError, type LLMErrors, type LLMMessage, LLMParseError, type LLMProvider, LLMProviderType, LLMRateLimitError, LLMService, LLMTimeoutError, LiteLLMProviderLive, LocalProviderLive, type ModelConfig, ModelConfigSchema, type ModelPresetName, ModelPresets, OpenAIProviderLive, PROVIDER_DEFAULT_MODELS, type Plan, PlanSchema, PromptManager, PromptManagerLive, type ReActAction, ReActActionSchema, type Reflection, ReflectionSchema, type StopReason, StopReasonSchema, type StrategySelection, StrategySelectionSchema, type StreamEvent, type StructuredCompletionRequest, type StructuredOutputCapabilities, TestLLMService, TestLLMServiceLayer, type TestTurn, TextContentBlockSchema, type ThoughtEvaluation, ThoughtEvaluationSchema, type TokenLogprob, type TokenUsage, TokenUsageSchema, type ToolCall, ToolCallSchema, type ToolCallSpec, type ToolDefinition, ToolDefinitionSchema, ToolResultContentBlockSchema, ToolUseContentBlockSchema, type TruncationStrategy, calculateCost, createLLMProviderLayer, createLLMProviderLayerWithConfig, defaultCircuitBreakerConfig, estimateTokenCount, getProviderDefaultModel, llmConfigFromEnv, makeCacheable, makeCircuitBreaker, makeEmbeddingCache, retryPolicy };