@nemesis-oss/ollama-sdk 1.0.0 → 1.3.0

package/CHANGELOG.md

@@ -5,6 +5,160 @@ 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.3.0] - 2026-08-25
+
+### Added
+
+- **Client-side quota monitoring (`QuotaManager`).** Ollama Cloud doesn't expose
+  account-level quota through the API — no response header or endpoint reports how much
+  of your plan's session/weekly limit is left (see
+  [ollama/ollama#15663](https://github.com/ollama/ollama/issues/15663)). `QuotaManager`
+  tracks usage you record (via `recordUsage`, which reads `extractUsage`-normalized token
+  counts off a raw response) against budgets you configure over one or more rolling
+  windows, and refuses to proceed (`canProceed`/`assertCanProceed`) once a window's budget
+  is spent — a local safety net to complement, not replace, catching the server's own
+  `OllamaRateLimitError`. `createOllamaCloudFreeTierQuota` is a convenience factory
+  wiring up the free tier's documented 5-hour session and 7-day weekly window cadence
+  (you still supply the token/request budgets, since Ollama doesn't publish the actual
+  ceilings). New `OllamaQuotaExceededError` (`code: 'quota_exceeded'`) is thrown by
+  `assertCanProceed`. See the [Quota Monitoring](./README.md#quota-monitoring) README
+  section.
+- **Credential-scoped multi-key routing.** `OllamaEndpoint` gains an optional `models`
+  allow-list, for the common case of several Ollama Cloud API keys each entitled to a
+  different model. `EndpointRegistry.candidates(model)` now filters to endpoints whose
+  `models` includes the requested model (endpoints without `models` stay eligible for
+  every model — fully backward compatible), so `chat`/`generate`/`embed`/`embeddings` and
+  model-lifecycle calls (`showModel`, `pullModel`, etc.) automatically resolve the
+  authorized credential for the model requested, and cross-endpoint failover between
+  differently-scoped endpoints never sends a request to a key that isn't entitled to that
+  model. Requesting a model no configured endpoint is scoped to throws the new
+  `OllamaModelRoutingError` (`code: 'model_routing_error'`) immediately, before any
+  network call — the SDK never probes unauthorized keys to see which one happens to
+  work. See the README's
+  ["Multiple API keys, each entitled to different models"](./README.md#multiple-api-keys-each-entitled-to-different-models)
+  and the
+  [multi-model agent benchmarking guide](./docs/guides/multi-model-agent-benchmarking.md).
+- **`credentials` + `modelBindings` config.** An ergonomic, map-based alternative to
+  writing `endpoints` with per-entry `models` allow-lists by hand: `OllamaClientConfig`
+  gains `credentials` (named `{ apiKey, baseUrl?, headers? }` entries, keyed by an id you
+  choose), `modelBindings` (maps a model to the credential id, or ids, authorized to serve
+  it), and `defaultCredential` (a fallback credential for any model with no explicit
+  binding). Both config shapes compile down to the same `EndpointRegistry`/
+  `executeWithFailover` routing above — this is config sugar, not a second routing
+  mechanism — so behavior (including `OllamaModelRoutingError` on an unrouted model) is
+  identical either way. `modelBindings` referencing an unknown credential id throws at
+  construction. New `resolveCredentialEndpoints` export for anyone who wants the
+  translation without going through `OllamaClient`.
+- **Round-robin candidate selection.** `EndpointRegistryOptions` (passed via
+  `OllamaClientConfig.endpointHealth`) gains `strategy: 'priority' | 'round-robin'`
+  (default `'priority'`, unchanged prior behavior). With `'round-robin'`,
+  `EndpointRegistry.candidates()` rotates each same-priority group of healthy candidates
+  by one position per call, so consecutive `chat`/`generate`/`embed`/etc. calls spread
+  across a pool of interchangeable endpoints or unbound `credentials` (e.g. several
+  free-tier Ollama Cloud keys with no `models`/`modelBindings` restriction) instead of
+  always preferring the first one. Candidates at different priorities are unaffected —
+  a higher-priority candidate is still always tried first — and failover to the rest of
+  the (rotated) list still applies if the first pick fails. See the README's
+  ["A free pool of interchangeable keys — and spreading load across it"](./README.md#a-free-pool-of-interchangeable-keys--and-spreading-load-across-it).
+- **Least-connections candidate selection.** `EndpointRegistryOptions.strategy` gains a
+  third value, `'least-connections'`, alongside `'priority'` (default) and
+  `'round-robin'`. Each same-priority tier is ordered by ascending in-flight request
+  count (new `EndpointRegistry.acquire`/`release`, wired into `OllamaClient.executeWithFailover`
+  around each attempt) rather than a fixed rotation, so concurrent `Promise.all`-style
+  fan-out deterministically lands on distinct candidates — the motivating case being
+  several Ollama Cloud free-tier accounts, each capped at 1 concurrent request: `N`
+  concurrent requests against `N` such accounts land one-per-account rather than risking
+  two on the same still-busy one, because the endpoint choice and its `acquire()` happen
+  synchronously with no `await` in between (JS's single-threaded execution rules out the
+  race entirely). `EndpointHealth` gains `activeRequests`, also exposed via
+  `client.endpointStatus()`, for observability regardless of `strategy`. See the README's
+  ["Concurrent requests across single-slot accounts (least-connections)"](./README.md#concurrent-requests-across-single-slot-accounts-least-connections).
+- **`maxConcurrentPerEndpoint` — queueing past capacity.** `EndpointRegistryOptions`
+  gains `maxConcurrentPerEndpoint`, capping in-flight requests per endpoint exactly. Once
+  every otherwise-eligible candidate is at that cap, a request waits (FIFO, new
+  `EndpointRegistry.filterWithCapacity`/`waitForCapacity`) for one to free rather than
+  being routed to an already-saturated candidate — the gap `'least-connections'` alone
+  doesn't close for `N + 1` concurrent calls against `N` capacity-1 candidates. Waiting is
+  bounded by the request's own `timeoutMs`/`AbortSignal`; a queued call that times out or
+  is cancelled is dequeued and rejects without ever being sent.
+
+### Fixed
+
+- **Streaming requests (`chatStream`/`generateStream`) now hold their endpoint's
+  concurrency slot for the lifetime of the stream, not just until it starts.**
+  Previously, `acquire`/`release` around a streaming call released the slot as soon as
+  `http.requestStream` resolved (response headers received) — before any tokens were
+  actually read — so `'least-connections'`/`maxConcurrentPerEndpoint` accounting stopped
+  reflecting reality the moment a stream was returned, undercounting real concurrency for
+  as long as the caller kept consuming it. `executeWithFailover` gains an internal
+  `holdUntil` hook, wired to the returned `OllamaStream`'s `finalResult` for `chatStream`/
+  `generateStream` (and the streaming `pull`/`push`/`create` progress endpoints), so the
+  slot now releases only once the stream is fully drained, errors, or is aborted.
+
+## [1.2.0] - 2026-08-24
+
+Closes gaps found during a documentation/API-parity review against the official Ollama
+API — two of which were genuine issues, the rest already covered (multimodal `images`,
+native `think`, `/api/embed`, and full model-lifecycle management all predate this
+release; see the new README sections documenting them).
+
+### Fixed
+
+- **`webSearch`/`webFetch` were non-functional against real Ollama Cloud.** They
+  previously posted to `<configured-baseUrl>/api/websearch` and `/webfetch` — the wrong
+  host (Ollama's web tools only ever exist at `https://ollama.com`, never proxied through
+  a local server) _and_ the wrong path (missing the underscore: `/api/web_search`,
+  `/api/web_fetch`) _and_ the wrong request/response field names. Both methods now always
+  target `https://ollama.com` regardless of `baseUrl`/`endpoints`, using the resolved
+  `apiKey`/`OLLAMA_API_KEY`, and use the real field names (`max_results` request,
+  `content` response). `WebSearchRequestOptions.count` and `WebSearchResult.snippet` are
+  kept as `@deprecated` back-compat aliases (mapped to/mirrored from the correct fields)
+  rather than removed outright. `WebFetchResponse` gains the `title`/`links` fields the
+  real API actually returns.
+
+### Added
+
+- **`logprobs`/`top_logprobs`:** Added to `ChatRequestOptions`/`GenerateRequestOptions`
+  (request) and `ChatResponse`/`GenerateResponse` (response, as a new `Logprob[]` typed
+  by the new `Logprob`/`LogprobToken` types), matching the official `/api/chat` and
+  `/api/generate` schemas.
+- `OLLAMA_CLOUD_BASE_URL` exported for consumers who want to reference the fixed web-tools
+  host directly.
+
+## [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