ollama-client 1.3.0 → 1.4.0

data/docs/runtime/STREAM_CONTRACT.md

@@ -0,0 +1,17 @@
+# Stream Contract (Draft)
+
+`ollama-client` is the canonical owner of stream semantics.
+
+## Required runtime semantics
+
+- Explicit lifecycle states
+- Cancellation semantics (graceful vs immediate)
+- UTF-8 safe chunk assembly
+- SSE boundary correctness
+- Backpressure and bounded buffering
+- Error channel for malformed/incomplete events
+
+## Contract direction
+
+Higher-level gems (`ollama-stream`, `ollama-rails`, `ollama-agent`) compose on top of
+core stream semantics and must not fork or redefine lifecycle guarantees.

data/docs/runtime/STREAM_RUNTIME.md

@@ -0,0 +1,20 @@
+# Stream Runtime Design (Draft)
+
+Target object:
+
+```ruby
+stream = client.chat.stream(...)
+stream.each_token { |t| ... }
+stream.each_chunk { |c| ... }
+stream.cancel
+stream.close
+```
+
+## Required semantics
+
+- Explicit lifecycle: open -> active -> closing -> closed
+- Cancellation modes: graceful vs immediate
+- Backpressure: bounded buffering
+- UTF-8 safe chunk assembly
+- SSE event boundary correctness
+- Error channel for malformed/incomplete events

data/docs/runtime/TRANSPORT_CONTRACT.md

@@ -0,0 +1,26 @@
+# Transport Contract
+
+`ollama-client` owns transport/runtime semantics.
+
+## Adapter interface (current baseline)
+
+- `request(uri:, request:, read_timeout:)`
+- `stream(uri:, request:, &block)` (defined contract; implementation may be pending)
+- `capabilities`
+
+## Response contract
+
+Adapters must return normalized transport responses with:
+
+- `status`
+- `headers`
+- `body`
+- `raw`
+- `duration_ms`
+
+Compatibility behavior for migration is allowed (e.g. status helper methods),
+but response normalization remains mandatory.
+
+## Ownership rule
+
+No orchestration repo may redefine transport contracts. They consume this contract.

data/docs/schema/README.md

@@ -0,0 +1,8 @@
+# Schema Docs
+
+Canonical schema semantics live in:
+
+- `docs/runtime/SCHEMA_CONTRACT.md`
+- `docs/schema/STRUCTURED_OUTPUTS.md`
+
+Typed schema and repair RFCs should be linked from `docs/rfcs/`.

data/docs/schema/STRUCTURED_OUTPUTS.md

@@ -0,0 +1,22 @@
+# Structured Outputs (Draft)
+
+## Goals
+
+- typed schema declarations
+- coercion + validation
+- repair strategies
+- deterministic parse contracts
+
+## Target APIs
+
+```ruby
+client.chat.parse(schema: TradeSignal)
+client.chat.stream_parse(schema: TradeSignal)
+```
+
+## Streaming requirements
+
+- incremental parse
+- partial AST assembly
+- stream-time validation
+- repair during stream

data/docs/streaming/README.md

@@ -0,0 +1,8 @@
+# Streaming Docs
+
+Canonical streaming contracts live in:
+
+- `docs/runtime/STREAM_CONTRACT.md`
+- `docs/runtime/STREAM_RUNTIME.md`
+
+Use this folder for parser/backpressure/cancellation implementation notes.

data/docs/testing/README.md

@@ -0,0 +1,7 @@
+# Testing Docs
+
+Testing and replay architecture references:
+
+- `docs/testing/REPLAY_SYSTEM.md`
+
+This folder covers deterministic replay, stream simulation, and failure injection design.

data/docs/testing/REPLAY_SYSTEM.md

@@ -0,0 +1,17 @@
+# Replay System (Draft)
+
+## Purpose
+
+Deterministic CI and incident reproduction for AI runtime behavior.
+
+## Capabilities
+
+- recorded fixtures
+- response replay
+- stream replay
+- latency injection
+- failure injection
+
+## Integration point
+
+Built on top of transport adapters (`:mock` first).

