ollama-client 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d553fa8a5ab841efb4e5c8e8369543618eca89b6930365a62f4af21a75df317
-  data.tar.gz: 455ef12da68ec09b33b32dea2404dfbf48ea4b087d96a8e140f681d1845377bf
+  metadata.gz: cb8311c8125a276a71ebb5793eaa3db0f12819a5c2860fdcfc684bbd2cc070a4
+  data.tar.gz: 6deb2ccaa92539928327cf56169764b2a3e96aba2f31effaf1ad5ab9ee615483
 SHA512:
-  metadata.gz: 211a89b870ec9e95c341f27cbe7f15d081a0537314ca578d388ee2a8677c16c58e4f6709cc33bb30cb2a58a478a058fc7f9c172af35a405f57372ce154e8fc72
-  data.tar.gz: 600cc892452d4e867dcd93bd6995a93aed8c69b5d1dc21600134c513b6ad65c1fd7d3fb13b18be2e8d4ee20ce9f5a74cb86afa5e30ffd7fb8ee588bd08109c1a
+  metadata.gz: 10af6c797b73974edb149e4daa7d7c81f856456fe17c9906feb0ee18215c4baf775b70be8bf88f5a1dc2ae182c3a29e24713f9fc6ba4a18a0b170804f51e62bb
+  data.tar.gz: a985ebf3f9f9b8ac52def574b0a160f8a639280c1f18c019ba75135548089caa12e7b3f9c292cd06f93463421d86658cea5e25388b305930d5ae385699b228ab

data/.env.example

@@ -0,0 +1,11 @@
+# Ollama local server by default. Use https://ollama.com for Ollama Cloud.
+OLLAMA_BASE_URL=http://localhost:11434
+
+# Single Ollama Cloud API key fallback.
+OLLAMA_API_KEY=
+
+# Optional comma-separated Ollama Cloud API key pool. Takes precedence over OLLAMA_API_KEY.
+OLLAMA_API_KEYS=
+
+# Set to true/1 to round-robin initial keys across concurrent request threads.
+ENABLE_MULTI_KEY_CONCURRENCY=false

data/API_CONTRACT.md

@@ -1,6 +1,6 @@
-# API Contract — v1.3.0
+# API Contract — v1.4.0
 
-This document defines the **public API surface** of `ollama-client` v1.3.0.
+This document defines the **public API surface** of `ollama-client` v1.4.0.
 Everything listed here is guaranteed stable until `v2.0.0` (unless explicitly marked as *may evolve* in minor releases).
 
 ## Public Methods
@@ -28,7 +28,9 @@ client = Ollama::Client.new(config: Ollama::Config.new)
 
 | Method | Signature | Returns |
 |---|---|---|
-| `generate` | `(prompt:, schema: nil, model: nil, strict: config.strict_json, return_meta: false, system: nil, images: nil, think: nil, return_reasoning: false, keep_alive: nil, suffix: nil, raw: nil, options: nil, hooks: {})` | `String` (no schema) or `Hash` (with schema) |
+| `generate` | `(prompt:, context: nil, schema: nil, model: nil, strict: config.strict_json, return_meta: false, system: nil, images: nil, think: nil, return_reasoning: false, keep_alive: nil, suffix: nil, raw: nil, options: nil, hooks: {}, tools: nil)` | `String` (no schema) or `Hash` (with schema) |
+
+`context:` accepts the `context` array returned by a previous `generate` call (or via `return_meta: true`) for `/api/generate`-side conversational memory, independent of `chat`'s message history.
 
 When `think: true` and `return_reasoning: true`, the return value is a `Hash` with:
 
@@ -43,13 +45,28 @@ When `think: true` and `return_reasoning: true`, the return value is a `Hash` wi
 | `list_model_names` | `()` | `Array<String>` |
 | `list_running` / `ps` | `()` | `Array<Hash>` |
 | `show_model` | `(model:, verbose: false)` | `Hash` |
