@ai-orchestration/core 0.1.0

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/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/docs/ARCHITECTURE.md

@@ -0,0 +1,126 @@
+# Framework Architecture
+
+## Overview
+
+The framework is designed following SOLID principles and plugin-based architecture, allowing extensibility without modifying core code.
+
+## Main Components
+
+### Core (`src/core/`)
+
+#### `interfaces.ts`
+Defines fundamental interfaces:
+- `AIService`: Contract that all providers must implement
+- `SelectionStrategy`: Contract for selection strategies
+- `OrchestratorConfig`: Orchestrator configuration
+- Configuration types for providers and strategies
+
+#### `types.ts`
+Shared types:
+- `ChatMessage`: Message in a conversation
+- `ChatOptions`: Options for chat completion
+- `ChatResponse`: Non-streaming response
+- `ChatChunk`: Streaming chunk
+- `ProviderHealth`: Provider health status
+- `ProviderMetadata`: Provider metadata
+
+#### `orchestrator.ts`
+Framework core:
+- `Orchestrator`: Main class that manages providers and strategies
+- Provider registration and management
+- Automatic provider selection
+- Automatic fallback on error
+- Periodic health checks
+
+### Providers (`src/providers/`)
+
+Each provider extends `BaseProvider` and implements:
+- `checkHealth()`: Health verification
+- `chat()`: Chat completion (non-streaming)
+- `chatStream()`: Chat completion (streaming)
+- `formatMessages()`: Conversion from standard format to provider format
+- `parseResponse()`: Conversion from provider response to standard format
+- `parseStream()`: Conversion from provider stream to standard format
+
+**Implemented providers:**
+- `GroqProvider`: Groq API integration
+- `OpenRouterProvider`: OpenRouter integration
+- `GeminiProvider`: Google Gemini integration
+- `CerebrasProvider`: Cerebras Inference API integration
+- `LocalProvider`: For local models (OpenAI-compatible API)
+
+### Strategies (`src/strategies/`)
+
+Each strategy extends `BaseStrategy` and implements:
+- `select()`: Provider selection logic
+- `update()` (optional): Internal state update
+
+**Implemented strategies:**
+- `RoundRobinStrategy`: Cycles through providers
+- `PriorityStrategy`: Selects by priority
+- `FallbackStrategy`: Tries in order until success
+- `WeightedStrategy`: Selection based on weights (load balancing)
+- `HealthAwareStrategy`: Selection based on health metrics
+
+### Factory (`src/factory/`)
+
+- `createOrchestrator()`: Creates an orchestrator from declarative configuration
+- `createProvider()`: Creates provider instances from configuration
+- `createStrategy()`: Creates strategy instances from configuration
+- `isValidOrchestratorConfig()`: Validates configuration
+
+## Data Flow
+
+```
+User
+  ↓
+Orchestrator.chat() / chatStream()
+  ↓
+Strategy.select() → Selects provider
+  ↓
+Provider.chat() / chatStream()
+  ↓
+Provider formats messages → formatMessages()
+  ↓
+Provider API call
+  ↓
+Provider parses response → parseResponse() / parseStream()
+  ↓
+Standard response to user
+```
+
+## Extensibility
+
+### Adding a New Provider
+
+1. Create class extending `BaseProvider`
+2. Implement required methods
+3. Register in `factory/index.ts` (`createProvider` method)
+
+### Adding a New Strategy
+
+1. Create class extending `BaseStrategy`
+2. Implement `select()` method
+3. Optionally implement `update()`
+4. Register in `factory/index.ts` (`createStrategy` method)
+
+## Applied Design Principles
+
+1. **Single Responsibility**: Each class has a single responsibility
+2. **Open/Closed**: Open for extension, closed for modification
+3. **Liskov Substitution**: Providers and strategies are interchangeable
+4. **Interface Segregation**: Specific and cohesive interfaces
+5. **Dependency Inversion**: Dependencies on abstractions, not implementations
+
+## Compatibility
+
+- **Node.js**: >= 18.0.0 (uses native ReadableStream)
+- **TypeScript**: 5.3+
+- **ES Modules**: Required
+
+## Performance Considerations
+
+- Health checks can run in parallel
+- Automatic fallback avoids unnecessary waits
+- Native streaming for long responses
+- Strategies can cache metrics for better performance

package/docs/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2025-12-05
+
+### Added
+- Complete AI orchestration framework
+- Support for multiple providers: Groq, OpenRouter, Gemini, Cerebras, Local
+- 5 selection strategies: Round-Robin, Priority, Fallback, Weighted, Health-Aware
+- Native streaming with ReadableStream
+- Automatic health checks with latency metrics
+- Factory for declarative creation
+- Custom error handling
+- Configuration validation
+- Complete documentation (README, ARCHITECTURE, CONTRIBUTING)
+- Usage examples
+- Basic tests
+- Node.js compatibility
+
+### Main Features
+- Plugin-based architecture (extensible without modifying core)
+- Declarative and programmatic API
+- Type-safe with TypeScript
+- Automatic fallback between providers
+- Support for cost-aware selection
+- Health-aware selection with real-time metrics

