llmjs2 1.3.9 → 1.7.1

package/core/cli.js

@@ -0,0 +1,275 @@
+#!/usr/bin/env node
+
+const { app } = require('./server');
+const { router } = require('./router');
+const { Graph } = require('../chain');
+const yaml = require('yaml');
+const fs = require('fs');
+const path = require('path');
+
+class CLI {
+  constructor() {
+    this.args = process.argv.slice(2);
+    this.options = this.parseArgs();
+  }
+
+  parseArgs() {
+    const options = {
+      mode: 'start',
+      start: false,
+      port: 3000,
+      host: 'localhost',
+      config: null,
+      flowPath: null,
+      inputStr: '',
+      help: false
+    };
+
+    if (this.args.length > 0 && this.args[0] === 'run') {
+      options.mode = 'run';
+      if (this.args.length < 2) {
+        console.error('Missing flow file for run command');
+        this.showHelp();
+        process.exit(1);
+      }
+      options.flowPath = this.args[1];
+      options.inputStr = this.args.slice(2).join(' ');
+      return options;
+    }
+
+    for (let i = 0; i < this.args.length; i++) {
+      const arg = this.args[i];
+
+      switch (arg) {
+        case '-S':
+          options.start = true;
+          break;
+        case '-p':
+        case '--port':
+          options.port = parseInt(this.args[++i], 10);
+          break;
+        case '-H':
+        case '--host':
+          options.host = this.args[++i];
+          break;
+        case '-c':
+        case '--config':
+          options.config = this.args[++i];
+          break;
+        case '-h':
+        case '--help':
+          options.help = true;
+          break;
+        default:
+          if (arg.startsWith('-')) {
+            console.error(`Unknown option: ${arg}`);
+            this.showHelp();
+            process.exit(1);
+          } else {
+            console.error(`Unexpected positional argument: ${arg}`);
+            this.showHelp();
+            process.exit(1);
+          }
+      }
+    }
+
+    return options;
+  }
+
+  parseInputs(inputStr) {
+    const inputs = {};
+    if (!inputStr.trim()) return inputs;
+
+    const pairs = inputStr.split(';').map((s) => s.trim()).filter((s) => s);
+    for (const pair of pairs) {
+      const [key, value] = pair.split('=');
+      if (key && value) {
+        const cleanValue = value.replace(/^["']|["']$/g, '');
+        inputs[key.trim()] = cleanValue;
+      }
+    }
+    return inputs;
+  }
+
+  async runWorkflow() {
+    try {
+      const config = JSON.parse(fs.readFileSync(this.options.flowPath, 'utf8'));
+      const workflow = Graph.load(config).compile();
+      const inputs = this.parseInputs(this.options.inputStr);
+
+      console.log(`Running workflow: ${config.name || this.options.flowPath}`);
+      console.log(`Inputs: ${JSON.stringify(inputs, null, 2)}`);
+
+      const result = await workflow.run(inputs);
+
+      console.log('Workflow completed successfully');
+      console.log(JSON.stringify(result, null, 2));
+    } catch (error) {
+      console.error('Failed to run workflow:', error.message);
+      process.exit(1);
+    }
+  }
+
+  showHelp() {
+    console.log(`
+llmjs2 - OpenAI-Compatible API Server and Workflow Runner
+
+USAGE:
+  llmjs2 -S [options]          Start the API server
+  llmjs2 run <flow> [inputs]   Run a workflow from JSON file
+
+DESCRIPTION:
+  Starts an OpenAI-compatible API server with intelligent routing and guardrails,
+  or runs workflows defined in JSON files with agent steps and conditional logic.
+
+OPTIONS:
+  -S                           Start the server
+  -c, --config <file>          YAML config file with models, guardrails, and routing
+  -p, --port <port>            Port to listen on (default: 3000)
+  -H, --host <host>            Host to bind to (default: localhost)
+  -h, --help                   Show this help message
+
+EXAMPLES:
+  llmjs2 -S
+  llmjs2 -S --config core/config.yaml
+  llmjs2 -S --port 8080 --host 0.0.0.0
+  llmjs2 run chain/workflow-example.json
+  llmjs2 run chain/workflow-example.json input="hello";reference="world"
+`);
+  }
+
+  loadConfig() {
+    if (!this.options.config) {
+      return this.createDefaultConfig();
+    }
+
+    const configPath = path.resolve(this.options.config);
+    if (!fs.existsSync(configPath)) {
+      throw new Error(`Configuration file not found: ${configPath}`);
+    }
+
+    const configContent = fs.readFileSync(configPath, 'utf8');
+    const config = yaml.parse(configContent);
+    return this.resolveEnvVars(config);
+  }
+
+  createDefaultConfig() {
+    return {
+      model_list: [
+        {
+          model_name: 'default',
+          llm_params: {
+            model: process.env.OLLAMA_DEFAULT_MODEL || 'ollama/minimax-m2.5:cloud',
+            api_key: process.env.OLLAMA_API_KEY,
+            api_base: process.env.OLLAMA_BASE_URL
+          }
+        }
+      ],
+      guardrails: [],
+      router_settings: {
+        routing_strategy: 'default',
+        allow_unsafe_guardrails: false
+      }
+    };
+  }
+
+  resolveEnvVars(obj) {
+    if (typeof obj === 'string') {
+      if (obj.startsWith('os.environ/')) {
+        const envVar = obj.replace('os.environ/', '');
+        return process.env[envVar] || obj;
+      }
+      return obj;
+    }
+
+    if (Array.isArray(obj)) {
+      return obj.map((item) => this.resolveEnvVars(item));
+    }
+
+    if (obj && typeof obj === 'object') {
+      const resolved = {};
+      for (const [key, value] of Object.entries(obj)) {
+        resolved[key] = this.resolveEnvVars(value);
+      }
+      return resolved;
+    }
+
+    return obj;
+  }
+
+  createRouter(config) {
+    const settings = config.router_settings || {};
+    const route = router(config.model_list || [], settings.routing_strategy || 'default', {
+      allowUnsafeGuardrails: Boolean(settings.allow_unsafe_guardrails)
+    });
+
+    if (Array.isArray(config.guardrails) && config.guardrails.length > 0) {
+      route.setGuardrails(config.guardrails);
+    }
+
+    return route;
+  }
+
+  async run() {
+    if (this.options.help) {
+      this.showHelp();
+      return;
+    }
+
+    if (this.options.mode === 'run') {
+      await this.runWorkflow();
+      return;
+    }
+
+    if (!this.options.start && this.args.length === 0) {
+      this.options.start = true;
+    }
+
+    if (!this.options.start) {
+      this.showHelp();
+      return;
+    }
+
+    try {
+      const config = this.loadConfig();
+      const route = this.createRouter(config);
+
+      console.log('Starting llmjs2 server...');
+      console.log(`Configuration: ${this.options.config || 'default'}`);
+      console.log(`Models: ${route.getAvailableModels().join(', ')}`);
+      console.log(`Strategy: ${(config.router_settings || {}).routing_strategy || 'default'}`);
+      console.log(`Guardrails: ${(config.guardrails || []).length}`);
+
+      app.use(route);
+      app.listen(this.options.port, this.options.host);
+    } catch (error) {
+      console.error('Failed to start server:', error.message);
+      process.exit(1);
+    }
+  }
+}
+
+function loadEnvFile() {
+  const envPath = path.join(process.cwd(), '.env');
+  if (!fs.existsSync(envPath)) {
+    return;
+  }
+
+  const envContent = fs.readFileSync(envPath, 'utf8');
+  const envVars = envContent.split('\n').filter((line) => line.trim() && !line.startsWith('#'));
+
+  envVars.forEach((line) => {
+    const [key, ...rest] = line.split('=');
+    const value = rest.join('=');
+    if (key && value) {
+      process.env[key.trim()] = value.trim();
+    }
+  });
+}
+
+loadEnvFile();
+const cli = new CLI();
+cli.run().catch((error) => {
+  console.error(error.message || String(error));
+  process.exit(1);
+});

package/core/docs/BASIC_USAGE.md

@@ -0,0 +1,62 @@
+# Basic Usage Guide
+
+This guide keeps llmjs2 usage minimal with only two completion patterns.
+
+## Pattern 1: Simple Prompt
+
+```javascript
+import { completion } from 'llmjs2';
+
+const response = await completion('Explain quantum physics in simple terms');
+console.log(response);
+```
+
+Behavior:
+- Reads configured providers from environment variables or constructor config.
+- Picks one available provider randomly for each request.
+- Uses that provider's default model.
+- Returns the assistant text directly.
+
+## Pattern 2: Full Object API
+
+```javascript
+import { completion } from 'llmjs2';
+
+const response = await completion({
+  model: 'ollama/minimax-m2.5:cloud',
+  host: 'https://ollama.com/api/chat', // optional - use env or default one
+  messages: [
+    { role: 'system', content: 'You are a helpful coding assistant.' },
+    { role: 'user', content: 'Write a function to reverse a string in JavaScript.' }
+  ],
+  apiKey: 'your-api-key', // optional - uses env vars if not provided
+  tools: [] // optional
+});
+
+console.log(response);
+```
+
+Notes:
+- `model` format must be `provider/model_name`.
+- `host` is optional and overrides provider base URL for this request.
+- `apiKey` is optional and overrides provider API key for this request.
+- `tools` is optional for function calling.
+
+## Environment Variables
+
+```bash
+# API Keys
+OPENAI_API_KEY=...
+OPEN_ROUTER_API_KEY=...
+OLLAMA_API_KEY=...
+
+# Default Models
+OPENAI_DEFAULT_MODEL=gpt-3.5-turbo
+OPEN_ROUTER_DEFAULT_MODEL=openrouter/free
+OLLAMA_DEFAULT_MODEL=minimax-m2.5:cloud
+
+# Optional Base URLs
+OPENAI_BASE_URL=https://api.openai.com/v1
+OPEN_ROUTER_BASE_URL=https://openrouter.ai/api/v1/chat/completions
+OLLAMA_BASE_URL=https://ollama.com/api/chat
+```

package/core/docs/CLI.md

@@ -0,0 +1,104 @@
+# CLI Guide
+
+Use the llmjs2 CLI to run the OpenAI-style API server or execute JSON workflows.
+
+## Install
+
+```bash
+npm install -g llmjs2
+```
+
+## Commands
+
+```bash
+llmjs2                     # Start server with defaults
+llmjs2 -S                  # Explicitly start server
+llmjs2 -S --config core/config.yaml
+llmjs2 -S --port 8080 --host 0.0.0.0
+llmjs2 run chain/workflow-example.json
+llmjs2 run chain/workflow-example.json input="hello";reference="world"
+llmjs2 --help
+```
+
+## Start Server
+
+The server listens on POST /v1/chat/completions and returns an OpenAI-style response body.
+
+```bash
+llmjs2 -S --config core/config.yaml --port 3000
+```
+
+### Options
+
+- -S: Start the API server.
+- -c, --config <file>: YAML config file with models, guardrails, and routing.
+- -p, --port <port>: Port to listen on (default: 3000).
+- -H, --host <host>: Host to bind to (default: localhost).
+- -h, --help: Show help.
+
+## Workflow Runner
+
+Run a workflow JSON file from the chain subsystem.
+
+```bash
+llmjs2 run chain/workflow-example.json
+```
+
+Pass workflow inputs as key=value pairs separated by semicolons:
+
+```bash
+llmjs2 run chain/workflow-example.json input="hello";reference="world"
+```
+
+## Configuration File
+
+Example config:
+
+```yaml
+model_list:
+  - model_name: default
+    llm_params:
+      model: ollama/minimax-m2.5:cloud
+      api_key: os.environ/OLLAMA_API_KEY
+      api_base: os.environ/OLLAMA_BASE_URL
+
+guardrails:
+  - name: request_logger
+    mode: pre_call
+    code: |
+      (processId, input) => {
+        console.log(`[${processId}] incoming messages=${input.messages.length}`);
+        return input;
+      }
+
+router_settings:
+  routing_strategy: default
+  allow_unsafe_guardrails: false
+```
+
+Notes:
+- String guardrails are disabled by default.
+- To allow string guardrails, set router_settings.allow_unsafe_guardrails=true or set LLMJS2_ALLOW_UNSAFE_GUARDRAILS=true.
+
+## Environment Variables
+
+```bash
+OPENAI_API_KEY=...
+OPEN_ROUTER_API_KEY=...
+OLLAMA_API_KEY=...
+
+OPENAI_DEFAULT_MODEL=gpt-4o-mini
+OPEN_ROUTER_DEFAULT_MODEL=openrouter/free
+OLLAMA_DEFAULT_MODEL=minimax-m2.5:cloud
+
+OPENAI_BASE_URL=https://api.openai.com/v1
+OPEN_ROUTER_BASE_URL=https://openrouter.ai/api/v1/chat/completions
+OLLAMA_BASE_URL=https://ollama.com/api/chat
+
+PORT=3000
+HOST=localhost
+```
+
+## .env Support
+
+If a .env file exists in the current directory, llmjs2 loads it automatically before running.

package/{docs → core/docs}/GET_STARTED.md

@@ -1,129 +1,129 @@
-# Getting Started with llmjs2
-
-Welcome to llmjs2! This guide will get you up and running in just 5 minutes.
-
-## Prerequisites
-
-Before you begin, make sure you have:
-
-- Node.js version 14.0.0 or higher
-- API keys for at least one LLM provider (Ollama or OpenRouter)
-
-## Installation
-
-### Option 1: Global Installation (Recommended)
-
-Install llmjs2 globally to use it from anywhere:
-
-```bash
-npm install -g llmjs2
-```
-
-### Option 2: Local Installation
-
-Install in your project directory:
-
-```bash
-npm install llmjs2
-```
-
-## Quick Setup
-
-### Step 1: Set API Keys
-
-Set your API keys as environment variables:
-
-```bash
-# For Ollama (get your key from https://ollama.com)
-export OLLAMA_API_KEY=your_ollama_api_key_here
-
-# For OpenRouter (get your key from https://openrouter.ai)
-export OPEN_ROUTER_API_KEY=your_openrouter_api_key_here
-```
-
-### Step 2: Your First Completion
-
-Create a simple test script:
-
-```javascript
-// hello-world.js
-import { completion } from 'llmjs2';
-
-async function helloWorld() {
-  try {
-    const response = await completion('Hello! Introduce yourself in one sentence.');
-    console.log('Response:', response);
-  } catch (error) {
-    console.error('Error:', error.message);
-  }
-}
-
-helloWorld();
-```
-
-Run it:
-
-```bash
-node hello-world.js
-```
-
-**Expected Output:**
-
-```
-Response: Hello! I'm an AI assistant powered by llmjs2, designed to help with various tasks and provide intelligent responses.
-```
-
-### Step 3: Test Different Models
-
-Try using specific models:
-
-```javascript
-// test-models.js
-import { completion } from 'llmjs2';
-
-async function testModels() {
-  try {
-    // Test Ollama
-    if (process.env.OLLAMA_API_KEY) {
-      const ollamaResponse = await completion('ollama/minimax-m2.5:cloud', 'What is AI?');
-      console.log('Ollama:', ollamaResponse);
-    }
-
-    // Test OpenRouter
-    if (process.env.OPEN_ROUTER_API_KEY) {
-      const openrouterResponse = await completion('openrouter/openrouter/free', 'What is machine learning?');
-      console.log('OpenRouter:', openrouterResponse);
-    }
-  } catch (error) {
-    console.error('Error:', error.message);
-  }
-}
-
-testModels();
-```
-
-## What's Next?
-
-Now that you have llmjs2 working, you can:
-
-1. **[Learn Basic Usage](BASIC_USAGE.md)** - Explore different API patterns and configuration options
-2. **[Run as a Server](SERVER_MODE.md)** - Set up an OpenAI-compatible API server
-3. **[Use the CLI](CLI.md)** - Manage servers and configurations from the command line
-
-## Supported Providers
-
-llmjs2 supports multiple LLM providers:
-
-- **Ollama** - Connect to Ollama's cloud API
-- **OpenRouter** - Access various models through OpenRouter
-
-## Need Help?
-
-If you encounter any issues:
-
-1. Check that your API keys are valid and have credits
-2. Ensure you're using the correct model format: `provider/model_name`
-3. Try the examples in this guide first
-4. Check your internet connection
-
-For more detailed usage, see the other guides in this documentation.
+# Getting Started with llmjs2
+
+Welcome to llmjs2! This guide will get you up and running in just 5 minutes.
+
+## Prerequisites
+
+Before you begin, make sure you have:
+
+- Node.js version 14.0.0 or higher
+- API keys for at least one LLM provider (Ollama or OpenRouter)
+
+## Installation
+
+### Option 1: Global Installation (Recommended)
+
+Install llmjs2 globally to use it from anywhere:
+
+```bash
+npm install -g llmjs2
+```
+
+### Option 2: Local Installation
+
+Install in your project directory:
+
+```bash
+npm install llmjs2
+```
+
+## Quick Setup
+
+### Step 1: Set API Keys
+
+Set your API keys as environment variables:
+
+```bash
+# For Ollama (get your key from https://ollama.com)
+export OLLAMA_API_KEY=your_ollama_api_key_here
+
+# For OpenRouter (get your key from https://openrouter.ai)
+export OPEN_ROUTER_API_KEY=your_OPEN_ROUTER_API_KEY_here
+```
+
+### Step 2: Your First Completion
+
+Create a simple test script:
+
+```javascript
+// hello-world.js
+import { completion } from 'llmjs2';
+
+async function helloWorld() {
+  try {
+    const response = await completion('Hello! Introduce yourself in one sentence.');
+    console.log('Response:', response);
+  } catch (error) {
+    console.error('Error:', error.message);
+  }
+}
+
+helloWorld();
+```
+
+Run it:
+
+```bash
+node hello-world.js
+```
+
+**Expected Output:**
+
+```
+Response: Hello! I'm an AI assistant powered by llmjs2, designed to help with various tasks and provide intelligent responses.
+```
+
+### Step 3: Test Different Models
+
+Try using specific models:
+
+```javascript
+// test-models.js
+import { completion } from 'llmjs2';
+
+async function testModels() {
+  try {
+    // Test Ollama
+    if (process.env.OLLAMA_API_KEY) {
+      const ollamaResponse = await completion('ollama/minimax-m2.5:cloud', 'What is AI?');
+      console.log('Ollama:', ollamaResponse);
+    }
+
+    // Test OpenRouter
+    if (process.env.OPEN_ROUTER_API_KEY) {
+      const openrouterResponse = await completion('openrouter/openrouter/free', 'What is machine learning?');
+      console.log('OpenRouter:', openrouterResponse);
+    }
+  } catch (error) {
+    console.error('Error:', error.message);
+  }
+}
+
+testModels();
+```
+
+## What's Next?
+
+Now that you have llmjs2 working, you can:
+
+1. **[Learn Basic Usage](BASIC_USAGE.md)** - Explore different API patterns and configuration options
+2. **[Run as a Server](SERVER_MODE.md)** - Set up an OpenAI-compatible API server
+3. **[Use the CLI](CLI.md)** - Manage servers and configurations from the command line
+
+## Supported Providers
+
+llmjs2 supports multiple LLM providers:
+
+- **Ollama** - Connect to Ollama's cloud API
+- **OpenRouter** - Access various models through OpenRouter
+
+## Need Help?
+
+If you encounter any issues:
+
+1. Check that your API keys are valid and have credits
+2. Ensure you're using the correct model format: `provider/model_name`
+3. Try the examples in this guide first
+4. Check your internet connection
+
+For more detailed usage, see the other guides in this documentation.