llmjs2 1.6.1 → 2.0.0

package/README.md

@@ -1,31 +1,129 @@
 # llmjs2
 
-llmjs2 is a unified Node.js library for OpenAI, Ollama, and OpenRouter with routing, guardrails, and an OpenAI-style server mode.
+A lightweight Node.js library for LLM completions, routing and simple agent workflows.
 
-## Quick Links
+**Description**: A minimal toolkit to call multiple LLM providers (OpenAI, OpenRouter, Ollama, BigModel), route requests across model lists with optional guardrails, and run simple agent workflows with pluggable tools and memory backends.
 
-- 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**
 
-## Install
+Install from npm:
 
-```bash
+```
 npm install llmjs2
 ```
 
-## Basic Usage
+**Build (from source)**
+
+```
+npm run build
+```
+
+**Quick Start**
+
+- **Simple completion (string prompt)**: Returns the raw provider response object.
+
+```js
+import { completion } from 'llmjs2';
+
+const resp = await completion('Write a friendly greeting.');
+console.log(resp);
+```
+
+- **Full options**: Provide `model` in the form `provider/model_name` (e.g. `openai/gpt-4o-mini`).
+
+```js
+import { completion } from 'llmjs2';
+
+const resp = await completion({
+  model: 'openai/gpt-4o-mini',
+  messages: [{ role: 'user', content: 'Summarize Node.js event loop.' }],
+});
+```
+
+**Router (multi-route LLM routing)**
+
+- Create a router from a config object or a path to a JSON/JS config file. The router selects a route (random or sequential) and applies optional guardrails.
+
+```js
+import { router } from 'llmjs2';
+
+const r = router({
+  routing: 'random',
+  model_list: [
+    { model_name: 'primary', llm_params: { model: 'openai/gpt-4o-mini' } },
+    { model_name: 'backup', llm_params: { model: 'openrouter/openai/gpt-4o-mini' } },
+  ],
+});
+
+const res = await r.completion({ messages: [{ role: 'user', content: 'Hello' }] });
+```
+
+Guardrails can be provided to modify requests pre-call or post-call.
+
+**Agent**
+
+- The `Agent` wraps a routing instance, optional `Memory` backend, and optional `tools`. It supports multi-turn flows and tool-calls returned by models.
+
+```js
+import { Agent, inMemory } from 'llmjs2';
+
+const agent = new Agent({
+  instruction: 'You are a helpful assistant.',
+  route: router({ model_list: [{ model_name: 'r', llm_params: { model: 'openai/gpt-4o-mini' } }] }),
+  memory: inMemory(),
+  tools: [
+    {
+      name: 'echo',
+      description: 'Echoes input',
+      parameters: { text: { type: 'string', description: 'Text', required: true } },
+      execute: async (params) => `ECHO: ${params.text}`,
+    },
+  ],
+});
+
+const out = await agent.generate('Say hello and use the echo tool.');
+console.log(out);
+```
+
+**Memory**
+
+- In-memory storage (ephemeral): `inMemory()`
+- File-based storage: `fileMemory({ path: './memory.json' })`
+
+Both implement: `save(resourceId, threadId, role, content)`, `list(resourceId, threadId, limit)`, `search(resourceId, query)`, `clear(resourceId, threadId)`.
 
-```javascript
-const { completion } = require('llmjs2');
+**Logging / Verbosity**
 
-(async () => {
-  const result = await completion({
-    model: 'openai/gpt-4',
-    messages: [{ role: 'user', content: 'Say hello in one sentence.' }]
-  });
+Set verbosity with `verbose('debug'|'info'|'none')`:
 
-  console.log(result);
-})();
+```js
+import { verbose } from 'llmjs2';
+verbose('debug');
 ```
