@probelabs/probe 0.6.0-rc154 → 0.6.0-rc161

package/README.md

@@ -131,11 +131,90 @@ export MODEL_NAME=claude-3-5-sonnet-20241022
 **ProbeAgent Features:**
 - **Multi-turn conversations** with automatic history management
 - **Code search integration** - Uses probe's search capabilities transparently
-- **Multiple AI providers** - Supports Anthropic Claude, OpenAI GPT, Google Gemini
+- **Multiple AI providers** - Supports Anthropic Claude, OpenAI GPT, Google Gemini, AWS Bedrock
+- **Automatic retry with exponential backoff** - Handles transient API failures gracefully
+- **Provider fallback** - Seamlessly switch between providers if one fails (e.g., Azure Claude → Bedrock Claude → OpenAI)
 - **Session management** - Maintain conversation context across calls
 - **Token tracking** - Monitor usage and costs
 - **Configurable personas** - Engineer, architect, code-review, and more
 
+### Retry and Fallback Support
+
+ProbeAgent includes comprehensive retry and fallback capabilities for maximum reliability:
+
+```javascript
+import { ProbeAgent } from '@probelabs/probe';
+
+const agent = new ProbeAgent({
+  path: '/path/to/your/project',
+
+  // Configure retry behavior
+  retry: {
+    maxRetries: 5,           // Retry up to 5 times per provider
+    initialDelay: 1000,      // Start with 1 second delay
+    maxDelay: 30000,         // Cap delays at 30 seconds
+    backoffFactor: 2         // Double the delay each time
+  },
+
+  // Configure provider fallback
+  fallback: {
+    strategy: 'custom',
+    providers: [
+      {
+        provider: 'anthropic',
+        apiKey: process.env.ANTHROPIC_API_KEY,
+        model: 'claude-3-7-sonnet-20250219',
+        maxRetries: 5  // Can override retry config per provider
+      },
+      {
+        provider: 'bedrock',
+        region: 'us-west-2',
+        accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+        model: 'anthropic.claude-sonnet-4-20250514-v1:0'
+      },
+      {
+        provider: 'openai',
+        apiKey: process.env.OPENAI_API_KEY,
+        model: 'gpt-4o'
+      }
+    ],
+    maxTotalAttempts: 15  // Maximum attempts across all providers
+  }
+});
+
+// API calls automatically retry on failures and fallback to other providers
+const answer = await agent.answer("Explain this codebase");
+```
+
+**Retry & Fallback Features:**
+- **Exponential backoff** - Intelligently delays retries to avoid overwhelming APIs
+- **Automatic error detection** - Retries on transient errors (Overloaded, 429, 503, timeouts, network errors)
+- **Multi-provider support** - Fallback across Anthropic, OpenAI, Google, and AWS Bedrock
+- **Cross-cloud failover** - Use Azure Claude → Bedrock Claude → OpenAI as fallback chain
+- **Statistics tracking** - Monitor retry attempts and provider usage
+- **Environment variable support** - Configure via env vars for easy deployment
+
+**Quick Setup with Auto-Fallback:**
+```bash
+# Set all your API keys
+export ANTHROPIC_API_KEY=sk-ant-xxx
+export OPENAI_API_KEY=sk-xxx
+export GOOGLE_API_KEY=xxx
+export AUTO_FALLBACK=1  # Enable automatic fallback
+export MAX_RETRIES=5    # Configure retry limit
+```
+
+```javascript
+// No configuration needed - uses all available providers automatically!
+const agent = new ProbeAgent({
+  path: '/path/to/your/project',
+  fallback: { auto: true }
+});
+```
+
+See [docs/RETRY_AND_FALLBACK.md](./docs/RETRY_AND_FALLBACK.md) for complete documentation and examples.
+
 ### Using as an MCP Server
 
 Probe includes a built-in MCP (Model Context Protocol) server for integration with AI assistants:

package/build/agent/FallbackManager.d.ts

