llmjs2 1.3.1 → 1.3.3

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
@@ -369,6 +392,69 @@ Run the test suite:
 npm test
 ```
 
+Test basic completion functionality:
+
+```bash
+npm run test:completion
+```
+
+## Logging
+
+Configure logging levels for LLM provider requests and responses:
+
+```bash
+# Show all logs (DEBUG, WARN, INFO, ERROR)
+LLMJS2_LOG=debug node your-script.js
+
+# Show INFO and ERROR logs only
+LLMJS2_LOG=info node your-script.js
+
+# Show WARN, INFO, and ERROR logs
+LLMJS2_LOG=warn node your-script.js
+
+# Show ERROR logs only
+LLMJS2_LOG=error node your-script.js
+
+# Examples
+LLMJS2_LOG=debug npm run chat
+LLMJS2_LOG=info npm run test:completion
+```
+
+### Log Levels
+
+- **DEBUG**: All logs including detailed request/response data
+- **INFO**: LLM provider communication and important events
+- **WARN**: Warnings and important notifications
+- **ERROR**: Errors and failures
+
+### Log Format
+
+```
+[TIMESTAMP] [LEVEL] MESSAGE
+DATA_OBJECT (JSON formatted)
+```
+
+### Example Output
+
+```
+[2026-04-13T10:14:58.123Z] [INFO] LLMJS2 📤 Sending to LLM provider
+{
+  "source": "completion",
+  "provider": "ollama",
+  "model": "minimax-m2.5:cloud",
+  "apiKey": "2620e31dea...",
+  "messages": [{"role": "user", "content": "Hello!"}]
+}
+
+[2026-04-13T10:15:01.456Z] [INFO] LLMJS2 📥 Received from LLM provider
+{
+  "source": "completion",
+  "content": "Hello! How can I help you?",
+  "role": "assistant",
+  "usage": {"prompt_eval_count": 10, "eval_count": 15}
+}
+```
+
 ## License
 
 MIT

package/index.js

@@ -3,6 +3,7 @@ const OllamaProvider = require('./providers/ollama');
 const OpenRouterProvider = require('./providers/openrouter');
 const { router } = require('./router');
 const { app } = require('./server');
+const logger = require('./logger');
 
 class LLMJS2 {
   constructor(config = {}) {
@@ -166,8 +167,25 @@ class LLMJS2 {
         provider.timeout = options.timeout;
       }
 
+      // Log request information
+      const apiKeyPreview = provider.apiKey ? provider.apiKey.substring(0, 10) + '...' : 'none';
+      logger.info('LLMJS2 📤 Sending to LLM provider', {
+        source: 'completion',
+        provider: provider.constructor.name.replace('Provider', '').toLowerCase(),
+        model: finalModel,
+        apiKey: apiKeyPreview,
+        messages: messages,
+        options: { ...options, model: finalModel }
+      });
+
       const result = await provider.createCompletion(messages, { ...options, model: finalModel });
 
+      // Log response information
+      logger.info('LLMJS2 📥 Received from LLM provider', {
+        source: 'completion',
+        ...result
+      });
+
       return result.content;
 
     } catch (error) {

package/logger.js

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+
+/**
+ * Simple logging utility for llmjs2
+ * Provides structured logging with timestamps and levels
+ */
+
+class Logger {
+  constructor() {
+    this.levels = {
+      DEBUG: 0,  // Shows all logs
+      INFO: 1,   // Shows INFO and ERROR only
+      WARN: 2,   // Shows WARN, INFO, and ERROR
+      ERROR: 3,  // Shows ERROR only
+      FATAL: 4
+    };
+
+    // Set level based on LLMJS2_LOG environment variable
+    this.setLevelFromEnv();
+  }
+
+  setLevelFromEnv() {
+    const envLevel = process.env.LLMJS2_LOG;
+    if (!envLevel) {
+      // Default to no logging if not set
+      this.currentLevel = 99; // Higher than any level
+      return;
+    }
+
+    const upperEnvLevel = envLevel.toUpperCase();
+    if (this.levels[upperEnvLevel] !== undefined) {
+      this.currentLevel = this.levels[upperEnvLevel];
+    } else {
+      // Default to INFO if invalid value
+      this.currentLevel = this.levels.INFO;
+    }
+  }
+
+  setLevel(level) {
+    if (this.levels[level] !== undefined) {
+      this.currentLevel = this.levels[level];
+    }
+  }
+
+  formatMessage(level, message, data = null) {
+    const timestamp = new Date().toISOString();
+    let output = `[${timestamp}] [${level}] ${message}`;
+
+    if (data) {
+      output += '\n' + JSON.stringify(data, null, 2);
+    }
+
+    return output;
+  }
+
+  shouldLog(level) {
+    const levelValue = this.levels[level];
+
+    // No logging if not configured
+    if (this.currentLevel === 99) return false;
+
+    // Custom logic based on user's requirements
+    if (this.currentLevel === this.levels.DEBUG) {
+      // Debug shows all levels
+      return true;
+    } else if (this.currentLevel === this.levels.INFO) {
+      // Info shows INFO and ERROR only
+      return level === 'INFO' || level === 'ERROR';
+    } else if (this.currentLevel === this.levels.WARN) {
+      // Warn shows WARN, INFO, and ERROR
+      return level === 'WARN' || level === 'INFO' || level === 'ERROR';
+    } else if (this.currentLevel === this.levels.ERROR) {
+      // Error shows ERROR only
+      return level === 'ERROR';
+    }
+
+    return false;
+  }
+
+  debug(message, data = null) {
+    if (this.shouldLog('DEBUG')) {
+      console.log(this.formatMessage('DEBUG', message, data));
+    }
+  }
+
+  info(message, data = null) {
+    if (this.shouldLog('INFO')) {
+      console.log(this.formatMessage('INFO', message, data));
+    }
+  }
+
+  warn(message, data = null) {
+    if (this.shouldLog('WARN')) {
+      console.warn(this.formatMessage('WARN', message, data));
+    }
+  }
+
+  error(message, data = null) {
+    if (this.shouldLog('ERROR')) {
+      console.error(this.formatMessage('ERROR', message, data));
+    }
+  }
+
+  fatal(message, data = null) {
+    if (this.shouldLog('FATAL')) {
+      console.error(this.formatMessage('FATAL', message, data));
+    }
+  }
+}
+
+// Create singleton logger instance
+const logger = new Logger();
+
+// Export for use in other modules
+module.exports = logger;

package/package.json

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

package/router.js

@@ -1,6 +1,7 @@
 const OpenAIProvider = require('./providers/openai');
 const OllamaProvider = require('./providers/ollama');
 const OpenRouterProvider = require('./providers/openrouter');
+const logger = require('./logger');
 
 class Router {
   constructor(modelList, strategy = 'default') {
@@ -180,7 +181,7 @@ class Router {
       };
 
     } catch (error) {
-      console.error(`[${processId}] Router error:`, error.message);
+      logger.error(`Router error`, { processId, error: error.message });
       throw error;
     }
   }
@@ -200,8 +201,8 @@ class Router {
       provider.apiKey = modelConfig.llm_params.api_key;
     }
 
-    // Call the provider directly with just the actual model name (without provider prefix)
-    return await provider.createCompletion(input.messages, {
+    // Prepare the completion options
+    const completionOptions = {
       model: actualModel,
       temperature: input.temperature,
       maxTokens: input.maxTokens,
@@ -211,7 +212,29 @@ class Router {
       stop: input.stop,
       tools: input.tools,
       toolChoice: input.toolChoice
+    };
+
+    // Log request information
+    const apiKeyPreview = provider.apiKey ? provider.apiKey.substring(0, 10) + '...' : 'none';
+    logger.info('LLMJS2 📤 Sending to LLM provider', {
+      source: 'router',
+      provider: providerName,
+      model: actualModel,
+      apiKey: apiKeyPreview,
+      messages: input.messages,
+      options: completionOptions
     });
+
+    // Call the provider directly with just the actual model name (without provider prefix)
+    const result = await provider.createCompletion(input.messages, completionOptions);
+
+    // Log response information
+    logger.info('LLMJS2 📥 Received from LLM provider', {
+      source: 'router',
+      ...result
+    });
+
+    return result;
   }
 
   generateProcessId() {

package/server.js

@@ -51,9 +51,12 @@ class Server {
         return;
       }
 
-      console.log(`[${new Date().toISOString()}] ${req.method} ${req.url}`);
-      console.log('Headers:', JSON.stringify(req.headers));
-      console.log('Body parsing completed successfully');
+      logger.debug('Incoming request', {
+        method: req.method,
+        url: req.url,
+        headers: req.headers,
+        bodyLength: JSON.stringify(body).length
+      });
 
       // Process the completion request
       const result = await this.processCompletion(body);
@@ -62,7 +65,7 @@ class Server {
       this.sendSuccess(res, result);
 
     } catch (error) {
-      console.error('Server error:', error);
+      logger.error('Server error', { error: error.message, url: req.url, method: req.method });
       this.sendError(res, 500, 'Internal Server Error', error.message);
     }
   }
@@ -114,7 +117,10 @@ class Server {
       throw new Error('No router configured. Use app.use(router) to add a router.');
     }
 
-    console.log(`Starting completion with model: ${body.model || 'auto-selected'}`);
+    logger.debug('Server processing completion request', {
+      model: body.model || 'auto-selected',
+      messageCount: body.messages?.length || 0
+    });
 
     const routerResponse = await this.router.completion(body);
     const { result, selectedModel, selectedModelName } = routerResponse;
@@ -168,6 +174,7 @@ class Server {
     const server = http.createServer((req, res) => this.handleRequest(req, res));
 
     server.listen(actualPort, actualHost, () => {
+      logger.info('Server started', { host: actualHost, port: actualPort });
       console.log(`🚀 llmjs2 server running on http://${actualHost}:${actualPort}`);
       if (callback) callback();
     });

