llmjs2 1.3.9 → 1.6.1

package/README.md

@@ -1,476 +1,31 @@
-# llmjs2
-
-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
-- **Intelligent Router**: Load balancing and multiple routing strategies
-- **Guardrails System**: Content filtering, logging, rate limiting, and custom processing
-- **OpenAI-Compatible Server**: Drop-in replacement for OpenAI API clients
-- **CLI Interface**: Command-line server management with configuration files
-- **Enterprise Security**: Input validation, error sanitization, and safe defaults
-- **Zero External Dependencies**: Pure Node.js implementation
-
-## Features
-
-- **Unified API**: Single interface for OpenAI, Ollama, and OpenRouter
-- **Auto-detection**: Automatically chooses available providers based on API keys
-- **Enterprise-grade**: Robust error handling, input validation, and security measures
-- **Zero dependencies**: Uses only Node.js built-in modules
-- **TypeScript-free**: Pure JavaScript, no compilation required
-- **Production-ready**: Comprehensive testing and security auditing
-
-## Installation
-
-```bash
-npm install llmjs2
-```
-
-Or for global CLI usage:
-
-```bash
-npm install -g llmjs2
-```
-
-## Quick Test
-
-Try the sample configuration:
-
-```bash
-# Start server with sample config
-llmjs2 --config config.yaml --port 3001
-
-# Test the API
-curl -X POST http://localhost:3001/v1/chat/completions \
-  -H "Content-Type: application/json" \
-  -d '{"messages":[{"role":"user","content":"Hello!"}]}'
-
-# Response format:
-# {
-#   "id": "chatcmpl-123456",
-#   "object": "chat.completion",
-#   "created": 1640995200,
-#   "model": "ollama/minimax-m2.5:cloud",
-#   "messages": [
-#     {"role": "user", "content": "Hello!"},
-#     {"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
-
-```javascript
-import { completion } from 'llmjs2';
-
-// Set API keys
-process.env.OPENAI_API_KEY = 'your-openai-key';
-process.env.OLLAMA_API_KEY = 'your-ollama-key';
-process.env.OPEN_ROUTER_API_KEY = 'your-openrouter-key';
-
-// Simple completion
-const response = await completion('Hello, how are you?');
-console.log(response);
-```
-
-## API Keys Setup
-
-Set your API keys as environment variables:
-
-```bash
-export OPENAI_API_KEY=your_openai_api_key
-export OLLAMA_API_KEY=your_ollama_api_key
-export OPEN_ROUTER_API_KEY=your_openrouter_api_key
-```
-
-## Usage Patterns
-
-### 1. Simple API (Auto-detection)
-
-```javascript
-import { completion } from 'llmjs2';
-
-// Auto-selects provider based on available API keys
-// Cycles through: Ollama → OpenRouter → OpenAI → Ollama...
-const response = await completion('Explain quantum physics simply');
-```
-
-**Auto-Selection Logic:**
-- Checks for `OLLAMA_API_KEY`, `OPEN_ROUTER_API_KEY`, `OPENAI_API_KEY`
-- Cycles sequentially through available providers
-- Uses default model for each provider
-- Falls back gracefully if keys are missing
-
-### 2. Provider-Specific Model
-
-```javascript
-// OpenAI
-const openaiResponse = await completion('openai/gpt-4', 'Write a haiku about coding');
-
-// Ollama
-const ollamaResponse = await completion('ollama/minimax-m2.5:cloud', 'What is AI?');
-
-// OpenRouter
-const openrouterResponse = await completion('openrouter/openrouter/free', 'Tell me a joke');
-```
-
-### 3. Advanced Object API
-
-```javascript
-const response = await completion({
-  model: 'openai/gpt-3.5-turbo',
-  messages: [
-    { role: 'system', content: 'You are a helpful assistant.' },
-    { role: 'user', content: 'What is the capital of France?' }
-  ],
-  temperature: 0.7,
-  maxTokens: 100
-});
-```
-
-## Configuration
-
-### Default Models
-
-Set default models for each provider:
-
-```bash
-export OPENAI_DEFAULT_MODEL=gpt-4
-export OLLAMA_DEFAULT_MODEL=minimax-m2.5:cloud
-export OPEN_ROUTER_DEFAULT_MODEL=openrouter/free
-```
-
-### Base URLs
-
-Customize API endpoints:
-
-```bash
-export OPENAI_BASE_URL=https://api.openai.com/v1
-export OLLAMA_BASE_URL=https://ollama.com/api/chat
-export OPEN_ROUTER_BASE_URL=https://openrouter.ai/api/v1/chat/completions
-```
-
-## Error Handling
-
-```javascript
-import { completion } from 'llmjs2';
-
-try {
-  const response = await completion('Tell me a joke');
-  console.log(response);
-} catch (error) {
-  console.error('Error:', error.message);
-}
-```
-
-## Conversations
-
-```javascript
-import { completion } from 'llmjs2';
-
-const messages = [
-  { role: 'system', content: 'You are a helpful coding assistant.' },
-  { role: 'user', content: 'How do I reverse a string in JavaScript?' }
-];
-
-let response = await completion({ model: 'openai/gpt-4', messages });
-console.log('Assistant:', response);
-
-// Continue conversation
-messages.push({ role: 'assistant', content: response });
-messages.push({ role: 'user', content: 'Can you show me with an example?' });
-
-response = await completion({ model: 'openai/gpt-4', messages });
-console.log('Assistant:', response);
-```
-
-## Function Calling (Tools)
-
-```javascript
-import { completion } from 'llmjs2';
-
-const weatherTool = {
-  type: 'function',
-  function: {
-    name: 'get_weather',
-    description: 'Get current weather for a location',
-    parameters: {
-      type: 'object',
-      properties: {
-        location: { type: 'string', description: 'City name' }
-      },
-      required: ['location']
-    }
-  }
-};
-
-const response = await completion({
-  model: 'openai/gpt-4',
-  messages: [{ role: 'user', content: 'What is the weather in Paris?' }],
-  tools: [weatherTool]
-});
-
-if (response.tool_calls) {
-  console.log('Tool calls:', response.tool_calls);
-}
-```
-
-## Router System
-
-Intelligent model routing with load balancing and multiple strategies:
-
-```javascript
-import { router } from 'llmjs2';
-
-const modelList = [
-  {
-    model_name: 'gpt-3.5-turbo',
-    llm_params: {
-      model: 'ollama/chatgpt-v-2',
-      api_key: process.env.OLLAMA_API_KEY
-    }
-  },
-  {
-    model_name: 'gpt-3.5-turbo',
-    llm_params: {
-      model: 'openai/gpt-3.5-turbo',
-      api_key: process.env.OPENAI_API_KEY
-    }
-  }
-];
-
-// Load balancing across models with same name
-const route = router(modelList, 'random');
-const response = await route.completion({
-  model: 'gpt-3.5-turbo',
-  messages: [{ role: 'user', content: 'Hello!' }]
-});
-
-// Auto-routing with different strategies
-const randomRouter = router(modelList, 'random');
-const sequentialRouter = router(modelList, 'sequential');
-```
-
-**Routing Strategies:**
-- `default`: Load balance across models with same name
-- `random`: Randomly select from all models
-- `sequential`: Cycle through models in order
-
-## Guardrails System
-
-Add custom logic before and after LLM calls for content filtering, logging, and processing:
-
-```javascript
-import { router } from 'llmjs2';
-
-const route = router(modelList);
-
-route.setGuardrails([
-  {
-    name: 'content_filter',
-    mode: 'pre_call',
-    code: (processId, input) => {
-      // Filter inappropriate content
-      const filteredMessages = input.messages.map(msg => ({
-        ...msg,
-        content: msg.content.replace(/badword/gi, '****')
-      }));
-      return { ...input, messages: filteredMessages };
-    }
-  },
-  {
-    name: 'response_logger',
-    mode: 'post_call',
-    code: (processId, result) => {
-      console.log(`[${processId}] Response:`, result);
-      return result;
-    }
-  }
-]);
-```
-
-## Server Mode
-
-Run an API server that returns responses with metadata and message arrays:
-
-```javascript
-import { router, app } from 'llmjs2';
-
-const route = router(modelList);
-app.use(route);
-app.listen(3000);
-```
-
-Or use the CLI:
-
-```bash
-llmjs2 --config config.yaml --port 3000
-```
-
-## CLI Interface
-
-Manage servers from the command line:
-
-```bash
-# Start server with defaults
-llmjs2
-
-# Use configuration file
-llmjs2 --config config.yaml
-
-# Custom port and host
-llmjs2 --port 8080 --host 0.0.0.0
-
-# Get help
-llmjs2 --help
-```
-
-## Configuration Files
-
-Use YAML for advanced configuration:
-
-```yaml
-model_list:
-  - model_name: premium
-    llm_params:
-      model: openrouter/openai/gpt-4
-      api_key: os.environ/OPEN_ROUTER_API_KEY
-
-  - model_name: standard
-    llm_params:
-      model: ollama/minimax-m2.5:cloud
-      api_key: os.environ/OLLAMA_API_KEY
-
-guardrails:
-  - name: content_filter
-    mode: pre_call
-    code: |
-      (processId, input) => {
-        // Content filtering logic
-        return input;
-      }
-
-router_settings:
-  routing_strategy: random
-```
-
-**Note**: Model names in the configuration use the format `[provider]/[actual-model-name]` (e.g., `openai/gpt-4`, `ollama/minimax-m2.5:cloud`). The `[provider]/` prefix is used for routing and is automatically stripped when sending requests to LLM providers.
-
-## Security Features
-
-- **No API key logging**: Sensitive information is never logged
-- **Input validation**: All inputs are validated and sanitized
-- **Error sanitization**: Error messages don't leak sensitive data
-- **Timeout protection**: Requests timeout to prevent hanging
-- **HTTPS only**: All communications use HTTPS
-
-## Testing
-
-Run the test suite:
-
-```bash
-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
-
-## Contributing
-
-Contributions welcome! Please ensure all tests pass and add tests for new features.
-
-## Support
-
-For issues and questions, please create an issue on GitHub.
+# llmjs2
+
+llmjs2 is a unified Node.js library for OpenAI, Ollama, and OpenRouter with routing, guardrails, and an OpenAI-style server mode.
+
+## Quick Links
+
+- Core README: core/README.md
+- CLI Guide: core/docs/CLI.md
+- Server Mode: core/docs/SERVER_MODE.md
+- Router Guide: core/docs/ROUTER_GUIDE.md
+
+## Install
+
+```bash
+npm install llmjs2
+```
+
+## Basic Usage
+
+```javascript
+const { completion } = require('llmjs2');
+
+(async () => {
+  const result = await completion({
+    model: 'openai/gpt-4',
+    messages: [{ role: 'user', content: 'Say hello in one sentence.' }]
+  });
+
+  console.log(result);
+})();
+```

