@ai-orchestration/core 0.1.0

package/package/dist/strategies/weighted.js

@@ -0,0 +1,58 @@
+/**
+ * Weighted strategy: selects providers based on weights (for load balancing or cost-aware selection)
+ */
+import { BaseStrategy } from './base.js';
+export class WeightedStrategy extends BaseStrategy {
+    weights = new Map();
+    costAware;
+    constructor(config) {
+        super();
+        this.costAware = config?.costAware ?? false;
+        if (config?.weights) {
+            Object.entries(config.weights).forEach(([id, weight]) => {
+                this.weights.set(id, weight);
+            });
+        }
+    }
+    async select(providers, context) {
+        const available = this.filterAttempted(providers, context);
+        if (available.length === 0) {
+            return null;
+        }
+        // Calculate effective weights
+        const weightedProviders = available.map((provider) => {
+            let weight = this.weights.get(provider.id) ?? 1.0;
+            // Adjust weight based on cost if cost-aware
+            if (this.costAware && provider.metadata.costPerToken) {
+                const avgCost = (provider.metadata.costPerToken.prompt +
+                    provider.metadata.costPerToken.completion) /
+                    2;
+                // Lower cost = higher weight (inverse relationship)
+                weight = weight / (avgCost + 0.0001); // Add small epsilon to avoid division by zero
+            }
+            return { provider, weight };
+        });
+        // Calculate total weight
+        const totalWeight = weightedProviders.reduce((sum, wp) => sum + wp.weight, 0);
+        if (totalWeight === 0) {
+            return available[0]; // Fallback to first available
+        }
+        // Select using weighted random
+        let random = Math.random() * totalWeight;
+        for (const { provider, weight } of weightedProviders) {
+            random -= weight;
+            if (random <= 0) {
+                return provider;
+            }
+        }
+        // Fallback (shouldn't reach here)
+        return available[0];
+    }
+    /**
+     * Set weight for a provider
+     */
+    setWeight(providerId, weight) {
+        this.weights.set(providerId, weight);
+    }
+}
+//# sourceMappingURL=weighted.js.map

package/package/dist/strategies/weighted.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"weighted.js","sourceRoot":"","sources":["../../src/strategies/weighted.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAQzC,MAAM,OAAO,gBAAiB,SAAQ,YAAY;IACxC,OAAO,GAAwB,IAAI,GAAG,EAAE,CAAC;IACzC,SAAS,CAAU;IAE3B,YAAY,MAA+B;QACzC,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,SAAS,GAAG,MAAM,EAAE,SAAS,IAAI,KAAK,CAAC;QAE5C,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;YACpB,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,MAAM,CAAC,EAAE,EAAE;gBACtD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;YAC/B,CAAC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,KAAK,CAAC,MAAM,CACV,SAAsB,EACtB,OAA0B;QAE1B,MAAM,SAAS,GAAG,IAAI,CAAC,eAAe,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QAC3D,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC3B,OAAO,IAAI,CAAC;QACd,CAAC;QAED,8BAA8B;QAC9B,MAAM,iBAAiB,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE;YACnD,IAAI,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,GAAG,CAAC;YAElD,4CAA4C;YAC5C,IAAI,IAAI,CAAC,SAAS,IAAI,QAAQ,CAAC,QAAQ,CAAC,YAAY,EAAE,CAAC;gBACrD,MAAM,OAAO,GACX,CAAC,QAAQ,CAAC,QAAQ,CAAC,YAAY,CAAC,MAAM;oBACpC,QAAQ,CAAC,QAAQ,CAAC,YAAY,CAAC,UAAU,CAAC;oBAC5C,CAAC,CAAC;gBACJ,oDAAoD;gBACpD,MAAM,GAAG,MAAM,GAAG,CAAC,OAAO,GAAG,MAAM,CAAC,CAAC,CAAC,8CAA8C;YACtF,CAAC;YAED,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;QAC9B,CAAC,CAAC,CAAC;QAEH,yBAAyB;QACzB,MAAM,WAAW,GAAG,iBAAiB,CAAC,MAAM,CAC1C,CAAC,GAAG,EAAE,EAAE,EAAE,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,MAAM,EAC5B,CAAC,CACF,CAAC;QAEF,IAAI,WAAW,KAAK,CAAC,EAAE,CAAC;YACtB,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,8BAA8B;QACrD,CAAC;QAED,+BAA+B;QAC/B,IAAI,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,WAAW,CAAC;QACzC,KAAK,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,iBAAiB,EAAE,CAAC;YACrD,MAAM,IAAI,MAAM,CAAC;YACjB,IAAI,MAAM,IAAI,CAAC,EAAE,CAAC;gBAChB,OAAO,QAAQ,CAAC;YAClB,CAAC;QACH,CAAC;QAED,kCAAkC;QAClC,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC;IACtB,CAAC;IAED;;OAEG;IACH,SAAS,CAAC,UAAkB,EAAE,MAAc;QAC1C,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IACvC,CAAC;CACF"}