package/test-completion.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+
+/**
+ * Simple Completion Test
+ * Tests basic llmjs2 completion functionality using defaults
+ */
+
+const { completion } = require('./index');
+
+async function testSimpleCompletion() {
+  console.log('🧪 Testing simple completion with defaults...\n');
+
+  try {
+    console.log('📤 Sending completion request...');
+    console.log('Prompt: "Hello! Can you tell me a short joke?"\n');
+
+    // Simple completion call - no model or API key specified
+    const response = await completion('Hello! Can you tell me a short joke?');
+
+    console.log('✅ Completion successful!');
+    console.log('📥 Response received:');
+    console.log('---');
+    console.log(response);
+    console.log('---\n');
+
+    // Basic validation
+    if (typeof response === 'string' && response.length > 0) {
+      console.log('✅ Response is valid string');
+      console.log(`📏 Response length: ${response.length} characters`);
+    } else {
+      console.log('❌ Response is not a valid string');
+      return false;
+    }
+
+    // Check if it looks like a joke or response
+    const hasJokeIndicators = response.toLowerCase().includes('joke') ||
+                            response.toLowerCase().includes('knock knock') ||
+                            response.includes('?') ||
+                            response.includes('!');
+
+    if (hasJokeIndicators) {
+      console.log('✅ Response appears to be joke-related');
+    } else {
+      console.log('ℹ️  Response received (may not be joke-related)');
+    }
+
+    console.log('\n🎉 Simple completion test passed!');
+    return true;
+
+  } catch (error) {
+    console.error('❌ Completion test failed:');
+    console.error('Error:', error.message);
+
+    if (error.message.includes('API key')) {
+      console.log('\n💡 Tip: Make sure you have API keys set in environment variables:');
+      console.log('   export OLLAMA_API_KEY=your_key');
+      console.log('   export OPEN_ROUTER_API_KEY=your_key');
+    }
+
+    return false;
+  }
+}
+
+// Check environment before running
+function checkEnvironment() {
+  const hasKeys = process.env.OLLAMA_API_KEY || process.env.OPEN_ROUTER_API_KEY;
+
+  if (!hasKeys) {
+    console.log('⚠️  No API keys found in environment variables.');
+    console.log('   Set at least one: OLLAMA_API_KEY or OPEN_ROUTER_API_KEY');
+    console.log('   The test will still run but may fail.\n');
+  } else {
+    console.log('✅ API keys found in environment\n');
+  }
+}
+
+// Run the test
+async function main() {
+  console.log('🚀 Running Simple Completion Test for llmjs2\n');
+
+  checkEnvironment();
+
+  const success = await testSimpleCompletion();
+
+  if (success) {
+    console.log('\n✨ Test completed successfully!');
+    process.exit(0);
+  } else {
+    console.log('\n💥 Test failed!');
+    process.exit(1);
+  }
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { testSimpleCompletion };

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!"}]}\'');