package/docs/CONTRIBUTING.md

@@ -0,0 +1,198 @@
+# Contributing Guide
+
+## Project Structure
+
+```
+src/
+├── core/           # Framework core (interfaces, types, orchestrator)
+├── providers/      # Provider implementations
+├── strategies/     # Selection strategies
+├── factory/        # Factory for declarative creation
+└── index.ts        # Main entry point
+```
+
+## Adding a New Provider
+
+1. **Create the provider file** in `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;
+  // ... other provider-specific fields
+}
+
+export class CustomProvider extends BaseProvider {
+  readonly id: string;
+  readonly metadata: ProviderMetadata;
+  
+  constructor(config: CustomProviderConfig) {
+    super();
+    // Initialization
+  }
+  
+  async checkHealth(): Promise<ProviderHealth> {
+    // Implement health check
+  }
+  
+  async chat(messages: ChatMessage[], options?: ChatOptions): Promise<ChatResponse> {
+    // Implement chat
+  }
+  
+  async chatStream(messages: ChatMessage[], options?: ChatOptions): Promise<ReadableStream<ChatChunk>> {
+    // Implement streaming
+  }
+  
+  protected formatMessages(messages: ChatMessage[]): unknown {
+    // Convert standard format to provider format
+  }
+  
+  protected parseResponse(response: unknown): ChatResponse {
+    // Convert response to standard format
+  }
+  
+  protected parseStream(stream: ReadableStream<unknown>): ReadableStream<ChatChunk> {
+    // Convert stream to standard format
+  }
+}
+```
+
+2. **Export in `src/providers/index.ts`**:
+
+```typescript
+export { CustomProvider } from './custom.js';
+export type { CustomProviderConfig } from './custom.js';
+```
+
+3. **Register in `src/factory/index.ts`**:
+
+```typescript
+import { CustomProvider, type CustomProviderConfig } from '../providers/index.js';
+
+// In the createProvider function:
+case 'custom':
+  return new CustomProvider({
+    id,
+    ...(rest as CustomProviderConfig),
+  } as CustomProviderConfig);
+```
+
+## Adding a New Strategy
+
+1. **Create the strategy file** in `src/strategies/`:
+
+```typescript
+import { BaseStrategy } from './base.js';
+import type { AIService, SelectionContext } from '../core/interfaces.js';
+
+export interface CustomStrategyConfig {
+  // Strategy-specific configuration
+}
+
+export class CustomStrategy extends BaseStrategy {
+  constructor(config?: CustomStrategyConfig) {
+    super();
+    // Initialization
+  }
+  
+  async select(
+    providers: AIService[],
+    context?: SelectionContext
+  ): Promise<AIService | null> {
+    // Implement selection logic
+  }
+  
+  update?(provider: AIService, success: boolean, metadata?: unknown): void {
+    // Optional: update internal state
+  }
+}
+```
+
+2. **Export in `src/strategies/index.ts`**
+
+3. **Register in `src/factory/index.ts`**
+
+## Code Conventions
+
+- **Strict TypeScript**: Use explicit types
+- **Descriptive names**: Variables and functions with clear names
+- **Documentation**: JSDoc for public functions
+- **Error handling**: Use custom error classes
+- **Tests**: Add tests for new functionality
+
+## Testing
+
+Tests are in `tests/`. Use Node.js test runner:
+
+```bash
+npm test
+```
+
+For local testing with mock providers:
+
+```bash
+npm run test:mock
+```
+
+For testing with real providers:
+
+```bash
+npm run test:local
+```
+
+## Versioning
+
+Follow [Semantic Versioning](https://semver.org/):
+- **MAJOR**: Incompatible API changes
+- **MINOR**: New backward-compatible functionality
+- **PATCH**: Backward-compatible bug fixes
+
+## Pull Requests
+
+1. Create a branch from `main`
+2. Implement changes
+3. Add tests
+4. Update documentation if necessary
+5. Ensure all tests pass
+6. Create PR with clear description
+
+## Development Setup
+
+1. **Clone the repository**
+2. **Install dependencies**:
+   ```bash
+   npm install
+   ```
+3. **Build the project**:
+   ```bash
+   npm run build
+   ```
+4. **Run tests**:
+   ```bash
+   npm test
+   ```
+
+## Code Style
+
+- Use TypeScript strict mode
+- Follow existing code style
+- Use meaningful variable and function names
+- Add comments for complex logic
+- Keep functions focused and small
+
+## Commit Messages
+
+Use clear, descriptive commit messages:
+- Use imperative mood ("Add feature" not "Added feature")
+- Reference issues when applicable
+- Keep messages concise but informative

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/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/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
+  }
+}
+