llmjs2 0.0.2 → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 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 +1,472 @@
-llmjs
+# llmjs2
+
+LLM abstraction layer for Node.js. Unified API for multiple LLM providers with error handling and automatic retry logic.
+
+**Supported Providers**: Ollama
+
+## 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
+
+## Installation
+
+```bash
+npm install llmjs2
+```
+
+## Quick Start
+
+### Basic Completion (Ollama)
+
+```javascript
+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);
+```
+
+### Using Ollama Locally
+
+```javascript
+import { completion } from 'llmjs2';
+
+const result = await completion({
+  model: 'ollama/mistral',
+  baseUrl: 'http://localhost:11434', // Default Ollama URL
+  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);
+  }
+});
+```
+
+### `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
+}
+```
+
+**Methods:**
+
+### `agent.generate(request: AgentGenerateRequest): Promise<AgentGenerateResponse>`
+
+Generate a response while maintaining conversation history.
+
+**Parameters:**
+- `userPrompt` (string, required): User message
+- `images` (string[], optional): Image data/URLs
+- `references` (string[], optional): Reference documents
+- `context` (Record, optional): Additional context variables
+
+**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.'
+});
+
+const result = await agent.generate({
+  userPrompt: 'How do I use async/await?',
+  context: { language: 'JavaScript' }
+});
+
+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...');
+    }
+  }
+}
+```
+
+## Advanced Usage
+
+### Function Calling (Ollama + embedded handlers)
+
+```javascript
+import { completion } from 'llmjs2';
+
+const result = await completion({
+  model: 'ollama/mistral',
+  baseUrl: 'http://localhost:11434',
+  messages: [
+    { role: 'user', content: 'What is the weather in San Francisco?' }
+  ],
+  tools: [
+    {
+      name: 'get_weather',
+      description: 'Get weather for a location',
+      parameters: {
+        location: { type: 'string', required: true },
+        unit: { type: 'string', enum: ['celsius', 'fahrenheit'] }
+      },
+        }
+      }
+    }
+  ]
+});
+
+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' }
+  ],
+  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';
+```
+
+## 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
+```
+
+## Building
+
+```bash
+# Build TypeScript to JavaScript
+npm run build
+
+# Build in watch mode
+npm run build:watch
+
+# Clean build artifacts
+npm run clean
+```
+
+## License
+
+MIT - See LICENSE file for details
+
+## Support
+
+- GitHub Issues: [github.com/littlellmjs/llmjs2/issues](https://github.com/littlellmjs/llmjs2/issues)
+- Documentation: Full API reference above
+
+## Changelog
+
+### 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

package/dist/agent.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Agent - Stateful conversation manager with tool support
+ */
+import { CompletionResponse, CompletionChunk, Message, Tool } from './index.js';
+/**
+ * Agent configuration
+ */
+export interface AgentConfig {
+    /** Model identifier (e.g., 'ollama/qwen3.5:397b-cloud') */
+    model: string;
+    /** API key for the provider (optional, reads from OLLAMA_CLOUD_API_KEY env by default) */
+    apiKey?: string;
+    /** Base URL for the API (optional, defaults to https://ollama.com) */
+    baseUrl?: string;
+    /** System instruction for the agent */
+    instruction?: string;
+    /** Available tools/functions with optional embedded handlers */
+    tools?: Tool[];
+    /** Tool executor function - receives tool name and arguments (deprecated: use tool.handler instead) */
+    toolExecutor?: (toolName: string, args: Record<string, unknown>) => string;
+}
+/**
+ * Agent generation request
+ */
+export interface AgentGenerateRequest {
+    /** User prompt/message */
+    userPrompt: string;
+    /** Optional images (base64 or URLs) */
+    images?: string[];
+    /** Optional reference documents or context */
+    references?: string[];
+    /** Additional context variables */
+    context?: Record<string, unknown>;
+}
+/**
+ * Agent generation response
+ */
+export interface AgentGenerateResponse {
+    /** Generated response */
+    response: string;
+    /** Full completion response from provider */
+    completion: CompletionResponse;
+}
+/**
+ * Stateful agent for conversations and tool use
+ */
+export declare class Agent {
+    private config;
+    private conversationHistory;
+    constructor(config: AgentConfig);
+    /**
+     * Generate a response for a user message
+     */
+    generate(request: AgentGenerateRequest): Promise<AgentGenerateResponse>;
+    /**
+     * Get completion from the model
+     */
+    private getCompletion;
+    /**
+     * Stream a response for a user message
+     */
+    generateStream(request: AgentGenerateRequest): AsyncIterable<CompletionChunk>;
+    /**
+     * Get conversation history
+     */
+    getHistory(): Message[];
+    /**
+     * Clear conversation history (keeps system instruction if set)
+     */
+    clearHistory(): void;
+    /**
+     * Add a message to history
+     */
+    addMessage(role: 'system' | 'user' | 'assistant', content: string): void;
+    /**
+     * Get the current configuration
+     */
+    getConfig(): AgentConfig;
+}
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAIL,kBAAkB,EAClB,eAAe,EACf,OAAO,EACP,IAAI,EAEL,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,2DAA2D;IAC3D,KAAK,EAAE,MAAM,CAAC;IAEd,0FAA0F;IAC1F,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,uCAAuC;IACvC,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,gEAAgE;IAChE,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC;IAEf,uGAAuG;IACvG,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC;CAC5E;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,0BAA0B;IAC1B,UAAU,EAAE,MAAM,CAAC;IAEnB,uCAAuC;IACvC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAElB,8CAA8C;IAC9C,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IAEtB,mCAAmC;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,yBAAyB;IACzB,QAAQ,EAAE,MAAM,CAAC;IAEjB,6CAA6C;IAC7C,UAAU,EAAE,kBAAkB,CAAC;CAChC;AAED;;GAEG;AACH,qBAAa,KAAK;IAChB,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,mBAAmB,CAAiB;gBAEhC,MAAM,EAAE,WAAW;IAgB/B;;OAEG;IACG,QAAQ,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IA2F7E;;OAEG;YACW,aAAa;IAY3B;;OAEG;IACI,cAAc,CACnB,OAAO,EAAE,oBAAoB,GAC5B,aAAa,CAAC,eAAe,CAAC;IAoDjC;;OAEG;IACH,UAAU,IAAI,OAAO,EAAE;IAIvB;;OAEG;IACH,YAAY,IAAI,IAAI;IAapB;;OAEG;IACH,UAAU,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAOxE;;OAEG;IACH,SAAS,IAAI,WAAW;CAGzB"}