@ai-orchestration/core 0.1.0

package/examples/strategies.ts

@@ -0,0 +1,112 @@
+/**
+ * Examples of different strategies
+ */
+
+import { createOrchestrator } from '../src/index.js';
+
+// Example 1: Priority Strategy
+export function createPriorityOrchestrator() {
+  return createOrchestrator({
+    providers: [
+      {
+        id: 'groq-1',
+        type: 'groq',
+        apiKey: process.env.GROQ_API_KEY || '',
+        priority: 1,
+      },
+      {
+        id: 'openrouter-1',
+        type: 'openrouter',
+        apiKey: process.env.OPENROUTER_API_KEY || '',
+        priority: 2,
+      },
+    ],
+    strategy: {
+      type: 'priority',
+      priorities: {
+        'groq-1': 1,
+        'openrouter-1': 2,
+      },
+    },
+  });
+}
+
+// Example 2: Fallback Strategy
+export function createFallbackOrchestrator() {
+  return createOrchestrator({
+    providers: [
+      {
+        id: 'groq-1',
+        type: 'groq',
+        apiKey: process.env.GROQ_API_KEY || '',
+      },
+      {
+        id: 'openrouter-1',
+        type: 'openrouter',
+        apiKey: process.env.OPENROUTER_API_KEY || '',
+      },
+      {
+        id: 'gemini-1',
+        type: 'gemini',
+        apiKey: process.env.GEMINI_API_KEY || '',
+      },
+    ],
+    strategy: {
+      type: 'fallback',
+      order: ['groq-1', 'openrouter-1', 'gemini-1'],
+    },
+  });
+}
+
+// Example 3: Weighted Strategy (Load Balancing)
+export function createWeightedOrchestrator() {
+  return createOrchestrator({
+    providers: [
+      {
+        id: 'groq-1',
+        type: 'groq',
+        apiKey: process.env.GROQ_API_KEY || '',
+        weight: 0.7,
+      },
+      {
+        id: 'openrouter-1',
+        type: 'openrouter',
+        apiKey: process.env.OPENROUTER_API_KEY || '',
+        weight: 0.3,
+      },
+    ],
+    strategy: {
+      type: 'weighted',
+      weights: {
+        'groq-1': 0.7,
+        'openrouter-1': 0.3,
+      },
+    },
+  });
+}
+
+// Example 4: Health-Aware Strategy
+export function createHealthAwareOrchestrator() {
+  return createOrchestrator({
+    providers: [
+      {
+        id: 'groq-1',
+        type: 'groq',
+        apiKey: process.env.GROQ_API_KEY || '',
+      },
+      {
+        id: 'openrouter-1',
+        type: 'openrouter',
+        apiKey: process.env.OPENROUTER_API_KEY || '',
+      },
+    ],
+    strategy: {
+      type: 'health-aware',
+      preferLowLatency: true,
+      minHealthScore: 0.5,
+    },
+    enableHealthChecks: true,
+    healthCheckInterval: 30000, // 30 seconds
+  });
+}
+

package/examples/test-local.ts

