@ai-orchestration/core 0.1.0 → 0.2.0

package/examples/chat-app/index.ts

@@ -35,6 +35,26 @@ interface AppConfig {
   chatOptions?: {
     temperature?: number;
     maxTokens?: number;
+    frequencyPenalty?: number;
+    presencePenalty?: number;
+    responseLanguage?: string;
+  };
+  orchestratorConfig?: {
+    maxRetries?: number;
+    requestTimeout?: number;
+    retryDelay?: number | 'exponential';
+    circuitBreaker?: {
+      enabled?: boolean;
+      failureThreshold?: number;
+      resetTimeout?: number;
+    };
+    healthCheck?: {
+      enabled?: boolean;
+      interval?: number;
+      timeout?: number;
+      maxConsecutiveFailures?: number;
+      latencyThreshold?: number;
+    };
   };
 }
 
@@ -102,6 +122,25 @@ async function initOrchestrator() {
           order: providers.map((p) => p.id),
         }),
       },
+      // Advanced configuration from config.json
+      ...(appConfig.orchestratorConfig || {
+        maxRetries: 3,
+        requestTimeout: 30000,
+        retryDelay: 'exponential',
+        circuitBreaker: {
+          enabled: true,
+          failureThreshold: 5,
+          resetTimeout: 60000,
+        },
+        healthCheck: {
+          enabled: true,
+          interval: 60000,
+          timeout: 5000,
+          maxConsecutiveFailures: 3,
+          latencyThreshold: 10000,
+        },
+      }),
+      defaultOptions: defaultChatOptions,
     });
     
     const totalProviders = orchestrator.getAllProviders();
@@ -228,8 +267,8 @@ async function sendMessage(message: string) {
     
     const startTime = Date.now();
     const response = await orchestrator.chat(messages, {
-      temperature: 0.7,
-      maxTokens: 1000,
+      ...defaultChatOptions,
+      // You can override per-request options here
     });
     const duration = Date.now() - startTime;
 

package/examples/config.example.json

@@ -4,7 +4,7 @@
       "id": "groq-primary",
       "type": "groq",
       "apiKey": "${GROQ_API_KEY}",
-      "model": "llama-3.1-70b-versatile",
+      "model": "llama-3.3-70b-versatile",
       "enabled": true,
       "priority": 1,
       "weight": 0.7
@@ -25,6 +25,13 @@
       "model": "gemini-pro",
       "enabled": true,
       "priority": 3
+    },
+    {
+      "id": "cerebras-1",
+      "type": "cerebras",
+      "apiKey": "${CEREBRAS_API_KEY}",
+      "model": "llama-3.3-70b",
+      "enabled": true
     }
   ],
   "strategy": {
@@ -34,9 +41,24 @@
   },
   "defaultOptions": {
     "temperature": 0.7,
-    "maxTokens": 1000
+    "maxTokens": 1000,
+    "frequencyPenalty": 0.5,
+    "presencePenalty": 0.3
+  },
+  "maxRetries": 3,
+  "requestTimeout": 30000,
+  "retryDelay": "exponential",
+  "circuitBreaker": {
+    "enabled": true,
+    "failureThreshold": 5,
+    "resetTimeout": 60000
   },
-  "enableHealthChecks": true,
-  "healthCheckInterval": 60000
+  "healthCheck": {
+    "enabled": true,
+    "interval": 60000,
+    "timeout": 5000,
+    "maxConsecutiveFailures": 3,
+    "latencyThreshold": 10000
+  }
 }
 

package/examples/language.ts