-| `pull` | `(model_name)` | `true` |
+| `pull` | `(model_name, insecure: false, stream: false, hooks: {})` | `Hash` (final status) |
 | `delete_model` | `(model:)` | `true` |
 | `copy_model` | `(source:, destination:)` | `true` |
-| `create_model` | `(model:, from:, system: nil, template: nil, license: nil, parameters: nil, messages: nil, quantize: nil, stream: false)` | `Hash` |
-| `push_model` | `(model:, insecure: false, stream: false)` | `Hash` |
+| `create_model` | `(model:, from: nil, modelfile: nil, path: nil, system: nil, template: nil, license: nil, parameters: nil, messages: nil, quantize: nil, stream: false)` | `Hash` |
+| `push_model` | `(model:, insecure: false, stream: false, hooks: {})` | `Hash` (final status) |
+| `blob_exists?` | `(digest:)` | `Boolean` |
+| `create_blob` | `(digest:, content:)` | `true` |
+| `load_model` | `(model:, keep_alive: "5m")` | `true` |
+| `unload_model` | `(model:)` | `true` |
 | `version` | `()` | `String` |
-| `embeddings` | _(attr_reader)_ | `Ollama::Embeddings` instance |
+| `embeddings` | *(attr_reader)* | `Ollama::Embeddings` instance |
+
+`pull` and `push_model` accept `hooks: { on_progress: ->(status) { ... } }`, invoked once per streamed NDJSON status line (`stream: true`) with the parsed status `Hash`.
+
+#### Web Search (Ollama Cloud)
+
+Require `config.base_url = "https://ollama.com"` and `config.api_key` / `OLLAMA_API_KEY`.
+
+| Method | Signature | Returns |
+|---|---|---|
+| `web_search` | `(query:, max_results: nil)` | `Array<Hash>` (`"title"`, `"url"`, `"content"`) |
+| `web_fetch` | `(url:)` | `Hash` (`"title"`, `"content"`, `"links"`) |
 
 ### `Ollama::Embeddings`
 
@@ -122,7 +139,7 @@ All attributes are read/write via `attr_accessor`:
 |---|---|---|---|
 | `base_url` | `String` | `"http://localhost:11434"` | Ollama server URL |
 | `api_key` | `String, nil` | `nil` | Optional Bearer token for Ollama Cloud (`https://ollama.com`) |
-| `model` | `String` | `"llama3.2:3b"` | Default model for generation |
+| `model` | `String` | `"qwen3.5:4b"` | Default model for generation |
 | `timeout` | `Integer` | `30` | HTTP read/open timeout in seconds |
 | `retries` | `Integer` | `2` | Max retry attempts |
 | `strict_json` | `Boolean` | `true` | Enable JSON validation + repair |
@@ -131,6 +148,60 @@ All attributes are read/write via `attr_accessor`:
 | `num_ctx` | `Integer` | `8192` | Context window size |
 | `on_response` | `Proc/nil` | `nil` | Global response callback |
 