package/package/docs/ARCHITECTURE.md

@@ -0,0 +1,127 @@
+# Arquitectura del Framework
+
+## Visión General
+
+El framework está diseñado siguiendo principios SOLID y arquitectura basada en plugins, permitiendo extensibilidad sin modificar el código core.
+
+## Componentes Principales
+
+### Core (`src/core/`)
+
+#### `interfaces.ts`
+Define las interfaces fundamentales:
+- `AIService`: Contrato que todos los proveedores deben implementar
+- `SelectionStrategy`: Contrato para estrategias de selección
+- `OrchestratorConfig`: Configuración del orchestrator
+- Tipos de configuración para proveedores y estrategias
+
+#### `types.ts`
+Tipos compartidos:
+- `ChatMessage`: Mensaje en una conversación
+- `ChatOptions`: Opciones para completado de chat
+- `ChatResponse`: Respuesta no-streaming
+- `ChatChunk`: Chunk de streaming
+- `ProviderHealth`: Estado de salud de un proveedor
+- `ProviderMetadata`: Metadatos del proveedor
+
+#### `orchestrator.ts`
+Núcleo del framework:
+- `Orchestrator`: Clase principal que gestiona proveedores y estrategias
+- Registro y gestión de proveedores
+- Selección automática de proveedores
+- Fallback automático en caso de error
+- Health checks periódicos
+
+### Providers (`src/providers/`)
+
+Cada proveedor extiende `BaseProvider` e implementa:
+- `checkHealth()`: Verificación de salud
+- `chat()`: Completado de chat (no-streaming)
+- `chatStream()`: Completado de chat (streaming)
+- `formatMessages()`: Conversión de formato estándar a formato del proveedor
+- `parseResponse()`: Conversión de respuesta del proveedor a formato estándar
+- `parseStream()`: Conversión de stream del proveedor a formato estándar
+
+**Proveedores implementados:**
+- `GroqProvider`: Integración con Groq API
+- `OpenRouterProvider`: Integración con OpenRouter
+- `GeminiProvider`: Integración con Google Gemini
+- `LocalProvider`: Para modelos locales (API compatible con OpenAI)
+
+### Strategies (`src/strategies/`)
+
+Cada estrategia extiende `BaseStrategy` e implementa:
+- `select()`: Lógica de selección de proveedor
+- `update()` (opcional): Actualización de estado interno
+
+**Estrategias implementadas:**
+- `RoundRobinStrategy`: Cicla entre proveedores
+- `PriorityStrategy`: Selecciona por prioridad
+- `FallbackStrategy`: Intenta en orden hasta éxito
+- `WeightedStrategy`: Selección basada en pesos (load balancing)
+- `HealthAwareStrategy`: Selección basada en métricas de salud
+
+### Factory (`src/factory/`)
+
+- `createOrchestrator()`: Crea un orchestrator desde configuración declarativa
+- `createProvider()`: Crea instancias de proveedores desde configuración
+- `createStrategy()`: Crea instancias de estrategias desde configuración
+- `isValidOrchestratorConfig()`: Valida configuración
+
+## Flujo de Datos
+
+```
+Usuario
+  ↓
+Orchestrator.chat() / chatStream()
+  ↓
+Strategy.select() → Selecciona proveedor
+  ↓
+Provider.chat() / chatStream()
+  ↓
+Provider formatea mensajes → formatMessages()
+  ↓
+Llamada a API del proveedor
+  ↓
+Provider parsea respuesta → parseResponse() / parseStream()
+  ↓
+Respuesta estándar al usuario
+```
+
+## Extensibilidad
+
+### Agregar un Nuevo Proveedor
+
+1. Crear clase que extienda `BaseProvider`
+2. Implementar métodos requeridos
+3. Registrar en `factory/index.ts` (método `createProvider`)
+
+### Agregar una Nueva Estrategia
+
+1. Crear clase que extienda `BaseStrategy`
+2. Implementar método `select()`
+3. Opcionalmente implementar `update()`
+4. Registrar en `factory/index.ts` (método `createStrategy`)
+
+## Principios de Diseño Aplicados
+
+1. **Single Responsibility**: Cada clase tiene una responsabilidad única
+2. **Open/Closed**: Abierto para extensión, cerrado para modificación
+3. **Liskov Substitution**: Proveedores y estrategias son intercambiables
+4. **Interface Segregation**: Interfaces específicas y cohesivas
+5. **Dependency Inversion**: Dependencias de abstracciones, no implementaciones
+
+## Compatibilidad
+
+- **Node.js**: >= 18.0.0 (usa ReadableStream nativo)
+- **Bun**: Compatible (usa APIs estándar)
+- **TypeScript**: 5.3+
+- **ES Modules**: Requerido
+
+## Consideraciones de Rendimiento
+
+- Health checks pueden ejecutarse en paralelo
+- Fallback automático evita esperas innecesarias
+- Streaming nativo para respuestas largas
+- Estrategias pueden cachear métricas para mejor rendimiento
+

