@warlock.js/ai-ollama 5.30.0 → 5.31.0

package/skills/setup-ollama/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: setup-ollama
-description: 'Wire @warlock.js/ai-ollama — new OllamaSDK({host?, headers?}) for local / self-hosted Ollama via the official ollama client (not OpenAI-compat). chat + embed, daemon-down error handling. .model({name, vision?, reasoning?}) with cost-truth capabilities — reasoning inferred from thinking-model tags (deepseek-r1/qwq/qwen3/gpt-oss…), promptCaching/audio/pdf honestly false; options.reasoning → Ollama native `think` flag; usage reasoningTokens/cachedTokens stay undefined (none reported). Triggers: `OllamaSDK`, `ollama.model`, `ollama.embedder`, `embedder.embedMany`, `ollama.count`, `host`, `headers`, `reasoning`, `think`, thinking models, `deepseek-r1`, `qwq`, `qwen3`, `gpt-oss`; "use ollama with warlock", "run llama3 locally", "self-hosted llama", "ollama reasoning / thinking models", "deepseek-r1 with warlock"; typical import `import { OllamaSDK } from "@warlock.js/ai-ollama"`. Skip: agent loop — the `run-ai-agent` topic of the `warlock-js-ai` skill; provider choice — the `pick-ai-provider` topic of the `warlock-js-ai` skill; embeddings core — the `embed-text` topic of the `warlock-js-ai` skill; siblings `@warlock.js/ai-openai`, `@warlock.js/ai-anthropic`, `@warlock.js/ai-google`; raw `ollama` npm, Vercel `@ai-sdk/ollama`; OpenAI-compat gateway via `@warlock.js/ai-openai` `baseURL`.'
+description: 'Wire @warlock.js/ai-ollama — new OllamaSDK({host?, headers?}) for local / self-hosted Ollama via the official ollama client (not OpenAI-compat). chat + embed, daemon-down error handling. .model({name, vision?, reasoning?}) with cost-truth capabilities — reasoning inferred from thinking-model tags (deepseek-r1/qwq/qwen3/gpt-oss…), promptCaching/audio/pdf honestly false; options.reasoning → Ollama native `think` flag; usage reasoningTokens/cachedTokens stay undefined (none reported). Triggers: `providerOptions`, `OllamaCallOptions`, `countTokens`, `OllamaSDK`, `ollama.model`, `ollama.embedder`, `embedder.embedMany`, `ollama.count`, `host`, `headers`, `reasoning`, `think`, thinking models, `streamChunks`, `message.thinking`, `deepseek-r1`, `qwq`, `qwen3`, `gpt-oss`; "use ollama with warlock", "run llama3 locally", "self-hosted llama", "ollama reasoning / thinking models", "deepseek-r1 with warlock"; typical import `import { OllamaSDK } from "@warlock.js/ai-ollama"`. Skip: agent loop — the `run-ai-agent` topic of the `warlock-js-ai` skill; provider choice — the `pick-ai-provider` topic of the `warlock-js-ai` skill; embeddings core — the `embed-text` topic of the `warlock-js-ai` skill; siblings `@warlock.js/ai-openai`, `@warlock.js/ai-anthropic`, `@warlock.js/ai-google`; raw `ollama` npm, Vercel `@ai-sdk/ollama`; OpenAI-compat gateway via `@warlock.js/ai-openai` `baseURL`.'
 ---
 
 # `@warlock.js/ai-ollama`
@@ -12,9 +12,9 @@ Provider adapter that turns a local (or self-hosted) Ollama server into a vendor
 ```ts
 import { OllamaSDK } from "@warlock.js/ai-ollama";
 
-const ollama = new OllamaSDK();                                  // local default host
+const ollama = new OllamaSDK(); // local default host
 const remote = new OllamaSDK({ host: "http://gpu-box.internal:11434" });
-const gated  = new OllamaSDK({
+const gated = new OllamaSDK({
   host: "https://ollama.internal",
   headers: { Authorization: `Bearer ${process.env.OLLAMA_TOKEN}` },
 });
@@ -25,20 +25,20 @@ const gated  = new OllamaSDK({
 ## Producing a model
 
 ```ts