@@ -0,0 +1,160 @@
+/**
+ * Example: Forcing response language
+ * 
+ * This example demonstrates how to force the AI to respond in a specific language
+ * using the responseLanguage option.
+ */
+
+import { createOrchestrator, type ProviderConfig } from '../src/index.js';
+
+async function main() {
+  // Check for API keys
+  const hasGroq = !!process.env.GROQ_API_KEY;
+  const hasOpenRouter = !!process.env.OPENROUTER_API_KEY;
+  const hasGemini = !!process.env.GEMINI_API_KEY;
+  const hasCerebras = !!process.env.CEREBRAS_API_KEY;
+
+  if (!hasGroq && !hasOpenRouter && !hasGemini && !hasCerebras) {
+    console.error('❌ Error: No API keys found!\n');
+    console.error('   Please set at least one of the following environment variables:');
+    console.error('   - GROQ_API_KEY (recommended)');
+    console.error('   - OPENROUTER_API_KEY');
+    console.error('   - GEMINI_API_KEY');
+    console.error('   - CEREBRAS_API_KEY\n');
+    console.error('   Example:');
+    console.error('   export GROQ_API_KEY="your-key"');
+    console.error('   npm run example:language\n');
+    process.exit(1);
+  }
+
+  // Use first available provider
+  const providers: ProviderConfig[] = [];
+  if (hasGroq) {
+    providers.push({
+      id: 'groq-1',
+      type: 'groq',
+      apiKey: process.env.GROQ_API_KEY!,
+    });
+  } else if (hasOpenRouter) {
+    providers.push({
+      id: 'openrouter-1',
+      type: 'openrouter',
+      apiKey: process.env.OPENROUTER_API_KEY!,
+    });
+  } else if (hasGemini) {
+    providers.push({
+      id: 'gemini-1',
+      type: 'gemini',
+      apiKey: process.env.GEMINI_API_KEY!,
+    });
+  } else if (hasCerebras) {
+    providers.push({
+      id: 'cerebras-1',
+      type: 'cerebras',
+      apiKey: process.env.CEREBRAS_API_KEY!,
+    });
+  }
+
+  console.log(`✅ Using provider: ${providers[0].id}\n`);
+
+  // Create orchestrator with a simple configuration
+  const orchestrator = createOrchestrator({
+    providers,
+    strategy: {
+      type: 'round-robin',
+    },
+  });
+
+  const messages = [
+    {
+      role: 'user' as const,
+      content: 'Tell me a joke',
+    },
+  ];
+
+  console.log('=== Example 1: Force Spanish ===\n');
+  try {
+    const response1 = await orchestrator.chat(messages, {
+      responseLanguage: 'es', // Force Spanish response
+      temperature: 0.7,
+    });
+    console.log('Response:', response1.content);
+    console.log('');
+  } catch (error) {
+    console.error('Error:', error);
+  }
+
+  console.log('=== Example 2: Force English ===\n');
+  try {
+    const response2 = await orchestrator.chat(messages, {
+      responseLanguage: 'en', // Force English response
+      temperature: 0.7,
+    });
+    console.log('Response:', response2.content);
+    console.log('');
+  } catch (error) {
+    console.error('Error:', error);
+  }
+
+  console.log('=== Example 3: Force French ===\n');
+  try {
+    const response3 = await orchestrator.chat(messages, {
+      responseLanguage: 'french', // Can also use full language name
+      temperature: 0.7,
+    });
+    console.log('Response:', response3.content);
+    console.log('');
+  } catch (error) {
+    console.error('Error:', error);
+  }
+
+  console.log('=== Example 4: With existing system message ===\n');
+  try {
+    // If you already have a system message, the language instruction will be prepended
+    const messagesWithSystem = [
+      {
+        role: 'system' as const,
+        content: 'You are a helpful assistant.',
+      },
+      {
+        role: 'user' as const,
+        content: 'What is the capital of France?',
+      },
+    ];
+
+    const response4 = await orchestrator.chat(messagesWithSystem, {
+      responseLanguage: 'es', // Will prepend Spanish instruction to system message
+      temperature: 0.7,
+    });
+    console.log('Response:', response4.content);
+    console.log('');
+  } catch (error) {
+    console.error('Error:', error);
+  }
+
+  console.log('=== Example 5: Streaming with language ===\n');
+  try {
+    const stream = await orchestrator.chatStream(messages, {
+      responseLanguage: 'es',
+      temperature: 0.7,
+    });
+
+    const reader = stream.getReader();
+    const decoder = new TextDecoder();
+
+    console.log('Streaming response: ');
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      process.stdout.write(value.content);
+    }
+    console.log('\n');
+  } catch (error) {
+    console.error('Error:', error);
+  }
+
+  orchestrator.dispose();
+}
+
+main().catch(console.error);
+

package/examples/metrics.ts

