llmjs2 1.3.9 → 1.6.1

package/core/index.js

@@ -0,0 +1,115 @@
+const OpenAIProvider = require('./providers/openai');
+const OllamaProvider = require('./providers/ollama');
+const OpenRouterProvider = require('./providers/openrouter');
+const { completion } = require('./completion');
+const { router } = require('./router');
+const { app } = require('./server');
+
+class LLMJS2 {
+  constructor(config = {}) {
+    this.defaultProvider = config.defaultProvider;
+    this.providers = {
+      openai: new OpenAIProvider(config.openai || {}),
+      ollama: new OllamaProvider(config.ollama || {}),
+      openrouter: new OpenRouterProvider(config.openrouter || {})
+    };
+  }
+
+  parseModel(modelString) {
+    if (!modelString || typeof modelString !== 'string') {
+      return { provider: null, model: null };
+    }
+
+    const firstSlashIndex = modelString.indexOf('/');
+    if (firstSlashIndex !== -1) {
+      return {
+        provider: modelString.substring(0, firstSlashIndex),
+        model: modelString.substring(firstSlashIndex + 1)
+      };
+    }
+
+    return { provider: null, model: modelString };
+  }
+
+  getAvailableProviders() {
+    const available = [];
+
+    const openaiKey = process.env.OPENAI_API_KEY || this.providers.openai.apiKey;
+    const ollamaKey = process.env.OLLAMA_API_KEY || this.providers.ollama.apiKey;
+    const openrouterKey = process.env.OPEN_ROUTER_API_KEY || this.providers.openrouter.apiKey;
+
+    if (openaiKey && typeof openaiKey === 'string' && openaiKey.trim() && !openaiKey.startsWith(':')) {
+      available.push('openai');
+    }
+    if (ollamaKey && typeof ollamaKey === 'string' && ollamaKey.trim() && !ollamaKey.startsWith(':')) {
+      available.push('ollama');
+    }
+    if (openrouterKey && typeof openrouterKey === 'string' && openrouterKey.trim() && !openrouterKey.startsWith(':')) {
+      available.push('openrouter');
+    }
+
+    return available;
+  }
+
+  getAutoProvider() {
+    const availableProviders = this.getAvailableProviders();
+    if (availableProviders.length === 0) {
+      throw new Error('No API keys found. Set OLLAMA_API_KEY, OPEN_ROUTER_API_KEY, or OPENAI_API_KEY environment variables.');
+    }
+
+    const randomIndex = Math.floor(Math.random() * availableProviders.length);
+    const providerName = availableProviders[randomIndex];
+    const provider = this.providers[providerName];
+
+    return {
+      provider,
+      model: provider.defaultModel
+    };
+  }
+
+  getProvider(modelString) {
+    const { provider: specifiedProvider, model } = this.parseModel(modelString);
+
+    if (specifiedProvider) {
+      const provider = this.providers[specifiedProvider];
+      if (!provider) {
+        throw new Error(`Unknown provider: ${specifiedProvider}`);
+      }
+      return { provider, model };
+    }
+
+    const availableProviders = this.getAvailableProviders();
+    if (availableProviders.length === 0) {
+      throw new Error('No API keys configured. Set OPENAI_API_KEY, OLLAMA_API_KEY, or OPEN_ROUTER_API_KEY environment variables.');
+    }
+
+    const providerName = this.defaultProvider && availableProviders.includes(this.defaultProvider)
+      ? this.defaultProvider
+      : availableProviders[0];
+    const provider = this.providers[providerName];
+
+    return {
+      provider,
+      model: model || provider.defaultModel
+    };
+  }
+
+  completion(input) {
+    return completion(input, {
+      defaultProvider: this.defaultProvider,
+      openai: { apiKey: this.providers.openai.apiKey, baseURL: this.providers.openai.baseURL, timeout: this.providers.openai.timeout },
+      ollama: { apiKey: this.providers.ollama.apiKey, baseURL: this.providers.ollama.baseURL, timeout: this.providers.ollama.timeout },
+      openrouter: { apiKey: this.providers.openrouter.apiKey, baseURL: this.providers.openrouter.baseURL, timeout: this.providers.openrouter.timeout }
+    });
+  }
+}
+
+module.exports = {
+  completion,
+  LLMJS2,
+  router,
+  app,
+  OpenAIProvider,
+  OllamaProvider,
+  OpenRouterProvider
+};

package/{providers → core/providers}/ollama.js

@@ -8,14 +8,18 @@ class OllamaProvider {
     this.timeout = config.timeout || 120000; // 2 minutes (LLMs can be slow)
   }
 
