ollama-client 0.2.5 → 0.2.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 687a8a4fbb73c24bbc408a902cbc94312923dd5c9a42823a2a5e13111977a6b9
-  data.tar.gz: 6c7992774151468a99a855671d2e2e17058a613377de970f5647411c9f627b81
+  metadata.gz: 53bd3c1ff3323d004a7ba3549317ef49d3ce9698d41133a1d2150d0a5135fa80
+  data.tar.gz: 4c726b2a7fabf164c91cd51206266d250de836986d1a36726556cbefb47a6e8e
 SHA512:
-  metadata.gz: c52ad58ee08f15b0014500ac9285c0d7a446447e72ec0df1da17b815ae249103adbf5f3a64ec66e83fc1c821e64d7297b84cd7e19d808c914c862fc3263e52ae
-  data.tar.gz: fad07b8161e7e1442ecfc203b4774e23ceb5075fe660adc1636a1fe81a8ac4a8e27fad80c91bcc20964a9a13e6733a1cb88612cb6d6de2b4c01b5bbbeba6eaf2
+  metadata.gz: 1cdcc10b54d2fa318daefc2736d338715b65f03cacf94c7c9303c07ec745ea510e6de0ac73c0c668b0301481663989af1368d86727ebfa1252a43edab9d7d711
+  data.tar.gz: aead7b8ae703d436866cf796e91b102fbcc21ff47e6528c2edf62b13a1bac1f98f36d1146ba3e56a7fa0792bd0aff0880be65450c05b2352336cd20b39b3f9ab

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 ## [Unreleased]
 