@@ -0,0 +1,150 @@
+/**
+ * Example: Using Metrics and Analytics
+ * 
+ * This example demonstrates how to track provider usage, costs, and strategy effectiveness
+ */
+
+import { createOrchestrator, type MetricsEvent } from '../src/index.js';
+
+async function main() {
+  // Check for API keys
+  const hasGroq = !!process.env.GROQ_API_KEY;
+  const hasOpenRouter = !!process.env.OPENROUTER_API_KEY;
+
+  if (!hasGroq && !hasOpenRouter) {
+    console.error('❌ Error: No API keys found!\n');
+    console.error('   Please set at least one API key:');
+    console.error('   export GROQ_API_KEY="your-key"\n');
+    process.exit(1);
+  }
+
+  const providers = [];
+  if (hasGroq) {
+    providers.push({
+      id: 'groq-1',
+      type: 'groq',
+      apiKey: process.env.GROQ_API_KEY!,
+      model: 'llama-3.3-70b-versatile',
+      // Optional: Add cost per token for cost tracking
+      metadata: {
+        costPerToken: {
+          prompt: 0.0000002, // $0.20 per 1M tokens
+          completion: 0.0000002,
+        },
+      },
+    });
+  }
+
+  if (hasOpenRouter) {
+    providers.push({
+      id: 'openrouter-1',
+      type: 'openrouter',
+      apiKey: process.env.OPENROUTER_API_KEY!,
+      model: 'openai/gpt-3.5-turbo',
+      metadata: {
+        costPerToken: {
+          prompt: 0.0000015, // $1.50 per 1M tokens
+          completion: 0.000002, // $2.00 per 1M tokens
+        },
+      },
+    });
+  }
+
+  console.log(`✅ Using ${providers.length} provider(s)\n`);
+
+  // Create orchestrator with metrics enabled
+  const orchestrator = createOrchestrator({
+    providers,
+    strategy: {
+      type: 'round-robin',
+    },
+    enableMetrics: true, // Enable metrics (default: true)
+    onMetricsEvent: (event: MetricsEvent) => {
+      // Optional: Log events in real-time
+      // console.log('📊 Event:', event.type, event.providerId);
+    },
+  });
+
+  // Make some requests
+  console.log('📝 Making requests...\n');
+  
+  for (let i = 0; i < 3; i++) {
+    try {
+      const response = await orchestrator.chat([
+        { role: 'user', content: `Say "Request ${i + 1}" in one word` },
+      ]);
+      console.log(`✅ Request ${i + 1}: ${response.content.substring(0, 20)}...`);
+    } catch (error) {
+      console.error(`❌ Request ${i + 1} failed:`, error);
+    }
+  }
+
+  console.log('\n📊 ===== METRICS REPORT =====\n');
+
+  // Get overall metrics
+  const overallMetrics = orchestrator.getMetrics().getOrchestratorMetrics();
+  
+  console.log('📈 Overall Statistics:');
+  console.log(`   Total Requests: ${overallMetrics.totalRequests}`);
+  console.log(`   Successful: ${overallMetrics.successfulRequests}`);
+  console.log(`   Failed: ${overallMetrics.failedRequests}`);
+  console.log(`   Error Rate: ${(overallMetrics.errorRate * 100).toFixed(2)}%`);
+  console.log(`   Average Latency: ${overallMetrics.averageRequestLatency.toFixed(2)}ms`);
+  console.log(`   Requests/Minute: ${overallMetrics.requestsPerMinute}`);
+  console.log(`   Total Cost: $${overallMetrics.totalCost.toFixed(6)}\n`);
+
+  // Get provider-specific metrics
+  console.log('🔌 Provider Metrics:\n');
+  const providerMetrics = orchestrator.getMetrics().getAllProviderMetrics();
+  
+  for (const [providerId, metrics] of providerMetrics) {
+    console.log(`   ${metrics.providerName} (${providerId}):`);
+    console.log(`     Model: ${metrics.model || 'N/A'}`);
+    console.log(`     Total Requests: ${metrics.totalRequests}`);
+    console.log(`     Successful: ${metrics.successfulRequests}`);
+    console.log(`     Failed: ${metrics.failedRequests}`);
+    console.log(`     Success Rate: ${metrics.totalRequests > 0 ? ((metrics.successfulRequests / metrics.totalRequests) * 100).toFixed(2) : 0}%`);
+    console.log(`     Average Latency: ${metrics.averageLatency.toFixed(2)}ms`);
+    console.log(`     Total Tokens: ${metrics.totalTokens.total.toLocaleString()}`);
+    console.log(`       - Prompt: ${metrics.totalTokens.prompt.toLocaleString()}`);
+    console.log(`       - Completion: ${metrics.totalTokens.completion.toLocaleString()}`);
+    console.log(`     Total Cost: $${metrics.totalCost.toFixed(6)}`);
+    if (metrics.lastUsed) {
+      console.log(`     Last Used: ${metrics.lastUsed.toLocaleString()}`);
+    }
+    console.log('');
+  }
+
+  // Get strategy metrics
+  console.log('🎯 Strategy Metrics:\n');
+  const strategyMetrics = orchestrator.getMetrics().getStrategyMetrics();
+  
+  console.log(`   Total Selections: ${strategyMetrics.totalSelections}`);
+  console.log(`   Average Selection Time: ${strategyMetrics.averageSelectionTime.toFixed(2)}ms`);
+  console.log(`   Selections by Provider:`);
+  for (const [providerId, count] of strategyMetrics.selectionsByProvider) {
+    const percentage = strategyMetrics.totalSelections > 0 
+      ? ((count / strategyMetrics.totalSelections) * 100).toFixed(1)
+      : '0';
+    console.log(`     ${providerId}: ${count} (${percentage}%)`);
+  }
+  console.log('');
+
+  // Get request history
+  console.log('📜 Recent Request History:\n');
+  const history = orchestrator.getMetrics().getRequestHistory({ limit: 5 });
+  for (const request of history) {
+    const status = request.success ? '✅' : '❌';
+    const tokens = request.tokens ? ` (${request.tokens.total} tokens)` : '';
+    const cost = request.cost ? ` - $${request.cost.toFixed(6)}` : '';
+    console.log(`   ${status} ${request.providerId} - ${request.latency}ms${tokens}${cost}`);
+  }
+
+  console.log('\n💡 Tip: Use orchestrator.getMetrics() to access all metrics programmatically');
+  console.log('   You can also register callbacks with onMetricsEvent() for real-time tracking\n');
+
+  orchestrator.dispose();
+}
+
+main().catch(console.error);
+

