@nemesis-oss/ollama-sdk 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -5,6 +5,40 @@ All notable changes to `@nemesis-oss/ollama-sdk` will be documented in this file
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.0] - 2026-08-23
+
+Brings the SDK's typed surface up to date with Ollama v0.13.3+.
+
+### Added
+
+- **`/api/create` field parity:** `CreateRequestOptions` now exposes the documented
+  `template`, `renderer`, `parser`, `license`, `system`, `parameters`, and `messages`
+  fields alongside the existing `from`/`files`/`adapters`/`quantize`. The old
+  `modelfile` string field is kept for backward compatibility but marked `@deprecated`
+  in favor of the discrete fields.
+- **OpenAI Responses API bridge:** `client.openai.responses()` / `createResponses()`
+  POST to `/v1/responses`. Ollama implements this non-statefully, so
+  `previous_response_id`/`conversation` are typed but documented as ignored.
+- **`reasoning_effort` / `reasoning.effort`:** Added to `OpenAIChatCompletionRequest`
+  for thinking models (`deepseek-r1`, `qwen3`, etc.), matching Ollama's OpenAI
+  compatibility docs.
+- **`tool_choice` / `parallel_tool_calls`:** Now typed as accepted-but-ignored on
+  `OpenAIChatCompletionRequest` (previously omitted entirely), so passing a standard
+  OpenAI request object type-checks without modification.
+- **Raw image bytes:** `Message.images` and `GenerateRequestOptions.images` accept
+  `Uint8Array` alongside base64 strings. `OllamaClient.chat()`/`generate()` encode any
+  `Uint8Array` entries to base64 automatically via the new `encodeImage` utility
+  (exported from the package root), using `Buffer` on Node and `btoa` elsewhere so it
+  stays Edge Runtime-safe.
+- **`doneReason` in stream results:** `ChatStreamResult`/`GenerateStreamResult` now
+  carry `doneReason`, mapped from the final chunk's `done_reason` (e.g. `"stop"`,
+  `"load"`, `"unload"`).
+
+### Fixed
+
+- `package.json`'s `homepage`, `repository`, and `bugs` URLs now point at
+  `ollama-sdk` instead of the pre-rename `ollama-client-ts`.
+
 ## [1.0.0] - 2026-08-17
 
 First public release. The version was `0.1.0` throughout development but was never

package/README.md

@@ -1,6 +1,6 @@
 # @nemesis-oss/ollama-sdk
 