+## [0.2.7] - 2026-02-04
+
+- Add MCP (Model Context Protocol) support for local and remote servers
+- Add `Ollama::MCP::StdioClient` for local MCP servers over stdio (e.g. `npx @modelcontextprotocol/server-filesystem`)
+- Add `Ollama::MCP::HttpClient` for remote MCP servers over HTTP (e.g. [gitmcp.io](https://gitmcp.io)/owner/repo)
+- Add `Ollama::MCP::ToolsBridge` to expose MCP tools to `Ollama::Agent::Executor` (`client:` or `stdio_client:`)
+- Add examples: `examples/mcp_executor.rb` (stdio), `examples/mcp_http_executor.rb` (URL)
+- Document MCP usage and GitMCP URL in README; fix RuboCop offenses in MCP code
+
+## [0.2.6] - 2026-01-26
+
+- Reorganize examples: move agent examples to separate repository, keep minimal client examples
+- Add comprehensive test coverage (increased from 65.66% to 79.59%)
+- Add test suite for `Ollama::DocumentLoader` (file loading, context building)
+- Add test suite for `Ollama::Embeddings` (API calls, error handling)
+- Add test suite for `Ollama::ChatSession` (session management)
+- Add test suite for tool classes (`Tool`, `Function`, `Parameters`, `Property`)
+- Rewrite testing documentation to focus on client-only testing (transport/protocol)
+- Add test checklist with specific test categories (G1-G3, C1-C3, A1-A2, F1-F3)
+- Update README with enhanced "What This Gem IS NOT" section
+- Fix RuboCop offenses and improve code quality
+
 ## [0.2.5] - 2026-01-22
 
 - Add `Ollama::DocumentLoader` for loading files as context in queries

data/README.md

@@ -26,11 +26,15 @@ Domain tools and application logic live **outside** this gem. For convenience, i
 
 ## 🚫 What This Gem IS NOT
 
-* ❌ Domain tool implementations
-* ❌ Domain logic
-* ❌ Memory store
-* ❌ Chat UI
-* ❌ A promise of full Ollama API coverage (it focuses on agent workflows)
+This gem is **NOT**:
+* ❌ A chatbot UI framework
+* ❌ A domain-specific agent implementation
+* ❌ A tool execution engine
+* ❌ A memory store
+* ❌ A promise of full Ollama API coverage (focuses on agent workflows)
+* ❌ An agent runtime (it provides transport + protocol, not agent logic)
+
+**Domain tools and application logic live outside this gem.**
 
 This keeps it **clean and future-proof**.
 
@@ -68,13 +72,115 @@ Or install it yourself as:
 gem install ollama-client
 ```
 
+## Quick Start
+
+### Step 1: Simple Text Generation
+
+```ruby
+require "ollama_client"
+
+client = Ollama::Client.new
+
+# Get plain text response (no schema = plain text)
+response = client.generate(
+  prompt: "Explain Ruby blocks in one sentence"
+)
+
+puts response
+# => "Ruby blocks are anonymous functions passed to methods..."
+```
+
+### Step 2: Structured Outputs (Recommended for Agents)
+
+```ruby
+require "ollama_client"
+
+client = Ollama::Client.new
+
+# Define JSON schema
+schema = {
+  "type" => "object",
+  "required" => ["action", "reasoning"],
+  "properties" => {
+    "action" => { "type" => "string", "enum" => ["search", "calculate", "finish"] },
+    "reasoning" => { "type" => "string" }
+  }
+}
+
+# Get structured decision
+result = client.generate(
+  prompt: "User wants weather in Paris. What should I do?",
+  schema: schema
+)
+
+puts result["action"]      # => "search"
+puts result["reasoning"]    # => "Need to fetch weather data..."
+```
+
+### Step 3: Agent Planning (Stateless)
+
+```ruby
+require "ollama_client"
+
+client = Ollama::Client.new
+planner = Ollama::Agent::Planner.new(client)
+
+decision_schema = {
+  "type" => "object",
+  "required" => ["action"],
+  "properties" => {
+    "action" => { "type" => "string", "enum" => ["search", "calculate", "finish"] }
+  }
+}
+
+plan = planner.run(
+  prompt: "Decide the next action",
+  schema: decision_schema
+)
+
+# Use the structured decision
+case plan["action"]
+when "search"
+  # Execute search
+when "calculate"
+  # Execute calculation
+when "finish"
+  # Task complete
+end
+```
+
+### Step 4: Tool Calling (Stateful)
+
+```ruby
+require "ollama_client"
+
+client = Ollama::Client.new
+
+# Define tools
+tools = {
+  "get_weather" => ->(city:) { { city: city, temp: 22, condition: "sunny" } }
+}
+
+executor = Ollama::Agent::Executor.new(client, tools: tools)
+
+answer = executor.run(
+  system: "You are a helpful assistant. Use tools when needed.",
+  user: "What's the weather in Paris?"
+)
+
+puts answer
+# => "The weather in Paris is 22°C and sunny."
+```
+
+**Next Steps:** See [Choosing the Correct API](#choosing-the-correct-api-generate-vs-chat) below for guidance on when to use each method.
+
 ## Usage
 
 **Note:** You can use `require "ollama_client"` (recommended) or `require "ollama/client"` directly. The client works with or without the global `OllamaClient` configuration module.
 
 ### Primary API: `generate()`
 
-**`generate(prompt:, schema: nil)`** is the **primary and recommended method** for agent-grade usage:
+**`generate(prompt:, schema: nil, model: nil, strict: false, return_meta: false)`** is the **primary and recommended method** for agent-grade usage:
 
 - ✅ Stateless, explicit state injection
 - ✅ Uses `/api/generate` endpoint
@@ -85,11 +191,46 @@ gem install ollama-client
 **This is the method you should use for hybrid agents.**
 
 **Usage:**
-- **With schema** (structured JSON): `generate(prompt: "...", schema: {...})`
-- **Without schema** (plain text): `generate(prompt: "...")` - returns plain text/markdown
+- **With schema** (structured JSON): `generate(prompt: "...", schema: {...})` - returns Hash
+- **Without schema** (plain text): `generate(prompt: "...")` - returns String (plain text/markdown)
 
 ### Choosing the Correct API (generate vs chat)
 
+**Decision Tree:**
+
+```
+Need structured JSON output?
+├─ Yes → Use generate() with schema
+│   └─ Need conversation history?
+│       ├─ No → Use generate() directly
+│       └─ Yes → Include context in prompt (generate() is stateless)
+│
+└─ No → Need plain text/markdown?
+    ├─ Yes → Use generate() without schema
+    │   └─ Need conversation history?
+    │       ├─ No → Use generate() directly
+    │       └─ Yes → Include context in prompt
+    │
+    └─ Need tool calling?
+        ├─ Yes → Use Executor (chat API with tools)
+        │   └─ Multi-step workflow with tool loops
+        │
+        └─ No → Use ChatSession (chat API for UI)
+            └─ Human-facing chat interface
+```
+
+**Quick Reference:**
+
+| Use Case | Method | API Endpoint | State |
+|----------|--------|--------------|-------|
+| Agent planning/routing | `generate()` | `/api/generate` | Stateless |
+| Structured extraction | `generate()` | `/api/generate` | Stateless |
+| Simple text generation | `generate()` | `/api/generate` | Stateless |
+| Tool-calling loops | `Executor` | `/api/chat` | Stateful |
+| UI chat interface | `ChatSession` | `/api/chat` | Stateful |
+
+**Detailed Guidance:**
+
 - **Use `/api/generate`** (via `Ollama::Client#generate` or `Ollama::Agent::Planner`) for **stateless planner/router** steps where you want strict, deterministic structured outputs.
 - **Use `/api/chat`** (via `Ollama::Agent::Executor`) for **stateful tool-using** workflows where the model may request tool calls across multiple turns.
 
@@ -260,13 +401,13 @@ require "ollama_client"
 
 client = Ollama::Client.new
 
-# Get plain text/markdown response (no schema required)
+# Get plain text/markdown response (omit schema for plain text)
 text_response = client.generate(
   prompt: "Explain Ruby in simple terms"
 )
 
 puts text_response
-# Output: Plain text or markdown explanation
+# Output: Plain text or markdown explanation (String)
 ```
 
 **Option 2: Using `chat_raw()` (for multi-turn conversations)**
@@ -289,8 +430,8 @@ puts text_response
 ```
 
 **When to use which:**
-- **`generate()` without schema** - Simple one-shot queries, explanations, text generation
-- **`generate()` with schema** - Structured JSON outputs for agents
+- **`generate()` without schema** - Simple one-shot queries, explanations, text generation (returns plain text)
+- **`generate()` with schema** - Structured JSON outputs for agents (recommended for agents)
 - **`chat_raw()` without format** - Multi-turn conversations with plain text
 - **`chat_raw()` with format** - Multi-turn conversations with structured outputs
 
@@ -298,7 +439,7 @@ puts text_response
 
 This gem intentionally focuses on **agent building blocks**:
 
-- **Supported**: `/api/generate`, `/api/chat`, `/api/tags`, `/api/ping`, `/api/embeddings`
+- **Supported**: `/api/generate`, `/api/chat`, `/api/tags`, `/api/ping`, `/api/embed`
 - **Not guaranteed**: full endpoint parity with every Ollama release (advanced model mgmt, etc.)
 
 ### Agent endpoint mapping (unambiguous)
@@ -315,6 +456,40 @@ Within `Ollama::Agent`:
 ```ruby
 require "ollama_client"
 
+client = Ollama::Client.new
+
+# Option 1: With schema (recommended for structured outputs)
+DECISION_SCHEMA = {
+  "type" => "object",
+  "required" => ["action", "reasoning"],
+  "properties" => {
+    "action" => {
+      "type" => "string",
+      "enum" => ["search", "calculate", "store", "retrieve", "finish"]
+    },
+    "reasoning" => {
+      "type" => "string"
+    }
+  }
+}
+
+planner = Ollama::Agent::Planner.new(client)
+
+plan = planner.run(
+  prompt: "Given the user request, decide the next action.",
+  schema: DECISION_SCHEMA,
+  context: { user_request: "Plan a weekend trip to Rome" }
+)
+
+puts plan["action"]      # => "search" (or one of the enum values)
+puts plan["reasoning"]    # => Explanation string
+```
+
+**Option 2: Without schema (returns any JSON)**
+
+```ruby
+require "ollama_client"
+
 client = Ollama::Client.new
 planner = Ollama::Agent::Planner.new(client)
 
@@ -326,7 +501,7 @@ plan = planner.run(
   context: { user_request: "Plan a weekend trip to Rome" }
 )
 
-puts plan
+puts plan  # => Any valid JSON structure
 ```
 
 ### Executor Agent (tool loop, /api/chat)
@@ -669,6 +844,61 @@ result2 = client.chat(messages: messages, format: decision_schema, allow_chat: t
 # Harder to reason about state in agent systems
 ```
 
+### Decision Table: `generate()` vs `chat()` vs `ChatSession`
+
+> **Use `generate()` for systems. Use `chat()` or `ChatSession` for humans.**
+
+| Use Case | Method | Schema Guarantees | Streaming | Memory | When to Use |
+|----------|--------|-------------------|-----------|--------|-------------|
+| **Agent planning/routing** | `generate()` | ✅ Strong | ❌ No | ❌ Stateless | Default for agents |
+| **Structured extraction** | `generate()` | ✅ Strong | ❌ No | ❌ Stateless | Data extraction, classification |
+| **Tool-calling loops** | `chat_raw()` | ⚠️ Weaker | ✅ Yes | ✅ Stateful | Executor agent internals |
+| **UI chat interface** | `ChatSession` | ⚠️ Best-effort | ✅ Yes | ✅ Stateful | Human-facing assistants |
+| **Multi-turn conversations** | `ChatSession` | ⚠️ Best-effort | ✅ Yes | ✅ Stateful | Interactive chat |
+
+**Core Rule:** Chat must be a feature flag, not default behavior.
+
+### Using `ChatSession` for Human-Facing Chat
+
+For UI assistants and interactive chat, use `ChatSession` to manage conversation state:
+
+```ruby
+require "ollama_client"
+
+# Enable chat in config
+config = Ollama::Config.new
+config.allow_chat = true
+config.streaming_enabled = true
+
+client = Ollama::Client.new(config: config)
+
+# Create streaming observer for presentation
+observer = Ollama::StreamingObserver.new do |event|
+  case event.type
+  when :token
+    print event.text
+  when :final
+    puts "\n--- DONE ---"
+  end
+end
+
+# Create chat session with system message
+chat = Ollama::ChatSession.new(
+  client,
+  system: "You are a helpful assistant",
+  stream: observer
+)
+
+# Send messages (history is managed automatically)
+chat.say("Hello")
+chat.say("Explain Ruby blocks")
+
+# Clear history if needed (keeps system message)
+chat.clear
+```
+
+**Important:** Schema validation in chat is **best-effort** for formatting, not correctness. Never use chat+schema for agent control flow.
+
 ### Example: Chat API (Advanced Use Case)
 
 ```ruby
@@ -790,6 +1020,58 @@ end
 - Both methods accept `tools:` parameter (Tool object, array of Tool objects, or array of hashes)
 - For agent tool loops, use `Ollama::Agent::Executor` instead (handles tool execution automatically)
 
+### MCP support (local and remote servers)
+
+You can connect to [Model Context Protocol](https://modelcontextprotocol.io) (MCP) servers and use their tools with the Executor.
+
+**Remote MCP server (HTTP URL, e.g. [GitMCP](https://gitmcp.io)):**
+
+```ruby
+require "ollama_client"
+
+client = Ollama::Client.new
+
+# Remote MCP server URL (e.g. GitMCP: https://gitmcp.io/owner/repo)
+mcp_client = Ollama::MCP::HttpClient.new(
+  url: "https://gitmcp.io/shubhamtaywade82/agent-runtime",
+  timeout_seconds: 60
+)
+
+bridge = Ollama::MCP::ToolsBridge.new(client: mcp_client)
+tools = bridge.tools_for_executor
+
+executor = Ollama::Agent::Executor.new(client, tools: tools)
+answer = executor.run(
+  system: "You have access to the agent-runtime docs. Use tools when the user asks about the repo.",
+  user: "What does this repo do?"
+)
+
+puts answer
+mcp_client.close
+```
+
+**Local MCP server (stdio, e.g. filesystem server):**
+
+```ruby
+# Local MCP server via stdio (requires Node.js/npx)
+mcp_client = Ollama::MCP::StdioClient.new(
+  command: "npx",
+  args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
+  timeout_seconds: 60
+)
+
+bridge = Ollama::MCP::ToolsBridge.new(stdio_client: mcp_client)  # or client: mcp_client
+tools = bridge.tools_for_executor
+# ... same executor usage
+mcp_client.close
+```
+
+- **Stdio**: `Ollama::MCP::StdioClient` — spawns a subprocess; use for local servers (e.g. `npx @modelcontextprotocol/server-filesystem`).
+- **HTTP**: `Ollama::MCP::HttpClient` — POSTs JSON-RPC to a URL; use for remote servers (e.g. [gitmcp.io/owner/repo](https://gitmcp.io)).
+- **Bridge**: `Ollama::MCP::ToolsBridge.new(client: mcp_client)` or `stdio_client: mcp_client`; then `tools_for_executor` for the Executor.
+- No extra gem; implementation is self-contained.
+- See [examples/mcp_executor.rb](examples/mcp_executor.rb) (stdio) and [examples/mcp_http_executor.rb](examples/mcp_http_executor.rb) (URL).
+
 ### Example: Data Analysis with Validation
 
 ```ruby
@@ -958,42 +1240,37 @@ client = Ollama::Client.new
 # Note: You need an embedding model installed in Ollama
 # Common models: nomic-embed-text, all-minilm, mxbai-embed-large
 # Check available models: client.list_models
+# The client uses /api/embed endpoint internally
 
 begin
   # Single text embedding
-  # Note: Use the full model name with tag if needed (e.g., "nomic-embed-text:latest")
+  # Note: Model name can be with or without tag (e.g., "nomic-embed-text" or "nomic-embed-text:latest")
   embedding = client.embeddings.embed(
-    model: "nomic-embed-text:latest",  # Use an available embedding model
+    model: "nomic-embed-text",  # Use an available embedding model
     input: "What is Ruby programming?"
   )
   # Returns: [0.123, -0.456, ...] (array of floats)
-  if embedding.empty?
-    puts "Warning: Empty embedding returned. Check model compatibility."
-  else
-    puts "Embedding dimension: #{embedding.length}"
-    puts "First few values: #{embedding.first(5).map { |v| v.round(4) }}"
-  end
+  # For nomic-embed-text, dimension is typically 768
+  puts "Embedding dimension: #{embedding.length}"
+  puts "First few values: #{embedding.first(5).map { |v| v.round(4) }}"
 
   # Multiple texts
   embeddings = client.embeddings.embed(
-    model: "nomic-embed-text:latest",
+    model: "nomic-embed-text",
     input: ["What is Ruby?", "What is Python?", "What is JavaScript?"]
   )
   # Returns: [[...], [...], [...]] (array of embedding arrays)
-  if embeddings.is_a?(Array) && embeddings.first.is_a?(Array)
-    puts "Number of embeddings: #{embeddings.length}"
-    puts "Each embedding dimension: #{embeddings.first.length}"
-  else
-    puts "Unexpected response format: #{embeddings.class}"
-  end
+  # Each inner array is an embedding vector for the corresponding input text
+  puts "Number of embeddings: #{embeddings.length}"
+  puts "Each embedding dimension: #{embeddings.first.length}"
 
 rescue Ollama::NotFoundError => e
   puts "Model not found. Install an embedding model first:"
   puts "  ollama pull nomic-embed-text"
   puts "Or check available models: client.list_models"
-  puts "Note: Use the full model name with tag (e.g., 'nomic-embed-text:latest')"
 rescue Ollama::Error => e
   puts "Error: #{e.message}"
+  # Error message includes helpful troubleshooting steps
 end
 
 # Use for semantic similarity in agents
@@ -1204,67 +1481,35 @@ end
 
 This keeps the `ollama-client` gem **domain-agnostic** and **reusable** across any project.
 
-**See `examples/tool_calling_pattern.rb` for a working implementation of this pattern.**
-
-## Advanced Examples
-
-The `examples/` directory contains advanced examples demonstrating production-grade patterns:
-
-### `tool_calling_pattern.rb`
-**Working implementation of the ToolRouter pattern from the Architecture section:**
-- Tool registry and routing
-- LLM outputs intent, agent executes tools
-- Demonstrates the correct separation of concerns
-- Matches the pattern shown in README.md lines 430-500
-
-### `dhanhq_trading_agent.rb`
-**Real-world integration: Ollama (reasoning) + DhanHQ (execution):**
-- Ollama analyzes market data and makes trading decisions
-- DhanHQ executes trades (place orders, check positions, etc.)
-- Demonstrates proper separation: LLM = reasoning, DhanHQ = execution
-- Shows risk management with super orders (SL/TP)
-- Perfect example of agent-grade tool calling pattern
-
-### `advanced_multi_step_agent.rb`
-Multi-step agent workflow with:
-- Complex nested schemas
-- State management across steps
-- Confidence thresholds
-- Risk assessment
-- Error recovery
-
-### `advanced_error_handling.rb`
-Comprehensive error handling patterns:
-- All error types (NotFoundError, HTTPError, TimeoutError, etc.)
-- Retry strategies with exponential backoff
-- Fallback mechanisms
-- Error statistics and observability
-
-### `advanced_complex_schemas.rb`
-Real-world complex schemas:
-- Financial analysis (nested metrics, recommendations, risk factors)
-- Code review (issues, suggestions, effort estimation)
-- Research paper analysis (findings, methodology, citations)
-
-### `advanced_performance_testing.rb`
-Performance and observability:
-- Latency measurement (min, max, avg, p95, p99)
-- Throughput testing
-- Error rate tracking
-- Metrics export
-
-### `advanced_edge_cases.rb`
-Boundary and edge case testing:
-- Empty/long prompts
-- Special characters and unicode
-- Minimal/strict schemas
-- Deeply nested structures
-- Enum constraints
-
-Run any example:
-```bash
-ruby examples/advanced_multi_step_agent.rb
-```
+**See the [ollama-agent-examples](https://github.com/shubhamtaywade82/ollama-agent-examples) repository for working implementations of this pattern.**
+
+## 📚 Examples
+
+### Minimal Examples (In This Repo)
+
+The `examples/` directory contains minimal examples demonstrating **client usage only**:
+
+- **`basic_generate.rb`** - Basic `/generate` usage with schema validation
+- **`basic_chat.rb`** - Basic `/chat` usage
+- **`tool_calling_parsing.rb`** - Tool-call parsing (no execution)
+- **`tool_dto_example.rb`** - Tool DTO serialization
+
+These examples focus on **transport and protocol correctness**, not agent behavior.
+
+### Full Agent Examples (Separate Repository)
+
+For complete agent examples (trading agents, coding agents, RAG agents, multi-step workflows, tool execution patterns, etc.), see:
+
+**[ollama-agent-examples](https://github.com/shubhamtaywade82/ollama-agent-examples)**
+
+This separation keeps `ollama-client` focused on the transport layer while providing comprehensive examples for agent developers.
+
+**Why this separation?**
+- Examples rot faster than APIs
+- Agent examples pull in domain-specific dependencies
+- Tool examples imply opinions about tool design
+- The client stays clean and maintainable
+- Users don't confuse client vs agent responsibilities
 
 ## Development
 

data/RELEASE_NOTES_v0.2.6.md

@@ -0,0 +1,41 @@
+# Release v0.2.6
+
+## 🎯 Major Changes
+
+### Test Coverage & Quality
+- **Increased test coverage from 65.66% to 79.59%**
+- Added comprehensive test suites for:
+  - `Ollama::DocumentLoader` (file loading, context building)
+  - `Ollama::Embeddings` (API calls, error handling)
+  - `Ollama::ChatSession` (session management)
+  - Tool classes (`Tool`, `Function`, `Parameters`, `Property`)
+
+### Documentation & Examples
+- **Reorganized examples**: Moved agent examples to separate repository (`ollama-agent-examples`)
+- Kept minimal client-focused examples in this repository
+- Rewrote testing documentation to focus on client-only testing (transport/protocol)
+- Added test checklist with specific test categories (G1-G3, C1-C3, A1-A2, F1-F3)
+- Updated README with enhanced "What This Gem IS NOT" section
+
+### Code Quality
+- Fixed all RuboCop offenses
+- Improved code quality and consistency
+- Aligned workflow with agent-runtime repository
+
+## 📦 Installation
+
+```bash
+gem install ollama-client
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem 'ollama-client', '~> 0.2.6'
+```
+
+## 🔗 Links
+
+- [Full Changelog](https://github.com/shubhamtaywade82/ollama-client/blob/main/CHANGELOG.md)
+- [Documentation](https://github.com/shubhamtaywade82/ollama-client#readme)
+- [Examples Repository](https://github.com/shubhamtaywade82/ollama-agent-examples)