@@ -0,0 +1,176 @@
+/**
+ * TypeScript type definitions for FallbackManager
+ */
+
+/**
+ * Fallback strategies
+ */
+export const FALLBACK_STRATEGIES: {
+  /** Try same model on different providers */
+  SAME_MODEL: 'same-model';
+  /** Try different models on same provider */
+  SAME_PROVIDER: 'same-provider';
+  /** Try any available provider/model */
+  ANY: 'any';
+  /** Use custom provider list */
+  CUSTOM: 'custom';
+};
+
+export type FallbackStrategy =
+  | 'same-model'
+  | 'same-provider'
+  | 'any'
+  | 'custom';
+
+/**
+ * Provider configuration
+ */
+export interface ProviderConfig {
+  /** Provider name */
+  provider: 'anthropic' | 'openai' | 'google' | 'bedrock';
+  /** Model name (uses provider default if omitted) */
+  model?: string;
+  /** API key for the provider */
+  apiKey?: string;
+  /** Custom API endpoint */
+  baseURL?: string;
+  /** Max retries for this provider (overrides global) */
+  maxRetries?: number;
+
+  // AWS Bedrock specific
+  /** AWS region (for Bedrock) */
+  region?: string;
+  /** AWS access key ID (for Bedrock) */
+  accessKeyId?: string;
+  /** AWS secret access key (for Bedrock) */
+  secretAccessKey?: string;
+  /** AWS session token (for Bedrock) */
+  sessionToken?: string;
+}
+
+/**
+ * Fallback configuration options
+ */
+export interface FallbackOptions {
+  /** Fallback strategy */
+  strategy?: FallbackStrategy;
+  /** List of models for same-provider fallback */
+  models?: string[];
+  /** List of provider configurations for custom fallback */
+  providers?: ProviderConfig[];
+  /** Stop on first successful response */
+  stopOnSuccess?: boolean;
+  /** Continue to fallback on non-retryable errors */
+  continueOnNonRetryableError?: boolean;
+  /** Maximum total attempts across all providers (1-100) */
+  maxTotalAttempts?: number;
+  /** Enable debug logging */
+  debug?: boolean;
+}
+
+/**
+ * Fallback statistics
+ */
+export interface FallbackStats {
+  /** Total number of provider attempts */
+  totalAttempts: number;
+  /** Number of attempts per provider */
+  providerAttempts: Record<string, number>;
+  /** Name of the successful provider */
+  successfulProvider: string | null;
+  /** List of failed providers with error details */
+  failedProviders: Array<{
+    provider: string;
+    error: {
+      message: string;
+      type: string;
+      statusCode?: number;
+    };
+  }>;
+}
+
+/**
+ * Auto-fallback provider build options
+ */
+export interface BuildFallbackOptions {
+  /** Primary provider to try first */
+  primaryProvider?: string;
+  /** Primary model to use */
+  primaryModel?: string;
+}
+
+/**
+ * FallbackManager class for handling provider and model fallback
+ */
+export class FallbackManager {
+  /** Fallback strategy */
+  strategy: FallbackStrategy;
+  /** List of models for same-provider fallback */
+  models: string[];
+  /** List of provider configurations */
+  providers: ProviderConfig[];
+  /** Stop on first success */
+  stopOnSuccess: boolean;
+  /** Continue on non-retryable errors */
+  continueOnNonRetryableError: boolean;
+  /** Maximum total attempts */
+  maxTotalAttempts: number;
+  /** Debug logging enabled */
+  debug: boolean;
+  /** Fallback statistics */
+  stats: FallbackStats;
+
+  /**
+   * Create a new FallbackManager
+   * @param options - Fallback configuration options
+   */
+  constructor(options?: FallbackOptions);
+
+  /**
+   * Execute a function with fallback support
+   * @param fn - Function that takes (provider, model, config) and returns a Promise
+   * @returns Result from the function
+   * @throws Error if all fallbacks are exhausted
+   */
+  executeWithFallback<T>(
+    fn: (
+      provider: any,
+      model: string,
+      config: ProviderConfig
+    ) => Promise<T>
+  ): Promise<T>;
+
+  /**
+   * Get fallback statistics
+   * @returns Statistics object (copy)
+   */
+  getStats(): FallbackStats;
+
+  /**
+   * Reset statistics
+   */
+  resetStats(): void;
+}
+
+/**
+ * Create a FallbackManager from environment variables
+ * @param debug - Enable debug logging
+ * @returns Configured FallbackManager instance or null if no config found
+ */
+export function createFallbackManagerFromEnv(
+  debug?: boolean
+): FallbackManager | null;
+
+/**
+ * Build a fallback provider list from current environment
+ * @param options - Options for building the list
+ * @returns List of provider configurations
+ */
+export function buildFallbackProvidersFromEnv(
+  options?: BuildFallbackOptions
+): ProviderConfig[];
+
+/**
+ * Default model mappings for each provider
+ */
+export const DEFAULT_MODELS: Record<string, string>;