-  async makeRequest(data) {
-    if (!this.apiKey) {
+  async makeRequest(data, requestOptions = {}) {
+    const apiKey = requestOptions.apiKey || this.apiKey;
+    const baseURL = requestOptions.baseURL || this.baseURL;
+    const timeout = requestOptions.timeout || this.timeout;
+
+    if (!apiKey) {
       throw new Error('Ollama API key is required. Set OLLAMA_API_KEY environment variable or pass apiKey in config.');
     }
 
     const postData = JSON.stringify(data);
 
-    const parsedUrl = new URL(this.baseURL);
+    const parsedUrl = new URL(baseURL);
 
     const options = {
       hostname: parsedUrl.hostname,
@@ -24,7 +28,7 @@ class OllamaProvider {
       method: 'POST',
       headers: {
         'Content-Type': 'application/json',
-        'Authorization': `Bearer ${this.apiKey}`,
+        'Authorization': `Bearer ${apiKey}`,
         'Content-Length': Buffer.byteLength(postData)
       }
     };
@@ -56,7 +60,7 @@ class OllamaProvider {
         reject(new Error(`Ollama request failed: ${error.message}`));
       });
 
-      req.setTimeout(this.timeout, () => {
+      req.setTimeout(timeout, () => {
         req.destroy();
         reject(new Error('Ollama request timed out'));
       });
@@ -100,7 +104,11 @@ class OllamaProvider {
       });
     }
 
-    const response = await this.makeRequest(data);
+    const response = await this.makeRequest(data, {
+      apiKey: options.apiKey,
+      baseURL: options.baseURL,
+      timeout: options.timeout
+    });
 
     return {
       content: response.message?.content || '',

package/{providers → core/providers}/openai.js

@@ -8,12 +8,16 @@ class OpenAIProvider {
     this.timeout = config.timeout || 60000; // 60 seconds
   }
 
-  async makeRequest(endpoint, data) {
-    if (!this.apiKey) {
+  async makeRequest(endpoint, data, requestOptions = {}) {
+    const apiKey = requestOptions.apiKey || this.apiKey;
+    const baseURL = requestOptions.baseURL || this.baseURL;
+    const timeout = requestOptions.timeout || this.timeout;
+
+    if (!apiKey) {
       throw new Error('OpenAI API key is required. Set OPENAI_API_KEY environment variable or pass apiKey in config.');
     }
 
-    const requestUrl = `${this.baseURL}${endpoint}`;
+    const requestUrl = `${baseURL}${endpoint}`;
     const postData = JSON.stringify(data);
 
     const parsedUrl = new URL(requestUrl);
@@ -25,7 +29,7 @@ class OpenAIProvider {
       method: 'POST',
       headers: {
         'Content-Type': 'application/json',
-        'Authorization': `Bearer ${this.apiKey}`,
+        'Authorization': `Bearer ${apiKey}`,
         'Content-Length': Buffer.byteLength(postData)
       }
     };
@@ -57,7 +61,7 @@ class OpenAIProvider {
         reject(new Error(`OpenAI request failed: ${error.message}`));
       });
 
-      req.setTimeout(this.timeout, () => {
+      req.setTimeout(timeout, () => {
         req.destroy();
         reject(new Error('OpenAI request timed out'));
       });
@@ -88,7 +92,11 @@ class OpenAIProvider {
       }
     });
 
-    const response = await this.makeRequest('/chat/completions', data);
+    const response = await this.makeRequest('/chat/completions', data, {
+      apiKey: options.apiKey,
+      baseURL: options.baseURL,
+      timeout: options.timeout
+    });
 
     return {
       content: response.choices[0]?.message?.content || '',

package/{providers → core/providers}/openrouter.js

@@ -9,14 +9,18 @@ class OpenRouterProvider {
     this.config = config; // Store entire config for additional properties like referer, title
   }
 
-  async makeRequest(data) {
-    if (!this.apiKey) {
+  async makeRequest(data, requestOptions = {}) {
+    const apiKey = requestOptions.apiKey || this.apiKey;
+    const baseURL = requestOptions.baseURL || this.baseURL;
+    const timeout = requestOptions.timeout || this.timeout;
+
+    if (!apiKey) {
       throw new Error('OpenRouter API key is required. Set OPEN_ROUTER_API_KEY environment variable or pass apiKey in config.');
     }
 
     const postData = JSON.stringify(data);
 
-    const parsedUrl = new URL(this.baseURL);
+    const parsedUrl = new URL(baseURL);
 
     const options = {
       hostname: parsedUrl.hostname,
@@ -25,7 +29,7 @@ class OpenRouterProvider {
       method: 'POST',
       headers: {
         'Content-Type': 'application/json',
-        'Authorization': `Bearer ${this.apiKey}`,
+        'Authorization': `Bearer ${apiKey}`,
         'Content-Length': Buffer.byteLength(postData),
         'HTTP-Referer': this.config.referer || process.env.OPEN_ROUTER_REFERER || '',
         'X-Title': this.config.title || process.env.OPEN_ROUTER_TITLE || ''
@@ -63,7 +67,7 @@ class OpenRouterProvider {
         reject(new Error(`OpenRouter request failed: ${error.message}`));
       });
 
-      req.setTimeout(this.timeout, () => {
+      req.setTimeout(timeout, () => {
         req.destroy();
         reject(new Error('OpenRouter request timed out'));
       });
@@ -97,7 +101,11 @@ class OpenRouterProvider {
       }
     });
 
-    const response = await this.makeRequest(data);
+    const response = await this.makeRequest(data, {
+      apiKey: options.apiKey,
+      baseURL: options.baseURL,
+      timeout: options.timeout
+    });
 
     return {
       content: response.choices[0]?.message?.content || '',

package/core/router.js

@@ -0,0 +1,252 @@
+const logger = require('./logger');
+const { completion } = require('./completion');
+
+function normalizeStrategy(strategy) {
+  const supportedStrategies = new Set(['default', 'random', 'sequential']);
+  return supportedStrategies.has(strategy) ? strategy : 'default';
+}
+
+function resolveApiKey(apiKey) {
+  if (typeof apiKey === 'string' && apiKey.startsWith('os.environ/')) {
+    const envVar = apiKey.replace('os.environ/', '');
+    return process.env[envVar] || apiKey;
+  }
+  return apiKey;
+}
+
+function normalizeModelList(modelList) {
+  if (!Array.isArray(modelList) || modelList.length === 0) {
+    throw new Error('Router requires a non-empty model list');
+  }
+
+  return modelList.map((model, index) => {
+    if (!model || typeof model !== 'object') {
+      throw new Error(`Model at index ${index} must be an object`);
+    }
+    if (!model.model_name) {
+      throw new Error(`Model at index ${index} is missing model_name`);
+    }
+    if (!model.llm_params || typeof model.llm_params !== 'object') {
+      throw new Error(`Model '${model.model_name}' is missing llm_params`);
+    }
+    if (!model.llm_params.model) {
+      throw new Error(`Model '${model.model_name}' is missing llm_params.model`);
+    }
+
+    return {
+      model_name: model.model_name,
+      llm_params: {
+        model: model.llm_params.model,
+        api_key: resolveApiKey(model.llm_params.api_key),
+        api_base: model.llm_params.api_base
+      }
+    };
+  });
+}
+
+function buildModelsByName(modelList) {
+  return modelList.reduce((accumulator, model) => {
+    if (!accumulator[model.model_name]) {
+      accumulator[model.model_name] = [];
+    }
+    accumulator[model.model_name].push(model);
+    return accumulator;
+  }, {});
+}
+
+function router(modelList, strategy = 'default', options = {}) {
+  const normalizedModelList = normalizeModelList(modelList);
+  const normalizedStrategy = normalizeStrategy(strategy);
+  const allowUnsafeGuardrails = Boolean(options.allowUnsafeGuardrails) || process.env.LLMJS2_ALLOW_UNSAFE_GUARDRAILS === 'true';
+  const guardrails = [];
+  const modelsByName = buildModelsByName(normalizedModelList);
+  let sequentialIndex = 0;
+
+  function getRandomItem(items) {
+    const randomIndex = Math.floor(Math.random() * items.length);
+    return items[randomIndex];
+  }
+
+  function getNextSequentialModel() {
+    const selectedModel = normalizedModelList[sequentialIndex];
+    sequentialIndex = (sequentialIndex + 1) % normalizedModelList.length;
+    return selectedModel;
+  }
+
+  function ensureModelsAvailable() {
+    if (normalizedModelList.length === 0) {
+      throw new Error('Router has no configured models');
+    }
+  }
+
+  function selectModel(modelName) {
+    ensureModelsAvailable();
+
+    if (!modelName) {
+      return autoSelectModel();
+    }
+
+    const availableModels = modelsByName[modelName];
+    if (!availableModels || availableModels.length === 0) {
+      throw new Error(`Model '${modelName}' not found in router configuration`);
+    }
+
+    if (availableModels.length === 1) {
+      return availableModels[0];
+    }
+
+    return getRandomItem(availableModels);
+  }
+
+  function autoSelectModel() {
+    ensureModelsAvailable();
+
+    switch (normalizedStrategy) {
+      case 'random':
+        return getRandomItem(normalizedModelList);
+      case 'sequential':
+      case 'default':
+      default:
+        return getNextSequentialModel();
+    }
+  }
+
+  function normalizeCompletionInput(input = {}) {
+    return {
+      modelName: input.model,
+      messages: input.messages || [],
+      stop: input.stop,
+      tools: input.tools,
+      toolChoice: input.tool_choice ?? input.toolChoice,
+      timeout: input.timeout,
+      apiKey: input.apiKey,
+      host: input.host || input.baseURL || input.baseUrl,
+      final: input.final ?? true
+    };
+  }
+
+  async function executeGuardrail(guardrail, processId, data) {
+    if (typeof guardrail.code === 'string') {
+      if (!allowUnsafeGuardrails) {
+        throw new Error(
+          `Guardrail '${guardrail.name}' uses string code, but unsafe execution is disabled. Set router option allowUnsafeGuardrails=true or LLMJS2_ALLOW_UNSAFE_GUARDRAILS=true to enable.`
+        );
+      }
+
+      const func = new Function('processId', 'data', `return (${guardrail.code})(processId, data)`);
+      return await func(processId, data);
+    }
+
+    if (typeof guardrail.code === 'function') {
+      return await guardrail.code(processId, data);
+    }
+
+    throw new Error(`Invalid guardrail code for '${guardrail.name}'`);
+  }
+
+  async function applyGuardrails(mode, processId, data) {
+    const modeLabel = mode === 'pre_call' ? 'Pre-call' : 'Post-call';
+    let currentValue = data;
+
+    for (const guardrail of guardrails) {
+      if (guardrail.mode !== mode) {
+        continue;
+      }
+
+      try {
+        const processed = await executeGuardrail(guardrail, processId, currentValue);
+        if (processed === null || processed === undefined) {
+          throw new Error(`Guardrail '${guardrail.name}' returned null/undefined`);
+        }
+        currentValue = processed;
+      } catch (error) {
+        throw new Error(`${modeLabel} guardrail '${guardrail.name}' failed: ${error.message}`);
+      }
+    }
+
+    return currentValue;
+  }
+
+  async function completionWithModel(modelConfig, input) {
+    return completion({
+      ...input,
+      model: modelConfig.llm_params.model,
+      apiKey: input.apiKey || modelConfig.llm_params.api_key,
+      host: input.host || modelConfig.llm_params.api_base,
+      final: false
+    });
+  }
+
+  function generateProcessId() {
+    return `req_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+  }
+
+  return {
+    setGuardrails(nextGuardrails) {
+      guardrails.length = 0;
+      if (Array.isArray(nextGuardrails)) {
+        guardrails.push(...nextGuardrails);
+      }
+    },
+
+    addGuardrail(guardrail) {
+      guardrails.push(guardrail);
+    },
+
+    getAvailableModels() {
+      return Object.keys(modelsByName);
+    },
+
+    getModelStats() {
+      const stats = {};
+      Object.keys(modelsByName).forEach((modelName) => {
+        stats[modelName] = modelsByName[modelName].length;
+      });
+      return stats;
+    },
+
+    selectModel,
+
+    autoSelectModel,
+
+    executeGuardrail,
+
+    async completion(input = {}) {
+      const processId = generateProcessId();
+
+      try {
+        const normalizedInput = normalizeCompletionInput(input);
+        const selectedModel = selectModel(normalizedInput.modelName);
+
+        logger.debug('Selected model', {
+          processId,
+          model: selectedModel.llm_params.model,
+          modelName: selectedModel.model_name
+        });
+
+        const { modelName, ...completionInput } = normalizedInput;
+        const preparedInput = {
+          model: selectedModel.llm_params.model,
+          ...completionInput
+        };
+
+        const processedInput = await applyGuardrails('pre_call', processId, preparedInput);
+        const result = await completionWithModel(selectedModel, processedInput);
+        const finalResult = await applyGuardrails('post_call', processId, result);
+
+        return {
+          result: finalResult,
+          selectedModel: selectedModel.llm_params.model,
+          selectedModelName: selectedModel.model_name
+        };
+      } catch (error) {
+        logger.error('Router error', { processId, error: error.message });
+        throw error;
+      }
+    }
+  };
+}
+
+module.exports = {
+  router
+};

package/{server.js → core/server.js}

@@ -1,5 +1,6 @@
 const http = require('http');
 const url = require('url');
+const logger = require('./logger');
 
 class Server {
   constructor(options = {}) {
@@ -101,8 +102,8 @@ class Server {
     }
 
     for (const message of body.messages) {
-      if (!message.role || !['system', 'user', 'assistant'].includes(message.role)) {
-        return { valid: false, error: 'Each message must have a valid role (system, user, or assistant)' };
+      if (!message.role || !['system', 'user', 'assistant', 'tool'].includes(message.role)) {
+        return { valid: false, error: 'Each message must have a valid role (system, user, assistant, or tool)' };
       }
       if (typeof message.content !== 'string') {
         return { valid: false, error: 'Each message must have string content' };
@@ -123,12 +124,12 @@ class Server {
     });
 
     const routerResponse = await this.router.completion(body);
-    const { result, selectedModel, selectedModelName } = routerResponse;
+    const { result, selectedModel } = routerResponse;
 
-    // Return format with metadata plus message array
     const assistantMessage = {
       role: 'assistant',
-      content: typeof result === 'string' ? result : result.content || ''
+      content: typeof result === 'string' ? result : result.content || '',
+      tool_calls: typeof result === 'object' ? result.tool_calls : undefined
     };
 
     // Include original messages plus assistant response
@@ -139,6 +140,15 @@ class Server {
       object: 'chat.completion',
       created: Math.floor(Date.now() / 1000),
       model: body.model || selectedModel, // Use selected model if auto-selected
+      choices: [
+        {
+          index: 0,
+          message: assistantMessage,
+          finish_reason: typeof result === 'object' ? (result.finishReason || 'stop') : 'stop'
+        }
+      ],
+      usage: typeof result === 'object' ? result.usage : undefined,
+      // Kept for backward compatibility with older llmjs2 clients
       messages: messages
     };
   }

package/package.json

@@ -1,48 +1,64 @@
 {
   "name": "llmjs2",
-  "version": "1.3.9",
-  "description": "A unified Node.js library for connecting to multiple LLM providers: OpenAI, Ollama, and OpenRouter",
-  "main": "index.js",
-  "type": "commonjs",
+  "version": "1.6.1",
+  "description": "A unified Node.js library for connecting to multiple Large Language Model (LLM) providers: OpenAI, Ollama, and OpenRouter.",
+  "main": "core/index.js",
+  "bin": {
+    "llmjs2": "core/cli.js"
+  },
   "scripts": {
-    "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",
+    "test": "node core/test.js",
+    "test:completion": "node core/test-completion.js",
+    "start": "node core/cli.js",
     "lint": "echo 'No linting configured'",
-    "typecheck": "echo 'No TypeScript configured'"
+    "typecheck": "echo 'No type checking configured'"
   },
   "keywords": [
     "llm",
-    "llmjs",
-    "llmjs2",
+    "ai",
     "openai",
     "ollama",
     "openrouter",
-    "ai",
     "chatgpt",
-    "completions",
+    "gpt",
+    "llmjs2",
+    "llmjs",
+    "language-model",
     "unified-api"
   ],
-  "author": "Your Name",
+  "author": "",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/littlellmjs/llmjs2.git"
+    "url": ""
   },
-  "bugs": {
-    "url": "https://github.com/littlellmjs/llmjs2/issues"
+  "dependencies": {
+    "yaml": "^2.0.0"
   },
-  "homepage": "https://github.com/littlellmjs/llmjs2#readme",
   "engines": {
     "node": ">=14.0.0"
   },
-  "dependencies": {
-    "yaml": "^2.3.4"
-  },
-  "bin": {
-    "llmjs2": "./cli.js"
-  }
-}
+  "files": [
+    "chain/index.js",
+    "chain/lib/",
+    "chain/docs/",
+    "chain/examples.js",
+    "chain/agent-step-example.js",
+    "chain/simple-agent-step-example.js",
+    "chain/workflow-example-usage.js",
+    "chain/workflow-example.json",
+    "chain/AGENT_STEP_README.md",
+    "chain/WORKFLOW_README.md",
+    "chain/README.md",
+    "core/cli.js",
+    "core/config.yaml",
+    "core/index.js",
+    "core/logger.js",
+    "core/router.js",
+    "core/server.js",
+    "core/providers/",
+    "core/docs/",
+    "core/README.md",
+    "README.md"
+  ]
+}