llmjs2 1.0.1 → 1.0.6

package/README.md

@@ -1,472 +1,129 @@
 # llmjs2
 
-LLM abstraction layer for Node.js. Unified API for multiple LLM providers with error handling and automatic retry logic.
-
-**Supported Providers**: Ollama
+`llmjs2` is a zero-dependency Node.js library that provides a small, robust interface for calling Ollama and Ollama Cloud from Node 18+.
 
 ## Features
 
-- 🚀 **Unified API**: Single interface for Ollama provider
--  **Automatic Retries**: Exponential backoff retry logic with configurable parameters
-- ⚙️ **Type-Safe**: Full TypeScript support with comprehensive type definitions
-- 🛡️ **Robust Error Handling**: Custom error types with retryability information
-- 🔍 **Debugging**: Built-in logging and debug mode for troubleshooting
-- 📦 **Zero Dependencies**: Pure Node.js with no external dependencies
-- ✅ **Production-Ready**: Enterprise-grade error handling and validation
+- 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
 
 ## Installation
 
+No dependencies are required. Install or link the package as usual:
+
 ```bash
 npm install llmjs2
 ```
 
-## Quick Start
+## Usage
 
-### Basic Completion (Ollama)
-
-```javascript
+```js
 import { completion } from 'llmjs2';
 
-const result = await completion({
-  model: 'ollama/mistral',
-  baseUrl: 'http://localhost:11434',
-  messages: [
-    { role: 'system', content: 'You are a helpful assistant.' },
-    { role: 'user', content: 'What is TypeScript?' }
-  ]
-});
-
-console.log(result.content);
+const response = await completion('ollama/llama3', 'Write a short poem about Node.js.');
+console.log(response);
 ```
 
-### Using Ollama Locally
+Or with a full options object:
 
-```javascript
+```js
 import { completion } from 'llmjs2';
 
-const result = await completion({
-  model: 'ollama/mistral',
-  baseUrl: 'http://localhost:11434', // Default Ollama URL
+const response = await completion({
+  model: 'ollama/llama3',
   messages: [
-    { role: 'user', content: 'Explain quantum computing' }
-  ]
-});
-
-console.log(result.content);
-```
-
-### Using Agent for Stateful Conversations
-
-```javascript
-import { Agent } from 'llmjs2';
-
-const agent = new Agent({
-  model: 'ollama/qwen3.5:397b-cloud',
-  baseUrl: 'https://ollama.com',
-  instruction: 'You are a helpful assistant that explains technical concepts.',
-  tools: [], // Optional function calling
-});
-
-// Generate response (maintains conversation history)
-const result = await agent.generate({
-  userPrompt: 'What is TypeScript?',
-  images: [],
-  references: [],
-  context: { role: 'student', level: 'beginner' }
-});
-
-console.log(result.response);
-
-// Continue conversation (history automatically maintained)
-const followUp = await agent.generate({
-  userPrompt: 'Can you give me an example?'
-});
-
-console.log(followUp.response);
-
-// Stream the response
-const stream = agent.generateStream({
-  userPrompt: 'Explain decorators in TypeScript'
-});
-
-for await (const chunk of stream) {
-  process.stdout.write(chunk.delta);
-}
-
-// Manage conversation history
-console.log(agent.getHistory()); // Get all messages
-agent.clearHistory();             // Clear history (keeps system instruction)
-agent.addMessage('system', 'New instruction');
-```
-
-## API Reference
-
-### `completion(request: CompletionRequest): Promise<CompletionResponse>`
-
-Create a completion request. Supports Ollama.
-
-**Parameters:**
-
-- `model` (string, required): Model identifier
-  - Ollama: `ollama/mistral`, `ollama/neural-chat`, `ollama/qwen3.5:397b-cloud`, etc.
-  
-- `messages` (Message[], required): Array of messages with `role` and `content`
-  
-- `baseUrl` (string, optional): Custom API endpoint (mainly for Ollama)
-
-- `maxTokens` (number, optional): Maximum tokens to generate
-
-- `temperature` (number, optional): Sampling temperature (0-2). Higher = more random
-
-- `topP` (number, optional): Nucleus sampling parameter (0-1)
-
-- `topK` (number, optional): Top-k sampling (Ollama)
-
-- `frequencyPenalty` (number, optional): Frequency penalty (-2 to 2)
-
-- `presencePenalty` (number, optional): Presence penalty (-2 to 2)
-
-- `stop` (string[], optional): Stop sequences
-
-- `timeout` (number, optional): Request timeout in milliseconds
-
-- `retry` (object, optional): Retry configuration
-  - `maxRetries` (number): Maximum retry attempts
-  - `backoffMultiplier` (number): Exponential backoff multiplier
-  - `initialDelayMs` (number): Initial retry delay
-
-**Returns:** `CompletionResponse`
-
-```typescript
-{
-  content: string;              // Generated text
-  model: string;                // Model used
-  stopReason?: string;          // Stop reason
-  usage?: {                      // Token usage (if available)
-    promptTokens?: number;
-    completionTokens?: number;
-    totalTokens?: number;
-  };
-  raw?: unknown;                // Raw provider response
-  toolCalls?: Array<{           // Function calls (if any)
-    id?: string;
-    name: string;
-    arguments: Record<string, unknown>;
-  }>;
-}
-```
-
-### `configure(options: CompletionOptions): void`
-
-Configure global settings for all completions.
-
-```javascript
-import { configure } from 'llmjs2';
-
-configure({
-  debug: true,  // Enable debug logging
-  globalTimeout: 60000,  // 60 second default timeout
-  globalRetry: {
-    maxRetries: 5,
-    backoffMultiplier: 2,
-    initialDelayMs: 1000
-  },
-  logger: (level, message, data) => {
-    console.log(`[${level}] ${message}`, data);
-  }
+    { role: 'system', content: 'You are a helpful assistant.' },
+    { role: 'user', content: 'Summarize the benefits of zero dependencies.' },
+  ],
 });
-```
-
-### `validateProvider(model: string, apiKey?: string, baseUrl?: string): Promise<void>`
-
-Validate that a provider is configured correctly and accessible.
-
-```javascript
-import { validateProvider } from 'llmjs2';
-
-try {
-  await validateProvider('ollama/mistral', process.env.OLLAMA_CLOUD_API_KEY);
-  console.log('Ollama provider is valid');
-} catch (error) {
-  console.error('Provider validation failed:', error.message);
-}
-```
-
-## Agent - Stateful Conversations
-
-### `new Agent(config: AgentConfig): Agent`
 