+### Raw Escape Hatch
+
+`client.raw` — direct HTTP access for endpoints without a dedicated method. Auth, retries, and error
+mapping (`handle_http_error`) are applied the same as typed methods; the response body is JSON-parsed.
+
+| Method | Signature | Returns |
+|---|---|---|
+| `raw.get` | `(path, query: nil)` | `Hash` |
+| `raw.post` | `(path, payload: {}, query: nil)` | `Hash` |
+| `raw.delete` | `(path, payload: nil, query: nil)` | `Hash` |
+
+### OpenAI Compatibility Facade
+
+`client.openai` — wraps `chat`, `generate`, `embeddings`, and `list_models` in OpenAI Chat Completions
+API request/response shapes, for code written against OpenAI-shaped SDKs.
+
+| Method | Signature | Returns |
+|---|---|---|
+| `openai.models.list` | `()` | `Hash` (`{"object"=>"list", "data"=>[...]}`) |
+| `openai.embeddings.create` | `(model:, input:, **opts)` | `Hash` (`{"object"=>"list", "data"=>[...], "model"=>...}`) |
+| `openai.chat.completions.create` | `(model:, messages:, tools: nil, temperature: nil, top_p: nil, **)` | `Hash` (OpenAI chat completion shape) |
+| `openai.completions.create` | `(model:, prompt:, temperature: nil, top_p: nil, **)` | `Hash` (OpenAI text completion shape) |
+
+## Policy Middleware (v1.4+)
+
+`client.use(policy_class, **options)` attaches production-behavior middleware to the request
+pipeline (chain order = registration order). All policies live under `Ollama::Policies::` and
+wrap non-streaming requests; HTTP failures surface inside the chain as typed errors
+(`Errors.from_response`), so policies observe 404/429/5xx responses.
+
+| Policy | Options | Behavior |
+|---|---|---|
+| `Policies::Retry` | `max_attempts:`, `strategy:` (`:exponential`/`:linear`/`:fixed`/`:jitter`), `base_delay:`, `max_delay:`, `jitter:`, `retryable_errors:`, `hooks:` | Retries network errors and HTTP 429/5xx with backoff |
+| `Policies::Timeout` | `connect_timeout:`, `read_timeout:`, `write_timeout:`, `hooks:` (`:on_timeout`) | Annotates `env[:timeouts]`; fires `:on_timeout` hook |
+| `Policies::AutoPull` | `enabled:`, `allowed_patterns:` (glob), `hooks:` (`:before_pull`, `:after_pull`) | On 404, pulls the requested model once and retries the request |
+| `Policies::Fallback` | `models:` (ordered list), `fallback_on:`, `hooks:` | Re-issues the request against each fallback model until one succeeds |
+| `Policies::RateLimit` | `requests_per_second:`, `requests_per_minute:`, `burst:`, `hooks:` | Token-bucket throttling before dispatch |
+| `Policies::CapabilityValidation` | `enabled:`, `cache:`, `cache_ttl:`, `hooks:` (`:capability_missing`) | Raises `UnsupportedCapabilityError` when the model profile lacks a requested capability (tools/thinking/vision/structured output) |
+| `Policies::RepairJson` | `max_repairs:`, `strategies:` (`:balanced`, `:extract_object`), `hooks:` | Repairs malformed JSON response bodies |
+| `Policies::SchemaRepair` | `max_repairs:`, `strict:`, `hooks:` | Validates structured output against the request `format` schema and repairs violations (missing fields, type mismatches, extras) |
+
+## Agent Executor (v1.4+)
+
+`Ollama::Agent::Executor` (required by the default load path) runs the chat + tool-calling loop:
+
+| Method | Signature | Returns |
+|---|---|---|
+| `Executor#run` | `(system:, user:)` | `String` — final assistant content |
+| `Executor#messages` | `()` | `Array<Hash>` — conversation history (system, user, assistant, tool turns) |
+
+Constructor: `Executor.new(client, tools: { "name" => callable_or_tool }, max_steps: 20, stream: nil)`.
+Tool keys may be strings or symbols. Pass `stream:` an `Ollama::StreamingObserver` to receive
+`:token`, `:tool_call_detected`, and `:state` events.
+
 ## Error Classes
 
 All errors inherit from `Ollama::Error < StandardError`.

data/CHANGELOG.md