data/docs/transport/README.md

@@ -0,0 +1,7 @@
+# Transport Docs
+
+Canonical transport semantics live in:
+
+- `docs/runtime/TRANSPORT_CONTRACT.md`
+
+This folder is reserved for adapter-specific design notes and future transport RFC mappings.

data/examples/README.md

@@ -0,0 +1,44 @@
+# Examples
+
+This directory contains working example scripts demonstrating various capabilities of `ollama-client`.
+
+## Running Examples
+
+Most examples assume you are in the project root and use `require_relative` to load the local gem:
+
+```bash
+bundle exec ruby examples/<script>.rb
+```
+
+## Overview
+
+| Script | What it demonstrates |
+|---|---|
+| [`agent_loop.rb`](agent_loop.rb) | Agentic loop with tool calling and stateful memory |
+| [`cloud_models.rb`](cloud_models.rb) | List Ollama Cloud models and probe which ones your account can access |
+| [`llama_cpp_gpu_test.rb`](llama_cpp_gpu_test.rb) | Connect to a llama.cpp GPU server via the OpenAI provider |
+| [`timeout_retry.rb`](timeout_retry.rb) | How timeout and exponential backoff work in production |
+| [`failure_modes/invalid_json_repair.rb`](failure_modes/invalid_json_repair.rb) | Automatic JSON repair when the model returns markdown-wrapped JSON |
+| [`production/rails_agent.rb`](production/rails_agent.rb) | Resilient background job pattern for Rails (e.g. Sidekiq) |
+| [`dhanhq_agent.rb`](dhanhq_agent.rb) | DhanHQ trading agent runner |
+| [`dhanhq/`](dhanhq/) | Modular DhanHQ technical analysis and trading agent system |
+
+## Cloud Model Accessibility Probe
+
+[`cloud_models.rb`](cloud_models.rb) is useful if you use Ollama Cloud and want to know which models are available under your current plan:
+
+```bash
+export OLLAMA_API_KEY="your-ollama-cloud-api-key"
+bundle exec ruby examples/cloud_models.rb
+```
+
+Output is JSON printed to stdout:
+
+```json
+[
+  { "name": "gpt-oss:20b", "accessible": true, "reason": null },
+  { "name": "deepseek-v4-pro", "accessible": false, "reason": "plan_restricted" }
+]
+```
+
+See the script's header comments for the full list of `reason` codes.

data/examples/basic_chat.rb

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Basic chat completion with Ollama
+require "ollama_client"
+
+client = Ollama::Client.new
+response = client.chat(model: "llama3.1:8b", messages: [{ role: "user", content: "Hello, how are you?" }])
+puts response