-ollama.model({ name: "llama3.1" })
-ollama.model({ name: "qwen2.5:14b", temperature: 0.2 })
-ollama.model({ name: "llama3.2-vision", maxTokens: 1024 })
+ollama.model({ name: "llama3.1" });
+ollama.model({ name: "qwen2.5:14b", temperature: 0.2 });
+ollama.model({ name: "llama3.2-vision", maxTokens: 1024 });
 ```
 
 ## Capabilities — what's auto-set
 
-| Flag | Default |
-| --- | --- |
-| `structuredOutput` | `true` (via Ollama's native `format` JSON-schema field) |
-| `vision` | Inferred from model tag substring. `true` for `llava`, `bakllava`, `*-vision`, `moondream`, `minicpm-v`, `qwen2-vl`, `qwen2.5-vl`, `llama4`, `gemma3`; `false` otherwise. |
-| `reasoning` | Inferred from model tag substring. `true` for `deepseek-r1`, `qwq`, `qwen3`, `magistral`, `phi4-reasoning`, `phi4-mini-reasoning`, `cogito`, `smallthinker`, `exaone-deep`, `gpt-oss`; `false` otherwise. |
-| `promptCaching` | `false` — Ollama has no provider-side prompt cache. |
-| `audio` / `pdf` | `false` — the Ollama chat API takes no audio / PDF content parts. |
+| Flag               | Default                                                                                                                                                                                                   |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `structuredOutput` | `true` (via Ollama's native `format` JSON-schema field)                                                                                                                                                   |
+| `vision`           | Inferred from model tag substring. `true` for `llava`, `bakllava`, `*-vision`, `moondream`, `minicpm-v`, `qwen2-vl`, `qwen2.5-vl`, `llama4`, `gemma3`; `false` otherwise.                                 |
+| `reasoning`        | Inferred from model tag substring. `true` for `deepseek-r1`, `qwq`, `qwen3`, `magistral`, `phi4-reasoning`, `phi4-mini-reasoning`, `cogito`, `smallthinker`, `exaone-deep`, `gpt-oss`; `false` otherwise. |
+| `promptCaching`    | `false` — Ollama has no provider-side prompt cache.                                                                                                                                                       |
+| `audio` / `pdf`    | `false` — the Ollama chat API takes no audio / PDF content parts.                                                                                                                                         |
 
 Explicit config always wins (`vision`, `structuredOutput`, `reasoning` overrides on `ollama.model({ … })`).
 
@@ -47,9 +47,9 @@ Explicit config always wins (`vision`, `structuredOutput`, `reasoning` overrides
 For thinking-capable families the adapter maps `ModelCallOptions.reasoning` onto Ollama's `think` request flag (`boolean | 'low' | 'medium' | 'high'`):
 
 ```ts
-ollama.model({ name: "deepseek-r1:7b" })
-await model.complete(messages, { reasoning: { effort: "high" } });   // → chat({ think: "high" })
-await model.complete(messages, { reasoning: { maxTokens: 2048 } });  // → chat({ think: true })
+ollama.model({ name: "deepseek-r1:7b" });
+await model.complete(messages, { reasoning: { effort: "high" } }); // → chat({ think: "high" })
+await model.complete(messages, { reasoning: { maxTokens: 2048 } }); // → chat({ think: true })
 ```
 
 - `reasoning.effort` (`low` / `medium` / `high`) passes straight through to `think`.
@@ -83,7 +83,17 @@ A multipart user message collapses to a single `content` string + an `images` ar
 
 `model.stream()` drains `chat({ stream: true })` (an `AbortableAsyncIterator`). Each chunk's `message.content` → `{ type: "delta" }`; `message.tool_calls` are emitted as `{ type: "tool-call" }` **fully formed**. Terminal `{ type: "done", finishReason, usage }` — usage from the final (`done: true`) chunk's `prompt_eval_count` / `eval_count`.
 
-**`options.signal` is honored** by calling the iterator's `abort()` (stream path; non-stream `complete()` ignores it — the agent still honors the signal at trip boundaries).
+Opt-in (`options.streamChunks`, set by `agent.stream()`): `{ type: "reasoning", delta }` per `message.thinking` piece when `think` is on:
+
+```ts
+for await (const chunk of model.stream(messages, { reasoning: { effort: "high" }, streamChunks: { reasoning: true } })) {
+  if (chunk.type === "reasoning") process.stderr.write(chunk.delta);
+}
+```
+
+Ollama's chat API has no built-in tools: an `ai.providerTool()` for another provider is left out with a warning.
+
+**`options.signal` is honored** on `stream()` and `complete()`: a pre-aborted signal rejects without sending, and aborting mid-call cancels the HTTP request. The `ollama` client has no per-request signal, so `OllamaSDK` wraps its `fetch` (yours, when you pass `fetch`) to apply each call's signal from async context; the stream iterator's `abort()` is called too.
 
 ## Finish-reason mapping
 
@@ -94,7 +104,7 @@ A multipart user message collapses to a single `content` string + an `images` ar
 ```ts
 const embedder = ollama.embedder({ name: "nomic-embed-text" });
 const { vector } = await embedder.embed("Hello world");