-Create a stateful agent for managing conversations with automatic history tracking.
-
-**Configuration:**
-
-```typescript
-interface AgentConfig {
-  model: string;              // Model identifier (required)
-  apiKey?: string;           // API key (if needed)
-  baseUrl?: string;          // Custom endpoint
-  instruction?: string;      // System instruction/role
-  tools?: Tool[];            // Available functions
-  maxTokens?: number;        // Max response tokens
-  temperature?: number;      // Sampling temperature
-  timeout?: number;          // Request timeout
-}
+console.log(response);
 ```
 
-**Methods:**
-
-### `agent.generate(request: AgentGenerateRequest): Promise<AgentGenerateResponse>`
-
-Generate a response while maintaining conversation history.
+## generate()
 
-**Parameters:**
-- `userPrompt` (string, required): User message
-- `images` (string[], optional): Image data/URLs
-- `references` (string[], optional): Reference documents
-- `context` (Record, optional): Additional context variables
+The library also exposes `generate()` for prompt-based flows with optional images, references, system instructions, and tools.
 
-**Returns:**
-```typescript
-{
-  response: string;                    // Generated text
-  completion: CompletionResponse;      // Full provider response
-  toolCalls?: Array<{                 // Function calls if any
-    name: string;
-    arguments: Record<string, unknown>;
-  }>;
-}
-```
-
-**Example:**
-```javascript
-const agent = new Agent({
-  model: 'ollama/qwen3.5:397b-cloud',
-  baseUrl: 'https://ollama.com',
-  instruction: 'You are a coding expert.'
-});
+```js
+import { generate } from 'llmjs2';
 