+
+**Configuration / Environment Variables**
+
+- `OPENAI_API_KEY`, `OPENAI_BASE_URL`, `OPENAI_DEFAULT_MODEL`
+- `OPEN_ROUTER_API_KEY`, `OPEN_ROUTER_BASE_URL`, `OPEN_ROUTER_DEFAULT_MODEL`
+- `BIGMODEL_API_KEY`, `BIGMODEL_BASE_URL`, `BIGMODEL_DEFAULT_MODEL`
+- `OLLAMA_API_KEY`, `OLLAMA_BASE_URL`, `OLLAMA_DEFAULT_MODEL`
+- `LLM_DEFAULT_MODEL` — fallback model when none provided in options
+
+The library reads these from `process.env` or via the `getConfig()` defaults.
+
+**API Reference (exports)**
+
+- `completion(promptOrOptions)` — single-call completion helper. Accepts a string or a `CompletionOptions` object.
+- `router(configOrPath)` — build a router instance from config object or file path. Returns `{ completion(options) }`.
+- `Agent` / `createAgent(config)` — agent class for multi-turn workflows and tool execution.
+- `inMemory()` / `fileMemory({ path })` — memory backends.
+- `verbose(level)` — set logger verbosity.
+
+**Build & Publish Notes**
+
+- The package builds to `dist/` via `npm run build` (uses `tsup`). The `prepublishOnly` script runs the build.
+- Entry points: CommonJS `./dist/index.js`, ESM `./dist/index.mjs`, types at `./dist/index.d.ts`.
+
+**License**
+
+ISC

package/dist/index.d.mts

