ollama-client 1.3.0 → 1.4.0

data/docs/API_GAPS.md

@@ -1,143 +1,20 @@
 # Gaps: Ollama REST API vs ollama-client Gem
 
-Comparison against the [Ollama API Reference](https://ollama.readthedocs.io/en/api/). The Postman collection at `c:\Users\shubh\Downloads\Ollama REST API.postman_collection.json` was not in the workspace; add it to the repo to diff against it as well.
-
----
-
-## 1. Blob API — **Not implemented**
-
-The API defines two blob endpoints for remote model creation:
-
-| Endpoint | Method | Purpose |
-|----------|--------|---------|
-| `/api/blobs/:digest` | HEAD | Check if a blob exists (200 vs 404) |
-| `/api/blobs/:digest` | POST | Create a blob (upload file; returns server path) |
-
-**Gap:** No `blob_exists?(digest)` or `create_blob(digest, file)` in the gem. Required for remote create when using `FROM`/`ADAPTER` with blobs.
-
----
-
-## 2. Create Model — **Parameter mismatch**
-
-**API parameters:** `model`, `modelfile` (optional), `path` (optional), `stream`, `quantize`.
-
-**Gem:** `create_model(model:, from:, system:, template:, license:, parameters:, messages:, quantize:, stream:)` and sends `from` (+ system, template, etc.) in the JSON body.
-
-- The reference docs do not list `from`, `system`, or `template` as top-level create parameters; they describe passing **modelfile content** or a **path** to a Modelfile.
-- If the Ollama server accepts `from` as a shorthand for a minimal modelfile, the gem may work but is undocumented in the official API.
-- **Gaps:**
-  - No way to pass raw **modelfile** string (full Modelfile content).
-  - No way to pass **path** (path to a Modelfile on the server).
-
-**Recommendation:** Add optional `modelfile:` and `path:` to `create_model`. If `modelfile` or `path` is present, use that; otherwise keep building from `from` + system/template for backward compatibility (and document that behavior).
-
----
-
-## 3. Pull — **Missing parameters**
-
-**API parameters:** `model`, `stream` (optional), `insecure` (optional).
-
-**Gem:** `pull(model_name)` — always sends `stream: false` and does not accept `insecure` or `stream`.
-
-**Gaps:**
-- No `insecure:` option (e.g. for pulling from a custom/self-hosted registry).
-- No choice of streaming vs non-streaming; callers cannot get progress via stream.
-
-**Recommendation:** Add `pull(model_name, stream: false, insecure: false)` and pass them through.
-
----
-
-## 4. Generate — **Context (conversational memory)**
-
-**API:** `/api/generate` accepts optional `context` (from a previous response) and returns `context` in the response for use in the next request.
-
-**Gem:** `generate` does not accept or return `context`. Multi-turn “memory” is only via chat, not via generate.
-
-**Gap:** No support for generate-side context for short conversational memory when using the generate endpoint.
-
-**Recommendation:** Optional `context:` argument and returning `context` in metadata when `return_meta: true` (or a dedicated accessor) would align with the API.
-
----
-
-## 5. Generate / Chat — **Options coverage**
-
-**API (Modelfile/options):** The docs list many options, including at least:
-
-- `min_p`
-- `penalize_newline`
-- `repeat_last_n`
-- `numa`
-- `num_batch`
-- `main_gpu`
-- `low_vram`
-- `vocab_only`
-- `use_mmap`
-- `use_mlock`
-
-**Gem:** `Ollama::Options` supports: `temperature`, `top_p`, `top_k`, `num_ctx`, `repeat_penalty`, `seed`, `num_predict`, `stop`, `tfs_z`, `mirostat`, `mirostat_tau`, `mirostat_eta`, `num_gpu`, `num_thread`, `num_keep`, `typical_p`, `presence_penalty`, `frequency_penalty`.
-
-**Gap:** Options such as `min_p`, `penalize_newline`, `repeat_last_n`, `numa`, `num_batch`, `main_gpu`, `low_vram`, `vocab_only`, `use_mmap`, `use_mlock` are not in the type-safe Options class. They can still be passed as a raw hash via `options:`, so behavior is only a **documentation/consistency** gap.
-
-**Recommendation:** Either extend `Ollama::Options` with these keys (and document which are server-dependent) or explicitly document that arbitrary option hashes are allowed and list the known API options in the yardocs.
-
----
-
-## 6. Push — **Streaming behavior**
-
-**API:** Supports `stream: true` (default) or `stream: false` with a single final JSON object.
-
-**Gem:** `push_model(model:, insecure: false, stream: false)` — implements both parameters. When `stream: true`, the current implementation uses a single `http_request` and `JSON.parse(res.body)`, which is wrong for streaming NDJSON.
-
-**Gap:** For `stream: true`, the gem would need to read the response body as a stream (NDJSON) and yield or return status updates, similar to pull/generate streaming. Currently only non-streaming push is correct.
-
----
-
-## 7. Pull — **Streaming behavior**
-
-**API:** Pull can stream progress (default) or return a single object when `stream: false`.
-
-**Gem:** Always sends `stream: false` and parses a single JSON object. No streaming pull.
-
-**Gap:** No API to get pull progress (e.g. status, digest, total, completed) via streaming. This is a **feature** gap, not a wrong-call gap.
-
----
-
-## 8. Chat — **Tool message role**
-
-**API:** Message object may have `role`: `system` | `user` | `assistant` | `tool`. Tool results are sent as messages with `role: "tool"`.
-
-**Gem:** Response wrapper and tool_calls handling are in place; no gap identified for normal tool use. If the client ever needs to **send** tool results back (e.g. in a follow-up request), the message format with `role: "tool"` should be documented or helpers provided. Not a missing endpoint, but worth documenting for agent loops.
-
----
-
-## 9. Embeddings — **Legacy endpoint**
-
-**API:** Documents both `/api/embed` (current) and `/api/embeddings` (superseded).
-
-**Gem:** Uses `/api/embed` only. No gap.
-
----
-
-## 10. Load / Unload model (explicit)
-
-**API:** Describes loading by calling generate/chat with empty prompt (and optional `keep_alive`), and unload with empty prompt + `keep_alive: 0`.
-
-**Gem:** No dedicated `load_model` or `unload_model` helpers. Callers can do the same by calling `generate(prompt: "", ...)` or `chat(messages: [], ...)` with `keep_alive`.
-
-**Gap:** Convenience only — optional helpers could reduce confusion and document the pattern.
-
----
-
-## Summary table
-
-| Area              | Severity   | Gap |
-|-------------------|------------|-----|
-| Blob API          | High       | HEAD/POST blobs not implemented |
-| Create model      | Medium     | No raw `modelfile` or `path`; uses `from` only |
-| Pull              | Medium     | No `insecure` or `stream`; no streaming progress |
-| Push              | Low        | `stream: true` not implemented as real streaming |
-| Generate context  | Low        | No `context` in/out for conversational memory |
-| Options           | Low        | Several Modelfile options not in `Ollama::Options` |
-| Load/Unload       | Optional   | No convenience methods for load/unload |
-
-Implementing **Blob API** and **Create model (modelfile/path)** would fully align the gem with the documented API for model creation. **Pull (insecure + stream)** and **Generate context** are the next most useful for parity and agent use cases.
+Original comparison against the [Ollama API Reference](https://ollama.readthedocs.io/en/api/). All 10
+items identified below have since been closed. This file is kept for history; the actively maintained
+gap tracker is [`docs/RUBYLLM_ADOPTION_MATRIX.md`](RUBYLLM_ADOPTION_MATRIX.md) section K.
+
+| # | Area | Original gap | Status |
+|---|---|---|---|
+| 1 | Blob API | No `blob_exists?`/`create_blob` | **Resolved** — `Client::ModelManagement#blob_exists?(digest:)`, `#create_blob(digest:, content:)` |
+| 2 | Create model | No raw `modelfile`/`path` | **Resolved** — `create_model(model:, from:, modelfile:, path:, ...)` |
+| 3 | Pull | No `insecure`/`stream` | **Resolved** — `pull(model_name, insecure:, stream:, hooks:)` |
+| 4 | Generate context | No `context` in/out | **Resolved** — `generate(prompt:, context:, ...)`, context returned via `return_meta:` |
+| 5 | Options coverage | Missing `min_p`, `penalize_newline`, `repeat_last_n`, `numa`, `num_batch`, `main_gpu`, `low_vram`, `vocab_only`, `use_mmap`, `use_mlock` | **Resolved** — all present on `Ollama::Options` |
+| 6 | Push streaming | `stream: true` not real NDJSON streaming | **Resolved** — `push_model` streams via `handle_ndjson_stream` + `hooks[:on_progress]` |
+| 7 | Pull streaming | No streaming progress | **Resolved** — same mechanism as push |
+| 8 | Tool message role | No `role: "tool"` helper for follow-up requests | **Resolved** — `Ollama::Agent::Messages#tool_result` (`lib/ollama/agent/messages.rb`) |
+| 9 | Embeddings legacy endpoint | n/a | No gap — `/api/embed` is the current documented endpoint; `/api/embeddings` is Ollama's deprecated alias |
+| 10 | Load/unload convenience | No dedicated helpers | **Resolved** — `load_model(model:, keep_alive:)`, `unload_model(model:)` |
+
+See `API_CONTRACT.md` for the current signatures of all methods above.

data/docs/ARCHITECTURE.md

@@ -0,0 +1,141 @@
+# ollama-client Architecture
+
+This document specifies the frozen v1 architecture design of `ollama-client`.
+
+```text
+ollama-client
+│
+├── Config
+├── Request
+├── Response
+├── Errors
+│
+├── Transport
+│   ├── HTTP
+│   ├── Mock
+│   └── Streaming
+│
+├── Middleware
+│   ├── Logger
+│   ├── Metrics
+│   ├── Cache
+│   ├── Tracing
+│   └── Base
+│
+├── Policies
+│   ├── Retry
+│   ├── AutoPull
+│   ├── RepairJson
+│   ├── SchemaRepair
+│   ├── CapabilityValidation
+│   └── RateLimit
+│
+├── Core
+│   ├── Chat
+│   ├── Generate
+│   ├── Embeddings
+│   ├── Models
+│   └── Version
+│
+├── Ruby
+│   ├── Messages
+│   ├── Tool
+│   ├── Schema
+│   ├── TypedResponses
+│   ├── Streaming
+│   └── Testing
+│
+├── Plugins
+│
+├── Rails (optional)
+│
+└── Compliance Tests
+```
+
+---
+
+## 1. Request/Response Pipeline Design
+
+All lifecycle hooks, logging, retries, and errors run inside a single composable pipeline of middleware:
+
+```text
+Request
+   │
+   ▼
+Middleware (Logger / Caching)
+   │
+   ▼
+Policies (Retry / AutoPull / JsonRepair)
+   │
+   ▼
+Transport Terminal (HTTP / Mock)
+   │
+   ▼
+Response
+   │
+   ▼
+Typed Objects
+```
+
+### Composable Middleware Stack
+
+Every middleware implements the following Rack/Faraday-style interface:
+
+```ruby
+class Base
+  def initialize(app, **options)
+    @app = app
+    @options = options
+  end
+
+  def call(request)
+    @app.call(request)
+  end
+end
+```
+
+---
+
+## 2. Core Abstractions
+
+### Request Object
+
+An immutable container for all request parameters, keeping core logic completely decoupled from HTTP adapters or JSON payloads.
+
+```ruby
+class Request
+  attr_reader :endpoint, :model, :messages, :prompt, :images, :tools, :schema, :options, :stream
+
+  def initialize(endpoint:, **args)
+    @endpoint = endpoint
+    @model = args[:model]
+    @messages = args[:messages]
+    @prompt = args[:prompt]
+    @images = args[:images]
+    @tools = args[:tools]
+    @schema = args[:schema]
+    @options = args[:options] || {}
+    @stream = args[:stream]
+    freeze
+  end
+
+  def streaming?
+    hooks = @options[:hooks]
+    (hooks && !hooks.empty?) || @stream == true
+  end
+end
+```
+
+### Response Object
+
+Typed accessors wrapping LLM returns instead of raw HTTP hashes:
+
+```ruby
+response.message.content
+response.done?
+response.total_duration
+```
+
+### Policies Namespace
+
+All recovery policies (AutoPull, Retry, RepairJson) live in the `Ollama::Policies` plural namespace for consistency.

data/docs/AREAS_FOR_CONSIDERATION.md

@@ -20,6 +20,7 @@ This document addresses three key areas that warrant attention in the `ollama-cl
 ### Responsibilities
 
 The `Client` class currently handles:
+
 1. HTTP communication with Ollama API
 2. JSON parsing and validation
 3. Schema validation
@@ -65,12 +66,14 @@ end
 ```
 
 **Benefits:**
+
 - Single Responsibility Principle
 - Easier to test
 - Easier to maintain
 - Can enable RuboCop metrics
 
 **Trade-offs:**
+
 - More files to navigate
 - Slightly more complex initialization
 
@@ -88,23 +91,27 @@ end
 ```
 
 **Benefits:**
+
 - Still one file
 - Better organization
 - Can test modules independently
 
 **Trade-offs:**
+
 - Still a large file
 - RuboCop metrics still problematic
 
 #### Option C: Accept Complexity (Current State)
 
 **Rationale:**
+
 - Client is the core API surface
 - All methods are public API
 - Breaking it up might make usage more complex
 - Current structure is functional
 
 **Action Items:**
+
 - Document why metrics are disabled
 - Add architectural decision record (ADR)
 - Consider refactoring in future major version
@@ -122,6 +129,7 @@ end
 ### Current State
 
 **Global Configuration:**
+
 ```ruby
 module OllamaClient
   @config_mutex = Mutex.new
@@ -136,6 +144,7 @@ end
 ```
 
 **Issues:**
+
 1. Mutex protects global config access, but warning says "not thread-safe"
 2. Confusing messaging - mutex IS present but warning suggests it's not safe
 3. Per-client config is recommended but not enforced
@@ -143,11 +152,13 @@ end
 ### Analysis
 
 **What's Actually Thread-Safe:**
+
 - ✅ Global config access (protected by mutex)
 - ✅ Per-client instances (each has own config)
 - ✅ Client methods (stateless, use instance config)
 
 **What's NOT Thread-Safe:**
+
 - ⚠️ Modifying global config while clients are using it
 - ⚠️ Shared config objects between threads (if mutated)
 
@@ -270,7 +281,7 @@ Need structured output?
 ```ruby
 # High-level API for beginners
 class SimpleAgent
-  def initialize(model: "llama3.2:3b")
+  def initialize(model: "qwen3.5:4b")
     @client = Ollama::Client.new
     @model = model
   end
@@ -294,6 +305,7 @@ end
 ### Recommended Approach
 
 **Immediate:**
+
 1. Add "Quick Start" section to README (Option A)
 2. Add decision tree diagram (Option B)
 

data/docs/CLOUD.md

@@ -27,3 +27,22 @@ Rules:
 ## Guardrails
 - Keep API surface stable and backward compatible.
 - Update specs when behavior changes.
+
+## Ollama Cloud Model Accessibility
+
+Ollama Cloud does not expose a `free` flag per model. The only reliable way to determine whether a model is accessible to your account is to attempt a tiny inference and observe the HTTP response.
+
+The project includes a standalone example script that automates this:
+
+```bash
+export OLLAMA_API_KEY="your-ollama-cloud-api-key"
+bundle exec ruby examples/cloud_models.rb
+```
+
+The script:
+1. Fetches the public cloud model catalog from `https://ollama.com/api/tags`
+2. Probes each model concurrently (10 threads) with a minimal chat request
+3. Classifies the response into accessibility statuses (`accessible`, `unauthorized`, `plan_restricted`, `usage_limit`, `unavailable`, `rate_limited`, `timeout`, etc.)
+4. Prints sorted JSON to stdout
+
+See [`examples/cloud_models.rb`](../examples/cloud_models.rb) for the full implementation and [`examples/README.md`](../examples/README.md) for usage details.

data/docs/CONSOLE_IMPROVEMENTS.md

@@ -15,6 +15,7 @@ When the LLM was processing a response, the `llm>` prompt appeared immediately,
 Added a **thinking indicator** that shows while waiting for the API response:
 
 **Before:**
+
 ```
 you> Hi
 llm> [cursor blinks here - looks like a prompt!]
@@ -23,6 +24,7 @@ llm> [cursor blinks here - looks like a prompt!]
 ```
 
 **After:**
+
 ```
 you> Hi
 ... [thinking indicator in cyan]
@@ -62,6 +64,7 @@ end
 ```
 
 **Key Changes:**
+
 - `\r` (carriage return) replaces `...` with `llm>` when first token arrives
 - `$stdout.flush` ensures immediate visual feedback
 - Clear visual state: thinking → responding → ready for input
@@ -71,11 +74,13 @@ end
 ### Problem
 
 Tool results were displayed as raw JSON dumps, making it hard to quickly understand:
+
 - **Which tool** was called
 - **What data** was retrieved
 - **Key information** from the response
 
 **Before:**
+
 ```
 Tool Results:
 - get_live_ltp
@@ -103,6 +108,7 @@ Tool Results:
 Implemented **formatted, human-readable tool results** that extract and display key information:
 
 **After:**
+
 ```
 🔧 Tool Called: get_live_ltp
    → NIFTY (IDX_I)
@@ -114,6 +120,7 @@ llm> The current price of NIFTY is 25694.35.
 ### Formatted Output by Tool
 
 #### 1. Live LTP (`get_live_ltp`)
+
 ```
 🔧 Tool Called: get_live_ltp
    → NIFTY (IDX_I)
@@ -121,6 +128,7 @@ llm> The current price of NIFTY is 25694.35.
 ```
 
 #### 2. Market Quote (`get_market_quote`)
+
 ```
 🔧 Tool Called: get_market_quote
    → RELIANCE
@@ -132,6 +140,7 @@ llm> The current price of NIFTY is 25694.35.
 #### 3. Historical Data (`get_historical_data`)
 
 **Regular data:**
+
 ```
 🔧 Tool Called: get_historical_data
    → Historical data: 30 records
@@ -139,6 +148,7 @@ llm> The current price of NIFTY is 25694.35.
 ```
 
 **With indicators:**
+
 ```
 🔧 Tool Called: get_historical_data
    → Technical Indicators:
@@ -150,6 +160,7 @@ llm> The current price of NIFTY is 25694.35.
 ```
 
 #### 4. Option Chain (`get_option_chain`)
+
 ```
 🔧 Tool Called: get_option_chain
    → Spot: ₹25694.35
@@ -158,6 +169,7 @@ llm> The current price of NIFTY is 25694.35.
 ```
 
 #### 5. Expiry List (`get_expiry_list`)
+
 ```
 🔧 Tool Called: get_expiry_list
    → Available expiries: 12
@@ -166,6 +178,7 @@ llm> The current price of NIFTY is 25694.35.
 ```
 
 #### 6. Find Instrument (`find_instrument`)
+
 ```
 🔧 Tool Called: find_instrument
    → Found: NIFTY
@@ -192,6 +205,7 @@ end
 ```
 
 Each tool has a dedicated formatter that:
+
 1. Extracts key information from the result
 2. Formats it in a human-readable way
 3. Uses color coding for better readability
@@ -200,11 +214,13 @@ Each tool has a dedicated formatter that:
 ## Benefits
 
 ### Chat Console
+
 ✅ **Clear visual feedback** - Users know when the LLM is thinking vs responding
 ✅ **No confusion** - Thinking indicator prevents accidental typing
 ✅ **Better UX** - Immediate response to user input
 
 ### DhanHQ Console
+
 ✅ **Instant comprehension** - See what tool was called at a glance
 ✅ **Key data highlighted** - Important values (price, volume) are prominent
 ✅ **Less noise** - No JSON clutter, just the facts
@@ -216,14 +232,16 @@ Each tool has a dedicated formatter that:
 Both consoles support environment variables:
 
 **Chat Console:**
+
 ```bash
 OLLAMA_BASE_URL=http://localhost:11434
-OLLAMA_MODEL=llama3.2:3b
+OLLAMA_MODEL=qwen3.5:4b
 OLLAMA_TEMPERATURE=0.7
 OLLAMA_SYSTEM="You are a helpful assistant"
 ```
 
 **DhanHQ Console:**
+
 ```bash
 # All chat console vars, plus:
 DHANHQ_CLIENT_ID=your_client_id
@@ -243,6 +261,7 @@ ruby examples/dhan_console.rb
 ```
 
 Try queries like:
+
 - "What is NIFTY price?" → See formatted LTP
 - "Get RELIANCE quote" → See formatted quote with OHLC
 - "Show me historical data for NIFTY" → See record count

data/docs/ECOSYSTEM_GEMS.md

@@ -0,0 +1,41 @@
+# Ollama Ruby Ecosystem Blueprint
+
+This repository remains the deterministic core runtime (`ollama-client`).
+
+## Proposed Gem Split
+
+- `ollama-client` (core): transport, retries, schema enforcement, model lifecycle, raw endpoint access, OpenAI facade.
+- `ollama-openai`: standalone OpenAI protocol adapter for external OpenAI SDK consumers (currently provided as an optional extension via `require "ollama/openai"` as an interim step).
+- `ollama-stream`: advanced streaming runtime (SSE object model, resumable streams, WS relay, backpressure primitives).
+- `ollama-observability`: OpenTelemetry spans, metrics, token accounting, structured log emitters.
+- `ollama-agent`: optional orchestration layer (tool runtime, memory, planners) kept separate from core transport.
+
+## Gem Scaffolding Checklist
+
+For each new gem:
+
+1. `bundle gem <name> --mit --test=rspec --ci=github`
+2. Add `README.md` with:
+   - scope boundaries
+   - compatibility matrix
+   - migration guide
+3. Add `sig/` RBS contracts for public APIs.
+4. Add integration tests against local Ollama.
+5. Publish with independent semver and changelog.
+
+## Suggested Release Order
+
+1. `ollama-openai` (highest interoperability impact)
+2. `ollama-observability`
+3. `ollama-stream`
+4. `ollama-agent`
+
+## Non-Goals for Core
+
+Core should not include:
+
+- vector DB abstractions
+- prompt-chain DSLs
+- opaque “magic” agent workflows
+
+Keep core deterministic and infra-grade.