-const result = await agent.generate({
-  userPrompt: 'How do I use async/await?',
-  context: { language: 'JavaScript' }
+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`,
+    },
+  ],
 });
 
-console.log(result.response);
-```
-
-### `agent.getHistory(): Message[]`
-
-Get the current conversation history.
-
-```javascript
-const messages = agent.getHistory();
-console.log(messages);
-```
-
-### `agent.clearHistory(): void`
-
-Clear conversation history (system instruction is preserved).
-
-```javascript
-agent.clearHistory();
-```
-
-### `agent.addMessage(role, content): void`
-
-Manually add a message to the history.
-
-```javascript
-agent.addMessage('assistant', 'Custom response');
-agent.addMessage('user', 'Follow-up question');
-```
-
-### `agent.getConfig(): AgentConfig`
-
-Get the current agent configuration.
-
-```javascript
-const config = agent.getConfig();
-```
-
-## Error Handling
-
-All errors are instances of `LLMError` with additional properties:
-
-```typescript
-interface LLMError extends Error {
-  code?: string;          // Error code
-  statusCode?: number;    // HTTP status code
-  details?: unknown;      // Additional error details
-  retryable?: boolean;    // Whether to retry
-}
-```
-
-**Example:**
-
-```javascript
-import { completion, LLMError } from 'llmjs2';
-
-try {
-  const result = await completion({
-    model: 'ollama/mistral',
-    baseUrl: 'http://localhost:11434',
-    messages: [{ role: 'user', content: 'Hello' }]
-  });
-} catch (error) {
-  if (error instanceof LLMError) {
-    console.error(`Error [${error.code}]:`, error.message);
-    
-    if (error.retryable) {
-      console.log('Error is retryable, will retry...');
-    }
-  }
-}
+console.log(response);
 ```
 
-## Advanced Usage
+You can also pass a message history directly:
 
-### Function Calling (Ollama + embedded handlers)
-
-```javascript
-import { completion } from 'llmjs2';
+```js
+import { generate } from 'llmjs2';
 
-const result = await completion({
-  model: 'ollama/mistral',
-  baseUrl: 'http://localhost:11434',
+const response = await generate({
+  model: 'ollama/llama3',
   messages: [
-    { role: 'user', content: 'What is the weather in San Francisco?' }
+    { role: 'system', content: 'You are a helpful assistant.' },
+    { role: 'user', content: 'Use a tool if needed.' },
   ],
   tools: [
     {
       name: 'get_weather',
-      description: 'Get weather for a location',
+      description: 'Get the current weather for a location',
       parameters: {
-        location: { type: 'string', required: true },
-        unit: { type: 'string', enum: ['celsius', 'fahrenheit'] }
+        location: { type: 'string', required: true, description: 'City and state' },
       },
-        }
-      }
-    }
-  ]
-});
-
-if (result.toolCalls) {
-  for (const call of result.toolCalls) {
-    console.log(`Function: ${call.name}`);
-    console.log(`Arguments:`, call.arguments);
-  }
-}
-```
-
-### Custom Request Headers
-
-```javascript
-import { completion } from 'llmjs2';
-
-const result = await completion({
-  model: 'ollama/mistral',
-  baseUrl: 'http://localhost:11434',
-  messages: [{ role: 'user', content: 'Hello' }],
-  headers: {
-    'X-Custom-Header': 'custom-value'
-  }
-});
-```
-
-### Provider-Specific Configuration
-
-For Ollama with custom settings:
-```javascript
-import { completion } from 'llmjs2';
-
-const result = await completion({
-  model: 'ollama/mistral',
-  baseUrl: 'http://192.168.1.100:11434',
-  messages: [
-    { role: 'user', content: 'Explain AI' }
+      handler: ({ location }) => `Weather in ${location}: Sunny`,
+    },
   ],
-  temperature: 0.7,
-  topK: 40,
-  topP: 0.9,
-  maxTokens: 2048
 });
-```
 
-## Environment Variables
-
-**Ollama:**
-- Ollama reads from local `http://localhost:11434` by default
-- Override with `baseUrl` parameter in request
-
-## Type Definitions
-
-Full TypeScript support with comprehensive types:
-
-```typescript
-import type {
-  CompletionRequest,
-  CompletionResponse,
-  CompletionChunk,
-  Message,
-  MessageRole,
-  Tool,
-  ProviderType,
-  ProviderConfig,
-  ProviderError,
-  CompletionOptions,
-  AgentConfig,
-  AgentGenerateRequest,
-  AgentGenerateResponse
-} from 'llmjs2';
-
-import { Agent } from 'llmjs2';
+console.log(response);
 ```
 
-## Performance Considerations
-
-1. **Batching**: Batch multiple requests to reduce API calls
-2. **Caching**: Implement caching for common queries
-3. **Timeouts**: Configure appropriate timeouts for your use case
-4. **Retry Logic**: Automatic exponential backoff is built-in and configurable
-
-## Testing
-
-```bash
-# Run tests
-npm test
-
-# Run tests in watch mode
-npm run test:watch
-```
+## Configuration
 
-## Building
+The library resolves connection details in this order:
 
-```bash
-# Build TypeScript to JavaScript
-npm run build
+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`
 
-# Build in watch mode
-npm run build:watch
+Example:
 
-# Clean build artifacts
-npm run clean
+```js
+const response = await completion({
+  model: 'ollama/llama3',
+  prompt: 'What is llmjs2?',
+  ollamaBaseUrl: 'https://my-ollama-proxy.local',
+  ollamaApiKey: process.env.OLLAMA_API_KEY,
+});
 ```
 
-## License
-
-MIT - See LICENSE file for details
-
-## Support
+## Error Handling
 
-- GitHub Issues: [github.com/littlellmjs/llmjs2/issues](https://github.com/littlellmjs/llmjs2/issues)
-- Documentation: Full API reference above
+- `llmjs2: Could not connect to [URL]. Check your OLLAMA_BASE_URL.`
+- `llmjs2: Model "[name]" not found on provider "[provider]".`
+- `llmjs2: Unsupported provider "[provider]".`
 
-## Changelog
+## Notes
 
-### 1.0.0
-- Initial production release
-- Ollama support
-- Streaming API with async generators
-- Automatic retry with exponential backoff
-- Comprehensive error handling
-- TypeScript 5+ support
-- Zero external dependencies
+- 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.

package/index.d.ts

@@ -0,0 +1,43 @@
+export interface Llmjs2Message {
+  role: 'system' | 'user' | 'assistant' | string;
+  content: string;
+}
+
+export interface CompletionOptions {
+  model: string;
+  messages?: Llmjs2Message[];
+  prompt?: string;
+  ollamaBaseUrl?: string;
+  ollamaApiKey?: string;
+}
+
+export interface ToolParameter {
+  type: string;
+  required?: boolean;
+  description: string;
+  enum?: string[];
+}
+
+export interface ToolSchema {
+  name: string;
+  description: string;
+  parameters: Record<string, ToolParameter>;
+  handler: (args: Record<string, any>) => string | Promise<string>;
+}
+
+export interface GenerateOptions {
+  model: string;
+  userPrompt?: string;
+  messages?: Llmjs2Message[];
+  images?: Array<string | Buffer>;
+  references?: Array<string | Buffer>;
+  tools?: ToolSchema[];
+  systemPrompt?: string;
+  ollamaBaseUrl?: string;
+  ollamaApiKey?: string;
+}
+
+export function completion(model: string, prompt: string): Promise<string>;
+export function completion(options: CompletionOptions): Promise<string>;
+export function generate(options: GenerateOptions): Promise<string>;
+export function generate(model: string, userPrompt: string, images?: Array<string | Buffer>, references?: Array<string | Buffer>, tools?: ToolSchema[]): Promise<string>;