ollama-client 0.2.6 → 0.2.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a1ba22e6a669d0617be340e290bb4009023583418afb1f4952f58b616e22369e
-  data.tar.gz: 33310224720f99ab82cf59b6e30166b682af648240fcecd84ecde9dc5bc88608
+  metadata.gz: 53bd3c1ff3323d004a7ba3549317ef49d3ce9698d41133a1d2150d0a5135fa80
+  data.tar.gz: 4c726b2a7fabf164c91cd51206266d250de836986d1a36726556cbefb47a6e8e
 SHA512:
-  metadata.gz: 29ff7766aebd45634c3170e6a2e8bdb09c97728f6d4dc726e17e9cc404d23c53e96c669effda77044c3a2296fcd0642e2a96bb845d84d4549f759b8de20383c0
-  data.tar.gz: d272a70b48a329c09c8b2ddc0baf98b61708a637eb4cbf92693af4291ccfbf42104ecdf3eef0a66b525ad45e57111c4d550baa525662c284482b15feacfcfafa
+  metadata.gz: 1cdcc10b54d2fa318daefc2736d338715b65f03cacf94c7c9303c07ec745ea510e6de0ac73c0c668b0301481663989af1368d86727ebfa1252a43edab9d7d711
+  data.tar.gz: aead7b8ae703d436866cf796e91b102fbcc21ff47e6528c2edf62b13a1bac1f98f36d1146ba3e56a7fa0792bd0aff0880be65450c05b2352336cd20b39b3f9ab

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 ## [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

data/README.md

@@ -72,28 +72,165 @@ 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, allow_plain_text: false)`** 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
 - ✅ Ideal for: agent planning, tool routing, one-shot analysis, classification, extraction
 - ✅ No implicit memory or conversation history
-- ✅ Supports both structured JSON (with schema) and plain text/markdown (with `allow_plain_text: true`)
+- ✅ Supports both structured JSON (with schema) and plain text/markdown (without schema)
 
 **This is the method you should use for hybrid agents.**
 
 **Usage:**
 - **With schema** (structured JSON): `generate(prompt: "...", schema: {...})` - returns Hash
-- **Without schema** (plain text): `generate(prompt: "...", allow_plain_text: true)` - returns String
+- **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.
 
@@ -264,10 +401,9 @@ require "ollama_client"
 
 client = Ollama::Client.new
 
-# Get plain text/markdown response (use allow_plain_text: true to skip schema)
+# Get plain text/markdown response (omit schema for plain text)
 text_response = client.generate(
-  prompt: "Explain Ruby in simple terms",
-  allow_plain_text: true
+  prompt: "Explain Ruby in simple terms"
 )
 
 puts text_response
@@ -294,8 +430,8 @@ puts text_response
 ```
 
 **When to use which:**