@@ -0,0 +1,146 @@
+type MessageContent = string;
+interface Message {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: MessageContent;
+    images?: string[];
+    tool_calls?: any[];
+    tool_call_id?: string;
+}
+interface ToolParameter {
+    type: string;
+    description: string;
+    required?: boolean;
+}
+interface Tool {
+    name: string;
+    description?: string;
+    parameters: Record<string, ToolParameter>;
+}
+interface CompletionOptions {
+    model: string;
+    host?: string;
+    baseUrl?: string;
+    messages: Message[];
+    apiKey?: string;
+    tools?: Tool[];
+}
+type GuardrailMode = 'pre_call' | 'post_call';
+interface PreCallInput {
+    model: string;
+    messages: Message[];
+    tools?: Tool[];
+    metadata?: Record<string, unknown>;
+}
+type GuardrailHandler = (processId: string, payload: any) => any | Promise<any>;
+interface GuardrailConfig {
+    name: string;
+    mode: GuardrailMode;
+    code: string | GuardrailHandler;
+    enabled?: boolean;
+    timeout_ms?: number;
+}
+type ProviderName = 'openai' | 'openrouter' | 'ollama' | 'bigmodel';
+interface ProviderConfig {
+    apiKey?: string;
+    baseUrl?: string;
+    defaultModel?: string;
+}
+interface Config {
+    openai: ProviderConfig;
+    openrouter: ProviderConfig;
+    ollama: ProviderConfig;
+    bigmodel: ProviderConfig;
+}
+
+declare function completion(promptOrOptions: string | CompletionOptions): Promise<any>;
+
+type RoutingStrategy = 'random' | 'sequential' | 'default';
+interface RouterModelParams extends Omit<CompletionOptions, 'messages'> {
+    model: string;
+    api_key?: string;
+    api_base?: string;
+}
+interface RouterModelEntry {
+    model_name: string;
+    llm_params: RouterModelParams;
+}
+interface RouterConfig {
+    routing?: RoutingStrategy;
+    model_list: RouterModelEntry[];
+    guardrails?: GuardrailConfig[];
+}
+interface RouterRequestOptions extends Omit<CompletionOptions, 'model'> {
+    model?: string;
+}
+interface RouterInstance {
+    completion(options: RouterRequestOptions): Promise<any>;
+}
+declare function router(configOrPath: RouterConfig | string): RouterInstance;
+
+type MemoryRole = 'user' | 'assistant';
+interface Memory {
+    save(resourceId: string, threadId: string, role: MemoryRole, content: string): Promise<void>;
+    list(resourceId: string, threadId: string, limit?: number): Promise<Array<{
+        role: MemoryRole;
+        content: string;
+    }>>;
+    search(resourceId: string, query: string): Promise<Array<{
+        content: string;
+        threadId: string;
+    }>>;
+    clear(resourceId: string, threadId: string): Promise<void>;
+}
+declare function inMemory(): Memory;
+declare function fileMemory(config: {
+    path: string;
+}): Memory;
+
+type memory_Memory = Memory;
+declare const memory_fileMemory: typeof fileMemory;
+declare const memory_inMemory: typeof inMemory;
+declare namespace memory {
+  export { type memory_Memory as Memory, memory_fileMemory as fileMemory, memory_inMemory as inMemory };
+}
+
+interface AgentTool extends Tool {
+    execute: (params: Record<string, unknown>) => Promise<string>;
+}
+interface AgentConfig {
+    instruction: string;
+    route: RouterInstance;
+    memory?: Memory;
+    session?: boolean;
+    relevance?: boolean;
+    tools?: AgentTool[];
+}
+interface GenerateMemoryRequest {
+    resourceId: string;
+    threadId: string;
+    session?: boolean;
+    relevance?: boolean;
+}
+interface GenerateRequest {
+    userPrompt: string;
+    memory?: GenerateMemoryRequest;
+    attachments?: (string | Buffer)[];
+}
+interface ToolCallResponse {
+    content: string;
+    toolCalls: Array<{
+        name: string;
+        parameters: Record<string, unknown>;
+        result: string;
+    }>;
+}
+declare class Agent {
+    private config;
+    constructor(config: AgentConfig);
+    generate(request: string | GenerateRequest): Promise<string | ToolCallResponse>;
+}
+/** @deprecated Use `new Agent(config)` instead. */
+declare function createAgent(config: AgentConfig): Agent;
+
+type VerboseLevel = 'debug' | 'info' | 'none';
+declare function verbose(level: VerboseLevel): void;
+
+export { Agent, type AgentConfig, type AgentTool, type CompletionOptions, type Config, type GenerateMemoryRequest, type GenerateRequest, type GuardrailConfig, type GuardrailHandler, type GuardrailMode, memory as Memory, type Message, type MessageContent, type PreCallInput, type ProviderConfig, type ProviderName, type RouterConfig, type RouterInstance, type RouterModelEntry, type RouterModelParams, type RouterRequestOptions, type RoutingStrategy, type Tool, type ToolCallResponse, type ToolParameter, completion, createAgent, fileMemory, inMemory, router, verbose };

package/dist/index.d.ts