-const { vectors } = await embedder.embedMany(["a", "b"]);   // single batched call
+const { vectors } = await embedder.embedMany(["a", "b"]); // single batched call
 const truncated = ollama.embedder({ name: "mxbai-embed-large", dimensions: 512 });
 ```
 
@@ -116,14 +126,52 @@ Wrapped into the typed `@warlock.js/ai` `AIError` hierarchy. The `ollama` client
 ## Token counting & usage (cost-truth)
 
 ```ts
-await ollama.count("some text")  // approximate heuristic, offline
+await ollama.count("some text"); // approximate heuristic, offline
 ```
 
 Per-call `Usage` comes from the chat response's `prompt_eval_count` (→ `input`) and `eval_count` (→ `output`); `total` is their sum. The adapter reports usage **truthfully** — it never fabricates a field Ollama doesn't return:
 
 - `cachedTokens` / `cacheWriteTokens` — **always undefined**. Ollama has no provider prompt cache, so there is no cache-hit or cache-write accounting (honest absence, not a false `0`).
-- `reasoningTokens` — **always undefined**. Reasoning models emit their thinking as the `message.thinking` *string*, but the wire format carries **no separate reasoning-token count** — those tokens are already folded into `eval_count`. The adapter does not estimate a count from the thinking text.
-- `cost` — populated only when a `ModelPricing` is configured (local Ollama is free, so usually undefined).
+- `reasoningTokens` — **always undefined**. Reasoning models emit their thinking as the `message.thinking` _string_, but the wire format carries **no separate reasoning-token count** — those tokens are already folded into `eval_count`. The adapter does not estimate a count from the thinking text.
+- `cost` — attached to each `complete()` / streaming `done` usage only when a `ModelPricing` is configured. The adapter ships no price table (a local model costs nothing per token), so it is usually undefined; set `pricing` for chargeback or a hosted Ollama endpoint.
+- `inputIncludesCache` — left unset: with no cache counters there is nothing to include or exclude.
+
+```ts
+import { totalCost } from "@warlock.js/ai";
+import { OllamaSDK } from "@warlock.js/ai-ollama";
+
+const ollama = new OllamaSDK({ pricing: { "llama3.2": { input: 0.05, output: 0.1 } } }); // internal chargeback rate
+const { usage } = await ollama
+  .model({ name: "llama3.2" })
+  .complete([{ role: "user", content: "hi" }]);
+console.log(totalCost(usage.cost));
+```
+
+## Provider body options
+
+Native body fields merge after neutral options. When both values are plain
+objects, their immediate keys merge and caller-provided keys win; untouched
+neutral fields remain. Arrays, scalars and `null` replace the field. This merge
+is one level deep: a nested object explicitly supplied by the caller replaces
+that nested value.
+
+`providerOptions.ollama.body` adds native chat request fields after neutral
+options, for completion and streaming:
+
+```ts
+await model.complete(messages, {
+  providerOptions: { ollama: { body: { keep_alive: "10m", options: { top_k: 4 } } } },
+});
+```
+
+The key stays `ollama` for custom provider labels. Other provider keys are
+ignored. `OllamaCallOptions` is exported. `model`, `messages`, `tools` and `stream`
+are protected; replacing them throws `InvalidRequestError`. Fields merge
+shallowly: a provider `options` object replaces the generated inference options,
+so include any neutral sampling settings you want to retain in that object.
+
+Ollama's chat transport has no native preflight token-count endpoint, so its
+model has no `countTokens` method. `sdk.count(text)` remains an offline estimate.
 
 ## When NOT to use this skill