@@ -5,6 +5,51 @@ All notable changes to this project 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.4.0] - 2026-08-18
+
+### Added
+- `Ollama::Policies::*` middleware is now **wired and public**: `client.use(Ollama::Policies::Retry, ...)` etc. attaches retry/timeout/auto-pull/fallback/rate-limit/capability-validation/JSON-repair/schema-repair policies to the request pipeline. The Rack-style `call(request, env)`/`@app` scaffolding was converted to the pipeline's `around` contract, and HTTP failures now surface as typed errors *inside* the chain (`Transport::Base#call` → `Errors.from_response`) so policies can observe 404/429/5xx responses. Documented in `API_CONTRACT.md`.
+- `Ollama::Agent::Executor` is wired into the default load path and `#run` now uses the current `chat()` API (streaming via `hooks:`) instead of the removed `chat_raw`; tool keys may be strings or symbols.
+- `SchemaViolationError` now carries structured `violations` (field/type data), raised by `SchemaValidator` and consumed by `SchemaRepair`.
+- `Ollama::Schemas.tool_intent` is now the default schema for `client.generate_tool_intent`.
+- `list_running`, `show_model`, and `version` now parse through `Parsers::{ListRunning,ShowModel,Version}` (previously dead files).
+- Multi-API-key Ollama Cloud failover via `Ollama::Config#api_keys`, `OLLAMA_API_KEYS`, and automatic HTTP 429 rotation with `Ollama::RateLimitExhaustedError` when every key remains rate-limited.
+- `ENABLE_MULTI_KEY_CONCURRENCY` / `Ollama::Config#enable_multi_key_concurrency` for thread-safe round-robin initial key distribution across concurrent requests.
+- `Ollama::Client#web_search` and `#web_fetch` — Ollama Cloud `/api/web_search` and `/api/web_fetch` endpoints (see `API_CONTRACT.md`).
+
+### Changed
+- Repositioned gem identity from "agent-first" to "Ruby AI SDK for Ollama" in gemspec and README. No API, behavior, or config changes.
+
+### Removed
+- Genuinely dead duplicates with zero references: `lib/ollama/parsers/{list_models,model_management}.rb` and `lib/ollama/serializers/vision.rb`.
+
+### Fixed
+- Repository-wide dead-code/bug audit: 37 of 110 `lib/` files were never `require`d anywhere in the gem's load chain, so nothing ever caught several of them raising on load. All 110 files now load cleanly (enforced by `spec/ollama/all_files_load_spec.rb`).
+  - `Ollama::Middleware::{Cache,Logger,Metrics,Tracing}` each reopened `Ollama::Middleware` (a class) as `module Middleware`, raising `TypeError` on load — the `client.use Ollama::Middleware::Logger` example in README.md has never worked. Fixed the reopening, two broken `require_relative` paths, and a missing `require "digest"`. `Tracing#before_request` also unconditionally called `request.headers`/`request.with_headers`, which `Ollama::Request` doesn't implement — guarded behind `respond_to?`.
+  - `Ollama::Tool` (and `Tool::Function`/`Parameters`/`Property`) was never required by `lib/ollama_client.rb`, so `examples/tool_calling_direct.rb`, `tool_dto_example.rb`, and `structured_tools.rb` raised `NameError` immediately. Added to the default load path.
+  - `Ollama::Agent::Executor#tool_definitions` had a stray, copy-pasted code fragment from `#infer_parameters` appended after its real `.map` block, referencing undefined locals — always raised `NameError`. Removed the fragment; the method now returns its intended array.
+  - Fixed the two broken example scripts that use `Ollama::Agent`/`Ollama::Tool` to require what they need, and rewrote `tool_calling_direct.rb`'s use of the removed `chat_raw`/`allow_chat:` API to the current `chat()` (which already returns a full `Ollama::Response`, including `tool_calls`).
+  - `lib/ollama/policies/*` (Retry, Timeout, AutoPull, RepairJson, SchemaRepair, Fallback, RateLimit, CapabilityValidation): fixed three broken `require_relative` paths and a `Retry`/`Retry::Strategies` naming collision that raised `TypeError: superclass mismatch`. Subsequently wired into the pipeline as `client.use` middleware — see the Added section above.
+  - Removed the now-redundant top-level `lib/ollama/openai_compat.rb` (zero references anywhere; `Ollama::Client` already includes `OpenAICompat` directly). `lib/ollama/openai.rb`'s `require "ollama/openai"` (documented in README) is kept for backwards compatibility — it's a harmless no-op now, since `client.openai` already works without it.
+  - `Ollama::Agent::Executor#run` still calls `Client#chat_raw`, a pre-refactor method that no longer exists (superseded by `chat()`), and is deliberately **not** added to the default load path — see the note in `lib/ollama/agent/executor.rb`: `docs/RUBYLLM_ADOPTION_MATRIX.md` section L tracks whether tool-execution loops belong in core or a separate `ollama-agent` gem as an open question. **Resolved in the Added section above: wired into the default load path on the current `chat()` API.**
+  - Confirmed genuinely dead with zero references anywhere (code, docs, examples): `lib/ollama/parsers/{list_models,list_running,model_management,show_model,version}.rb`, `lib/ollama/serializers/vision.rb`, `lib/ollama/schemas/tool_intent.rb`. Since resolved: `list_running`/`show_model`/`version` parsers are wired into model management, `Schemas.tool_intent` is the default intent schema, and the remaining dead duplicates were removed (see Added/Removed above).
+
+### Documentation
+- `API_CONTRACT.md`: documented `hooks: { on_progress: }` on `pull`/`push_model`, and the full `create_model`/`pull` keyword signatures (previously only partially listed).
+
+### Testing
+- Added `spec/ollama/vcr/` — VCR-cassette specs replaying real, recorded Ollama Cloud responses for `chat` (incl. tools, `think:`, `format:`, streaming), `generate` (incl. `schema:`, `context`, streaming), `list_models`, `show_model`, `version`, `web_search`, and `web_fetch`. Cassettes are committed under `spec/cassettes/` and replay with no network access or API key required; see `spec/cassettes/README.md` for scope, rationale, and the re-recording workflow. `embeddings` and model-management mutation endpoints (`pull`/`push`/`create`/`delete`/`copy`) remain WebMock-only — Ollama Cloud has no embedding models and rejects those endpoints for a regular API key.
+- A few real-response findings surfaced by recording: `chat(format:)` doesn't enforce/repair schema compliance the way `generate(schema:)` does (confirms the known gap in `docs/RUBYLLM_ADOPTION_MATRIX.md` C3); `generate`'s `context` field can be absent (`nil`) for Cloud-hosted chat-tuned models rather than always populated; `Ollama::Capabilities.for` doesn't yet recognize the `gptoss` family, so `show_model`'s derived capability hash reports `tools`/`thinking` as `false` for `gpt-oss:20b` even though the server's own `capabilities` array says otherwise (confirms `docs/RUBYLLM_ADOPTION_MATRIX.md` E3). No code changes made for these — they're documented via the new specs' comments, not fixed, since fixing them is separate roadmap work.
+
+### CI/CD
+- CI now also runs against Ruby 3.4, and splits `rspec`/`rubocop` into separate steps so failures are distinguishable at a glance.
+- Added a `build` job that builds the gem, installs it, and verifies the public API loads — catches packaging regressions on every PR instead of only at release time.
+- Added a `dependency-audit` job (`bundler-audit`) that fails the build on known CVEs in `Gemfile.lock`; fixed three vulnerable transitive dependencies it found (`erb`, `json`, `concurrent-ruby`, `addressable`).
+- Added a `ci` gate job aggregating `test`/`build`/`dependency-audit` for a single required branch-protection check.
+- Added a weekly CodeQL security-analysis workflow for Ruby.
+- Added Dependabot for weekly Bundler and GitHub Actions dependency updates.
+- `release.yml` now runs the full test suite and RuboCop before building/publishing a tagged gem.
+
 ## [1.3.0] - 2026-04-20
 
 ### Added

data/CONTRIBUTING.md

@@ -18,6 +18,14 @@ bundle install
 bundle exec rake
 ```
 
+## Testing
+
+Most specs stub HTTP with WebMock. `spec/ollama/vcr/*.rb` instead replays real, pre-recorded Ollama
+Cloud responses via VCR cassettes committed under `spec/cassettes/` — see
+`spec/cassettes/README.md` for what's covered, why, and how to re-record after a behavior change.
+Neither needs a live server or an API key to run normally; VCR cassette recording is the one
+exception, and only when adding or refreshing a `spec/ollama/vcr/` scenario.
+
 ## What to include in a PR
 
 - Clear description of *why* the change exists (not just what changed)