data/examples/cloud_models.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require_relative "../lib/ollama_client"
+require "json"
+
+begin
+  require "concurrent"
+rescue LoadError
+  warn "Error: concurrent-ruby is required. Add it to your Gemfile."
+  exit 1
+end
+
+# ---------------------------------------------------------------------------
+# Cloud Model Accessibility Probe
+#
+# Lists all models available on Ollama Cloud and probes each one to determine
+# whether the current authenticated account can run inference against it.
+# Results are printed as JSON to stdout and saved to examples/free_catalog.json.
+# ---------------------------------------------------------------------------
+
+OUTPUT_FILE = File.join(__dir__, "free_catalog.json").freeze
+ONLY_ACCESSIBLE = ARGV.include?("--accessible")
+NAMES_ONLY = ARGV.include?("--names-only")
+
+api_key = ENV.fetch("OLLAMA_API_KEY", nil)
+if api_key.nil? || api_key.empty?
+  warn <<~USAGE
+    Usage: OLLAMA_API_KEY=<your-key> bundle exec ruby examples/cloud_models.rb
+
+    Please set the OLLAMA_API_KEY environment variable to your Ollama Cloud API key.
+  USAGE
+  exit 1
+end
+
+config = Ollama::Config.new
+config.base_url = "https://ollama.com"
+config.api_key  = api_key
+config.timeout  = 30
+config.retries  = 0
+
+client = Ollama::Client.new(config: config)
+
+# Fetch the public model catalog from Ollama Cloud.
+begin
+  catalog = client.raw.get("/api/tags")
+rescue Ollama::Error => e
+  warn "Failed to fetch model catalog: #{e.message}"
+  exit 1
+end
+
+models = catalog["models"] || []
+names  = models.map { |m| m["name"] }.compact.sort
+
+catalog_capabilities = {}
+models.each do |m|
+  name = m["name"]
+  next unless name
+
+  catalog_capabilities[name] = Ollama::Capabilities.for(m)
+end
+
+# Also try the OpenAI-compatible endpoint for a broader model list.
+begin
+  openai_models = client.raw.get("/v1/models")
+  openai_names  = (openai_models["data"] || []).map { |m| m["id"] }.compact
+  added = openai_names - names
+  names = (names + openai_names).uniq.sort
+  warn "/v1/models returned #{openai_names.length} model(s), #{added.length} new"
+rescue Ollama::Error => e
+  warn "Warning: could not fetch /v1/models (#{e.message}), using /api/tags only"
+end
+
+# Known Ollama Cloud models not always surfaced by /api/tags.
+EXTRA_MODELS = %w[
+  gemma4:12b
+  gemma4:26b
+  gemma4:31b
+  qwen3.5:0.8b
+  qwen3.5:2b
+  qwen3.5:4b
+  qwen3.5:9b
+  qwen3.5:27b
+  qwen3.5:35b
+  qwen3.5:122b
+  mistral-large-3:123b
+  mistral-large-3:400b
+  nemotron-3-nano:4b
+  gemini-3-flash-preview
+  glm-5
+  kimi-k2.5
+].freeze
+
+extra = EXTRA_MODELS - names
+names = (names + extra).uniq.sort
+warn "Added #{extra.length} extra known cloud model(s) to probe"
+
+if names.empty?
+  puts "[]"
+  exit 0
+end
+
+warn "Probing #{names.length} cloud model(s) with 10 concurrent threads..."
+
+results = Concurrent::Array.new
+pool    = Concurrent::FixedThreadPool.new(10)
+
+names.each do |name|
+  pool.post do
+    sleep(rand * 0.2)
+
+    result = { name: name, accessible: false, reason: nil, capabilities: catalog_capabilities[name] || {} }
+
+    begin
+      client.chat(
+        model: name,
+        messages: [{ role: "user", content: "ping" }],
+        options: { num_predict: 1 }
+      )
+
+      result[:accessible] = true
+    rescue Ollama::UnauthorizedError
+      result[:reason] = "unauthorized"
+    rescue Ollama::ModelUnavailableError
+      result[:reason] = "unavailable"
+    rescue Ollama::NotFoundError
+      result[:reason] = "not_found"
+    rescue Ollama::HTTPError => e
+      reason = case e.status_code
+               when 402 then "usage_limit"
+               when 403 then "plan_restricted"
+               when 429 then "rate_limited"
+               else "http_error"
+               end
+      result[:reason] = reason
+    rescue Ollama::TimeoutError
+      result[:reason] = "timeout"
+    rescue StandardError => e
+      result[:reason] = "error: #{e.class}: #{e.message}"
+    end
+
+    results << result
+  end
+end
+
+pool.shutdown
+pool.wait_for_termination
+
+sorted = results.sort_by { |r| r[:name] }
+
+if ONLY_ACCESSIBLE
+  sorted = sorted.select { |r| r[:accessible] }
+  warn "Filtering to #{sorted.length} accessible model(s) (--accessible)"
+end
+
+if NAMES_ONLY
+  sorted.each { |r| puts r[:name] }
+else
+  json = JSON.pretty_generate(sorted)
+  puts json
+  File.write(OUTPUT_FILE, json + "\n")
+  warn "Saved free catalog to #{OUTPUT_FILE}"
+end