@@ -0,0 +1,146 @@
+type MessageContent = string;
+interface Message {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: MessageContent;
+    images?: string[];
+    tool_calls?: any[];
+    tool_call_id?: string;
+}
+interface ToolParameter {
+    type: string;
+    description: string;
+    required?: boolean;
+}
+interface Tool {
+    name: string;
+    description?: string;
+    parameters: Record<string, ToolParameter>;
+}
+interface CompletionOptions {
+    model: string;
+    host?: string;
+    baseUrl?: string;
+    messages: Message[];
+    apiKey?: string;
+    tools?: Tool[];
+}
+type GuardrailMode = 'pre_call' | 'post_call';
+interface PreCallInput {
+    model: string;
+    messages: Message[];
+    tools?: Tool[];
+    metadata?: Record<string, unknown>;
+}
+type GuardrailHandler = (processId: string, payload: any) => any | Promise<any>;
+interface GuardrailConfig {
+    name: string;
+    mode: GuardrailMode;
+    code: string | GuardrailHandler;
+    enabled?: boolean;
+    timeout_ms?: number;
+}
+type ProviderName = 'openai' | 'openrouter' | 'ollama' | 'bigmodel';
+interface ProviderConfig {
+    apiKey?: string;
+    baseUrl?: string;
+    defaultModel?: string;
+}
+interface Config {
+    openai: ProviderConfig;
+    openrouter: ProviderConfig;
+    ollama: ProviderConfig;
+    bigmodel: ProviderConfig;
+}
+
+declare function completion(promptOrOptions: string | CompletionOptions): Promise<any>;
+
+type RoutingStrategy = 'random' | 'sequential' | 'default';
+interface RouterModelParams extends Omit<CompletionOptions, 'messages'> {
+    model: string;
+    api_key?: string;
+    api_base?: string;
+}
+interface RouterModelEntry {
+    model_name: string;
+    llm_params: RouterModelParams;
+}
+interface RouterConfig {
+    routing?: RoutingStrategy;
+    model_list: RouterModelEntry[];
+    guardrails?: GuardrailConfig[];
+}
+interface RouterRequestOptions extends Omit<CompletionOptions, 'model'> {
+    model?: string;
+}
+interface RouterInstance {
+    completion(options: RouterRequestOptions): Promise<any>;
+}
+declare function router(configOrPath: RouterConfig | string): RouterInstance;
+
+type MemoryRole = 'user' | 'assistant';
+interface Memory {
+    save(resourceId: string, threadId: string, role: MemoryRole, content: string): Promise<void>;
+    list(resourceId: string, threadId: string, limit?: number): Promise<Array<{
+        role: MemoryRole;
+        content: string;
+    }>>;
+    search(resourceId: string, query: string): Promise<Array<{
+        content: string;
+        threadId: string;
+    }>>;
+    clear(resourceId: string, threadId: string): Promise<void>;
+}
+declare function inMemory(): Memory;
+declare function fileMemory(config: {
+    path: string;
+}): Memory;
+
+type memory_Memory = Memory;
+declare const memory_fileMemory: typeof fileMemory;
+declare const memory_inMemory: typeof inMemory;
+declare namespace memory {
+  export { type memory_Memory as Memory, memory_fileMemory as fileMemory, memory_inMemory as inMemory };
+}
+
+interface AgentTool extends Tool {
+    execute: (params: Record<string, unknown>) => Promise<string>;
+}
+interface AgentConfig {
+    instruction: string;
+    route: RouterInstance;
+    memory?: Memory;
+    session?: boolean;
+    relevance?: boolean;
+    tools?: AgentTool[];
+}
+interface GenerateMemoryRequest {
+    resourceId: string;
+    threadId: string;
+    session?: boolean;
+    relevance?: boolean;
+}
+interface GenerateRequest {
+    userPrompt: string;
+    memory?: GenerateMemoryRequest;
+    attachments?: (string | Buffer)[];
+}
+interface ToolCallResponse {
+    content: string;
+    toolCalls: Array<{
+        name: string;
+        parameters: Record<string, unknown>;
+        result: string;
+    }>;
+}
+declare class Agent {
+    private config;
+    constructor(config: AgentConfig);
+    generate(request: string | GenerateRequest): Promise<string | ToolCallResponse>;
+}
+/** @deprecated Use `new Agent(config)` instead. */
+declare function createAgent(config: AgentConfig): Agent;
+
+type VerboseLevel = 'debug' | 'info' | 'none';
+declare function verbose(level: VerboseLevel): void;
+
+export { Agent, type AgentConfig, type AgentTool, type CompletionOptions, type Config, type GenerateMemoryRequest, type GenerateRequest, type GuardrailConfig, type GuardrailHandler, type GuardrailMode, memory as Memory, type Message, type MessageContent, type PreCallInput, type ProviderConfig, type ProviderName, type RouterConfig, type RouterInstance, type RouterModelEntry, type RouterModelParams, type RouterRequestOptions, type RoutingStrategy, type Tool, type ToolCallResponse, type ToolParameter, completion, createAgent, fileMemory, inMemory, router, verbose };