llmjs2 1.0.8 → 1.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 littlellmjs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,129 +1,357 @@
 # llmjs2
 
-`llmjs2` is a lightweight llm wrapper for building simple / personal AI applications.
+A lightweight llm Node.js library for building simple / personal AI applications
 
-## Features
+## Supported Providers
 
-- Zero runtime dependencies
-- ESM-only
-- OpenAI-compatible `messages` schema
-- Automatic provider routing via `provider/model-name`
-- Default fallback to `https://api.ollama.com`
-- Clear connection and model errors
+- **Ollama** - Connect to Ollama's cloud API
+- **OpenRouter** - Access multiple LLM models through OpenRouter
 
 ## Installation
 
-No dependencies are required. Install or link the package as usual:
-
 ```bash
 npm install llmjs2
 ```
 
 ## Usage
 
-```js
+llmjs2 supports three calling conventions:
+
+### Simple API (Auto-Detection)
+
+```javascript
 import { completion } from 'llmjs2';
 
-const response = await completion('ollama/llama3', 'Write a short poem about Node.js.');
-console.log(response);
+// Just provide a prompt - the library handles the rest
+const result = await completion('Explain the use of llmjs2');
+
+// Or provide a model and prompt
+const result = await completion('ollama/minimax-m2.5:cloud', 'Explain the use of llmjs2');
 ```
 
-Or with a full options object:
+**How it works:**
+- Looks for `OLLAMA_API_KEY` and `OPEN_ROUTER_API_KEY` environment variables
+- If only one is set, uses that provider
+- If both are set, randomly chooses one
+- Uses `OLLAMA_DEFAULT_MODEL` or defaults to `minimax-m2.5:cloud` for Ollama
+- Uses `OPEN_ROUTER_DEFAULT_MODEL` or defaults to `openrouter/free` for OpenRouter
+- If a model is provided, uses that model instead of the default
+
+### Function-Based API
 
-```js
+```javascript
 import { completion } from 'llmjs2';
 
-const response = await completion({
-  model: 'ollama/llama3',
-  messages: [
-    { role: 'system', content: 'You are a helpful assistant.' },
-    { role: 'user', content: 'Summarize the benefits of zero dependencies.' },
-  ],
-});
+// Using Ollama
+const resultOllama = await completion('ollama/minimax-m2.5:cloud', 'Explain the use of llmjs2', 'your-api-key');
 
-console.log(response);
+// Using OpenRouter
+const resultOR = await completion('openrouter/openrouter/free', 'Explain the use of llmjs2', 'your-api-key');
 ```
 
-## generate()
-
-The library also exposes `generate()` for prompt-based flows with optional images, references, system instructions, and tools.
+### Object-Based API
 
-```js
-import { generate } from 'llmjs2';
+```javascript
+import { completion } from 'llmjs2';
 