data/examples/embeddings.rb

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Generate embeddings
+require "ollama_client"
+
+client = Ollama::Client.new
+response = client.embeddings.embed(model: "nomic-embed-text", input: "Hello, world!")
+puts "Embedding dimension: #{response.length}"
+puts "First 5 values: #{response.first(5)}"

data/examples/free_catalog.json

@@ -0,0 +1,290 @@
+[
+  {
+    "name": "deepseek-v4-flash",
+    "accessible": false,
+    "reason": "plan_restricted",
+    "capabilities": {
+      "tools": false,
+      "thinking": false,
+      "vision": false,
+      "embeddings": false
+    }
+  },
+  {
+    "name": "deepseek-v4-flash:0731",
+    "accessible": false,
+    "reason": "plan_restricted",
+    "capabilities": {
+      "tools": false,
+      "thinking": false,
+      "vision": false,
+      "embeddings": false
+    }
+  },
+  {
+    "name": "deepseek-v4-pro",
+    "accessible": false,
+    "reason": "plan_restricted",
+    "capabilities": {
+      "tools": false,
+      "thinking": false,
+      "vision": false,
+      "embeddings": false
+    }
+  },
+  {
+    "name": "gemini-3-flash-preview",
+    "accessible": false,
+    "reason": "http_error",
+    "capabilities": {}
+  },
+  {
+    "name": "gemma4:12b",
+    "accessible": false,
+    "reason": "not_found",
+    "capabilities": {}
+  },
+  {
+    "name": "gemma4:26b",
+    "accessible": false,
+    "reason": "not_found",
+    "capabilities": {}
+  },
+  {
+    "name": "gemma4:31b",
+    "accessible": true,
+    "reason": null,
+    "capabilities": {
+      "tools": false,
+      "thinking": true,
+      "vision": false,
+      "embeddings": false
+    }
+  },
+  {
+    "name": "glm-5",
+    "accessible": false,
+    "reason": "http_error",
+    "capabilities": {}
+  },
+  {
+    "name": "glm-5.1",
+    "accessible": false,
+    "reason": "plan_restricted",
+    "capabilities": {
+      "tools": false,
+      "thinking": false,
+      "vision": false,
+      "embeddings": false
+    }
+  },
+  {
+    "name": "glm-5.2",
+    "accessible": false,
+    "reason": "plan_restricted",
+    "capabilities": {
+      "tools": false,
+      "thinking": false,
+      "vision": false,
+      "embeddings": false
+    }
+  },
+  {
+    "name": "gpt-oss:120b",
+    "accessible": true,
+    "reason": null,
+    "capabilities": {
+      "tools": false,
+      "thinking": false,
+      "vision": false,
+      "embeddings": false
+    }
+  },
+  {
+    "name": "gpt-oss:20b",
+    "accessible": true,
+    "reason": null,
+    "capabilities": {
+      "tools": false,
+      "thinking": false,
+      "vision": false,
+      "embeddings": false
+    }
+  },
+  {
+    "name": "kimi-k2.5",
+    "accessible": false,
+    "reason": "http_error",
+    "capabilities": {}
+  },
+  {
+    "name": "kimi-k2.6",
+    "accessible": false,
+    "reason": "plan_restricted",
+    "capabilities": {
+      "tools": false,
+      "thinking": false,
+      "vision": false,
+      "embeddings": false
+    }
+  },
+  {
+    "name": "kimi-k2.7-code",
+    "accessible": false,
+    "reason": "plan_restricted",
+    "capabilities": {
+      "tools": false,
+      "thinking": false,
+      "vision": false,
+      "embeddings": false
+    }
+  },
+  {
+    "name": "kimi-k3",
+    "accessible": false,
+    "reason": "plan_restricted",
+    "capabilities": {
+      "tools": false,
+      "thinking": false,
+      "vision": false,
+      "embeddings": false
+    }
+  },
+  {
+    "name": "minimax-m2.7",
+    "accessible": false,
+    "reason": "plan_restricted",
+    "capabilities": {
+      "tools": false,
+      "thinking": false,
+      "vision": false,
+      "embeddings": false
+    }
+  },
+  {
+    "name": "minimax-m3",
+    "accessible": true,
+    "reason": null,
+    "capabilities": {
+      "tools": false,
+      "thinking": false,
+      "vision": false,
+      "embeddings": false
+    }
+  },
+  {
+    "name": "mistral-large-3:123b",
+    "accessible": false,
+    "reason": "not_found",
+    "capabilities": {}
+  },
+  {
+    "name": "mistral-large-3:400b",
+    "accessible": false,
+    "reason": "not_found",
+    "capabilities": {}
+  },
+  {
+    "name": "mistral-large-3:675b",
+    "accessible": false,
+    "reason": "plan_restricted",
+    "capabilities": {
+      "tools": false,
+      "thinking": false,
+      "vision": false,
+      "embeddings": false
+    }
+  },
+  {
+    "name": "nemotron-3-nano:30b",
+    "accessible": true,
+    "reason": null,
+    "capabilities": {
+      "tools": false,
+      "thinking": false,
+      "vision": false,
+      "embeddings": false
+    }
+  },
+  {
+    "name": "nemotron-3-nano:4b",
+    "accessible": false,
+    "reason": "not_found",
+    "capabilities": {}
+  },
+  {
+    "name": "nemotron-3-super",
+    "accessible": true,
+    "reason": null,
+    "capabilities": {
+      "tools": false,
+      "thinking": false,
+      "vision": false,
+      "embeddings": false
+    }
+  },
+  {
+    "name": "nemotron-3-ultra",
+    "accessible": true,
+    "reason": null,
+    "capabilities": {
+      "tools": false,
+      "thinking": false,
+      "vision": false,
+      "embeddings": false
+    }
+  },
+  {
+    "name": "qwen3.5:0.8b",
+    "accessible": false,
+    "reason": "not_found",
+    "capabilities": {}
+  },
+  {
+    "name": "qwen3.5:122b",
+    "accessible": false,
+    "reason": "rate_limited",
+    "capabilities": {}
+  },
+  {
+    "name": "qwen3.5:27b",
+    "accessible": false,
+    "reason": "rate_limited",
+    "capabilities": {}
+  },
+  {
+    "name": "qwen3.5:2b",
+    "accessible": false,
+    "reason": "rate_limited",
+    "capabilities": {}
+  },
+  {
+    "name": "qwen3.5:35b",
+    "accessible": false,
+    "reason": "not_found",
+    "capabilities": {}
+  },
+  {
+    "name": "qwen3.5:397b",
+    "accessible": false,
+    "reason": "plan_restricted",
+    "capabilities": {
+      "tools": false,
+      "thinking": false,
+      "vision": false,
+      "embeddings": false
+    }
+  },
+  {
+    "name": "qwen3.5:4b",
+    "accessible": false,
+    "reason": "not_found",
+    "capabilities": {}
+  },
+  {
+    "name": "qwen3.5:9b",
+    "accessible": false,
+    "reason": "rate_limited",
+    "capabilities": {}
+  }
+]

data/examples/generate.rb

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Single completion (generate endpoint)
+require "ollama_client"
+
+client = Ollama::Client.new
+response = client.generate(prompt: "Explain quantum computing in one sentence", model: "llama3.1:8b")
+puts response

data/examples/streaming.rb

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Streaming chat completion
+require "ollama_client"
+
+client = Ollama::Client.new
+client.chat(model: "llama3.1:8b", messages: [{ role: "user", content: "Count from 1 to 5" }], stream: true) do |chunk|
+  print chunk.dig("message", "content")
+  $stdout.flush
+end
+puts