@@ -0,0 +1,150 @@
+/**
+ * Local test script
+ * Run with: npm run test:local
+ * or: tsx examples/test-local.ts
+ */
+
+import { createOrchestrator } from '../src/index.js';
+
+async function main() {
+  console.log('🚀 Iniciando prueba del framework...\n');
+
+  // Verificar variables de entorno
+  const hasGroq = !!process.env.GROQ_API_KEY;
+  const hasOpenRouter = !!process.env.OPENROUTER_API_KEY;
+  const hasGemini = !!process.env.GEMINI_API_KEY;
+
+  console.log('📋 Estado de API Keys:');
+  console.log(`  Groq: ${hasGroq ? '✅' : '❌'}`);
+  console.log(`  OpenRouter: ${hasOpenRouter ? '✅' : '❌'}`);
+  console.log(`  Gemini: ${hasGemini ? '✅' : '❌'}\n`);
+
+  if (!hasGroq && !hasOpenRouter && !hasGemini) {
+    console.log('⚠️  No se encontraron API keys.');
+    console.log('   Configura las variables de entorno:');
+    console.log('   export GROQ_API_KEY="tu-key"');
+    console.log('   export OPENROUTER_API_KEY="tu-key"');
+    console.log('   export GEMINI_API_KEY="tu-key"\n');
+    console.log('   O crea un archivo .env con:');
+    console.log('   GROQ_API_KEY=tu-key');
+    console.log('   OPENROUTER_API_KEY=tu-key');
+    console.log('   GEMINI_API_KEY=tu-key\n');
+    return;
+  }
+
+  // Crear configuración dinámica basada en las keys disponibles
+  const providers: any[] = [];
+
+  if (hasGroq) {
+    providers.push({
+      id: 'groq-1',
+      type: 'groq',
+      apiKey: process.env.GROQ_API_KEY,
+      model: 'llama-3.1-70b-versatile',
+    });
+  }
+
+  if (hasOpenRouter) {
+    providers.push({
+      id: 'openrouter-1',
+      type: 'openrouter',
+      apiKey: process.env.OPENROUTER_API_KEY,
+      model: 'openai/gpt-3.5-turbo',
+    });
+  }
+
+  if (hasGemini) {
+    providers.push({
+      id: 'gemini-1',
+      type: 'gemini',
+      apiKey: process.env.GEMINI_API_KEY,
+      model: 'gemini-pro',
+    });
+  }
+
+  try {
+    console.log('🔧 Creando orchestrator...');
+    const orchestrator = createOrchestrator({
+      providers,
+      strategy: {
+        type: 'round-robin',
+      },
+    });
+
+    console.log(`✅ Orchestrator creado con ${providers.length} proveedor(es)\n`);
+
+    // Test 1: Chat simple
+    console.log('📝 Test 1: Chat simple');
+    console.log('─────────────────────────────────');
+    const messages = [
+      { role: 'user' as const, content: 'Di "Hola" en una sola palabra' },
+    ];
+
+    const startTime = Date.now();
+    const response = await orchestrator.chat(messages, {
+      temperature: 0.7,
+      maxTokens: 50,
+    });
+    const duration = Date.now() - startTime;
+
+    console.log(`Respuesta: ${response.content}`);
+    console.log(`Modelo: ${response.model || 'N/A'}`);
+    console.log(`Tiempo: ${duration}ms`);
+    if (response.usage) {
+      console.log(`Tokens: ${response.usage.totalTokens} (prompt: ${response.usage.promptTokens}, completion: ${response.usage.completionTokens})`);
+    }
+    console.log('');
+
+    // Test 2: Verificar salud de proveedores
+    console.log('🏥 Test 2: Health checks');
+    console.log('─────────────────────────────────');
+    const allProviders = orchestrator.getAllProviders();
+    for (const provider of allProviders) {
+      try {
+        const health = await provider.checkHealth();
+        console.log(`${provider.id}: ${health.healthy ? '✅' : '❌'} ${health.latency ? `(${health.latency}ms)` : ''}`);
+      } catch (error) {
+        console.log(`${provider.id}: ❌ Error - ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+    console.log('');
+
+    // Test 3: Streaming (opcional, comentado por defecto)
+    if (process.env.TEST_STREAMING === 'true') {
+      console.log('🌊 Test 3: Streaming');
+      console.log('─────────────────────────────────');
+      const stream = await orchestrator.chatStream([
+        { role: 'user' as const, content: 'Cuenta del 1 al 5, un número por línea' },
+      ]);
+
+      const reader = stream.getReader();
+      let fullContent = '';
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        fullContent += value.content;
+        process.stdout.write(value.content);
+      }
+      console.log('\n✅ Streaming completado\n');
+    }
+
+    // Cleanup
+    orchestrator.dispose();
+    console.log('✅ Pruebas completadas exitosamente!');
+
+  } catch (error) {
+    console.error('\n❌ Error durante las pruebas:');
+    if (error instanceof Error) {
+      console.error(`   ${error.name}: ${error.message}`);
+      if (error.stack) {
+        console.error(`   Stack: ${error.stack}`);
+      }
+    } else {
+      console.error(`   ${String(error)}`);
+    }
+    process.exit(1);
+  }
+}
+
+main().catch(console.error);
+

package/examples/test-mock.ts

@@ -0,0 +1,172 @@
+/**
+ * Test with mock provider (no API keys required)
+ * Run with: npm run test:mock
+ * or: tsx examples/test-mock.ts
+ */
+
+import {
+  Orchestrator,
+  RoundRobinStrategy,
+  PriorityStrategy,
+  FallbackStrategy,
+} from '../src/index.js';
+import type { AIService, ChatMessage, ChatResponse, ChatChunk, ProviderHealth } from '../src/index.js';
+
+// Mock provider para pruebas sin API keys
+class MockProvider implements AIService {
+  readonly id: string;
+  readonly metadata = {
+    id: '',
+    name: 'Mock Provider',
+  };
+
+  constructor(id: string) {
+    this.id = id;
+    this.metadata.id = id;
+  }
+
+  async checkHealth(): Promise<ProviderHealth> {
+    return {
+      healthy: true,
+      latency: Math.random() * 100,
+      lastChecked: new Date(),
+    };
+  }
+
+  async chat(messages: ChatMessage[]): Promise<ChatResponse> {
+    const lastMessage = messages[messages.length - 1]?.content || '';
+    return {
+      content: `[Mock ${this.id}] Respuesta a: "${lastMessage}"`,
+      usage: {
+        promptTokens: 10,
+        completionTokens: 5,
+        totalTokens: 15,
+      },
+      model: 'mock-model',
+      finishReason: 'stop',
+    };
+  }
+
+  async chatStream(messages: ChatMessage[]): Promise<ReadableStream<ChatChunk>> {
+    const lastMessage = messages[messages.length - 1]?.content || '';
+    const words = `[Mock ${this.id}] Respuesta a: "${lastMessage}"`.split(' ');
+
+    return new ReadableStream({
+      async start(controller) {
+        for (const word of words) {
+          await new Promise((resolve) => setTimeout(resolve, 50));
+          controller.enqueue({
+            content: word + ' ',
+            done: false,
+          });
+        }
+        controller.enqueue({
+          content: '',
+          done: true,
+          finishReason: 'stop',
+        });
+        controller.close();
+      },
+    });
+  }
+}
+
+async function main() {
+  console.log('🧪 Prueba con proveedores Mock\n');
+
+  // Test 1: Round-Robin Strategy
+  console.log('📋 Test 1: Round-Robin Strategy');
+  console.log('─────────────────────────────────');
+  const roundRobinStrategy = new RoundRobinStrategy();
+  const orchestrator1 = new Orchestrator(roundRobinStrategy);
+
+  orchestrator1.registerProvider(new MockProvider('mock-1'));
+  orchestrator1.registerProvider(new MockProvider('mock-2'));
+  orchestrator1.registerProvider(new MockProvider('mock-3'));
+
+  for (let i = 0; i < 5; i++) {
+    const provider = await orchestrator1.selectProvider();
+    console.log(`  Request ${i + 1}: ${provider?.id}`);
+  }
+  console.log('');
+
+  // Test 2: Priority Strategy
+  console.log('📋 Test 2: Priority Strategy');
+  console.log('─────────────────────────────────');
+  const priorityStrategy = new PriorityStrategy({
+    priorities: {
+      'mock-1': 1,
+      'mock-2': 2,
+      'mock-3': 3,
+    },
+  });
+  const orchestrator2 = new Orchestrator(priorityStrategy);
+
+  orchestrator2.registerProvider(new MockProvider('mock-1'));
+  orchestrator2.registerProvider(new MockProvider('mock-2'));
+  orchestrator2.registerProvider(new MockProvider('mock-3'));
+
+  for (let i = 0; i < 3; i++) {
+    const provider = await orchestrator2.selectProvider();
+    console.log(`  Request ${i + 1}: ${provider?.id} (siempre el mismo por prioridad)`);
+  }
+  console.log('');
+
+  // Test 3: Fallback Strategy
+  console.log('📋 Test 3: Fallback Strategy');
+  console.log('─────────────────────────────────');
+  const fallbackStrategy = new FallbackStrategy({
+    order: ['mock-1', 'mock-2', 'mock-3'],
+  });
+  const orchestrator3 = new Orchestrator(fallbackStrategy);
+
+  orchestrator3.registerProvider(new MockProvider('mock-1'));
+  orchestrator3.registerProvider(new MockProvider('mock-2'));
+  orchestrator3.registerProvider(new MockProvider('mock-3'));
+
+  const provider = await orchestrator3.selectProvider();
+  console.log(`  Seleccionado: ${provider?.id} (siempre el primero de la lista)`);
+  console.log('');
+
+  // Test 4: Chat real con mock
+  console.log('📋 Test 4: Chat con Mock Provider');
+  console.log('─────────────────────────────────');
+  const orchestrator4 = new Orchestrator(new RoundRobinStrategy());
+  orchestrator4.registerProvider(new MockProvider('mock-1'));
+  orchestrator4.registerProvider(new MockProvider('mock-2'));
+
+  const response = await orchestrator4.chat([
+    { role: 'user', content: 'Hola, ¿cómo estás?' },
+  ]);
+
+  console.log(`  Respuesta: ${response.content}`);
+  console.log(`  Tokens: ${response.usage?.totalTokens}`);
+  console.log('');
+
+  // Test 5: Streaming con mock
+  console.log('📋 Test 5: Streaming con Mock Provider');
+  console.log('─────────────────────────────────');
+  const stream = await orchestrator4.chatStream([
+    { role: 'user', content: 'Cuenta hasta 3' },
+  ]);
+
+  const reader = stream.getReader();
+  process.stdout.write('  Stream: ');
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    process.stdout.write(value.content);
+  }
+  console.log('\n');
+
+  // Cleanup
+  orchestrator1.dispose();
+  orchestrator2.dispose();
+  orchestrator3.dispose();
+  orchestrator4.dispose();
+
+  console.log('✅ Todas las pruebas completadas!');
+}
+
+main().catch(console.error);
+

package/package/.eslintrc.json

@@ -0,0 +1,27 @@
+{
+  "parser": "@typescript-eslint/parser",
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended"
+  ],
+  "parserOptions": {
+    "ecmaVersion": 2022,
+    "sourceType": "module"
+  },
+  "env": {
+    "node": true,
+    "es2022": true
+  },
+  "rules": {
+    "@typescript-eslint/no-unused-vars": [
+      "error",
+      {
+        "argsIgnorePattern": "^_",
+        "varsIgnorePattern": "^_"
+      }
+    ],
+    "@typescript-eslint/explicit-module-boundary-types": "off",
+    "@typescript-eslint/no-explicit-any": "warn"
+  }
+}
+

package/package/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+Todos los cambios notables en este proyecto serán documentados en este archivo.
+
+El formato está basado en [Keep a Changelog](https://keepachangelog.com/es-ES/1.0.0/),
+y este proyecto adhiere a [Semantic Versioning](https://semver.org/lang/es/).
+
+## [0.1.0] - 2024-12-XX
+
+### Agregado
+- Framework completo de orquestación de IA
+- Soporte para múltiples proveedores: Groq, OpenRouter, Gemini, Local
+- 5 estrategias de selección: Round-Robin, Priority, Fallback, Weighted, Health-Aware
+- Streaming nativo con ReadableStream
+- Health checks automáticos con métricas de latencia
+- Factory para creación declarativa
+- Manejo de errores personalizado
+- Validación de configuración
+- Documentación completa (README, ARCHITECTURE, USAGE, CONTRIBUTING)
+- Ejemplos de uso
+- Tests básicos
+- Compatibilidad con Node.js y Bun
+
+### Características Principales
+- Arquitectura basada en plugins (extensible sin modificar el core)
+- API declarativa y programática
+- Type-safe con TypeScript
+- Fallback automático entre proveedores
+- Soporte para cost-aware selection
+- Health-aware selection con métricas en tiempo real
+

package/package/CONTRIBUTING.md

@@ -0,0 +1,156 @@
+# Guía de Contribución
+
+## Estructura del Proyecto
+
+```
+src/
+├── core/           # Núcleo del framework (interfaces, tipos, orchestrator)
+├── providers/      # Implementaciones de proveedores
+├── strategies/     # Estrategias de selección
+├── factory/        # Factory para creación declarativa
+└── index.ts        # Punto de entrada principal
+```
+
+## Agregar un Nuevo Proveedor
+
+1. **Crear el archivo del proveedor** en `src/providers/`:
+
+```typescript
+import { BaseProvider } from './base.js';
+import type {
+  ChatMessage,
+  ChatOptions,
+  ChatResponse,
+  ChatChunk,
+  ProviderHealth,
+  ProviderMetadata,
+} from '../core/types.js';
+
+export interface CustomProviderConfig {
+  id: string;
+  apiKey: string;
+  // ... otros campos específicos
+}
+
+export class CustomProvider extends BaseProvider {
+  readonly id: string;
+  readonly metadata: ProviderMetadata;
+  
+  constructor(config: CustomProviderConfig) {
+    super();
+    // Inicialización
+  }
+  
+  async checkHealth(): Promise<ProviderHealth> {
+    // Implementar health check
+  }
+  
+  async chat(messages: ChatMessage[], options?: ChatOptions): Promise<ChatResponse> {
+    // Implementar chat
+  }
+  
+  async chatStream(messages: ChatMessage[], options?: ChatOptions): Promise<ReadableStream<ChatChunk>> {
+    // Implementar streaming
+  }
+  
+  protected formatMessages(messages: ChatMessage[]): unknown {
+    // Convertir formato estándar a formato del proveedor
+  }
+  
+  protected parseResponse(response: unknown): ChatResponse {
+    // Convertir respuesta a formato estándar
+  }
+  
+  protected parseStream(stream: ReadableStream<unknown>): ReadableStream<ChatChunk> {
+    // Convertir stream a formato estándar
+  }
+}
+```
+
+2. **Exportar en `src/providers/index.ts`**:
+
+```typescript
+export { CustomProvider } from './custom.js';
+export type { CustomProviderConfig } from './custom.js';
+```
+
+3. **Registrar en `src/factory/index.ts`**:
+
+```typescript
+import { CustomProvider, type CustomProviderConfig } from '../providers/index.js';
+
+// En la función createProvider:
+case 'custom':
+  return new CustomProvider({
+    id,
+    ...(rest as CustomProviderConfig),
+  } as CustomProviderConfig);
+```
+
+## Agregar una Nueva Estrategia
+
+1. **Crear el archivo de la estrategia** en `src/strategies/`:
+
+```typescript
+import { BaseStrategy } from './base.js';
+import type { AIService, SelectionContext } from '../core/interfaces.js';
+
+export interface CustomStrategyConfig {
+  // Configuración específica
+}
+
+export class CustomStrategy extends BaseStrategy {
+  constructor(config?: CustomStrategyConfig) {
+    super();
+    // Inicialización
+  }
+  
+  async select(
+    providers: AIService[],
+    context?: SelectionContext
+  ): Promise<AIService | null> {
+    // Implementar lógica de selección
+  }
+  
+  update?(provider: AIService, success: boolean, metadata?: unknown): void {
+    // Opcional: actualizar estado interno
+  }
+}
+```
+
+2. **Exportar en `src/strategies/index.ts`**
+
+3. **Registrar en `src/factory/index.ts`**
+
+## Convenciones de Código
+
+- **TypeScript estricto**: Usar tipos explícitos
+- **Nombres descriptivos**: Variables y funciones con nombres claros
+- **Documentación**: JSDoc para funciones públicas
+- **Manejo de errores**: Usar clases de error personalizadas
+- **Tests**: Agregar tests para nuevas funcionalidades
+
+## Testing
+
+Los tests están en `tests/`. Usar Bun test runner:
+
+```bash
+bun test tests/
+```
+
+## Versionado
+
+Seguir [Semantic Versioning](https://semver.org/):
+- **MAJOR**: Cambios incompatibles en la API
+- **MINOR**: Nueva funcionalidad compatible hacia atrás
+- **PATCH**: Correcciones de bugs compatibles
+
+## Pull Requests
+
+1. Crear una rama desde `main`
+2. Implementar cambios
+3. Agregar tests
+4. Actualizar documentación si es necesario
+5. Asegurar que todos los tests pasen
+6. Crear PR con descripción clara
+