-[![CI](https://github.com/shubhamtaywade82/ollama-client-ts/actions/workflows/ci.yml/badge.svg)](https://github.com/shubhamtaywade82/ollama-client-ts/actions/workflows/ci.yml)
+[![CI](https://github.com/shubhamtaywade82/ollama-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/shubhamtaywade82/ollama-sdk/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/@nemesis-oss/ollama-sdk.svg)](https://www.npmjs.com/package/@nemesis-oss/ollama-sdk)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
@@ -11,12 +11,12 @@
 ## Key Features
 
 - 🚀 **Native Web Standards**: Built on native `fetch` and Web Streams. Zero external HTTP dependencies.
-- 🧠 **Reasoning & Thinking Tokens**: First-class support for reasoning models (`qwen3.5:2b`, `deepseek-r1`) with discrete `thinking` and `token` streaming events.
+- 🧠 **Reasoning & Thinking Tokens**: First-class support for reasoning models (`qwen3:8b`, `deepseek-r1:8b`) with discrete `thinking` and `token` streaming events.
 - 🎯 **Zod-Powered Structured Outputs**: Strictly typed schema enforcement via `chatWithSchema` and `generateWithSchema` with resilient markdown JSON parsing.
 - 🛠️ **Autonomous Agent & Tool Calling**: Multi-turn agent loop (`Agent`) with automated tool execution, parameter validation, and self-correcting error recovery.
 - 🌐 **High Availability & Failover**: Multi-endpoint registry with priority routing, circuit breaker failover, and active health checks.
 - 🔌 **Model Context Protocol (MCP)**: Native adapters to convert MCP tools into Ollama-compatible function schemas.
-- 🌉 **OpenAI & Anthropic Compatibility Bridges**: Built-in clients for `/v1/chat/completions`, `/v1/models`, and `/v1/messages`.
+- 🌉 **OpenAI & Anthropic Compatibility Bridges**: Built-in clients for `/v1/chat/completions`, `/v1/responses`, `/v1/models`, and `/v1/messages`, including `reasoning_effort`/`reasoning.effort` for thinking models.
 - 🌊 **Web Stream Adapters**: Drop-in adapters (`toTextStream`, `toDataStream`, `toResponse`) for Next.js Route Handlers and Vercel AI SDK.
 - 📈 **OpenTelemetry Instrumentation**: Automatic spans for HTTP requests, endpoint failover, chat/generate calls, and agent runs — zero-cost when OpenTelemetry isn't installed.
 - ⚡ **Edge Runtime Verified**: CI bundles and runs the client in a real Edge Runtime sandbox (Cloudflare Workers/Vercel Edge-compatible) with zero Node.js APIs.
@@ -45,7 +45,7 @@ const client = new OllamaClient();
 
 // Text helper
 const answer = await client.chatText({
-  model: 'qwen3.5:2b',
+  model: 'qwen3:8b',
   messages: [{ role: 'user', content: 'Explain quantum computing in one sentence.' }],
 });
 console.log(answer);
@@ -55,7 +55,7 @@ console.log(answer);
 
 ```typescript
 const stream = await client.chatStream({
-  model: 'qwen3.5:2b',
+  model: 'qwen3:8b',
   messages: [{ role: 'user', content: 'What is 18 * 4?' }],
   options: { temperature: 0 },
 });
@@ -86,7 +86,7 @@ const ProductSchema = z.object({
 
 const product = await client.chatWithSchema(
   {
-    model: 'qwen3.5:2b',
+    model: 'qwen3:8b',
     messages: [{ role: 'user', content: 'Generate a gaming keyboard item.' }],
   },
   ProductSchema,
@@ -131,7 +131,7 @@ const registry = new ToolRegistry([weatherTool]);
 const agent = new Agent(client, { tools: registry, maxIterations: 5 });
 
 const response = await agent.run({
-  model: 'qwen3.5:2b',
+  model: 'qwen3:8b',
   messages: [{ role: 'user', content: 'What is the weather in Tokyo?' }],
 });
 
@@ -191,7 +191,7 @@ import { toResponse } from '@nemesis-oss/ollama-sdk';
 export async function POST(req: Request) {
   const { messages } = await req.json();
   const stream = await client.chatStream({
-    model: 'qwen3.5:2b',
+    model: 'qwen3:8b',
     messages,
   });
 
@@ -208,6 +208,13 @@ const openAIRes = await client.openai.chatCompletions({
   messages: [{ role: 'user', content: 'Hello via OpenAI bridge' }],
 });
 
+// OpenAI Responses API endpoint (/v1/responses) — added in Ollama v0.13.3
+const responsesRes = await client.openai.responses({
+  model: 'llama3.2',
+  input: 'Hello via the OpenAI Responses bridge',
+});
+console.log(responsesRes.output[0]?.content[0]?.text);
+
 // Anthropic compatibility endpoint (/v1/messages)
 const anthropicRes = await client.anthropic.messages({
   model: 'llama3.2',
@@ -215,6 +222,25 @@ const anthropicRes = await client.anthropic.messages({
 });
 ```
 
+`/v1/responses` is implemented non-statefully by Ollama: send the full conversation in
+`input` on every call — `previous_response_id` and `conversation` are accepted for
+OpenAI request-shape compatibility but ignored (see `OpenAIResponsesRequest` JSDoc).
+
+For thinking models (`deepseek-r1`, `qwen3`, etc.), both compatibility bridges' chat
+completions request accept a reasoning effort knob:
+
+```typescript
+await client.openai.chatCompletions({
+  model: 'deepseek-r1:8b',
+  messages: [{ role: 'user', content: 'Solve: 17 * 23' }],
+  reasoning_effort: 'high', // or `reasoning: { effort: 'high' }`
+});
+```
+
+`tool_choice` and `parallel_tool_calls` are also typed on the request so a standard
+OpenAI request object type-checks unmodified, but Ollama's compat layer does not honor
+either — see the `@remarks` on each field in `OpenAIChatCompletionRequest`.
+
 ### Multi-Endpoint High Availability Failover
 
 ```typescript
@@ -325,7 +351,7 @@ the original error via the standard `cause` property:
 import { OllamaClientError, OllamaRateLimitError } from '@nemesis-oss/ollama-sdk';
 
 try {
-  await client.chatText({ model: 'qwen3.5:2b', messages: [...] });
+  await client.chatText({ model: 'qwen3:8b', messages: [...] });
 } catch (err) {
   if (err instanceof OllamaRateLimitError) {
     console.warn(`Rate limited, retry after ${err.retryAfterMs}ms`);
@@ -347,7 +373,7 @@ observe per-endpoint circuit state directly.
 
 ## Testing
 
-The test suite contains 105 automated tests across 4 testing tiers:
+The test suite contains 114 automated tests across 4 testing tiers:
 
 ```bash
 # Run unit, integration, and functional test suite

package/dist/{compose-DC11aDJn.d.cts → compose-DJjVpDrk.d.cts}

@@ -28,7 +28,12 @@ interface ToolCall {
 interface Message {
     readonly role: Role;
     readonly content: string;
-    readonly images?: readonly string[] | undefined;
+    /**
+     * Base64-encoded image strings, or raw `Uint8Array` image bytes. `Uint8Array` entries
+     * are base64-encoded automatically (see {@link encodeImage}) before the request reaches
+     * the wire — Ollama's REST API only ever accepts base64 strings.
+     */
+    readonly images?: readonly (string | Uint8Array)[] | undefined;
     readonly tool_calls?: readonly ToolCall[] | undefined;
     /** Set on a `role: 'tool'` message to identify which {@link ToolCall.id} this answers. */
     readonly tool_call_id?: string | undefined;
@@ -123,7 +128,12 @@ interface GenerateRequestOptions extends RequestCancellationOptions {
     readonly stream?: boolean | undefined;
     readonly raw?: boolean | undefined;
     readonly format?: FormatOption | undefined;
-    readonly images?: readonly string[] | undefined;
+    /**
+     * Base64-encoded image strings, or raw `Uint8Array` image bytes. `Uint8Array` entries
+     * are base64-encoded automatically (see {@link encodeImage}) before the request reaches
+     * the wire — Ollama's REST API only ever accepts base64 strings.
+     */
+    readonly images?: readonly (string | Uint8Array)[] | undefined;
     readonly options?: ModelOptions | undefined;
     readonly keep_alive?: string | number | undefined;
     readonly think?: boolean | 'low' | 'medium' | 'high' | 'max' | undefined;
@@ -225,12 +235,29 @@ interface PushRequestOptions extends RequestCancellationOptions {
 }
 interface CreateRequestOptions extends RequestCancellationOptions {
     readonly model: string;
+    /**
+     * @deprecated Not part of the official `/api/create` REST payload — Ollama's server
+     * only ever accepted this in older client tooling that assembled a Modelfile string
+     * client-side. Use the discrete fields below instead (`from`, `files`, `adapters`,
+     * `template`, `system`, `parameters`, `license`, `messages`), which map 1:1 onto the
+     * documented Modelfile instructions and are validated server-side. Kept for backward
+     * compatibility with existing callers; not read by this SDK, but still forwarded as-is
+     * in the request body for any server/proxy that inspects it.
+     */
     readonly modelfile?: string | undefined;
     readonly stream?: boolean | undefined;
     readonly quantize?: string | undefined;
     readonly from?: string | undefined;
     readonly files?: Record<string, string> | undefined;
     readonly adapters?: Record<string, string> | undefined;
+    readonly template?: string | undefined;
+    readonly renderer?: string | undefined;
+    readonly parser?: string | undefined;
+    readonly license?: string | readonly string[] | undefined;
+    readonly system?: string | undefined;
+    /** Modelfile `PARAMETER` instructions, e.g. `{ temperature: 0.7, stop: ['\n'] }`. */
+    readonly parameters?: Record<string, unknown> | undefined;
+    readonly messages?: readonly Message[] | undefined;
 }
 interface DeleteRequestOptions extends RequestCancellationOptions {
     readonly model: string;

package/dist/{compose-DC11aDJn.d.ts → compose-DJjVpDrk.d.ts}

@@ -28,7 +28,12 @@ interface ToolCall {
 interface Message {
     readonly role: Role;
     readonly content: string;
-    readonly images?: readonly string[] | undefined;
+    /**
+     * Base64-encoded image strings, or raw `Uint8Array` image bytes. `Uint8Array` entries
+     * are base64-encoded automatically (see {@link encodeImage}) before the request reaches
+     * the wire — Ollama's REST API only ever accepts base64 strings.
+     */
+    readonly images?: readonly (string | Uint8Array)[] | undefined;
     readonly tool_calls?: readonly ToolCall[] | undefined;
     /** Set on a `role: 'tool'` message to identify which {@link ToolCall.id} this answers. */
     readonly tool_call_id?: string | undefined;
@@ -123,7 +128,12 @@ interface GenerateRequestOptions extends RequestCancellationOptions {
     readonly stream?: boolean | undefined;
     readonly raw?: boolean | undefined;
     readonly format?: FormatOption | undefined;
-    readonly images?: readonly string[] | undefined;
+    /**
+     * Base64-encoded image strings, or raw `Uint8Array` image bytes. `Uint8Array` entries
+     * are base64-encoded automatically (see {@link encodeImage}) before the request reaches
+     * the wire — Ollama's REST API only ever accepts base64 strings.
+     */
+    readonly images?: readonly (string | Uint8Array)[] | undefined;
     readonly options?: ModelOptions | undefined;
     readonly keep_alive?: string | number | undefined;
     readonly think?: boolean | 'low' | 'medium' | 'high' | 'max' | undefined;
@@ -225,12 +235,29 @@ interface PushRequestOptions extends RequestCancellationOptions {
 }
 interface CreateRequestOptions extends RequestCancellationOptions {
     readonly model: string;
+    /**
+     * @deprecated Not part of the official `/api/create` REST payload — Ollama's server
+     * only ever accepted this in older client tooling that assembled a Modelfile string
+     * client-side. Use the discrete fields below instead (`from`, `files`, `adapters`,
+     * `template`, `system`, `parameters`, `license`, `messages`), which map 1:1 onto the
+     * documented Modelfile instructions and are validated server-side. Kept for backward
+     * compatibility with existing callers; not read by this SDK, but still forwarded as-is
+     * in the request body for any server/proxy that inspects it.
+     */
     readonly modelfile?: string | undefined;
     readonly stream?: boolean | undefined;
     readonly quantize?: string | undefined;
     readonly from?: string | undefined;
     readonly files?: Record<string, string> | undefined;
     readonly adapters?: Record<string, string> | undefined;
+    readonly template?: string | undefined;
+    readonly renderer?: string | undefined;
+    readonly parser?: string | undefined;
+    readonly license?: string | readonly string[] | undefined;
+    readonly system?: string | undefined;
+    /** Modelfile `PARAMETER` instructions, e.g. `{ temperature: 0.7, stop: ['\n'] }`. */
+    readonly parameters?: Record<string, unknown> | undefined;
+    readonly messages?: readonly Message[] | undefined;
 }
 interface DeleteRequestOptions extends RequestCancellationOptions {
     readonly model: string;

package/dist/index.cjs

@@ -822,6 +822,7 @@ function aggregateChat(accumulated, chunk) {
     },
     model: chunk.model,
     done: chunk.done,
+    doneReason: chunk.done ? chunk.done_reason : accumulated.doneReason,
     totalDurationMs: chunk.done && chunk.total_duration !== void 0 ? chunk.total_duration / NANOS_PER_MS : accumulated.totalDurationMs,
     usage: chunk.done ? extractUsage(chunk) : accumulated.usage,
     raw: chunk
@@ -871,6 +872,7 @@ function aggregateGenerate(accumulated, chunk) {
     response: accumulated.response + (chunk.response ?? ""),
     model: chunk.model,
     done: chunk.done,
+    doneReason: chunk.done ? chunk.done_reason : accumulated.doneReason,
     totalDurationMs: chunk.done && chunk.total_duration !== void 0 ? chunk.total_duration / NANOS_PER_MS : accumulated.totalDurationMs,
     usage: chunk.done ? extractUsage(chunk) : accumulated.usage,
     raw: chunk
@@ -1159,6 +1161,16 @@ var OpenAICompatClient = class {
       signal
     });
   }
+  async createResponses(request, signal) {
+    return this.http.request({
+      path: "/v1/responses",
+      body: request,
+      signal
+    });
+  }
+  async responses(request, signal) {
+    return this.createResponses(request, signal);
+  }
 };
 
 // src/integrations/anthropic.ts
@@ -1179,6 +1191,32 @@ var AnthropicCompatClient = class {
   }
 };
 
+// src/utils.ts
+async function encodeImage(image) {
+  if (typeof image === "string") return image;
+  const bufferCtor = globalThis.Buffer;
+  if (bufferCtor !== void 0) return bufferCtor.from(image).toString("base64");
+  const CHUNK_SIZE = 32768;
+  let binary = "";
+  for (let i = 0; i < image.length; i += CHUNK_SIZE) {
+    binary += String.fromCharCode(...image.subarray(i, i + CHUNK_SIZE));
+  }
+  return btoa(binary);
+}
+async function encodeImages(images) {
+  if (images === void 0) return void 0;
+  return Promise.all(images.map((image) => encodeImage(image)));
+}
+async function withEncodedImages(req) {
+  if (!req.images?.some((image) => image instanceof Uint8Array)) return req;
+  return { ...req, images: await encodeImages(req.images) };
+}
+async function withEncodedMessageImages(messages) {
+  if (!messages.some((message) => message.images?.some((image) => image instanceof Uint8Array)))
+    return messages;
+  return Promise.all(messages.map((message) => withEncodedImages(message)));
+}
+
 // src/client.ts
 var OllamaClient = class {
   registry;
@@ -1264,12 +1302,13 @@ var OllamaClient = class {
     }
   }
   async chat(req) {
+    const messages = await withEncodedMessageImages(req.messages);
     if (req.stream) {
       return this.executeWithFailover(async (http, signal) => {
         if (req.format !== void 0) this.assertStructuredOutputSupported(http.baseUrl, req.model);
         const stream = await http.requestStream({
           path: "/api/chat",
-          body: { ...req, stream: true },
+          body: { ...req, messages, stream: true },
           signal
         });
         return normalizeChatStream(stream);
@@ -1288,7 +1327,7 @@ var OllamaClient = class {
             this.assertStructuredOutputSupported(http.baseUrl, req.model);
           return http.request({
             path: "/api/chat",
-            body: { ...req, stream: false },
+            body: { ...req, messages, stream: false },
             signal
           });
         }, req);
@@ -1315,34 +1354,36 @@ var OllamaClient = class {
     return parseStructuredOutput(res.message.content, schema);
   }
   async generate(req) {
-    if (req.stream) {
+    const encodedReq = await withEncodedImages(req);
+    if (encodedReq.stream) {
       return this.executeWithFailover(async (http, signal) => {
-        if (req.format !== void 0) this.assertStructuredOutputSupported(http.baseUrl, req.model);
+        if (encodedReq.format !== void 0)
+          this.assertStructuredOutputSupported(http.baseUrl, encodedReq.model);
         const stream = await http.requestStream({
           path: "/api/generate",
-          body: { ...req, stream: true },
+          body: { ...encodedReq, stream: true },
           signal
         });
         return normalizeGenerateStream(stream);
-      }, req);
+      }, encodedReq);
     }
     return withSpan(
-      `text_completion ${req.model}`,
+      `text_completion ${encodedReq.model}`,
       {
         [ATTR_GEN_AI_SYSTEM]: GEN_AI_SYSTEM_OLLAMA,
         [ATTR_GEN_AI_OPERATION_NAME]: "text_completion",
-        [ATTR_GEN_AI_REQUEST_MODEL]: req.model
+        [ATTR_GEN_AI_REQUEST_MODEL]: encodedReq.model
       },
       async (span) => {
         const res = await this.executeWithFailover((http, signal) => {
-          if (req.format !== void 0)
-            this.assertStructuredOutputSupported(http.baseUrl, req.model);
+          if (encodedReq.format !== void 0)
+            this.assertStructuredOutputSupported(http.baseUrl, encodedReq.model);
           return http.request({
             path: "/api/generate",
-            body: { ...req, stream: false },
+            body: { ...encodedReq, stream: false },
             signal
           });
-        }, req);
+        }, encodedReq);
         span?.setAttributes({
           [ATTR_GEN_AI_RESPONSE_MODEL]: res.model,
           ...res.prompt_eval_count !== void 0 ? { [ATTR_GEN_AI_USAGE_INPUT_TOKENS]: res.prompt_eval_count } : {},
@@ -2026,6 +2067,7 @@ exports.createConsoleLogger = createConsoleLogger;
 exports.createTimeoutSignal = createTimeoutSignal;
 exports.defineTool = defineTool;
 exports.detectModelCapabilities = detectModelCapabilities;
+exports.encodeImage = encodeImage;
 exports.extractUsage = extractUsage;
 exports.inferRuntimeMode = inferRuntimeMode;
 exports.listAvailableModels = listAvailableModels;