@nemesis-oss/ollama-sdk 1.3.0 → 1.4.1

package/dist/{compose-CDWq8oxJ.d.ts → types-BQhgW-du.d.ts}

@@ -1,9 +1,14 @@
-import { z } from 'zod';
-
 /**
  * Core protocol and message types for the Ollama REST API.
  */
 type Role = 'system' | 'user' | 'assistant' | 'tool' | 'thought';
+/** Ollama native thinking control: booleans, null for model default, or model-defined levels. */
+type ThinkValue = boolean | string | null;
+/** Thinking capability metadata returned by `/api/show`. */
+interface ThinkingMetadata {
+    readonly values: readonly (boolean | string)[];
+    readonly default?: boolean | string | null | undefined;
+}
 interface ToolCallFunction {
     readonly name: string;
     readonly arguments: Record<string, unknown>;
@@ -35,7 +40,16 @@ interface Message {
      */
     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. */
+    /**
+     * Ollama's native `/api/chat` field identifying which tool produced this result.
+     * For `role: 'tool'` messages this should be the registered tool's name.
+     */
+    readonly tool_name?: string | undefined;
+    /**
+     * @deprecated SDK-local correlation metadata only. Ollama's native `/api/chat` protocol
+     * does not use `tool_call_id`; native requests strip this field before transmission.
+     * OpenAI compatibility uses its own `OpenAIMessage.tool_call_id` type.
+     */
     readonly tool_call_id?: string | undefined;
     readonly thinking?: string | undefined;
 }
@@ -46,15 +60,20 @@ interface ToolProperty {
     readonly items?: Record<string, unknown> | undefined;
     readonly properties?: Record<string, unknown> | undefined;
     readonly required?: readonly string[] | undefined;
+    /** Additional JSON Schema keywords are preserved for MCP/provider interoperability. */
+    readonly [keyword: string]: unknown;
+}
+interface ToolParameters {
+    readonly type: 'object';
+    readonly properties: Record<string, ToolProperty>;
+    readonly required?: readonly string[] | undefined;
+    /** Additional JSON Schema keywords such as $defs, anyOf, allOf, and additionalProperties. */
+    readonly [keyword: string]: unknown;
 }
 interface ToolFunctionDefinition {
     readonly name: string;
     readonly description: string;
-    readonly parameters: {
-        readonly type: 'object';
-        readonly properties: Record<string, ToolProperty>;
-        readonly required?: readonly string[] | undefined;
-    };
+    readonly parameters: ToolParameters;
 }
 interface ToolDefinition {
     readonly type: 'function';
@@ -80,6 +99,8 @@ interface ModelOptions {
     readonly num_keep?: number | undefined;
     readonly seed?: number | undefined;
     readonly num_predict?: number | undefined;
+    /** Number of tokens to predict with a draft/speculative model, when supported. */
+    readonly draft_num_predict?: number | undefined;
     readonly top_k?: number | undefined;
     readonly top_p?: number | undefined;
     readonly min_p?: number | undefined;
@@ -118,7 +139,17 @@ interface ChatRequestOptions extends RequestCancellationOptions {
     readonly options?: ModelOptions | undefined;
     readonly stream?: boolean | undefined;
     readonly keep_alive?: string | number | undefined;
-    readonly think?: boolean | 'low' | 'medium' | 'high' | 'max' | undefined;
+    /**
+     * Controls thinking output. Use `client.capabilities(model).thinking` to discover
+     * model-defined string levels and the model default.
+     */
+    readonly think?: ThinkValue | undefined;
+    /** Experimental image-generation width in pixels. */
+    readonly width?: number | undefined;
+    /** Experimental image-generation height in pixels. */
+    readonly height?: number | undefined;
+    /** Experimental image-generation diffusion steps. */
+    readonly steps?: number | undefined;
     /** Whether to return log probabilities of the output tokens. See {@link ChatResponse.logprobs}. */
     readonly logprobs?: boolean | undefined;
     /** Number of most likely alternative tokens to return at each position. Requires `logprobs: true`. */
@@ -133,6 +164,8 @@ interface ChatResponse {
     readonly total_duration?: number | undefined;
     readonly load_duration?: number | undefined;
     readonly prompt_eval_count?: number | undefined;
+    /** Number of prompt tokens read from the KV cache. */
+    readonly prompt_eval_cached_count?: number | undefined;
     readonly prompt_eval_duration?: number | undefined;
     readonly eval_count?: number | undefined;
     readonly eval_duration?: number | undefined;
@@ -157,11 +190,17 @@ interface GenerateRequestOptions extends RequestCancellationOptions {
     readonly images?: readonly (string | Uint8Array)[] | undefined;
     readonly options?: ModelOptions | undefined;
     readonly keep_alive?: string | number | undefined;
-    readonly think?: boolean | 'low' | 'medium' | 'high' | 'max' | undefined;
+    readonly think?: ThinkValue | undefined;
     /** Whether to return log probabilities of the output tokens. See {@link GenerateResponse.logprobs}. */
     readonly logprobs?: boolean | undefined;
     /** Number of most likely alternative tokens to return at each position. Requires `logprobs: true`. */
     readonly top_logprobs?: number | undefined;
+    /** Experimental image-generation width in pixels. */
+    readonly width?: number | undefined;
+    /** Experimental image-generation height in pixels. */
+    readonly height?: number | undefined;
+    /** Experimental image-generation diffusion steps. */
+    readonly steps?: number | undefined;
 }
 interface GenerateResponse {
     readonly model: string;
@@ -173,12 +212,20 @@ interface GenerateResponse {
     readonly total_duration?: number | undefined;
     readonly load_duration?: number | undefined;
     readonly prompt_eval_count?: number | undefined;
+    /** Number of prompt tokens read from the KV cache. */
+    readonly prompt_eval_cached_count?: number | undefined;
     readonly prompt_eval_duration?: number | undefined;
     readonly eval_count?: number | undefined;
     readonly eval_duration?: number | undefined;
     readonly thinking?: string | undefined;
     /** Present when the request set `logprobs: true`. */
     readonly logprobs?: readonly Logprob[] | undefined;
+    /** Base64-encoded generated image data for image-generation models. */
+    readonly image?: string | undefined;
+    /** Number of completed image-generation steps. */
+    readonly completed?: number | undefined;
+    /** Total image-generation steps. */
+    readonly total?: number | undefined;
 }
 interface EmbedRequestOptions extends RequestCancellationOptions {
     readonly model: string;
@@ -222,6 +269,8 @@ interface ModelResponse {
     readonly details: ModelDetails;
     readonly expires_at?: string | undefined;
     readonly size_vram?: number | undefined;
+    /** Context window length reported for currently running models by /api/ps. */
+    readonly context_length?: number | undefined;
 }
 interface ListResponse {
     readonly models: readonly ModelResponse[];
@@ -242,6 +291,8 @@ interface ShowResponse {
     readonly messages?: readonly Message[] | undefined;
     readonly model_info?: Record<string, unknown> | undefined;
     readonly capabilities?: readonly string[] | undefined;
+    /** Model-defined thinking levels and default, when reported by Ollama. */
+    readonly thinking?: ThinkingMetadata | undefined;
     readonly modified_at?: string | undefined;
 }
 interface ProgressResponse {
@@ -274,8 +325,12 @@ interface CreateRequestOptions extends RequestCancellationOptions {
     readonly modelfile?: string | undefined;
     readonly stream?: boolean | undefined;
     readonly quantize?: string | undefined;
+    /** Quantization level to apply to draft weights during import. */
+    readonly draft_quantize?: string | undefined;
     readonly from?: string | undefined;
     readonly files?: Record<string, string> | undefined;
+    /** Draft source file names mapped to their SHA-256 digests. */
+    readonly draft_files?: Record<string, string> | undefined;
     readonly adapters?: Record<string, string> | undefined;
     readonly template?: string | undefined;
     readonly renderer?: string | undefined;
@@ -285,6 +340,8 @@ interface CreateRequestOptions extends RequestCancellationOptions {
     /** Modelfile `PARAMETER` instructions, e.g. `{ temperature: 0.7, stop: ['\n'] }`. */
     readonly parameters?: Record<string, unknown> | undefined;
     readonly messages?: readonly Message[] | undefined;
+    /** Minimum Ollama version required by the model. */
+    readonly requires?: string | undefined;
 }
 interface DeleteRequestOptions extends RequestCancellationOptions {
     readonly model: string;
@@ -343,164 +400,4 @@ interface WebFetchResponse {
     readonly links?: readonly string[] | undefined;
 }
 
-/**
- * Tool definition, handler, and execution types.
- */
-
-interface ToolExecutionContext {
-    readonly signal?: AbortSignal | undefined;
-}
-type ToolHandler<TParams, TResult> = (params: TParams, context: ToolExecutionContext) => Promise<TResult> | TResult;
-interface Tool<TParams = Record<string, unknown>, TResult = unknown> {
-    readonly name: string;
-    readonly description: string;
-    readonly schema: z.ZodType<TParams>;
-    readonly execute: ToolHandler<TParams, TResult>;
-    readonly definition: ToolDefinition;
-    /**
-     * Per-tool execution timeout in milliseconds, overriding the registry's default.
-     * Pass `0` to explicitly disable timeout enforcement for this tool.
-     */
-    readonly timeoutMs?: number | undefined;
-}
-/**
- * A `Tool` of *any* parameter shape, for heterogeneous collections — i.e. what
- * `ToolRegistry` stores and accepts.
- *
- * `Tool<TParams>` is **invariant** in `TParams`, because `TParams` appears both
- * covariantly (`schema: z.ZodType<TParams>`) and contravariantly
- * (`execute: ToolHandler<TParams, …>`). That makes `Tool<never, unknown>` — the obvious-
- * looking "bottom" type for a mixed collection — assignable from *nothing*: a perfectly
- * ordinary `Tool<{ city: string }, string>` from `defineTool` is rejected by it. `any` is
- * the standard escape hatch for exactly this case, and it is confined to this one alias:
- * `defineTool` still infers `TParams` from the Zod schema and still type-checks `execute`
- * against it, so tool authoring keeps full type safety. Only the registry's *storage*
- * type is widened, and the registry never does anything with a tool's params beyond
- * handing `schema.safeParse`'s validated output straight back to that same tool's
- * `execute`.
- */
-type AnyTool = Tool<any, unknown>;
-interface ToolExecutionSuccess {
-    readonly toolName: string;
-    /** Echoes the originating {@link ToolCall.id}, if the call had one. */
-    readonly toolCallId?: string | undefined;
-    readonly success: true;
-    readonly result: unknown;
-    readonly outputString: string;
-}
-interface ToolExecutionFailure {
-    readonly toolName: string;
-    /** Echoes the originating {@link ToolCall.id}, if the call had one. */
-    readonly toolCallId?: string | undefined;
-    readonly success: false;
-    readonly error: Error;
-    readonly outputString: string;
-}
-type ToolExecutionResult = ToolExecutionSuccess | ToolExecutionFailure;
-
-/**
- * Tool registry for managing definitions and executing model tool calls.
- */
-
-interface ToolRegistryOptions {
-    readonly tools?: readonly AnyTool[] | undefined;
-    readonly onError?: ((error: Error, toolCall: ToolCall) => string) | undefined;
-    /**
-     * Default per-call execution timeout in milliseconds, applied to any tool that
-     * doesn't declare its own `timeoutMs`. Undefined (the default) means no timeout is
-     * enforced, matching prior behavior. Recommended whenever tool arguments or
-     * implementations are influenced by model output you don't fully control, since an
-     * unbounded tool call can otherwise stall the entire agent loop indefinitely.
-     *
-     * Enforcement is cooperative: it races the tool's promise against a timer and
-     * reports a timeout failure, but cannot forcibly halt synchronous or non-abort-aware
-     * asynchronous work already in flight on the same thread. Tools that perform I/O
-     * should honor `ToolExecutionContext.signal` to stop promptly on timeout.
-     */
-    readonly timeoutMs?: number | undefined;
-    /**
-     * Maximum number of tool calls executed concurrently by `executeToolCalls`.
-     * Undefined (the default) runs all calls in parallel, matching prior behavior.
-     */
-    readonly maxConcurrency?: number | undefined;
-    /**
-     * Maximum length of a tool's `outputString` before it is truncated. Guards against a
-     * single tool call flooding the conversation history / model context (and process
-     * memory) with unbounded output. Undefined (the default) applies no limit.
-     */
-    readonly maxOutputChars?: number | undefined;
-}
-declare class ToolRegistry {
-    private readonly tools;
-    private readonly onError?;
-    private readonly defaultTimeoutMs?;
-    private readonly maxConcurrency?;
-    private readonly maxOutputChars?;
-    constructor(toolsOrOptions?: readonly AnyTool[] | ToolRegistryOptions | undefined);
-    register(tool: AnyTool): this;
-    registerMany(tools: readonly AnyTool[]): this;
-    get(name: string): AnyTool | undefined;
-    definitions(): ToolDefinition[];
-    executeToolCall(toolCall: ToolCall, ctx?: ToolExecutionContext): Promise<ToolExecutionResult>;
-    private executeToolCallUninstrumented;
-    /**
-     * Executes every call in `toolCalls` and returns results in the same order, so results
-     * are always correlatable by array position regardless of `id`. Each result also echoes
-     * its call's `toolCallId` for callers who'd rather match by ID — see the {@link ToolCall}
-     * docs for how that id is produced. Runs fully in parallel (`Promise.all`) unless
-     * `maxConcurrency` was configured, in which case a bounded worker pool is used instead.
-     */
-    executeToolCalls(toolCalls: readonly ToolCall[], ctx?: ToolExecutionContext): Promise<ToolExecutionResult[]>;
-    private runWithTimeout;
-    private truncateOutput;
-    private handleExecutionError;
-}
-
-/**
- * SKILL.md frontmatter and skill registry types.
- */
-interface SkillFrontmatter {
-    readonly name: string;
-    readonly description: string;
-    readonly 'allowed-tools'?: readonly string[] | undefined;
-    readonly [key: string]: unknown;
-}
-interface SkillSummary {
-    readonly name: string;
-    readonly description: string;
-    readonly path: string;
-}
-interface Skill extends SkillSummary {
-    readonly frontmatter: SkillFrontmatter;
-    readonly body: string;
-    readonly allowedTools?: readonly string[] | undefined;
-}
-
-/**
- * Lightweight frontmatter parser for SKILL.md files.
- */
-
-interface ParsedFrontmatter {
-    readonly frontmatter: SkillFrontmatter;
-    readonly body: string;
-}
-declare function parseFrontmatter(source: string, path?: string): ParsedFrontmatter;
-
-/**
- * Skill composition and context injection.
- */
-
-interface ApplySkillOptions {
-    readonly messages: readonly Message[];
-    readonly tools?: ToolRegistry;
-}
-interface AppliedSkillResult {
-    readonly messages: readonly Message[];
-    readonly tools?: ToolRegistry;
-}
-/**
- * Injects a skill's body into messages as a system prompt and applies allowed tool filters.
- */
-declare function applySkill(skill: Skill, options: ApplySkillOptions): AppliedSkillResult;
-
-export { type WebSearchResult as $, type AnyTool as A, type ModelDetails as B, type ChatResponse as C, type DeleteRequestOptions as D, type EmbedRequestOptions as E, type FormatOption as F, type GenerateResponse as G, type ParsedFrontmatter as H, type Role as I, type Skill as J, type SkillFrontmatter as K, type ListResponse as L, type Message as M, type SkillSummary as N, type ToolCallFunction as O, type ProgressResponse as P, type ToolExecutionContext as Q, type RequestCancellationOptions as R, type ShowRequestOptions as S, type ToolCall as T, type ToolExecutionFailure as U, type VersionResponse as V, type WebSearchRequestOptions as W, type ToolExecutionSuccess as X, type ToolFunctionDefinition as Y, type ToolProperty as Z, type ToolRegistryOptions as _, type ModelResponse as a, applySkill as a0, parseFrontmatter as a1, type ShowResponse as b, type PullRequestOptions as c, type PushRequestOptions as d, type CreateRequestOptions as e, type StatusResponse as f, type CopyRequestOptions as g, type PsResponse as h, type ChatRequestOptions as i, type GenerateRequestOptions as j, type EmbedResponse as k, type EmbeddingsRequestOptions as l, type EmbeddingsResponse as m, type WebSearchResponse as n, type WebFetchRequestOptions as o, type WebFetchResponse as p, type ToolHandler as q, type Tool as r, ToolRegistry as s, type ToolExecutionResult as t, type ModelOptions as u, type ToolDefinition as v, type AppliedSkillResult as w, type ApplySkillOptions as x, type Logprob as y, type LogprobToken as z };
+export type { ToolParameters as A, ToolProperty as B, CreateRequestOptions as C, DeleteRequestOptions as D, EmbedRequestOptions as E, FormatOption as F, GenerateRequestOptions as G, WebSearchResult as H, ListResponse as L, Message as M, PullRequestOptions as P, RequestCancellationOptions as R, ShowRequestOptions as S, ToolDefinition as T, VersionResponse as V, WebSearchRequestOptions as W, ToolCall as a, ThinkingMetadata as b, ModelResponse as c, ShowResponse as d, ProgressResponse as e, PushRequestOptions as f, StatusResponse as g, CopyRequestOptions as h, PsResponse as i, ChatRequestOptions as j, ChatResponse as k, GenerateResponse as l, EmbedResponse as m, EmbeddingsRequestOptions as n, EmbeddingsResponse as o, WebSearchResponse as p, WebFetchRequestOptions as q, WebFetchResponse as r, ModelOptions as s, ThinkValue as t, Logprob as u, LogprobToken as v, ModelDetails as w, Role as x, ToolCallFunction as y, ToolFunctionDefinition as z };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nemesis-oss/ollama-sdk",
-  "version": "1.3.0",
-  "description": "Production-grade TypeScript SDK for Ollama with native fetch, high availability failover, multi-turn tool calling, structured outputs, reasoning stream tokens, OpenAI/Anthropic bridges, MCP, and Web Stream adapters.",
+  "version": "1.4.1",
+  "description": "Production-grade TypeScript SDK for Ollama with native fetch, high availability failover, multi-turn tool calling, structured outputs, reasoning stream tokens, OpenAI/Anthropic bridges, MCP, Web Stream adapters, and a contract-first hybrid architecture that generates TypeScript types, API classes, MCP tools, and Zod schemas from a single canonical IR.",
   "keywords": [
     "ollama",
     "ollama-client",
@@ -59,12 +59,90 @@
         "default": "./dist/skills.cjs"
       }
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./mcp/stdio": {
+      "import": {
+        "types": "./dist/mcp-stdio.d.ts",
+        "default": "./dist/mcp-stdio.js"
+      },
+      "require": {
+        "types": "./dist/mcp-stdio.d.cts",
+        "default": "./dist/mcp-stdio.cjs"
+      }
+    },
+    "./mcp/http": {
+      "import": {
+        "types": "./dist/mcp-http.d.ts",
+        "default": "./dist/mcp-http.js"
+      },
+      "require": {
+        "types": "./dist/mcp-http.d.cts",
+        "default": "./dist/mcp-http.cjs"
+      }
+    },
+    "./generated/runtime": {
+      "import": {
+        "types": "./dist/generated-runtime.d.ts",
+        "default": "./dist/generated-runtime.js"
+      },
+      "require": {
+        "types": "./dist/generated-runtime.d.cts",
+        "default": "./dist/generated-runtime.cjs"
+      }
+    },
+    "./generated/api": {
+      "import": {
+        "types": "./dist/generated-api.d.ts",
+        "default": "./dist/generated-api.js"
+      },
+      "require": {
+        "types": "./dist/generated-api.d.cts",
+        "default": "./dist/generated-api.cjs"
+      }
+    },
+    "./generated/models/schemas": {
+      "import": {
+        "types": "./dist/generated-models-schemas.d.ts",
+        "default": "./dist/generated-models-schemas.js"
+      },
+      "require": {
+        "types": "./dist/generated-models-schemas.d.cts",
+        "default": "./dist/generated-models-schemas.cjs"
+      }
+    },
+    "./mcp/generated": {
+      "import": {
+        "types": "./dist/mcp-generated.d.ts",
+        "default": "./dist/mcp-generated.js"
+      },
+      "require": {
+        "types": "./dist/mcp-generated.d.cts",
+        "default": "./dist/mcp-generated.cjs"
+      }
+    }
   },
   "typesVersions": {
     "*": {
       "skills": [
         "dist/skills.d.ts"
+      ],
+      "mcp/stdio": [
+        "dist/mcp-stdio.d.ts"
+      ],
+      "mcp/http": [
+        "dist/mcp-http.d.ts"
+      ],
+      "generated/runtime": [
+        "dist/generated-runtime.d.ts"
+      ],
+      "generated/api": [
+        "dist/generated-api.d.ts"
+      ],
+      "generated/models/schemas": [
+        "dist/generated-models-schemas.d.ts"
+      ],
+      "mcp/generated": [
+        "dist/mcp-generated.d.ts"
       ]
     }
   },
@@ -95,21 +173,32 @@
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "verify:edge-runtime": "tsx scripts/verify-edge-runtime.ts",
+    "verify:contract-parity": "tsx scripts/verify-contract-parity.ts",
+    "contract:fetch": "tsx scripts/fetch-contract.ts",
+    "contract:normalize": "tsx scripts/build-contract.ts",
+    "contract:validate": "tsx scripts/verify-contract.ts",
+    "contract:diff": "tsx scripts/diff-contract.ts",
+    "contract:generate": "tsx scripts/generate-contract.ts && prettier --write src/generated/",
+    "contract:drift": "tsx scripts/drift-contract.ts",
     "bench": "vitest bench --run",
     "bench:watch": "vitest bench",
     "check:types": "npx --yes @arethetypeswrong/cli@latest --pack .",
-    "verify": "npm run typecheck && npm run lint && npm run test && npm run build && npm run verify:edge-runtime",
+    "verify": "npm run typecheck && npm run lint && npm run test && npm run build && npm run verify:edge-runtime && npm run verify:contract-parity",
     "example": "tsx",
     "lab": "tsx lab/run.ts",
-    "prepublishOnly": "npm run clean && npm run typecheck && npm run lint && npm test && npm run build && npm run verify:edge-runtime"
+    "prepublishOnly": "npm run clean && npm run typecheck && npm run lint && npm run test && npm run build && npm run verify:edge-runtime && npm run verify:contract-parity"
   },
   "peerDependencies": {
+    "@modelcontextprotocol/client": "^2.1.0",
     "@opentelemetry/api": "^1.9.0",
     "zod": "^3.22.0 || ^4.0.0"
   },
   "peerDependenciesMeta": {
     "@opentelemetry/api": {
       "optional": true
+    },
+    "@modelcontextprotocol/client": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -120,6 +209,7 @@
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/context-async-hooks": "^1.30.1",
     "@opentelemetry/sdk-trace-base": "^1.30.1",
+    "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.20.0",
     "@vitest/coverage-v8": "^4.1.9",
     "cross-env": "^10.1.0",
@@ -127,6 +217,7 @@
     "esbuild": "^0.27.7",
     "eslint": "^9.39.4",
     "eslint-config-prettier": "^9.1.2",
+    "js-yaml": "^5.4.2",
     "prettier": "^3.9.4",
     "tsup": "^8.5.1",
     "tsx": "^4.23.0",