package/chain/AGENT_STEP_README.md

@@ -0,0 +1,102 @@
+# AgentStep Examples
+
+This directory contains example programs demonstrating how to use AgentStep in llmjs-chain workflows.
+
+## Files
+
+- **`simple-agent-step-example.js`** - Complete example with mock agents (fast execution)
+- **`agent-step-example.js`** - Advanced example with real AI agents (slower but comprehensive)
+
+## Running the Examples
+
+### Simple Example (Recommended for Testing)
+```bash
+node simple-agent-step-example.js
+```
+
+**Features Demonstrated:**
+- ✅ Function-based input/output mapping
+- ✅ Template-based input mapping (`{{variable}}` syntax)
+- ✅ Default mapping behavior
+- ✅ Sequential workflow execution
+- ✅ Parallel agent execution
+- ✅ Context passing between steps
+- ✅ Mock agents for fast testing
+
+### Advanced Example (Real AI)
+```bash
+node agent-step-example.js
+```
+
+**Features Demonstrated:**
+- ✅ Real AI agent integration
+- ✅ Multi-agent content creation pipeline
+- ✅ Complex input/output mapping
+- ✅ Tool usage within agents
+- ✅ Error handling
+
+## Key AgentStep Features
+
+### Input Mapping Options
+
+```javascript
+// 1. Function mapper - full control
+inputMapper: (context) => `Process: ${JSON.stringify(context.data)}`
+
+// 2. Template mapper - simple interpolation
+inputMapper: 'Analyze {{data}} from step {{stepName}}'
+
+// 3. Default mapper - automatic context conversion
+// (no inputMapper specified)
+```
+
+### Output Mapping Options
+
+```javascript
+// Custom transformation
+outputMapper: (agentResponse, context) => ({
+  result: agentResponse,
+  processedAt: new Date(),
+  confidence: 0.95
+})
+
+// Default mapping returns: { response, agent, timestamp }
+```
+
+### Workflow Integration
+
+```javascript
+const workflow = new Graph({ name: 'ai-workflow' })
+  .step(agentStep1, agentStep2, regularStep)
+  .edge(agentStep1, agentStep2)
+  .edge(agentStep2, regularStep)
+  .compile();
+
+const result = await workflow.run(initialContext);
+```
+
+## Use Cases
+
+- **Content Creation**: Multi-agent writing and editing pipelines
+- **Data Analysis**: Specialized agents for different analysis stages
+- **Quality Assurance**: AI-powered validation and testing
+- **Decision Making**: Agent-based routing and recommendations
+- **Integration Workflows**: Mix of AI and traditional processing steps
+
+## Performance Notes
+
+- **Mock Agents**: Use for development and testing (fast)
+- **Real Agents**: Production use with proper rate limiting
+- **Parallel Execution**: Multiple agents can run simultaneously
+- **Context Size**: Large contexts may impact performance
+
+## Integration with Existing Workflows
+
+AgentStep is fully compatible with:
+- Regular Step classes
+- Graph.load() JSON workflows
+- Conditional edges
+- Parallel execution
+- Memory systems
+
+Start with the simple example to understand the API, then move to real agents for production use!