package/examples/strategies.ts

@@ -105,8 +105,10 @@ export function createHealthAwareOrchestrator() {
       preferLowLatency: true,
       minHealthScore: 0.5,
     },
-    enableHealthChecks: true,
-    healthCheckInterval: 30000, // 30 seconds
+    healthCheck: {
+      enabled: true,
+      interval: 30000, // 30 seconds
+    },
   });
 }
 

package/examples/test-local.ts

@@ -36,12 +36,12 @@ async function main() {
   const providers: any[] = [];
 
   if (hasGroq) {
-    providers.push({
-      id: 'groq-1',
-      type: 'groq',
-      apiKey: process.env.GROQ_API_KEY,
-      model: 'llama-3.1-70b-versatile',
-    });
+    providers.push(      {
+        id: 'groq-1',
+        type: 'groq',
+        apiKey: process.env.GROQ_API_KEY,
+        model: 'llama-3.3-70b-versatile',
+      });
   }
 
   if (hasOpenRouter) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-orchestration/core",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Modular AI orchestration framework for multiple LLM providers",
   "type": "module",
   "main": "./dist/index.js",
@@ -14,9 +14,13 @@
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
-    "test": "npx tsx tests/basic.test.ts",
+    "test": "node --test --loader tsx tests/**/*.test.ts",
     "test:local": "npx tsx examples/test-local.ts",
     "test:mock": "npx tsx examples/test-mock.ts",
+    "example:basic": "npx tsx examples/basic.ts",
+    "example:strategies": "npx tsx examples/strategies.ts",
+    "example:language": "npx tsx examples/language.ts",
+    "example:metrics": "npx tsx examples/metrics.ts",
     "lint": "eslint src --ext .ts",
     "typecheck": "tsc --noEmit",
     "link": "npm run build && npm link",