llmjs2 1.0.0 → 1.0.5

package/index.js

@@ -0,0 +1,465 @@
+import fs from 'node:fs/promises';
+
+const DEFAULT_BASE_URL = 'https://api.ollama.com';
+const DEFAULT_CHAT_PATH = '/api/chat';
+
+const isString = (value) => typeof value === 'string' && value.trim().length > 0;
+
+const prettyPrint = (value, max = 3000) => {
+  const text = typeof value === 'string' ? value : JSON.stringify(value, null, 2);
+  return text.length > max ? `${text.slice(0, max)}\n...TRUNCATED (${text.length} chars)...` : text;
+};
+
+const normalizeBaseUrl = (baseUrl) => {
+  const candidate = baseUrl ?? process.env.OLLAMA_BASE_URL ?? DEFAULT_BASE_URL;
+  if (!isString(candidate)) {
+    throw new TypeError('llmjs2: Invalid OLLAMA_BASE_URL. Provide a valid URL string.');
+  }
+
+  try {
+    return new URL(candidate).toString().replace(/\/+$|\/$/, '');
+  } catch {
+    throw new TypeError(`llmjs2: Invalid base URL "${candidate}".`);
+  }
+};
+
+const getApiKey = (apiKey) => (isString(apiKey) ? apiKey : process.env.OLLAMA_API_KEY);
+
+const buildEndpoint = (baseUrl) => `${normalizeBaseUrl(baseUrl)}${DEFAULT_CHAT_PATH}`;
+
+const parseModel = (model) => {
+  if (!isString(model) || !model.includes('/')) {
+    throw new TypeError('llmjs2: model must be provider/model-name.');
+  }
+
+  const [provider, ...rest] = model.split('/');
+  const modelName = rest.join('/').trim();
+
+  if (!isString(provider) || !isString(modelName)) {
+    throw new TypeError('llmjs2: model must be provider/model-name.');
+  }
+
+  return { provider: provider.trim(), modelName };
+};
+
+const normalizeCompletionInput = (modelOrOptions, prompt) => {
+  if (isString(modelOrOptions)) {
+    if (!isString(prompt)) {
+      throw new TypeError('llmjs2: prompt must be a non-empty string.');
+    }
+
+    return {
+      model: modelOrOptions.trim(),
+      messages: [{ role: 'user', content: prompt.trim() }],
+      baseUrl: undefined,
+      apiKey: undefined,
+    };
+  }
+
+  if (typeof modelOrOptions !== 'object' || modelOrOptions === null) {
+    throw new TypeError('llmjs2: completion requires either (model, prompt) or an options object.');
+  }
+
+  const { model, messages, prompt: promptField, ollamaBaseUrl, ollamaApiKey } = modelOrOptions;
+
+  if (!isString(model)) {
+    throw new TypeError('llmjs2: options.model must be a non-empty string.');
+  }
+
+  const normalizedMessages = Array.isArray(messages)
+    ? messages
+    : isString(promptField)
+    ? [{ role: 'user', content: promptField.trim() }]
+    : undefined;
+
+  if (!Array.isArray(normalizedMessages) || normalizedMessages.length === 0) {
+    throw new TypeError('llmjs2: options.messages or options.prompt must be provided.');
+  }
+
+  return {
+    model: model.trim(),
+    messages: normalizedMessages,
+    baseUrl: ollamaBaseUrl,
+    apiKey: ollamaApiKey,
+  };
+};
+
+const normalizeMessages = (messages) =>
+  messages.map((message, index) => {
+    if (!message || typeof message !== 'object' || !isString(message.content)) {
+      // If it's a tool call response from the assistant, it might not have content
+      if (message.role === 'assistant' && (message.tool_calls || message.tool_call)) {
+          return message;
+      }
+      throw new TypeError(`llmjs2: messages[${index}] must be an object with a non-empty content string.`);
+    }
+
+    return {
+      role: isString(message.role) ? message.role : 'user',
+      content: message.content,
+    };
+  });
+
+const isUrl = (value) => {
+  if (!isString(value)) return false;
+  try {
+    new URL(value);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+const fileExists = async (filePath) => {
+  if (!isString(filePath)) return false;
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+const loadReference = async (reference) => {
+  if (Buffer.isBuffer(reference)) {
+    return reference.toString('utf8');
+  }
+
+  if (!isString(reference)) {
+    throw new TypeError('llmjs2: references must be strings or buffers.');
+  }
+
+  if (isUrl(reference)) {
+    try {
+      const response = await fetch(reference);
+      if (response.ok) {
+        return await response.text();
+      }
+    } catch {
+      return reference;
+    }
+    return reference;
+  }
+
+  if (await fileExists(reference)) {
+    try {
+      return (await fs.readFile(reference)).toString('utf8');
+    } catch {
+      return reference;
+    }
+  }
+
+  return reference;
+};
+
+const loadImage = async (image) => {
+  if (Buffer.isBuffer(image)) {
+    return image.toString('base64');
+  }
+
+  if (!isString(image)) {
+    throw new TypeError('llmjs2: images must be strings or buffers.');
+  }
+
+  if (isUrl(image)) {
+    try {
+      const response = await fetch(image);
+      if (!response.ok) {
+        throw new Error(`Failed to download image: ${response.status}`);
+      }
+      const arrayBuffer = await response.arrayBuffer();
+      return Buffer.from(arrayBuffer).toString('base64');
+    } catch {
+      return image;
+    }
+  }
+
+  if (await fileExists(image)) {
+    try {
+      const data = await fs.readFile(image);
+      return data.toString('base64');
+    } catch {
+      return image;
+    }
+  }
+
+  return image;
+};
+
+const buildGeneratePrompt = (userPrompt, references) => {
+  const sections = [`User prompt: ${userPrompt}`];
+
+  if (references.length) {
+    sections.push('References:');
+    sections.push(...references.map((item, index) => `  [${index + 1}] ${item}`));
+  }
+
+  sections.push('Generate a response using the prompt and references above.');
+  return sections.join('\n');
+};
+
+const parseToolCall = (text) => {
+  if (!isString(text)) return undefined;
+  const trimmed = text.trim();
+  
+  // Try to parse direct JSON first (often returned by tool-calling models)
+  try {
+    const data = JSON.parse(trimmed);
+    // Support both direct {tool, arguments} and OpenAI-style {name, arguments}
+    const name = data.tool || data.name;
+    const args = data.arguments;
+    if (isString(name) && typeof args === 'object') {
+      return { tool: name, arguments: args };
+    }
+  } catch {
+    // Fallback to regex for text-wrapped JSON
+    const jsonMatch = trimmed.match(/({[\s\S]*})/);
+    if (jsonMatch) {
+      try {
+        const data = JSON.parse(jsonMatch[1]);
+        const name = data.tool || data.name;
+        if (isString(name)) return { tool: name, arguments: data.arguments || {} };
+      } catch { /* ignore */ }
+    }
+  }
+
+  return undefined;
+};
+
+const runTool = async (toolCall, tools) => {
+  const tool = Array.isArray(tools) ? tools.find((item) => item.name === toolCall.tool) : undefined;
+  if (!tool) {
+    throw new Error(`llmjs2: Tool not found: ${toolCall.tool}`);
+  }
+
+  if (typeof tool.handler !== 'function') {
+    throw new TypeError(`llmjs2: Tool handler for ${toolCall.tool} must be a function.`);
+  }
+
+  const result = await tool.handler(toolCall.arguments || {});
+  return String(result);
+};
+
+const extractText = (body) => {
+  if (!body || typeof body !== 'object') return undefined;
+  const message = body.message;
+
+  // Handle native Ollama/OpenAI tool calls
+  if (message?.tool_calls && message.tool_calls.length > 0) {
+    return JSON.stringify(message.tool_calls[0].function);
+  }
+
+  if (isString(message?.content)) return message.content;
+  if (isString(body.result)) return body.result;
+  if (isString(body.content)) return body.content;
+  if (Array.isArray(body.output) && isString(body.output[0]?.content)) return body.output[0].content;
+  if (Array.isArray(body.choices)) {
+    const choice = body.choices[0];
+    if (choice?.message?.tool_calls) return JSON.stringify(choice.message.tool_calls[0].function);
+    if (isString(choice?.message?.content)) return choice.message.content;
+    if (isString(choice?.text)) return choice.text;
+  }
+};
+
+const extractError = (body) => {
+  if (!body || typeof body !== 'object') return undefined;
+  if (isString(body.error)) return body.error;
+  if (isString(body.message)) return body.message;
+  if (isString(body.detail)) return body.detail;
+  if (Array.isArray(body.errors) && isString(body.errors[0]?.message)) return body.errors[0].message;
+};
+
+const wrapFetchError = (error, url) => {
+  if (
+    error instanceof TypeError ||
+    error?.name === 'FetchError' ||
+    ['ECONNREFUSED', 'ENOTFOUND', 'EAI_AGAIN'].includes(error?.code) ||
+    error?.message?.includes('fetch')
+  ) {
+    throw new Error(`llmjs2: Could not connect to ${url}. Check your OLLAMA_BASE_URL.`);
+  }
+  throw error;
+};
+
+const requestOllama = async (modelName, messages, baseUrl, apiKey, images = [], tools = []) => {
+  const url = buildEndpoint(baseUrl);
+  const headers = { 'Content-Type': 'application/json' };
+  const token = getApiKey(apiKey);
+
+  if (token) {
+    headers.Authorization = `Bearer ${token}`;
+  }
+
+  const payloadMessages = Array.isArray(images) && images.length
+    ? messages.map((message, index) =>
+        index === 0 && message.role === 'user'
+          ? { ...message, images }
+          : message
+      )
+    : messages;
+
+  const payload = { model: modelName, messages: payloadMessages, stream: false };
+
+  // Fixed tool payload format for Ollama/OpenAI compatibility
+  if (Array.isArray(tools) && tools.length > 0) {
+    payload.tools = tools.map((tool) => ({
+      type: 'function',
+      function: {
+        name: tool.name,
+        description: tool.description,
+        parameters: tool.parameters,
+      }
+    }));
+  }
+
+  //console.log('llmjs2: Ollama request:\n' + prettyPrint({ url, headers, payload }));
+
+  let response;
+  try {
+    response = await fetch(url, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(payload),
+    });
+  } catch (error) {
+    wrapFetchError(error, url);
+  }
+
+  const text = await response.text();
+  let body;
+
+  try {
+    body = text ? JSON.parse(text) : undefined;
+  } catch {
+    body = undefined;
+  }
+
+  //console.log('llmjs2: Ollama raw response:\n' + prettyPrint({ url, status: response.status, text, body }));
+
+  if (!response.ok) {
+    if (response.status === 404) {
+      throw new Error(`llmjs2: Model "${modelName}" not found on provider "ollama".`);
+    }
+
+    const message = extractError(body) || text || response.statusText;
+    throw new Error(`llmjs2: Request to ${url} failed with status ${response.status}: ${message}`);
+  }
+
+  const responseText = extractText(body);
+  if (!isString(responseText)) {
+    throw new Error(`llmjs2: Could not parse assistant response from ${url}.`);
+  }
+
+  return responseText;
+};
+
+export async function completion(modelOrOptions, prompt) {
+  const { model, messages, baseUrl, apiKey } = normalizeCompletionInput(modelOrOptions, prompt);
+  const { provider, modelName } = parseModel(model);
+
+  if (provider !== 'ollama') {
+    throw new Error(`llmjs2: Unsupported provider "${provider}".`);
+  }
+
+  return requestOllama(modelName, normalizeMessages(messages), baseUrl, apiKey);
+}
+
+export async function generate(optionsOrModel, userPrompt, images = [], references = [], tools = []) {
+  const options =
+    typeof optionsOrModel === 'object' && optionsOrModel !== null && !isString(optionsOrModel)
+      ? optionsOrModel
+      : {
+          model: optionsOrModel,
+          userPrompt,
+          images,
+          references,
+          tools,
+        };
+
+  const {
+    model,
+    userPrompt: promptText,
+    messages: providedMessages,
+    images: imageInput = [],
+    references: referenceInput = [],
+    tools: toolInput = [],
+    systemPrompt,
+    ollamaBaseUrl,
+    ollamaApiKey,
+  } = options;
+
+  if (!isString(model)) {
+    throw new TypeError('llmjs2: model must be a non-empty string.');
+  }
+
+  const { provider, modelName } = parseModel(model.trim());
+  if (provider !== 'ollama') {
+    throw new Error(`llmjs2: Unsupported provider "${provider}".`);
+  }
+
+  const imageList = Array.isArray(imageInput) ? imageInput : [imageInput];
+  const referenceList = Array.isArray(referenceInput) ? referenceInput : [referenceInput];
+  const toolList = Array.isArray(toolInput) ? toolInput : [];
+
+  const resolvedImages = (await Promise.all(imageList.map(loadImage))).filter(isString);
+  const resolvedReferences = (await Promise.all(referenceList.map(loadReference))).filter(isString);
+
+  const messages = providedMessages
+    ? normalizeMessages(providedMessages)
+    : (() => {
+        if (!isString(promptText)) {
+          throw new TypeError('llmjs2: userPrompt must be a non-empty string when messages are not provided.');
+        }
+
+        const prompt = buildGeneratePrompt(promptText.trim(), resolvedReferences);
+        const result = [];
+
+        if (isString(systemPrompt)) {
+          result.push({ role: 'system', content: systemPrompt.trim() });
+        }
+
+        result.push({ role: 'user', content: prompt });
+        return normalizeMessages(result);
+      })();
+
+  // Simplified tool mapping to be passed to requestOllama
+  const toolDefinitions = toolList.map((tool) => ({
+    name: tool.name,
+    description: tool.description,
+    parameters: tool.parameters,
+  }));
+
+  let response = await requestOllama(
+    modelName,
+    messages,
+    ollamaBaseUrl,
+    ollamaApiKey,
+    resolvedImages,
+    toolDefinitions
+  );
+
+  let cycles = 0;
+  while (cycles < 3) {
+    const toolCall = parseToolCall(response);
+    if (!toolCall) {
+      return response;
+    }
+
+    const toolResult = await runTool(toolCall, toolList);
+    messages.push({ role: 'assistant', content: response });
+    messages.push({ role: 'user', content: `Tool ${toolCall.tool} returned:\n${toolResult}` });
+
+    response = await requestOllama(
+      modelName,
+      messages,
+      ollamaBaseUrl,
+      ollamaApiKey,
+      resolvedImages,
+      toolDefinitions
+    );
+
+    cycles += 1;
+  }
+
+  return response;
+}

package/package.json

@@ -1,55 +1,15 @@
 {
   "name": "llmjs2",
-  "version": "1.0.0",
-  "description": "LLM abstraction layer for Node.js. Unified API for OpenAI and Ollama with error handling and retry logic.",
-  "main": "dist/dex.js",
-  "types": "dist/index.d.ts",
+  "version": "1.0.5",
+  "description": "Minimal zero-dependency Node.js client for Ollama and Ollama Cloud.",
   "type": "module",
+  "main": "index.js",
   "exports": {
     ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "import": "./index.js"
     }
   },
-  "keywords": [
-    "llm",
-    "llmjs2",
-    "openai",
-    "ollama",
-    "ai",
-    "machine-learning",
-    "abstraction",
-    "unified-api"
-  ],
-  "author": "littlellmjs",
-  "license": "MIT",
-  "files": [
-    "dist",
-    "src",
-    "README.md",
-    "LICENSE"
-  ],
-  "engines": {
-    "node": ">=16.0.0"
-  },
-  "scripts": {
-    "build": "tsc",
-    "build:watch": "tsc --watch",
-    "clean": "rm -rf dist",
-    "test": "node --test test.js",
-    "test:watch": "node --watch test.js",
-    "prepublishOnly": "npm run build && npm run test"
-  },
-  "devDependencies": {
-    "@types/node": "^20.10.0",
-    "typescript": "^5.9.3"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/littlellmjs/llmjs2"
-  },
-  "bugs": {
-    "url": "https://github.com/littlellmjs/llmjs2/issues"
-  },
-  "homepage": "https://github.com/littlellmjs/llmjs2#readme"
+  "types": "index.d.ts",
+  "keywords": ["llm", "ollama", "node", "ai", "client", "llmjs", "llmjs2"],
+  "license": "MIT"
 }

package/spec.txt

@@ -0,0 +1,73 @@
+This specification defines **llmjs2**, a minimalist Node.js library designed to provide a robust, standardized interface for interacting with LLMs. It focuses on a "zero-config" developer experience, initially targeting **Ollama** with a fallback to **Ollama Cloud**.
+
+---
+
+## 1. Project Identity
+* **Name:** `llmjs2`
+* **Mission:** To be the most lightweight, concise, and robust bridge between Node.js applications and AI models.
+* **Core Principle:** Favor convention over configuration. Use OpenAI-compatible schemas to minimize the learning curve.
+
+---
+
+## 2. Technical Requirements
+* **Runtime:** Node.js 18.0.0+ (Required for native `fetch` and `web streams`).
+* **Module System:** ESM (EcmaScript Modules).
+* **Dependencies:** **Zero.** The library must not depend on external packages to ensure a small footprint and security.
+
+---
+
+## 3. Configuration & Environment
+The library automatically resolves connection details using the following hierarchy:
+1.  **Explicit Config:** Passed during initialization (if implemented).
+2.  **Environment Variables:** * `OLLAMA_BASE_URL`: The target API host. 
+    * `OLLAMA_API_KEY`: The bearer token for authenticated proxies or Cloud access.
+3.  **Default Fallback:** `https://api.ollama.com` (Ollama Cloud).
+
+---
+
+## 4. API Specification
+
+### The `completion` Function
+The library exports a single overloaded function: `completion`.
+
+**Signatures:**
+* `completion(model: string, prompt: string): Promise<string>`
+* `completion(options: CompletionOptions): Promise<string>`
+
+**Input Object (`CompletionOptions`):**
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| **model** | `string` | Format: `provider/model-name` (e.g., `ollama/llama3`). |
+| **messages** | `Array` | Standard OpenAI `role`/`content` objects. |
+
+**Output:** * Returns a **Promise** that resolves to a **string** containing the assistant's response.
+
+---
+
+## 5. Internal Architecture
+
+### A. Provider Routing
+The library utilizes a "prefix-router." It splits the `model` string at the first `/`.
+* If prefix is `ollama`, the request is routed to the `OllamaProvider`.
+* The prefix is stripped before the request is sent to the provider's API.
+
+### B. Request Normalization
+To maintain simplicity, **llmjs2** ignores hyper-parameters like `temperature` or `max_tokens` in the high-level API, allowing the model's internal defaults to govern the output. This ensures the library remains "future-proof" against changing API parameters.
+
+### C. Error Handling
+The library must catch and wrap low-level network errors into high-level, actionable messages:
+* **Connection Error:** "llmjs2: Could not connect to [URL]. Check your OLLAMA_BASE_URL."
+* **Model Error:** "llmjs2: Model [name] not found on provider [provider]."
+
+---
+
+## 6. Implementation Checklist
+
+* [ ] **Env Loader:** Logic to check `process.env` and apply fallbacks.
+* [ ] **URL Parser:** Logic to ensure the base URL and `/api/chat` path are joined correctly without double slashes.
+* [ ] **Fetch Wrapper:** A standard `POST` implementation using `Headers` and `body`.
+* [ ] **Response Extractor:** Logic to navigate the JSON response (e.g., `json.message.content`) and return the raw string.
+
+---
+
+**Would you like me to generate the actual `index.ts` file that implements this full specification?**

package/test-generate-tools-suite.js

@@ -0,0 +1,100 @@
+import { generate } from './index.js';
+
+const MODEL = 'ollama/qwen3.5:397b-cloud';
+
+const tools = [
+  {
+    name: 'get_weather',
+    description: 'Get the current weather for a location',
+    parameters: {
+      location: {
+        type: 'string',
+        required: true,
+        description: 'The city and state, e.g. San Francisco, CA',
+      },
+      unit: {
+        type: 'string',
+        enum: ['celsius', 'fahrenheit'],
+        description: 'Temperature unit',
+      },
+    },
+    handler: ({ location, unit = 'fahrenheit' }) => {
+      const weatherData = {
+        'San Francisco, CA': { temp: 72, condition: 'Sunny' },
+        'New York, NY': { temp: 45, condition: 'Cloudy' },
+        'London, UK': { temp: 48, condition: 'Rainy' },
+      };
+
+      const data = weatherData[location] || { temp: 70, condition: 'Unknown' };
+      const temp = unit === 'celsius' ? Math.round((data.temp - 32) * (5 / 9)) : data.temp;
+      return `Weather in ${location}: ${temp}°${unit === 'celsius' ? 'C' : 'F'}, ${data.condition}`;
+    },
+  },
+];
+
+const tests = [
+  {
+    name: 'Tool call with default unit',
+    input: {
+      model: MODEL,
+      userPrompt: 'Please use get_weather to fetch the weather for San Francisco, CA.',
+      tools,
+    },
+    expected: /San Francisco, CA/i,
+  },
+  {
+    name: 'Tool call with explicit celsius',
+    input: {
+      model: MODEL,
+      userPrompt: 'Please use get_weather to fetch the weather for London, UK in celsius.',
+      tools,
+    },
+    expected: /London, UK/i,
+  },
+  {
+    name: 'No tool needed direct answer',
+    input: {
+      model: MODEL,
+      userPrompt: 'What is 2 + 2?',
+      tools,
+    },
+    expected: /4|four/i,
+  },
+  {
+    name: 'Explicit messages payload with tool definitions',
+    input: {
+      model: MODEL,
+      messages: [
+        { role: 'system', content: 'You are a tool-aware assistant.' },
+        { role: 'user', content: 'Use get_weather for New York, NY.' },
+      ],
+      tools,
+    },
+    expected: /Weather in New York, NY/i,
+  },
+];
+
+const runTest = async (test) => {
+  console.log(`\n=== ${test.name} ===`);
+  try {
+    const result = await generate(test.input);
+    console.log('Result:');
+    console.log(result);
+    if (test.expected && !test.expected.test(result)) {
+      console.warn('Warning: result did not match expected pattern.');
+    }
+  } catch (error) {
+    console.error('Error:', error?.message ?? error);
+  }
+};
+
+const runAll = async () => {
+  for (const test of tests) {
+    await runTest(test);
+  }
+};
+
+runAll().catch((error) => {
+  console.error('Unexpected failure:', error);
+  process.exit(1);
+});