llmjs2 1.3.1 → 1.3.2

package/README.md

@@ -1,6 +1,6 @@
 # llmjs2
 
-A unified, enterprise-grade Node.js library for connecting to multiple Large Language Model (LLM) providers: OpenAI, Ollama, and OpenRouter.
+A unified Node.js library for connecting to multiple Large Language Model (LLM) providers: OpenAI, Ollama, and OpenRouter.
 
 **Features:**
 - **Unified API**: Single interface for OpenAI, Ollama, and OpenRouter
@@ -37,11 +37,8 @@ npm install -g llmjs2
 Try the sample configuration:
 
 ```bash
-# Validate configuration
-node validate-config.js
-
 # Start server with sample config
-node cli.js --config config.yaml --port 3001
+llmjs2 --config config.yaml --port 3001
 
 # Test the API
 curl -X POST http://localhost:3001/v1/chat/completions \
@@ -59,8 +56,34 @@ curl -X POST http://localhost:3001/v1/chat/completions \
 #     {"role": "assistant", "content": "Hi there!"}
 #   ]
 # }
+
+## Programmatic Configuration
+
+For advanced users, you can configure llmjs2 router programmatically instead of using YAML:
+
+```bash
+npm run router:example
 ```
 
+See `server-config.js` for a complete example of configuring models, guardrails, and routing in JavaScript code, with direct completion usage.
+
+## AI Chat App
+
+Experience llmjs2 with a simple terminal-based chat interface:
+
+```bash
+npm run chat
+```
+
+Features:
+- Conversational chat with message history
+- Automatic model routing (random selection)
+- Shows which model was used for each response
+- Simple guardrails (logging)
+- Graceful exit with "exit", "quit", or "bye"
+
+The chat app uses the same router configuration as the programmatic examples but provides an interactive chat experience.
+
 See `CONFIG_README.md` for detailed configuration examples.
 
 ## Quick Start

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llmjs2",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "description": "A unified Node.js library for connecting to multiple LLM providers: OpenAI, Ollama, and OpenRouter",
   "main": "index.js",
   "type": "commonjs",
@@ -8,6 +8,8 @@
     "test": "node test.js",
     "start": "node cli.js",
     "server": "node cli.js",
+    "router:example": "node server-config.js",
+    "chat": "node chat-app.js",
     "lint": "echo 'No linting configured'",
     "typecheck": "echo 'No TypeScript configured'"
   },

package/CONFIG_README.md

@@ -1,98 +0,0 @@
-# llmjs2 Configuration Guide
-
-This directory contains sample configuration files for testing the llmjs2 library.
-
-## Files
-
-- `config.yaml` - Comprehensive sample configuration with models, guardrails, and routing
-- `.env` - Sample environment variables (add your API keys here)
-- `validate-config.js` - Script to validate your configuration
-
-## Quick Start
-
-1. **Add your API keys** to `.env`:
-   ```bash
-   # Uncomment and add your keys
-   OPENAI_API_KEY=your_actual_openai_key
-   # OLLAMA_API_KEY and OPEN_ROUTER_API_KEY are already set for testing
-   ```
-
-2. **Validate the configuration**:
-   ```bash
-   node validate-config.js
-   ```
-
-3. **Start the server**:
-   ```bash
-   node cli.js --config config.yaml --port 3001
-   ```
-
-4. **Test the API**:
-   ```bash
-   curl -X POST http://localhost:3001/v1/chat/completions \
-     -H "Content-Type: application/json" \
-     -d '{"messages":[{"role":"user","content":"Hello!"}]}'
-   ```
-
-## Configuration Structure
-
-### Model List
-Defines available models and their providers:
-- `model_name`: Alias for routing (can have multiple providers)
-- `llm_params`: Provider-specific configuration
-  - `model`: Full model identifier in format `[provider]/[actual-model-name]` (e.g., `openai/gpt-4`, `ollama/minimax-m2.5:cloud`)
-  - `api_key`: API key (supports `os.environ/VAR_NAME` syntax)
-  - `api_base`: Optional custom API endpoint
-
-**Important**: The `[provider]/` prefix is used internally for routing. When requests are sent to LLM providers, only the `[actual-model-name]` part is used.
-
-### Guardrails
-Custom processing logic for requests/responses:
-- `name`: Unique identifier
-- `mode`: `pre_call` (before LLM) or `post_call` (after LLM)
-- `code`: JavaScript function as string
-
-### Router Settings
-- `routing_strategy`: `default`, `random`, or `sequential`
-
-## Testing Different Features
-
-### Load Balancing
-The config includes multiple models with the same `model_name` (like `free-model`) to demonstrate load balancing.
-
-### Guardrails
-Try sending requests with inappropriate content to see filtering in action:
-```bash
-curl -X POST http://localhost:3001/v1/chat/completions \
-  -H "Content-Type: application/json" \
-  -d '{"messages":[{"role":"user","content":"This contains badword"}]}'
-```
-
-### Different Routing Strategies
-Edit `router_settings.routing_strategy` to test:
-- `random`: Random model selection
-- `sequential`: Cycle through models
-- `default`: Load balance same model names
-
-## Environment Variables
-
-The configuration supports environment variables:
-- `os.environ/VAR_NAME` syntax in YAML
-- `.env` file loaded automatically
-- Standard environment variables override defaults
-
-## Troubleshooting
-
-- **"Model not found"**: Check that API keys are set in `.env`
-- **"Rate limit exceeded"**: The config includes rate limiting (10 requests/minute)
-- **Server won't start**: Run `node validate-config.js` to check configuration
-- **API errors**: Check server logs for detailed error messages
-
-## Production Usage
-
-For production:
-1. Remove test API keys from `.env`
-2. Add your actual API keys
-3. Configure proper rate limiting and content filtering
-4. Set up proper logging and monitoring
-5. Use environment-specific config files (dev/prod)

package/validate-config.js

@@ -1,87 +0,0 @@
-#!/usr/bin/env node
-
-// Test script to validate config.yaml loading
-const yaml = require('yaml');
-const fs = require('fs');
-const path = require('path');
-
-function loadAndValidateConfig() {
-  const configPath = path.join(__dirname, 'config.yaml');
-
-  if (!fs.existsSync(configPath)) {
-    console.error('❌ config.yaml not found');
-    return false;
-  }
-
-  try {
-    const configContent = fs.readFileSync(configPath, 'utf8');
-    const config = yaml.parse(configContent);
-
-    console.log('✅ Config file loaded successfully');
-    console.log(`📋 Found ${config.model_list?.length || 0} models`);
-    console.log(`🛡️ Found ${config.guardrails?.length || 0} guardrails`);
-    console.log(`🔀 Routing strategy: ${config.router_settings?.routing_strategy || 'default'}`);
-
-    // Validate model list
-    if (!config.model_list || !Array.isArray(config.model_list)) {
-      console.error('❌ model_list must be an array');
-      return false;
-    }
-
-    // Check each model
-    const modelNames = [];
-    for (const model of config.model_list) {
-      if (!model.model_name || !model.llm_params?.model) {
-        console.error('❌ Each model must have model_name and llm_params.model');
-        return false;
-      }
-      modelNames.push(model.model_name);
-    }
-
-    console.log(`📊 Model names: ${[...new Set(modelNames)].join(', ')}`);
-
-    // Validate guardrails
-    if (config.guardrails) {
-      for (const guardrail of config.guardrails) {
-        if (!guardrail.name || !guardrail.mode || !guardrail.code) {
-          console.error(`❌ Guardrail "${guardrail.name || 'unnamed'}" missing required fields`);
-          return false;
-        }
-        if (!['pre_call', 'post_call'].includes(guardrail.mode)) {
-          console.error(`❌ Guardrail "${guardrail.name}" has invalid mode: ${guardrail.mode}`);
-          return false;
-        }
-      }
-    }
-
-    // Test environment variable resolution
-    const testModel = config.model_list[0];
-    if (testModel.llm_params.api_key?.startsWith('os.environ/')) {
-      const envVar = testModel.llm_params.api_key.replace('os.environ/', '');
-      const envValue = process.env[envVar];
-      console.log(`🔑 API key for ${testModel.llm_params.model}: ${envValue ? '✅ Set' : '❌ Not set'}`);
-    }
-
-    console.log('🎉 Config validation passed!');
-    return true;
-
-  } catch (error) {
-    console.error('❌ Config validation failed:', error.message);
-    return false;
-  }
-}
-
-// Run validation
-console.log('🔍 Validating config.yaml...\n');
-const success = loadAndValidateConfig();
-
-if (!success) {
-  process.exit(1);
-}
-
-console.log('\n💡 To test the server, run:');
-console.log('  node cli.js --config config.yaml --port 3001');
-console.log('\n📖 To test with curl:');
-console.log('  curl -X POST http://localhost:3001/v1/chat/completions \\');
-console.log('    -H "Content-Type: application/json" \\');
-console.log('    -d \'{"messages":[{"role":"user","content":"Hello!"}]}\'');