@nemesis-oss/ollama-sdk 1.16.0 → 1.18.0

package/CHANGELOG.md

@@ -1,5 +1,65 @@
 # Changelog
 
+## [1.18.0] — Pull/push progress with speed & ETA, decision confidence gates, abort-safety pin, System One score 26→10 refresh
+
+The October 15 digest ("Structured Output Type Inference, Stream Cancellation Memory Barriers, Model Pull/Push Progress Multiplexing") plus its morning upstream-specs companion (System One confidence calibration, a claimed zero-truncation 413 rule) were audited against the codebase before any implementation (see [ADR 0033](./docs/adr/0033-progress-speed-decision-gates-abort-pin-systemone-refresh.md)). Verdicts: the structured-output claim was stale (`chatWithSchema`/`generateWithSchema` already ship full Zod inference + validation + markdown-JSON extraction — the proposed `structured?: T` field injection was declined as both weaker and contract-breaking); the stream-abort claim was stale as a defect (every teardown seam is guarded — most load-bearingly, `holdUntil` attaches a catch handler to every client stream's `finalResult` before the stream is returned) but the invariant is now pinned by real-wire tests; and the pull/push claim was half right — `onProgress()` with a pre-computed `percent` existed internally with 13 tests but was **not exported from the root entry**, and transfer speed didn't exist at all. The morning digest's 413/2-token scoring-head specification appears nowhere upstream (the real `/v1/systemone` 413 is the request-byte cap the SDK has enforced client-side since the System One waves); its one honest catch — taken from its own "OpenAPI Parity Inspection" focus item — is real: upstream tightened System One score criteria from 2–26 to 2–10 levels. All additive, no breaking changes. 1024 pre-existing tests stay green, 23 new tests added.
+
+### Model pull & push progress, with speed and ETA (OPR-01)
+
+- **`onProgress(stream, callback)` is now root-exported** — it was fully implemented (typed `PullProgressEvent` with a clamped two-decimal `percent`, `computeProgressPercent()`, `toPullProgressEvent()`, 13 tests) but absent from `src/index.ts`, so npm consumers couldn't import any of it. All four functions and the three types are public now.
+- **`createProgressSpeedTracker()`** — the stateful per-layer byte counter the digest correctly said consumers were forced to hand-roll: feed it every raw progress chunk and it returns `bytesPerSecond` + `etaSeconds` for that chunk's layer. Semantics chosen for stable progress bars: a **cumulative average** since the layer's first byte-bearing frame (instantaneous frame-to-frame rates jitter wildly), **per-layer epochs** (the tracker resets whenever `digest` changes or `completed` regresses, so a multi-layer pull never averages across layers — the classic hand-rolled-counter bug), `performance.now()` monotonic timing, and guards for zero-elapsed, zero-transfer, and missing-total frames (ETA `undefined`, never `NaN` or fake `0`).
+- `onProgress` wires the tracker in: every callback event now carries `bytesPerSecond`/`etaSeconds` alongside `percent` once two byte-bearing frames of a layer have arrived. The pure wrapper (`toPullProgressEvent`) never measures time — deterministic tests mock `performance.now()` with an exact manually-advanced clock.
+- Declined: a `client.pullWithProgress()` method or progress-multiplexer object — the typed dual-mode stream already _is_ the multiplexed channel; a callback helper composes over it without forking the request path (ADR 0033).
+
+### System One decision confidence gates (morning-digest kernel)
+
+- The six `client.decision` helpers now take **opt-in** calibration gates for autonomous flows — the digest's real concern (an agent acting on a 0.51 coin-flip `true` it never inspected):
+  - `choice()` / `score()` / `route()` / `rank()` accept `minConfidence` (inclusive lower bound in (0, 1]; `RangeError` otherwise, validated **before** any request is sent) and flag results with `isConfident: confidence >= minConfidence`. The value is still returned — the caller decides whether to act.
+  - `noul()` / `verify()` accept `minProbability`, which raises the bar their derived boolean must clear (default 0.5 unchanged). Noul answers carry no separate confidence field, so the threshold _is_ the boolean bar — a redundant `isConfident` would always equal `bool`.
+- Without the options, every result shape and default behavior is byte-identical — gates are purely additive, and `isConfident` is present only when configured.
+- Declined with reasoning in ADR 0033: the `SystemOneDecisionHelper.evaluateDecisions` wrapper class (zero config around one map iteration) and the `ContextBudgetGuard` token estimator (a pre-flight guard against a spec that doesn't exist — the claimed HTTP-413-on-context-overflow and two-token scoring-head reservation appear in neither the official decision docs nor the OpenAPI; inventing an estimation formula for undocumented server behavior manufactures false confidence).
+
+### Stream abort safety (STR-03 — stale defect, invariant pinned)
+
+- The digest's claimed unhandled-rejection race is guarded at every seam: `requestStream` wires the caller signal to an `AbortController` with listener cleanup in the generator's `finally`; `parseNdjsonStream` runs under `await using disposableReader` (cancel rejections swallowed, lock released); `OllamaStream.abort()` cancels the source before rejecting `finalResult`; and `executeWithFailover` attaches `void holdUntil(stream).catch(() => undefined)` to every client-produced stream's `finalResult` **synchronously, before the stream is returned** — the internally-held promise can never surface as a process-level `unhandledRejection`. The digest's `guardedStreamReader` sketch re-implements this stack with weaker structure.
+- The invariant is now pinned (BUF-01 precedent): `test/stream-abort-mid-read.test.ts` aborts a real wire stream with the next frame genuinely in flight (public mock server, 50 ms chunk delays) in both iterator and events mode — asserting the mapped `OllamaAbortError` is delivered to the consumer, zero process-level `unhandledRejection` events fire after the rejection chains settle, the endpoint slot releases (`activeRequests` back to 0 under `maxConcurrentPerEndpoint: 1`), and a follow-up request on that single-slot client completes immediately.
+
+### System One contract refresh (score criteria 2–26 → 2–10)
+
+- Upstream's `docs/openapi.yaml` now natively carries the System One schemas (the SDK pin previously hand-assembled them from the rendered docs) and tightens **score criteria to `maxItems: 10`** (answer scale `maximum: 9`), drops the noul criteria's hardcoded `'Yes'`/`'No'` defaults ("omitted entries use model-specific defaults"), and simplifies the model/images descriptions. The pin was hand-refreshed in its cleaned style (running `contract:fetch` verbatim would clobber its documented intentional deviations) and the contract regenerated: IR, `SystemOneScoreQuestion`/`SystemOneScoreAnswer` models + Zod schemas (`score: z.number().min(0).max(9)`), and MCP tool descriptors. Boundary tests updated (11-criteria requests now rejected client-side before the round-trip; 10-criteria accepted at the new boundary) with the upstream change date recorded.
+- `decision.ts`'s score JSDoc and the README examples now say 2–10.
+
+### Structured outputs (TYP-04 — stale, documented)
+
+- `chatWithSchema<T>(req, zodSchema)` / `generateWithSchema<T>(req, zodSchema)` already deliver exactly what the digest asked for — inferred `T` returns, runtime validation (`OllamaToolValidationError` with Zod issues when the model's JSON drifts from the schema), and resilient extraction from markdown-fenced output — all root-exported and README-documented since the Zod waves. The digest's redesign (a `structured?: T` field on the response message, populated by a blind `JSON.parse(...) as T`) was declined: no runtime validation is precisely the unsafety the finding complains about, and injecting SDK-computed fields into wire-contract response types breaks the contract-parity discipline (ADR 0033).
+
+## [1.17.0] — Streaming blob uploads (`duplex:'half'`, two-pass file upload), typed-array view-safety pins, tracing-header verdicts
+
+The October 14 digest ("Raw Model Blob Ingestion Streaming Backpressure, W3C Distributed Tracing Baggage Injection, Defensive Serialization for Typed Arrays") targeted heavy binary asset streaming, operational provenance, and low-level buffer safety. Audited against the codebase first (see [ADR 0032](./docs/adr/0032-streaming-blob-uploads-tracing-verdicts-view-safety.md)): the heap-exhaustion claim was real on the blob path — `createBlobFromFile` bulk-read the whole file (`fs.readFile`) before uploading, and the `ReadableStream` member of `BinaryBody` was a promise the transport couldn't keep (Node 18+ `fetch` rejects stream bodies without `duplex: 'half'`) — though the `/api/create` framing was misdirected (its request body is a small JSON digest map, not a stream). The tracing claim was stale (client-level `headers`, per-request headers, and the middleware seam already forward any W3C headers verbatim — nothing is stripped). The typed-array claim was stale as a defect (`src/` has zero `Buffer.from` call sites; the SDK's Web APIs are view-safe by construction, and adopting the proposed `Buffer`-coupled helpers would regress the edge-runtime zero-Node-builtins gate) — but the invariant is now pinned by tests. The companion upstream-specs digest (System One batching, payload caps, `expires_at`, model warmth) was comprehensively stale — every recommendation already ships. All additive, no breaking changes. 1012 pre-existing tests stay green, 12 new tests added.
+
+### Streaming blob uploads (MOD-01 — multi-GB GGUFs never enter the heap)
+
+- **Transport**: both fetch call sites (middleware `finalHandler` and the direct path, previously duplicated init construction) now share one `buildFetchInit` that sets `duplex: 'half'` exactly when the body is a web `ReadableStream`. The guard is structural (`getReader` duck-typing) so cross-realm streams (workers, VM contexts) still get the member; the init type is a local `RequestInit & { duplex?: 'half' }` intersection because `@types/node` 22's `RequestInit` doesn't carry the member yet — assignable to the plain `RequestInit` `FetchLike` expects. Harmless (and spec'd) in browsers.
+- **`createBlobFromStream(digest, stream, request?)`** — the multi-gigabyte-safe counterpart of `createBlobFromData`: pipes any web `ReadableStream<Uint8Array>` straight into the request body with HEAD-dedupe semantics identical to the data-based variant. The digest must be known up front — it _is_ the upload URL, and the server verifies streamed content against it, so a truncated or corrupted stream fails the upload instead of poisoning the store.
+- **`createBlobFromFile` rewritten as two streaming passes** (same signature, same result shape): a SHA-256 hash pass through `node:crypto`'s incremental digest in 256 KiB chunks (skipped entirely when `opts.digest` is provided), then an upload pass piping `createReadStream` → `Readable.toWeb` into the streaming upload. Peak heap is O(chunk) in both passes; `createModelFromGguf` (which routes every shard through this method) inherits the bound. The method was already Node-only (hidden-specifier dynamic `node:fs`); the new `node:crypto`/`node:stream` imports follow the same pattern, keeping the main entry edge-portable.
+- **Cancellation plumbing**: `createBlob`/`checkBlob` now accept `RequestCancellationOptions` (`signal`/`timeoutMs`) like their siblings, and `createBlobFromData`'s previously decorative `signal` option is actually wired through. Aborts surface as `OllamaAbortError` from both file passes (the hash pass checks between chunks and destroys the fd; the upload pass forwards the signal to `fetch` and destroys the stream on abort).
+- New coverage pins the whole story: duplex injection (unit, injected `fetch`), byte-exact streamed uploads against a real capture server, the two-pass file flow (streaming digest matches the whole-file digest; wire bytes equal the file byte-for-byte), abort-before-traffic and abort-mid-stalled-upload, and daemonless public-mock round trips including `createModelFromGguf`'s headline flow (blob POST carries the shard, `/api/create` references it under its basename).
+
+### Typed-array view safety (BUF-01 — stale defect, pinned invariant)
+
+- The audit found zero `Buffer.from(view.buffer)`-style call sites: `computeBlobDigest` uses Web Crypto, which hashes a `BufferSource` view's bytes per spec, and `fetch` serializes `Uint8Array` bodies per-view. The digest's `safeUint8ArrayToBuffer`/`toUint8Array` helpers were declined — they couple a runtime-portable SDK to Node's `Buffer` and would regress the edge-runtime gate (ADR 0032).
+- The invariant is now pinned by the digest's own suggested probe, hardened with an external oracle: a `subarray(10, 20)` view of a 1024-byte patterned pool hashes to the standalone slice's digest (cross-checked against `node:crypto`) and arrives on the wire as exactly its 10 bytes — never the parent buffer.
+- Cleanup: `computeBlobDigest`'s misleading `data as unknown as ArrayBuffer` cast removed (the local structural `SubtleCrypto` type already accepts `ArrayBufferView`).
+
+### Tracing headers (TRC-01 — stale, documented)
+
+- The SDK forwards headers verbatim through three existing seams: client-level `headers` configuration (every request, every endpoint), per-request `headers` on transport request options (merged last, so they win), and middleware's mutable `RequestContext.headers` record — an OpenTelemetry-style extractor plugs in without touching a single method signature. The README's middleware section now shows the W3C `traceparent`/`tracestate`/`baggage` propagation pattern explicitly.
+- The digest's `traceContext` option on every client method and ambient `AsyncLocalStorage` capture were declined (ADR 0032): signature inflation and hidden global state for capability that already exists.
+
+### Upstream-specs digest verdicts (all stale — pointers, no new API)
+
+- **System One batching**: `client.systemOne()` already evaluates N named questions against shared state in one round trip, with compile-time question→answer type correlation the sketch lacks. **Payload caps**: `MAX_SYSTEM_ONE_REQUEST_BYTES` (64 KiB) / `MAX_SYSTEM_ONE_IMAGES_BYTES` (32 MiB) are exported, `estimateSystemOneRequestBytes()` is the pre-flight estimator, and the runtime enforces both client-side. **`expires_at`**: typed on `ModelResponse` from `/api/ps`, returned by `client.ps()`. **Model warmth**: `pin()`/`unload()`/`KEEP_ALIVE_INDEFINITE`/per-call `keep_alive`/`warmModelAffinity()` are the supported primitives; a background `ModelWarmthKeeper` timer daemon was declined (hidden event-loop work that escapes the client-teardown contract — reasoning in ADR 0032).
+
 ## [1.16.0] — Stream observation (`observeStream`), network-error classification & context-window recommendations
 
 The October 13 second digest ("Stream Multi-Sink Teeing, Context Window Overflow, Socket Hangup Recovery") targeted edge transport hazards and memory boundaries during high-throughput agent execution. Audited against the codebase first (see [ADR 0031](./docs/adr/0031-stream-observation-network-classification-context-recommendations.md)): the stream-teeing claim was the real gap (no observer utility existed, and `OllamaStream`'s dual modes are mutually exclusive — you couldn't tap a stream you were iterating); the context-overflow claim was comprehensively stale (a superior CJK-aware estimator with three-tier window resolution, `onContextOverflow` policies, and `getContextLength()` discovery has shipped since the v1.9.0 era — only its concrete-window suggestion was missing); and the socket-retry claim was inverted on the headline (every SDK-routed call already retries with backoff _and_ fails over — three retries where the digest asked for one) but real in one seam: network-error classification was `TypeError`-only, so code-carrying socket errors from custom `fetch` implementations and nested undici `cause` chains died un-retried on first attempt. All additive, no breaking changes. 977 pre-existing tests stay green, 35 new tests added.

package/README.md

@@ -24,16 +24,18 @@ Nexum’s model harness (2026-10-09) exercised this SDK via `gemma4:cloud` and `
 - 🧠 **Reasoning & Thinking Tokens**: First-class support for reasoning models (`qwen3:8b`, `deepseek-r1:8b`) via the native `think` parameter, with discrete `thinking` and `token` streaming events, plus `logprobs`/`top_logprobs` for token-level confidence scoring.
 - 🖼️ **Multimodal / Vision Input**: `images` on `Message`/`generate()` is a universal resolver — pass raw base64 strings, `data:image/...;base64,` data URIs, `http(s)://` URLs (fetched), local file paths (`.png`/`.jpg`/`.webp`/…, read via `node:fs` on Node), or raw `Buffer`/`Uint8Array` bytes — everything is normalized to the raw base64 Ollama's REST API expects, matching the official SDK vision convention.
 - 🎯 **Zod-Powered Structured Outputs**: Strictly typed schema enforcement via `chatWithSchema` and `generateWithSchema` with resilient markdown JSON parsing.
+- ⚖️ **System One Decision Helpers**: `client.decision` wraps Ollama's `/v1/systemone` classification engine with six ergonomic single-question APIs — `choice` / `noul` (yes-no) / `score` / `route` / `verify` / `rank` — each returning calibrated probabilities, and **opt-in confidence gates** (`minConfidence` / `minProbability`) so autonomous flows refuse to act on barely-majority decisions (a 0.51 coin-flip) without seeing the numbers.
 - 🛠️ **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, active health checks, and per-endpoint `models` allow-lists for routing several model-specific API keys through one client.
 - 🔌 **Model Context Protocol (MCP)**: First-class, transport-neutral `McpBridge` for converting MCP tool descriptors into Ollama function definitions and registering executable MCP-backed tools.
 - 📚 **Full Model Lifecycle**: `pullModel`, `pushModel`, `createModel`, `copyModel`, `deleteModel`, `listModels`, `showModel`, and `ps()` (currently loaded models) — full parity with Ollama's model management API.
+- 📶 **Pull & Push Progress with Speed/ETA**: `onProgress()` subscribes a typed callback to `pullModel`/`pushModel` NDJSON streams with a pre-computed `percent`, and `createProgressSpeedTracker()` adds per-layer `bytesPerSecond` + `etaSeconds` — the stateful byte counter CLIs and dashboards used to hand-roll, with layer-epoch reset semantics built in.
 - 🔎 **Ollama Cloud Web Tools**: `webSearch`/`webFetch` wrap Ollama's hosted `/api/web_search` and `/api/web_fetch` tools at `ollama.com` (requires an `OLLAMA_API_KEY`), independent of any local `baseUrl` — and `createWebTools(client)` exposes them as model-callable `web_search`/`web_fetch` tools with bounded, valid-JSON output for the documented search-agent pattern.
 - 💳 **Ollama Cloud Usage & Balance**: `usage()`/`balance()` wrap Ollama's hosted account endpoints (`GET /api/usage`, `GET /api/balance`) — request counts, USD spend, cached-token totals bucketed by hour/day, and remaining included/purchased credits (including the legacy session/weekly plan shapes) — with the same fixed-cloud-host, API-key, timeout, and retry semantics as the web tools.
 - 🌉 **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 — plus an ergonomic dual-mode `client.responses.create()` bridge that prefers native `/v1/responses` and transparently re-issues via `/api/chat` on older servers (pre-v0.13.3).
 - 💬 **KV-Cache-Aware Conversation Sessions**: `client.session(model, systemPrompt)` keeps an append-only, prefix-stable history that maximizes Ollama's KV-cache reuse across turns, surfaces per-turn + cumulative cache hit rates (`prompt_eval_cached_count`) so cache degradation is visible instead of silent, and offers a one-call `compact()` sliding-window escape hatch when a session outgrows its window.
 - 🛑 **Context-Window Safety**: Heuristic client-side token estimation warns (or throws, `onContextOverflow: 'throw'`) before a request is sent when the prompt approaches the effective `num_ctx` window — Ollama's default behavior is to _silently truncate_ oversized prompts — and `defaultContextLength` makes the window explicit on every request.
-- 📦 **Blob & Custom Model Publishing**: Content-addressed blob management per Ollama's documented protocol — `computeBlobDigest()` (SHA-256 → `sha256:<hex>`), `createBlobFromData()`/`createBlobFromFile()` (HEAD-check + upload, skipping existing blobs), and one-shot `createModelFromGguf()` (upload GGUF shard blobs, then `/api/create` with `files: {name: digest}`) — with **speculative-decoding assembly**: `draftGguf` uploads the draft network's shards into `draft_files`, `draft_quantize` compresses them independently, and `parameters.draft_num_predict` tunes the per-step draft length.
+- 📦 **Blob & Custom Model Publishing**: Content-addressed blob management per Ollama's documented protocol — `computeBlobDigest()` (SHA-256 → `sha256:<hex>`), `createBlobFromData()`/`createBlobFromFile()` (HEAD-check + upload, skipping existing blobs), **streaming uploads with O(chunk) heap** (`createBlobFromFile` hashes and uploads in 256 KiB chunks — multi-GB GGUFs never enter the Node heap; `createBlobFromStream()` pipes any web `ReadableStream` straight into `fetch` with `duplex: 'half'`), and one-shot `createModelFromGguf()` (upload GGUF shard blobs, then `/api/create` with `files: {name: digest}`) — with **speculative-decoding assembly**: `draftGguf` uploads the draft network's shards into `draft_files`, `draft_quantize` compresses them independently, and `parameters.draft_num_predict` tunes the per-step draft length.
 - 🏁 **Speculative Draft Benchmark (`compareDraftPerformance`)**: One call answers "does drafting pay off for _this_ prompt?" — identical prompt on both sides, deterministic sampling (`temperature: 0` + fixed seed), warm-up discard, several samples per side with **medians** compared, throughput via `formatTelemetry` — reported as baseline vs. speculative tok/s, `speedupMultiplier`, and `effectiveGain` past a configurable threshold. A ≈1.0 speedup is itself diagnostic: the model has no draft network, so the server silently ignores the option.
 - 🧪 **In-Memory Mock Server (`@nemesis-oss/ollama-sdk/testing`)**: The SDK's own deterministic test double, promoted public — `createMockOllamaServer()` with scriptable NDJSON routes, built-in liveness/version defaults (so `ping()` works out of the box), request recording for wire-level assertions, **request-aware routes** (`responder` — per-request responses for fail-twice-then-succeed retry drills and body-dependent payloads), mid-stream **in-band error injection** (`{"error": "..."}` frames at HTTP 200, exactly how a real daemon reports GPU OOM), connection drops, and correctly-shaped chunk builders for streaming text and **parallel tool calls** — zero network, zero daemon, CI-deterministic.
 - 🧵 **Batched Embeddings with Backpressure**: `client.embedBatch()` splits corpora of any size into bounded `/api/embed` batches (default 32 inputs × 3 in flight) — order-preserving, fail-fast, progress-reporting — so RAG/vector ingestion can't OOM a local daemon or saturate `OLLAMA_MAX_QUEUE` the way `Promise.all` floods do, with per-string context-window pre-flight against silent truncation.
@@ -500,6 +502,34 @@ await client.models.createModelFromGguf('my-model', [
 ]);
 ```
 
+#### Streaming uploads — multi-gigabyte weights with O(chunk) heap
+
+Both `createBlobFromFile` and `createModelFromGguf` (which routes every shard
+through it) stream instead of bulk-reading: the SHA-256 hash pass and the
+upload pass each consume the file in 256 KiB chunks, so peak heap is a chunk,
+never the file. Pass `digest` when you already know it to skip the hash pass
+entirely. When you own the bytes (a chunk producer, a WASM/SharedArrayBuffer
+pipeline, a resumed download), `createBlobFromStream` pipes any web
+`ReadableStream<Uint8Array>` straight into the request body — the transport
+sets `duplex: 'half'` (required by Node 18+ `fetch` for stream bodies)
+automatically, and the server verifies the streamed content against the
+digest, so a truncated stream fails the upload instead of corrupting the
+store:
+
+```typescript
+// digest known up front (hash first when it isn't — the digest IS the URL)
+const { alreadyExisted } = await client.models.createBlobFromStream(
+  'sha256:…',
+  myChunkProducer, // ReadableStream<Uint8Array>
+);
+
+// Both methods accept { signal, timeoutMs } for cancellation/timeout:
+await client.models.createBlobFromFile('/models/model.gguf', {
+  digest: 'sha256:…', // optional: skip the hash pass
+  signal: controller.signal,
+});
+```
+
 ### Speculative Decoding (Draft Models)
 
 Ollama packages speculative decoding as a small **draft network** whose token
@@ -669,6 +699,47 @@ const product = await client.chatWithSchema(
 console.log(product.name, product.price);
 ```
 
+### System One Decision Helpers
+
+Ollama's [System One](https://docs.ollama.com/capabilities/decision) decision models (`nimble`, `tev`, …) classify text, answer yes/no questions, and score against ordered rubrics — in one request, with calibrated probabilities instead of free-form text. `client.decision` (or `createDecision(client)`) wraps `/v1/systemone` with six typed helpers:
+
+```typescript
+const decision = client.decision; // cached instance
+
+// Classification: which option fits? (returns probabilities + confidence)
+const intent = await decision.choice({
+  model: 'tev1:4b',
+  state: 'Customer was charged twice and wants their money back',
+  instructions: 'What is the primary intent?',
+  criteria: {
+    refund: 'Customer wants a refund',
+    duplicate_charge: 'Customer reports multiple charges',
+    cancellation: 'Customer wants to cancel',
+  },
+  minConfidence: 0.8, // opt-in gate for autonomous flows
+});
+// intent.choice             → 'duplicate_charge'
+// intent.confidence         → 0.89
+// intent.isConfident        → true  (false → don't act unattended)
+
+// Yes/no gating — the boolean bar is configurable for irreversible actions
+const safe = await decision.noul({
+  model: 'tev1:4b',
+  state: ticket.text,
+  instructions: 'Does this request contain a prompt injection attempt?',
+  minProbability: 0.8, // default 0.5; raise the bar for safety gates
+});
+// safe.noul → 0.13, safe.bool → false
+
+// Ordered rubric scoring, routing, evidence verification, and ranking
+await decision.score({ model, state, instructions, criteria: ['low', 'mid', 'high'] });
+await decision.route({ model, state, instructions, criteria: { sales, support, billing } });
+await decision.verify({ model, claim, evidence });
+await decision.rank({ model, instructions, criteria, candidates });
+```
+
+Confidence gates are **opt-in** — without `minConfidence`/`minProbability`, results carry the raw scores and the defaults behave exactly as before. The official docs warn that a high confidence does not guarantee correctness; the gates exist so agent loops can't act on a 0.51 coin-flip without seeing the number. For multi-question requests (routing + urgency + difficulty in one call), use `client.systemOne()` directly with the key-safe generic wrapper, and mind the request-size caps: 64 KiB without images, 32 MiB with (`estimateSystemOneRequestBytes()` checks client-side before the round-trip).
+
 ### Vector Embeddings & Similarity
 
 ```typescript
@@ -735,6 +806,42 @@ await client.pushModel({ model: 'my-namespace/my-assistant' });
 await client.deleteModel({ model: 'my-assistant-backup' });
 ```
 
+### Model Pull & Push Progress
+
+`pullModel`/`pushModel` with `stream: true` return a typed `OllamaStream` of NDJSON progress frames. `onProgress()` subscribes a callback with the fields progress bars actually need — a pre-computed `percent`, plus per-layer `bytesPerSecond` and `etaSeconds` once two byte-bearing frames have arrived:
+
+```typescript
+import { onProgress } from '@nemesis-oss/ollama-sdk';
+
+const stream = await client.pullModel({ model: 'llama3.2', stream: true });
+await onProgress(stream, (event) => {
+  if (event.percent !== undefined) {
+    const speed = event.bytesPerSecond
+      ? ` at ${(event.bytesPerSecond / 1024 / 1024).toFixed(1)} MiB/s`
+      : '';
+    const eta = event.etaSeconds ? `, ETA ${Math.ceil(event.etaSeconds)}s` : '';
+    console.log(`${event.status}: ${event.percent.toFixed(2)}%${speed}${eta}`);
+  } else {
+    console.log(event.status); // "pulling manifest", "verifying sha256 digest", …
+  }
+});
+console.log('pull complete');
+```
+
+Speed semantics are chosen for stable UIs: a **cumulative average** since the layer's first byte-bearing frame (instantaneous frame-to-frame rates jitter wildly), with automatic **per-layer epochs** — the tracker resets whenever the `digest` changes or `completed` regresses, so a 4-layer pull never averages across layers. Consumers iterating the raw stream themselves (structured logging, custom dashboards) can use `createProgressSpeedTracker()` directly — the same stateful byte counter, without hand-rolling one:
+
+```typescript
+import { createProgressSpeedTracker } from '@nemesis-oss/ollama-sdk';
+
+const speed = createProgressSpeedTracker();
+for await (const event of stream) {
+  if (event.type === 'message') {
+    const { bytesPerSecond, etaSeconds } = speed(event.data.chunk);
+    // …render your own bar
+  }
+}
+```
+
 ### Web Search & Web Fetch (Ollama Cloud)
 
 `webSearch`/`webFetch` wrap Ollama's **hosted** web tools (`POST https://ollama.com/api/web_search` and `/api/web_fetch`) — a fixed Ollama Cloud service, entirely separate from whatever local `baseUrl`/`endpoints` the client is configured with. They require an Ollama account API key (`apiKey` on the client, or the `OLLAMA_API_KEY` environment variable) regardless of where your inference traffic goes:
@@ -1934,6 +2041,25 @@ around the underlying HTTP request for native endpoints, OpenAI/Anthropic compat
 model health checks, and the hosted web tools. Lifecycle events expose `start`, `success`,
 `retry`, and `error` events with a request id, timing, and status/error information.
 
+**Distributed tracing (W3C `traceparent`/`tracestate`/`baggage`)**: the SDK forwards
+whatever headers it is given and never strips or rewrites yours — three seams cover
+propagation. Client-wide (every request, every endpoint):
+
+```ts
+const client = new OllamaClient({
+  headers: {
+    traceparent: carrierHeader('traceparent'), // from your inbound request
+    baggage: carrierHeader('baggage'),
+  },
+});
+```
+
+Per-request or computed (the middleware seam from above — `request.headers` is a mutable
+record, so an OpenTelemetry-style extractor plugs in directly and can vary headers per
+call). A `traceContext` option on every SDK method was considered and declined
+(ADR 0032): it would inflate every signature for something these seams already do
+without touching them.
+
 ```ts
 const client = new OllamaClient({
   middleware: [

package/dist/{anthropic-AKbXnWJU.d.cts → anthropic-BvHOsidk.d.cts}

@@ -552,10 +552,10 @@ type SystemOneProbabilities = {
  */
 
 interface SystemOneRequest {
-    /** Local model trained for System One, such as nimble. Requires compatible GGUF weights and a scoring-capable runner; cloud and MLX/Safetensors models are not supported. */
+    /** Local model trained for System One, such as nimble. */
     readonly model: string;
     readonly state: SystemOneContent;
-    /** Base64-encoded images shared by all questions, in request order. Requires Clef or Clef Flash with vision weights. URLs and data URLs are not supported. */
+    /** Base64-encoded images shared by all questions, in request order. Requires a model with vision, such as Clef. URLs and data URLs are not supported. */
     readonly images?: readonly string[] | undefined;
     /** Named questions about the shared state. Answers are not passed to later questions. */
     readonly questions: {
@@ -614,7 +614,7 @@ interface SystemOneScoreAnswer {
 interface SystemOneScoreQuestion {
     readonly type: 'score';
     readonly instructions: SystemOneContent;
-    /** Descriptions ordered from the lowest score (index 0) to the highest. Defines a scale from 0 to the number of criteria minus 1. The maximum number of levels depends on the model. */
+    /** Descriptions ordered from the lowest score (index 0) to the highest. Defines a scale from 0 to the number of criteria minus 1. */
     readonly criteria: readonly string[];
 }
 

package/dist/{anthropic-CTv2acbj.d.ts → anthropic-CvGVSoVP.d.ts}

@@ -552,10 +552,10 @@ type SystemOneProbabilities = {
  */
 
 interface SystemOneRequest {
-    /** Local model trained for System One, such as nimble. Requires compatible GGUF weights and a scoring-capable runner; cloud and MLX/Safetensors models are not supported. */
+    /** Local model trained for System One, such as nimble. */
     readonly model: string;
     readonly state: SystemOneContent;
-    /** Base64-encoded images shared by all questions, in request order. Requires Clef or Clef Flash with vision weights. URLs and data URLs are not supported. */
+    /** Base64-encoded images shared by all questions, in request order. Requires a model with vision, such as Clef. URLs and data URLs are not supported. */
     readonly images?: readonly string[] | undefined;
     /** Named questions about the shared state. Answers are not passed to later questions. */
     readonly questions: {
@@ -614,7 +614,7 @@ interface SystemOneScoreAnswer {
 interface SystemOneScoreQuestion {
     readonly type: 'score';
     readonly instructions: SystemOneContent;
-    /** Descriptions ordered from the lowest score (index 0) to the highest. Defines a scale from 0 to the number of criteria minus 1. The maximum number of levels depends on the model. */
+    /** Descriptions ordered from the lowest score (index 0) to the highest. Defines a scale from 0 to the number of criteria minus 1. */
     readonly criteria: readonly string[];
 }
 

package/dist/generated-api.d.cts

@@ -1,5 +1,5 @@
-import { O as OpenAIChatCompletionRequest, a as OpenAIChatCompletionResponse, b as OpenAIChatCompletionChunk, c as OpenAICompletionRequest, d as OpenAICompletionResponse, e as OpenAICompletionChunk, f as OpenAIEmbeddingRequest, g as OpenAIEmbeddingResponse, h as OpenAIListModelsResponse, i as OpenAIModelItem, j as OpenAIResponsesRequest, k as OpenAIResponsesResponse, l as OpenAIResponsesStreamEvent, A as AnthropicMessagesRequest, m as AnthropicMessagesResponse, n as AnthropicMessageStreamEvent } from './anthropic-AKbXnWJU.cjs';
-export { N as NativeApi } from './anthropic-AKbXnWJU.cjs';
+import { O as OpenAIChatCompletionRequest, a as OpenAIChatCompletionResponse, b as OpenAIChatCompletionChunk, c as OpenAICompletionRequest, d as OpenAICompletionResponse, e as OpenAICompletionChunk, f as OpenAIEmbeddingRequest, g as OpenAIEmbeddingResponse, h as OpenAIListModelsResponse, i as OpenAIModelItem, j as OpenAIResponsesRequest, k as OpenAIResponsesResponse, l as OpenAIResponsesStreamEvent, A as AnthropicMessagesRequest, m as AnthropicMessagesResponse, n as AnthropicMessageStreamEvent } from './anthropic-BvHOsidk.cjs';
+export { N as NativeApi } from './anthropic-BvHOsidk.cjs';
 import { O as OllamaRuntime } from './runtime-CdZP-N7j.cjs';
 export { a as OperationDefinition } from './runtime-CdZP-N7j.cjs';
 import './types-DbPnfVh-.cjs';

package/dist/generated-api.d.ts

@@ -1,5 +1,5 @@
-import { O as OpenAIChatCompletionRequest, a as OpenAIChatCompletionResponse, b as OpenAIChatCompletionChunk, c as OpenAICompletionRequest, d as OpenAICompletionResponse, e as OpenAICompletionChunk, f as OpenAIEmbeddingRequest, g as OpenAIEmbeddingResponse, h as OpenAIListModelsResponse, i as OpenAIModelItem, j as OpenAIResponsesRequest, k as OpenAIResponsesResponse, l as OpenAIResponsesStreamEvent, A as AnthropicMessagesRequest, m as AnthropicMessagesResponse, n as AnthropicMessageStreamEvent } from './anthropic-CTv2acbj.js';
-export { N as NativeApi } from './anthropic-CTv2acbj.js';
+import { O as OpenAIChatCompletionRequest, a as OpenAIChatCompletionResponse, b as OpenAIChatCompletionChunk, c as OpenAICompletionRequest, d as OpenAICompletionResponse, e as OpenAICompletionChunk, f as OpenAIEmbeddingRequest, g as OpenAIEmbeddingResponse, h as OpenAIListModelsResponse, i as OpenAIModelItem, j as OpenAIResponsesRequest, k as OpenAIResponsesResponse, l as OpenAIResponsesStreamEvent, A as AnthropicMessagesRequest, m as AnthropicMessagesResponse, n as AnthropicMessageStreamEvent } from './anthropic-CvGVSoVP.js';
+export { N as NativeApi } from './anthropic-CvGVSoVP.js';
 import { O as OllamaRuntime } from './runtime-CFuv7Ifh.js';
 export { a as OperationDefinition } from './runtime-CFuv7Ifh.js';
 import './types-DbPnfVh-.js';

package/dist/generated-models-schemas.cjs

@@ -328,7 +328,7 @@ var SystemOneNoulQuestionSchema = zod.z.object({
 var SystemOneScoreQuestionSchema = zod.z.object({
   type: zod.z.enum(["score"]),
   instructions: SystemOneContentSchema,
-  criteria: zod.z.array(zod.z.string()).min(2).max(26)
+  criteria: zod.z.array(zod.z.string()).min(2).max(10)
 });
 
 // src/generated/models/SystemOneRequest.schema.ts
@@ -349,7 +349,7 @@ var SystemOneRequestSchema = zod.z.object({
 });
 var SystemOneScoreAnswerSchema = zod.z.object({
   type: zod.z.enum(["score"]),
-  score: zod.z.number().min(0).max(25),
+  score: zod.z.number().min(0).max(9),
   legend: zod.z.object({}).catchall(zod.z.string()),
   probabilities: SystemOneProbabilitiesSchema,
   confidence: SystemOneConfidenceSchema