-const response = await generate({
-  model: 'ollama/llama3',
-  userPrompt: 'Describe this picture.',
-  images: ['https://example.com/image.png'],
-  references: ['Some reference text about the image.'],
-  systemPrompt: 'You are a visual assistant.',
-  tools: [
-    {
-      name: 'get_weather',
-      description: 'Get the current weather for a location',
-      parameters: {
-        location: { type: 'string', required: true, description: 'City and state' },
-      },
-      handler: ({ location }) => `Weather in ${location}: Sunny`,
-    },
+// Using Ollama with system message
+const resultOllama = await completion({
+  model: 'ollama/minimax-m2.5:cloud',
+  messages: [
+    { role: 'system', content: 'You are a helpful AI assistant.' },
+    { role: 'user', content: 'Explain the use of llmjs2.' }
   ],
+  apiKey: 'your-api-key' // optional
 });
 
-console.log(response);
+// Using OpenRouter with system message
+const resultOR = await completion({
+  model: 'openrouter/openrouter/free',
+  messages: [
+    { role: 'system', content: 'You are a helpful AI assistant.' },
+    { role: 'user', content: 'Explain the use of llmjs2.' }
+  ],
+  apiKey: 'your-api-key' // optional
+});
 ```
 
-You can also pass a message history directly:
+## Tools Support
+
+llmjs2 supports function calling (tools) through the object-based API:
 
-```js
-import { generate } from 'llmjs2';
+```javascript
+import { completion } from 'llmjs2';
 
-const response = await generate({
-  model: 'ollama/llama3',
+const result = await completion({
+  model: 'openrouter/openrouter/free',
   messages: [
-    { role: 'system', content: 'You are a helpful assistant.' },
-    { role: 'user', content: 'Use a tool if needed.' },
+    { role: 'user', content: 'What is the weather like in Paris?' }
   ],
   tools: [
     {
-      name: 'get_weather',
-      description: 'Get the current weather for a location',
-      parameters: {
-        location: { type: 'string', required: true, description: 'City and state' },
-      },
-      handler: ({ location }) => `Weather in ${location}: Sunny`,
-    },
-  ],
+      type: 'function',
+      function: {
+        name: 'get_weather',
+        description: 'Get the current weather in a given location',
+        parameters: {
+          type: 'object',
+          properties: {
+            location: {
+              type: 'string',
+              description: 'The city and state, e.g. San Francisco, CA'
+            },
+            unit: {
+              type: 'string',
+              enum: ['celsius', 'fahrenheit'],
+              description: 'The temperature unit to use'
+            }
+          },
+          required: ['location']
+        }
+      }
+    }
+  ]
 });
 
-console.log(response);
+// Result when tools are used:
+// {
+//   content: '',
+//   tool_calls: [
+//     {
+//       id: 'call_123',
+//       type: 'function',
+//       function: {
+//         name: 'get_weather',
+//         arguments: '{"location": "Paris, France"}'
+//       }
+//     }
+//   ]
+// }
 ```
 
-## Configuration
+## API Key Configuration
 
-The library resolves connection details in this order:
+You can provide API keys in four ways:
 
-1. Explicit config via `options.ollamaBaseUrl` / `options.ollamaApiKey`
-2. Environment variables `OLLAMA_BASE_URL` and `OLLAMA_API_KEY`
-3. Default fallback `https://api.ollama.com`
+### 1. Simple API (Environment Variables)
 
-Example:
+```bash
+export OLLAMA_API_KEY=your-ollama-api-key
+export OPEN_ROUTER_API_KEY=your-openrouter-api-key
+
+# Optional: Set default models
+export OLLAMA_DEFAULT_MODEL=minimax-m2.5:cloud
+export OPEN_ROUTER_DEFAULT_MODEL=openrouter/free
+```
+
+```javascript
+const result = await completion('Your prompt');
+```
+
+### 2. Direct Parameter (Function API)
 
-```js
-const response = await completion({
-  model: 'ollama/llama3',
-  prompt: 'What is llmjs2?',
-  ollamaBaseUrl: 'https://my-ollama-proxy.local',
-  ollamaApiKey: process.env.OLLAMA_API_KEY,
+```javascript
+const result = await completion('ollama/minimax-m2.5:cloud', 'Your prompt', 'your-api-key');
+```
+
+### 3. Object Property (Object API)
+
+```javascript
+const result = await completion({
+  model: 'ollama/minimax-m2.5:cloud',
+  messages: [{ role: 'user', content: 'Your prompt' }],
+  apiKey: 'your-api-key'
 });
 ```
 
+### 4. Environment Variables (Function/Object API)
+
+```bash
+export OLLAMA_API_KEY=your-ollama-api-key
+export OPEN_ROUTER_API_KEY=your-openrouter-api-key
+```
+
+```javascript
+// Function API
+const result = await completion('ollama/minimax-m2.5:cloud', 'Your prompt');
+
+// Object API
+const result = await completion({
+  model: 'ollama/minimax-m2.5:cloud',
+  messages: [{ role: 'user', content: 'Your prompt' }]
+});
+```
+
+## Model Format
+
+Models must be specified in the format: `provider/model_name`
+
+The provider is the text before the first `/`, and the model name is everything after it.
+
+Examples:
+- `ollama/minimax-m2.5:cloud`
+- `ollama/llama2`
+- `openrouter/openrouter/free`
+- `openrouter/meta-llama/llama-2-70b-chat`
+
+## Messages Format (Object API)
+
+The `messages` parameter is an array of message objects with the following structure:
+
+```javascript
+[
+  { role: 'system', content: 'You are a helpful AI assistant.' },
+  { role: 'user', content: 'What is the capital of France?' },
+  { role: 'assistant', content: 'The capital of France is Paris.' },
+  { role: 'user', content: 'What is its population?' }
+]
+```
+
+**Supported roles:**
+- `system` - System instructions
+- `user` - User messages
+- `assistant` - Assistant responses
+
+## Tools Format (Object API)
+
+The `tools` parameter is an array of tool definitions:
+
+```javascript
+[
+  {
+    type: 'function',
+    function: {
+      name: 'function_name',
+      description: 'Description of what the function does',
+      parameters: {
+        type: 'object',
+        properties: {
+          param1: {
+            type: 'string',
+            description: 'Description of parameter'
+          }
+        },
+        required: ['param1']
+      }
+    }
+  }
+]
+```
+
 ## Error Handling
 
-- `llmjs2: Could not connect to [URL]. Check your OLLAMA_BASE_URL.`
-- `llmjs2: Model "[name]" not found on provider "[provider]".`
-- `llmjs2: Unsupported provider "[provider]".`
+The library throws descriptive errors for:
+- Missing or invalid parameters
+- Missing API keys
+- API request failures
+- Invalid response formats
+- Request timeouts (60 seconds)
+- Invalid tools format
+
+```javascript
+try {
+  const result = await completion('Your prompt');
+} catch (error) {
+  console.error('Completion failed:', error.message);
+}
+```
+
+## Example Programs
+
+### Main Example
+
+A real usage test program is included in `example.js`. To run it:
+
+```bash
+# Set your API keys
+export OLLAMA_API_KEY=your-ollama-api-key
+export OPEN_ROUTER_API_KEY=your-openrouter-api-key
+
+# Run the example
+node example.js
+```
+
+The example program will:
+- Test simple API (auto-detection)
+- Test simple API with model
+- Test Ollama with function-based API
+- Test Ollama with object-based API
+- Test Ollama with tools
+- Test OpenRouter with function-based API
+- Test OpenRouter with object-based API
+- Test OpenRouter with tools
+- Display results and test summary
+
+
+
+## API Reference
+
+### completion(prompt)
+
+**Simple API (Prompt Only)**
+
+**Parameters:**
+- `prompt` (string): The prompt to send to the LLM
+
+**Returns:**
+- `Promise<string>`: The completion result
+
+**Behavior:**
+- Auto-detects provider based on available API keys
+- Uses `OLLAMA_DEFAULT_MODEL` or defaults to `minimax-m2.5:cloud` for Ollama
+- Uses `OPEN_ROUTER_DEFAULT_MODEL` or defaults to `openrouter/free` for OpenRouter
+- Randomly chooses provider if both API keys are set
+
+### completion(model, prompt)
+
+**Simple API (Model and Prompt)**
+
+**Parameters:**
+- `model` (string): Model identifier in format "provider/model_name"
+- `prompt` (string): The prompt to send to the LLM
+
+**Returns:**
+- `Promise<string>`: The completion result
+
+**Behavior:**
+- Auto-detects provider based on available API keys
+- Uses the provided model instead of the default
+- Randomly chooses provider if both API keys are set
+
+### completion(model, prompt, apiKey)
+
+**Function-Based API**
+
+**Parameters:**
+- `model` (string): Model identifier in format "provider/model_name"
+- `prompt` (string): The prompt to send to the LLM
+- `apiKey` (string, optional): API key (falls back to environment variables)
+
+**Returns:**
+- `Promise<string>`: The completion result
+
+### completion(options)
+
+**Object-Based API**
+
+**Parameters:**
+- `options` (object): Configuration object
+  - `model` (string): Model identifier in format "provider/model_name"
+  - `messages` (array): Array of message objects with role and content
+  - `apiKey` (string, optional): API key (falls back to environment variables)
+  - `tools` (array, optional): Array of tool definitions
+
+**Returns:**
+- `Promise<string|object>`: The completion result (string or object with tool calls)
+
+**Throws:**
+- Error if model format is invalid
+- Error if prompt/messages is missing
+- Error if API key is not provided
+- Error if API request fails
+- Error if request times out (60 seconds)
+- Error if tools format is invalid
 
-## Notes
+## License
 
-- Node.js 18.0.0 or later is required for native `fetch` support.
-- No hyper-parameters such as `temperature` or `max_tokens` are exposed in the high-level API.
+MIT