package/package/examples/basic.ts

@@ -0,0 +1,58 @@
+/**
+ * Basic usage example
+ */
+
+import { createOrchestrator } from '../src/index.js';
+
+async function main() {
+  // Create orchestrator with declarative config
+  const orchestrator = createOrchestrator({
+    providers: [
+      {
+        id: 'groq-1',
+        type: 'groq',
+        apiKey: process.env.GROQ_API_KEY || '',
+        model: 'llama-3.3-70b-versatile', // Updated: llama-3.1-70b-versatile was decommissioned
+      },
+      {
+        id: 'openrouter-1',
+        type: 'openrouter',
+        apiKey: process.env.OPENROUTER_API_KEY || '',
+        model: 'openai/gpt-3.5-turbo',
+      },
+    ],
+    strategy: {
+      type: 'round-robin',
+    },
+    enableHealthChecks: true,
+    healthCheckInterval: 60000, // 60 seconds
+  });
+
+  // Simple chat
+  console.log('=== Simple Chat ===');
+  const response = await orchestrator.chat([
+    { role: 'user', content: 'Say hello in one sentence' },
+  ]);
+  console.log('Response:', response.content);
+  console.log('Usage:', response.usage);
+
+  // Streaming chat
+  console.log('\n=== Streaming Chat ===');
+  const stream = await orchestrator.chatStream([
+    { role: 'user', content: 'Count from 1 to 5' },
+  ]);
+
+  const reader = stream.getReader();
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    process.stdout.write(value.content);
+  }
+  console.log('\n');
+
+  // Cleanup
+  orchestrator.dispose();
+}
+
+main().catch(console.error);
+

package/package/examples/chat-app/README.md