-- **`generate()` with `allow_plain_text: true`** - Simple one-shot queries, explanations, text generation
-- **`generate()` with schema** - Structured JSON outputs for agents (default, recommended)
+- **`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
 
@@ -303,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)
@@ -884,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
@@ -1052,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

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)

data/docs/AREAS_FOR_CONSIDERATION.md

@@ -0,0 +1,325 @@
+# Areas for Consideration
+
+This document addresses three key areas that warrant attention in the `ollama-client` codebase.
+
+## ⚠️ 1. Complex Client Class
+
+### Current State
+
+- **File:** `lib/ollama/client.rb`
+- **Size:** 860 lines
+- **RuboCop Disables:**
+  - `Metrics/ClassLength` (entire class)
+  - `Metrics/MethodLength` (multiple methods)
+  - `Metrics/ParameterLists` (multiple methods)
+  - `Metrics/AbcSize` (multiple methods)
+  - `Metrics/CyclomaticComplexity` (multiple methods)
+  - `Metrics/PerceivedComplexity` (multiple methods)
+  - `Metrics/BlockLength` (multiple methods)
+
+### Responsibilities
+
+The `Client` class currently handles:
+1. HTTP communication with Ollama API
+2. JSON parsing and validation
+3. Schema validation
+4. Retry logic
+5. Error handling and enhancement
+6. Tool normalization
+7. Response formatting
+8. Streaming response parsing
+9. Model suggestion logic
+10. Response hooks/callbacks
+
+### Recommendations
+
+#### Option A: Extract Service Objects (Recommended)
+
+Break down into focused service classes:
+
+```ruby
+# lib/ollama/http_client.rb
+class HttpClient
+  # Handles all HTTP communication
+end
+
+# lib/ollama/response_parser.rb
+class ResponseParser
+  # Handles JSON parsing, markdown stripping, etc.
+end
+
+# lib/ollama/retry_handler.rb
+class RetryHandler
+  # Handles retry logic and error classification
+end
+
+# lib/ollama/client.rb (simplified)
+class Client
+  def initialize(config: nil)
+    @config = config || default_config
+    @http_client = HttpClient.new(@config)
+    @response_parser = ResponseParser.new
+    @retry_handler = RetryHandler.new(@config)
+  end
+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
+
+#### Option B: Extract Concerns into Modules
+
+Keep single file but organize with modules:
+
+```ruby
+class Client
+  include HTTPCommunication
+  include ResponseParsing
+  include RetryHandling
+  include ErrorEnhancement
+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
+
+### Recommended Approach
+
+**Short-term:** Document the decision (Option C)
+**Medium-term:** Extract HTTP client (Option A, partial)
+**Long-term:** Full service object extraction (Option A)
+
+---
+
+## ⚠️ 2. Thread Safety
+
+### Current State
+
+**Global Configuration:**
+```ruby
+module OllamaClient
+  @config_mutex = Mutex.new
+  
+  def self.configure
+    @config_mutex.synchronize do
+      @config ||= Ollama::Config.new
+      yield(@config)
+    end
+  end
+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
+
+### 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)
+
+### Recommendations
+
+#### Option A: Clarify Documentation (Recommended)
+
+Update warnings to be more accurate:
+
+```ruby
+# ⚠️ THREAD SAFETY WARNING:
+# Global configuration access is protected by mutex, but modifying
+# global config while clients are active can cause race conditions.
+# For concurrent agents, prefer per-client configuration:
+#
+#   config = Ollama::Config.new
+#   config.model = "llama3.1"
+#   client = Ollama::Client.new(config: config)
+```
+
+#### Option B: Make Global Config Immutable
+
+```ruby
+def self.configure
+  @config_mutex.synchronize do
+    @config ||= Ollama::Config.new
+    frozen_config = @config.dup.freeze
+    yield(frozen_config)
+    @config = frozen_config.dup  # Create new instance
+  end
+end
+```
+
+#### Option C: Deprecate Global Config
+
+```ruby
+def self.configure
+  warn "[DEPRECATED] OllamaClient.configure is deprecated. " \
+       "Use per-client config: Ollama::Client.new(config: ...)"
+  # ... existing implementation
+end
+```
+
+### Recommended Approach
+
+**Immediate:** Clarify documentation (Option A)
+**Future:** Consider deprecation path (Option C) if usage patterns show global config is rarely needed
+
+---
+
+## ⚠️ 3. Learning Curve
+
+### Current State
+
+The gem provides two agent patterns:
+
+1. **Planner** (`Ollama::Agent::Planner`)
+   - Stateless
+   - Uses `/api/generate`
+   - Returns structured JSON
+   - For: routing, classification, decisions
+
+2. **Executor** (`Ollama::Agent::Executor`)
+   - Stateful
+   - Uses `/api/chat`
+   - Tool-calling loops
+   - For: multi-step workflows
+
+### Challenges for Beginners
+
+1. **Conceptual Complexity:**
+   - Two different patterns (why?)
+   - When to use which?
+   - Stateless vs stateful concepts
+
+2. **API Surface:**
+   - `generate()` vs `chat()` vs `chat_raw()`
+   - When to use schema vs plain text
+   - Tool calling setup
+
+3. **Documentation:**
+   - README is comprehensive but dense
+   - Examples are minimal
+   - Agent patterns require understanding of concepts
+
+### Recommendations
+
+#### Option A: Enhanced Quick Start Guide
+
+Create a step-by-step guide:
+
+```markdown
+# Quick Start Guide
+
+## Step 1: Simple Text Generation
+[Example]
+
+## Step 2: Structured Outputs
+[Example]
+
+## Step 3: Agent Planning
+[Example]
+
+## Step 4: Tool Calling
+[Example]
+```
+
+#### Option B: Decision Tree / Flowchart
+
+```
+Need structured output?
+├─ Yes → Use generate() with schema
+└─ No → Need conversation?
+    ├─ Yes → Use chat_raw() or ChatSession
+    └─ No → Use generate() with allow_plain_text: true
+```
+
+#### Option C: Simplified Wrapper API
+
+```ruby
+# High-level API for beginners
+class SimpleAgent
+  def initialize(model: "llama3.1:8b")
+    @client = Ollama::Client.new
+    @model = model
+  end
+  
+  def ask(question, schema: nil)
+    if schema
+      @client.generate(prompt: question, schema: schema)
+    else
+      @client.generate(prompt: question, allow_plain_text: true)
+    end
+  end
+end
+```
+
+#### Option D: Video Tutorials / Interactive Examples
+
+- Video walkthrough
+- Interactive REPL examples
+- Common patterns cookbook
+
+### Recommended Approach
+
+**Immediate:**
+1. Add "Quick Start" section to README (Option A)
+2. Add decision tree diagram (Option B)
+
+**Short-term:**
+3. Create `examples/quick_start/` directory with progressive examples
+4. Add "Common Patterns" section
+
+**Long-term:**
+5. Consider simplified API wrapper (Option C) if demand exists
+6. Create video tutorials if community requests
+
+---
+
+## Summary
+
+| Area | Current State | Recommended Action | Priority |
+|------|--------------|-------------------|----------|
+| **Complex Client** | 860 lines, metrics disabled | Document decision, plan extraction | Medium |
+| **Thread Safety** | Mutex present but confusing docs | Clarify documentation | High |
+| **Learning Curve** | Comprehensive but dense | Add quick start guide + decision tree | High |
+
+## Next Steps
+
+1. ✅ Create this document (done)
+2. Update thread safety documentation
+3. Add quick start guide to README
+4. Create decision tree diagram
+5. Consider ADR for Client class architecture
+6. Gather user feedback on learning curve