@@ -0,0 +1,146 @@
+# Chat App Example
+
+A simple chat application to test `@ai-orchestration/core` using npm link.
+
+## Quick Setup
+
+### 1. Link the Package
+
+```bash
+# In the ia-orchestration directory (from project root)
+cd /path/to/ia-orchestration
+npm run link
+```
+
+### 2. Setup This Project
+
+```bash
+# In this directory
+cd examples/chat-app
+npm install
+npm link @ai-orchestration/core
+```
+
+### 3. Configure Environment Variables
+
+Create a `.env` file from the example:
+
+```bash
+# Copy the example file
+cp .env.example .env
+
+# Edit .env with your real API keys
+# GROQ_API_KEY=your-real-key-here
+# OPENROUTER_API_KEY=your-real-key-here
+# GEMINI_API_KEY=your-real-key-here
+# CEREBRAS_API_KEY=your-real-key-here
+```
+
+**Important**: The `.env` file is in `.gitignore` and will not be committed to the repository.
+
+**Note**: You only need to configure at least ONE API key for it to work.
+
+### 4. (Optional) Customize Configuration
+
+You can edit `config.json` to:
+- Change default models
+- Change initial strategy
+- Adjust chat options (temperature, maxTokens)
+- Add or remove providers
+
+### 5. Run
+
+```bash
+npm start
+```
+
+## Usage
+
+The application allows you to:
+- Chat with multiple AI providers
+- Change strategy at runtime
+- See which provider is being used
+- View usage statistics
+
+## Available Commands
+
+- `/help` - Show help
+- `/strategy <type>` - Change strategy (round-robin, priority, fallback)
+- `/providers` - List available providers
+- `/health` - Check provider health
+- `/clear` - Clear conversation history
+- `/exit` or `/quit` - Exit the application
+
+## Example Session
+
+```
+🚀 Chat App - Example with @ai-orchestration/core
+
+💡 Type /help to see available commands
+
+🔧 Creating orchestrator...
+✅ Orchestrator created with 2 provider(s)
+
+💬 You: Hello!
+🤔 Thinking... 
+✅ Response (1234ms):
+
+   Hello! How can I help you today?
+
+💬 You: /providers
+📋 Available providers:
+  1. groq-1 (Groq)
+  2. openrouter-1 (OpenRouter)
+
+💬 You: /exit
+👋 Goodbye!
+```
+
+## Verification
+
+To verify everything is configured correctly:
+
+```bash
+# Verify that the link works
+npm list @ai-orchestration/core
+
+# Should show:
+# chat-app-example@1.0.0
+# └── @ai-orchestration/core@0.1.0 -> /path/to/ia-orchestration
+```
+
+## Troubleshooting
+
+### Error: "Cannot find module '@ai-orchestration/core'"
+
+```bash
+# Verify link exists
+npm list @ai-orchestration/core
+
+# If it doesn't exist, re-link
+npm link @ai-orchestration/core
+```
+
+### Error: "No providers configured"
+
+- Verify that `.env` exists in `examples/chat-app/`
+- Verify it has at least one API key configured
+- Verify there are no spaces around `=` in `.env`
+- Verify values are not the example ones (`your-*-api-key-here`)
+
+### Error: "Module not found" or TypeScript errors
+
+```bash
+# Reinstall dependencies
+rm -rf node_modules package-lock.json
+npm install
+```
+
+### Changes in package not reflected
+
+```bash
+# In the ia-orchestration directory (root)
+npm run build
+
+# Changes should be reflected automatically
+```

package/package/examples/chat-app/config.json

@@ -0,0 +1,34 @@
+{
+  "providers": [
+    {
+      "id": "groq-1",
+      "type": "groq",
+      "envKey": "GROQ_API_KEY",
+      "model": "llama-3.3-70b-versatile"
+    },
+    {
+      "id": "openrouter-1",
+      "type": "openrouter",
+      "envKey": "OPENROUTER_API_KEY",
+      "model": "openai/gpt-3.5-turbo"
+    },
+    {
+      "id": "gemini-1",
+      "type": "gemini",
+      "envKey": "GEMINI_API_KEY",
+      "model": "gemini-pro"
+    },
+    {
+      "id": "cerebras-1",
+      "type": "cerebras",
+      "envKey": "CEREBRAS_API_KEY",
+      "model": "llama-3.3-70b"
+    }
+  ],
+  "defaultStrategy": "round-robin",
+  "chatOptions": {
+    "temperature": 0.7,
+    "maxTokens": 1000
+  }
+}
+