ollama-client 0.2.5 → 0.2.7

data/docs/TEST_CHECKLIST.md

@@ -0,0 +1,450 @@
+# Test Checklist: `ollama-client` Client-Only Testing
+
+This checklist ensures comprehensive testing of the `ollama-client` transport layer without leaking agent concerns.
+
+## Category A: `/generate` Mode Tests (Stateless, Deterministic)
+
+### ✅ G1 — Basic Generate
+- [ ] Response is a Hash
+- [ ] JSON is parsed correctly
+- [ ] No `tool_calls` present
+- [ ] No streaming artifacts
+- [ ] Schema validation passes (if schema provided)
+
+**Test File:** `spec/ollama/client_generate_spec.rb`
+
+**Example Test:**
+```ruby
+it "parses JSON response from generate endpoint" do
+  stub_request(:post, "http://localhost:11434/api/generate")
+    .to_return(
+      status: 200,
+      body: { response: '{"status":"ok"}' }.to_json
+    )
+
+  result = client.generate(
+    prompt: "Output a JSON object with a single key 'status' and value 'ok'.",
+    schema: { "type" => "object", "required" => ["status"] }
+  )
+
+  expect(result).to be_a(Hash)
+  expect(result["status"]).to eq("ok")
+  expect(result).not_to have_key("tool_calls")
+end
+```
+
+---
+
+### ✅ G2 — Strict Schema Enforcement
+- [ ] Raises error if schema violated
+- [ ] Rejects extra fields (if strict mode enabled)
+- [ ] Validates required fields
+- [ ] Validates type constraints
+- [ ] Validates enum constraints
+- [ ] Validates number min/max
+- [ ] Validates string minLength/maxLength
+
+**Test File:** `spec/ollama/client_generate_spec.rb` or `spec/ollama/schema_validator_spec.rb`
+
+**Example Test:**
+```ruby
+it "rejects responses that violate schema" do
+  stub_request(:post, "http://localhost:11434/api/generate")
+    .to_return(
+      status: 200,
+      body: { response: '{"count":"not-a-number"}' }.to_json
+    )
+
+  schema = {
+    "type" => "object",
+    "required" => ["count"],
+    "properties" => {
+      "count" => { "type" => "number" }
+    }
+  }
+
+  expect do
+    client.generate(prompt: "Output JSON with key 'count' as a number.", schema: schema)
+  end.to raise_error(Ollama::SchemaViolationError)
+end
+```
+
+---
+
+### ❌ G3 — Tool Attempt in Generate (Must Fail)
+- [ ] No `tool_calls` parsed
+- [ ] No silent acceptance of tool intent
+- [ ] Either ignored or explicit error
+- [ ] `/generate` remains non-agentic
+
+**Test File:** `spec/ollama/client_generate_spec.rb`
+
+**Example Test:**
+```ruby
+it "ignores tool calls in generate mode" do
+  stub_request(:post, "http://localhost:11434/api/generate")
+    .to_return(
+      status: 200,
+      body: { response: '{"action":"call read_file tool on foo.rb"}' }.to_json
+    )
+
+  result = client.generate(
+    prompt: "Call the read_file tool on foo.rb",
+    schema: { "type" => "object" }
+  )
+
+  expect(result).not_to have_key("tool_calls")
+  expect(result).not_to have_key("tool_use")
+end
+```
+
+---
+
+## Category B: `/chat` Mode Tests (Stateful, Tool-Aware)
+
+### ✅ C1 — Simple Chat
+- [ ] Response contains assistant message
+- [ ] Message history preserved in request
+- [ ] Role is correct
+- [ ] Content is parsed correctly
+
+**Test File:** `spec/ollama/client_chat_spec.rb` or `spec/ollama/client_chat_raw_spec.rb`
+
+**Example Test:**
+```ruby
+it "handles simple chat messages" do
+  stub_request(:post, "http://localhost:11434/api/chat")
+    .to_return(
+      status: 200,
+      body: {
+        message: { role: "assistant", content: "Hello!" }
+      }.to_json
+    )
+
+  response = client.chat_raw(
+    messages: [{ role: "user", content: "Say hello." }],
+    allow_chat: true
+  )
+
+  expect(response.message.content).to eq("Hello!")
+  expect(response.message.role).to eq("assistant")
+end
+```
+
+---
+
+### ✅ C2 — Tool-Call Parsing (Critical)
+- [ ] `tool_calls` extracted correctly
+- [ ] Tool name parsed
+- [ ] Arguments parsed as hash
+- [ ] **No execution happens** (client must not execute tools)
+- [ ] Multiple tool calls handled
+- [ ] Tool call ID preserved (if present)
+
+**Test File:** `spec/ollama/client_chat_raw_spec.rb`
+
+**Example Test:**
+```ruby
+it "extracts tool calls from chat response" do
+  stub_request(:post, "http://localhost:11434/api/chat")
+    .to_return(
+      status: 200,
+      body: {
+        message: {
+          role: "assistant",
+          content: "I'll call the ping tool.",
+          tool_calls: [
+            {
+              type: "function",
+              function: {
+                name: "ping",
+                arguments: { "x" => 1 }.to_json
+              }
+            }
+          ]
+        }
+      }.to_json
+    )
+
+  response = client.chat_raw(
+    messages: [{ role: "user", content: "If a tool named 'ping' exists, call it with { 'x': 1 }." }],
+    tools: [tool_definition],
+    allow_chat: true
+  )
+
+  tool_calls = response.message.tool_calls
+  expect(tool_calls).not_to be_empty
+  expect(tool_calls.first["function"]["name"]).to eq("ping")
+  expect(JSON.parse(tool_calls.first["function"]["arguments"])).to eq("x" => 1)
+end
+```
+
+---
+
+### ✅ C3 — Tool Result Round-Trip Formatting
+- [ ] Client serializes tool message correctly
+- [ ] Ollama accepts tool result message
+- [ ] Response parsed cleanly after tool result
+- [ ] Tool name preserved
+- [ ] Tool content serialized as JSON string
+
+**Test File:** `spec/ollama/client_chat_raw_spec.rb`
+
+**Example Test:**
+```ruby
+it "serializes tool result messages correctly" do
+  messages = [
+    { role: "user", content: "Call ping tool" },
+    { role: "assistant", content: "", tool_calls: [...] },
+    { role: "tool", name: "ping", content: { ok: true }.to_json }
+  ]
+
+  stub_request(:post, "http://localhost:11434/api/chat")
+    .with(body: hash_including(messages: messages))
+    .to_return(
+      status: 200,
+      body: { message: { role: "assistant", content: "Done!" } }.to_json
+    )
+
+  response = client.chat_raw(messages: messages, allow_chat: true)
+  expect(response.message.content).to eq("Done!")
+end
+```
+
+---
+
+## Category C: Protocol Adapters (Anthropic / Native)
+
+### ✅ A1 — Anthropic Message Shape
+- [ ] Messages serialized as content blocks
+- [ ] Tool calls emitted as `tool_use` (if Anthropic mode)
+- [ ] Tool results serialized as `tool_result`
+- [ ] Request payload matches Anthropic format
+
+**Test File:** `spec/ollama/client_chat_raw_spec.rb` or new `spec/ollama/protocol_adapter_spec.rb`
+
+**Example Test:**
+```ruby
+it "serializes messages in Anthropic format" do
+  stub_request(:post, "http://localhost:11434/api/chat")
+    .with do |req|
+      body = JSON.parse(req.body)
+      expect(body["messages"]).to be_an(Array)
+      expect(body["messages"].first).to include("role", "content")
+    end
+    .to_return(status: 200, body: { message: {} }.to_json)
+
+  client.chat_raw(
+    messages: [{ role: "user", content: "Test" }],
+    allow_chat: true
+  )
+end
+```
+
+---
+
+### ✅ A2 — Anthropic Response Parsing
+- [ ] Client normalizes Anthropic format into internal `tool_calls`
+- [ ] Protocol adapter correctness
+- [ ] Tool use ID preserved
+- [ ] Tool input parsed correctly
+
+**Test File:** `spec/ollama/client_chat_raw_spec.rb` or new `spec/ollama/protocol_adapter_spec.rb`
+
+**Example Test:**
+```ruby
+it "normalizes Anthropic-style responses into internal format" do
+  anthropic_response = {
+    content: [
+      {
+        type: "tool_use",
+        id: "call_123",
+        name: "search",
+        input: { q: "foo" }
+      }
+    ]
+  }
+
+  stub_request(:post, "http://localhost:11434/api/chat")
+    .to_return(status: 200, body: anthropic_response.to_json)
+
+  response = client.chat_raw(
+    messages: [{ role: "user", content: "Search for foo" }],
+    allow_chat: true
+  )
+
+  tool_calls = response.message.tool_calls
+  expect(tool_calls).not_to be_empty
+  expect(tool_calls.first["function"]["name"]).to eq("search")
+end
+```
+
+---
+
+## Category D: Failure Modes (Non-Negotiable)
+
+### ✅ F1 — Ollama Down
+- [ ] Connection refused raises correct exception
+- [ ] No hangs
+- [ ] Retries handled correctly (if retryable)
+- [ ] Error message is clear
+
+**Test File:** `spec/ollama/errors_spec.rb` or `spec/ollama/client_spec.rb`
+
+**Example Test:**
+```ruby
+it "handles connection refused gracefully" do
+  stub_request(:post, "http://localhost:11434/api/generate")
+    .to_raise(Errno::ECONNREFUSED)
+
+  start_time = Time.now
+  expect do
+    client.generate(prompt: "test", schema: schema)
+  end.to raise_error(Ollama::Error)
+
+  # Verify no hangs
+  expect(Time.now - start_time).to be < 5
+end
+```
+
+---
+
+### ✅ F2 — Invalid JSON from Model
+- [ ] Client raises parse error
+- [ ] Does not silently continue
+- [ ] Retries handled (if retryable)
+- [ ] Error message includes context
+
+**Test File:** `spec/ollama/errors_spec.rb`
+
+**Example Test:**
+```ruby
+it "raises error on invalid JSON response" do
+  stub_request(:post, "http://localhost:11434/api/generate")
+    .to_return(status: 200, body: { response: "not json at all" }.to_json)
+
+  expect do
+    client.generate(prompt: "test", schema: schema)
+  end.to raise_error(Ollama::InvalidJSONError)
+end
+```
+
+---
+
+### ✅ F3 — Streaming Interruption
+- [ ] Partial stream handled
+- [ ] Client terminates cleanly
+- [ ] No corrupted state
+- [ ] Error raised appropriately
+
+**Test File:** `spec/ollama/client_chat_raw_spec.rb` (if streaming tests exist)
+
+**Example Test:**
+```ruby
+it "handles partial stream gracefully" do
+  stub_request(:post, "http://localhost:11434/api/chat")
+    .to_return(
+      status: 200,
+      body: "data: {\"message\":{\"content\":\"partial\"}}\n",
+      headers: { "Content-Type" => "text/event-stream" }
+    )
+
+  # Simulate stream interruption
+  expect do
+    client.chat_raw(messages: [{ role: "user", content: "test" }], allow_chat: true)
+  end.to raise_error(Ollama::Error)
+end
+```
+
+---
+
+## Additional Test Areas
+
+### Retry Logic
+- [ ] Retries up to `config.retries` times
+- [ ] Only retries retryable errors (5xx, 408, 429)
+- [ ] Raises `RetryExhaustedError` after max retries
+- [ ] Succeeds if retry succeeds
+- [ ] Non-retryable errors (400, 404) fail immediately
+
+### Error Handling
+- [ ] **404 (NotFoundError)**: Model not found, no retries, includes suggestions
+- [ ] **500 (HTTPError)**: Retryable, retries up to config limit
+- [ ] **400 (HTTPError)**: Non-retryable, fails immediately
+- [ ] **TimeoutError**: Retries on timeout
+- [ ] **InvalidJSONError**: Retries on JSON parse errors
+- [ ] **SchemaViolationError**: Retries on schema validation failures
+- [ ] **Connection Errors**: Retries on network failures
+
+### Edge Cases
+- [ ] JSON wrapped in markdown code blocks
+- [ ] Plain JSON responses
+- [ ] Empty model lists
+- [ ] Missing response fields
+- [ ] Malformed JSON
+- [ ] Empty prompts
+- [ ] Very long prompts
+- [ ] Special characters in prompts
+
+### Model Suggestions
+- [ ] Suggests similar models on 404
+- [ ] Fuzzy matching on model names
+- [ ] Limits suggestions to 5 models
+- [ ] Handles model listing failures gracefully
+
+---
+
+## What NOT to Test (Agent Concerns)
+
+❌ **Do not test:**
+- Infinite loops
+- Retries based on content
+- Agent stopping behavior
+- Tool side effects
+- Correctness of answers
+- Agent convergence logic
+- Policy decisions
+- Tool execution
+- Agent state management
+
+**Those belong to `agent-runtime` and app repos.**
+
+---
+
+## Test Coverage Goals
+
+- **Transport layer**: 100% coverage
+- **Protocol parsing**: 100% coverage
+- **Error handling**: 100% coverage
+- **Schema validation**: 100% coverage
+- **Tool-call parsing**: 100% coverage
+
+**Note:** We don't aim for 100% line coverage of agent logic because agent logic doesn't belong in this gem.
+
+---
+
+## Running the Checklist
+
+1. Review each category
+2. Mark tests as complete when implemented
+3. Add test file references
+4. Update this checklist as new test categories are identified
+5. Remove tests that leak agent concerns
+
+---
+
+## Test File Organization
+
+```
+spec/
+├── ollama/
+│   ├── client_spec.rb                    # Basic initialization, config
+│   ├── client_generate_spec.rb           # Category A (G1-G3)
+│   ├── client_chat_spec.rb               # Category B (C1-C3) - basic chat
+│   ├── client_chat_raw_spec.rb           # Category B (C1-C3) - tool calls
+│   ├── protocol_adapter_spec.rb          # Category C (A1-A2) - if needed
+│   ├── errors_spec.rb                    # Category D (F1-F3)
+│   ├── schema_validator_spec.rb          # Category A (G2)
+│   ├── client_list_models_spec.rb        # Model listing
+│   └── client_model_suggestions_spec.rb   # Model suggestions
+```

data/examples/README.md

@@ -1,92 +1,91 @@
 # Examples
 
-This directory contains working examples demonstrating various features of the ollama-client gem.
+This directory contains **minimal examples** demonstrating `ollama-client` usage. These examples focus on **transport and protocol correctness**, not agent behavior.
 
-## Quick Start Examples
+## Minimal Examples
 
-### Basic Tool Calling
-- **[test_tool_calling.rb](test_tool_calling.rb)** - Simple tool calling demo with weather tool
-- **[tool_calling_pattern.rb](tool_calling_pattern.rb)** - Recommended patterns for tool calling
-- **[tool_calling_direct.rb](tool_calling_direct.rb)** - Direct tool calling without Executor
+### Basic Client Usage
 
-### DhanHQ Market Data
-- **[test_dhanhq_tool_calling.rb](test_dhanhq_tool_calling.rb)** - DhanHQ tools with updated intraday & indicators
-- **[dhanhq_tools.rb](dhanhq_tools.rb)** - DhanHQ API wrapper tools
-- **[dhan_console.rb](dhan_console.rb)** - Interactive DhanHQ console with planning
+- **[basic_generate.rb](basic_generate.rb)** - Basic `/generate` usage with schema validation
+  - Demonstrates stateless, deterministic JSON output
+  - Shows schema enforcement
+  - No agent logic
 
-### Multi-Step Agents
-- **[multi_step_agent_e2e.rb](multi_step_agent_e2e.rb)** - End-to-end multi-step agent example
-- **[multi_step_agent_with_external_data.rb](multi_step_agent_with_external_data.rb)** - Agent with external data integration
+- **[basic_chat.rb](basic_chat.rb)** - Basic `/chat` usage
+  - Demonstrates stateful message handling
+  - Shows multi-turn conversation structure
+  - No agent loops
 
-### Structured Data
-- **[structured_outputs_chat.rb](structured_outputs_chat.rb)** - Structured outputs with schemas
-- **[structured_tools.rb](structured_tools.rb)** - Structured tool definitions
-- **[tool_dto_example.rb](tool_dto_example.rb)** - Using DTOs for tool definitions
+- **[tool_calling_parsing.rb](tool_calling_parsing.rb)** - Tool-call parsing (no execution)
+  - Demonstrates tool-call detection and extraction
+  - Shows how to parse tool calls from LLM response
+  - **Does NOT execute tools** - that's agent responsibility
 
-### Advanced Features
-- **[advanced_multi_step_agent.rb](advanced_multi_step_agent.rb)** - Complex multi-step workflows
-- **[advanced_error_handling.rb](advanced_error_handling.rb)** - Error handling patterns
-- **[advanced_edge_cases.rb](advanced_edge_cases.rb)** - Edge case handling
-- **[advanced_complex_schemas.rb](advanced_complex_schemas.rb)** - Complex schema definitions
-- **[advanced_performance_testing.rb](advanced_performance_testing.rb)** - Performance testing
+- **[tool_dto_example.rb](tool_dto_example.rb)** - Tool DTO serialization
+  - Demonstrates Tool class serialization/deserialization
+  - Shows DTO functionality
 
-### Interactive Consoles
-- **[chat_console.rb](chat_console.rb)** - Simple chat console with streaming
-- **[dhan_console.rb](dhan_console.rb)** - DhanHQ market data console with formatted tool results
+- **[mcp_executor.rb](mcp_executor.rb)** - MCP tools with Executor (local stdio)
+  - Connects to a local MCP server (stdio)
+  - Requires Node.js/npx for the filesystem server example
 
-### Complete Workflows
-- **[complete_workflow.rb](complete_workflow.rb)** - Complete agent workflow example
+- **[mcp_http_executor.rb](mcp_http_executor.rb)** - MCP tools with Executor (remote URL)
+  - Connects to a remote MCP server via HTTP (e.g. [gitmcp.io](https://gitmcp.io)/owner/repo)
+  - Use the same URL you would add to Cursor’s `mcp.json`
 
-## DhanHQ Examples
+## Running Examples
 
-The `dhanhq/` subdirectory contains more specialized DhanHQ examples:
-- Technical analysis agents
-- Market scanners (intraday options, swing trading)
-- Pattern recognition and trend analysis
-- Multi-agent orchestration
+All examples are standalone and can be run directly:
 
-See [dhanhq/README.md](dhanhq/README.md) for details.
+```bash
+# Basic generate
+ruby examples/basic_generate.rb
 
-## Running Examples
+# Basic chat
+ruby examples/basic_chat.rb
 
-Most examples are standalone and can be run directly:
+# Tool calling parsing
+ruby examples/tool_calling_parsing.rb
 
-```bash
-# Basic tool calling
-ruby examples/test_tool_calling.rb
+# Tool DTO
+ruby examples/tool_dto_example.rb
 
-# DhanHQ with intraday data
-ruby examples/test_dhanhq_tool_calling.rb
+# MCP Executor (local stdio; requires Node.js/npx)
+ruby examples/mcp_executor.rb
 
-# Interactive console
-ruby examples/chat_console.rb
+# MCP Executor (remote URL, e.g. GitMCP)
+ruby examples/mcp_http_executor.rb
 ```
 
 ### Requirements
 
-Some examples require additional setup:
-
-**DhanHQ Examples:**
-- Set `DHANHQ_CLIENT_ID` and `DHANHQ_ACCESS_TOKEN` environment variables
-- Or create `.env` file with credentials
-
-**Ollama:**
 - Ollama server running (default: `http://localhost:11434`)
 - Set `OLLAMA_BASE_URL` if using a different URL
 - Set `OLLAMA_MODEL` if not using default model
 
-## Learning Path
+## Full Agent Examples
+
+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.
+
+## What These Examples Demonstrate
+
+These minimal examples prove:
+
+✅ **Transport layer** - HTTP requests/responses  
+✅ **Protocol correctness** - Request shaping, response parsing  
+✅ **Schema enforcement** - JSON validation  
+✅ **Tool-call parsing** - Detecting and extracting tool calls  
 
-1. **Start here:** `test_tool_calling.rb` - Learn basic tool calling
-2. **Structured data:** `structured_outputs_chat.rb` - Schema-based outputs
-3. **Multi-step:** `multi_step_agent_e2e.rb` - Complex agent workflows
-4. **Market data:** `test_dhanhq_tool_calling.rb` - Real-world API integration
-5. **Interactive:** `dhan_console.rb` - Full-featured console with planning
+These examples do **NOT** demonstrate:
 
-## Contributing
+❌ Agent loops  
+❌ Tool execution  
+❌ Convergence logic  
+❌ Policy decisions  
+❌ Domain-specific logic  
 
-When adding new examples:
-- Include clear comments explaining what the example demonstrates
-- Add `#!/usr/bin/env ruby` shebang at the top
-- Use `frozen_string_literal: true`
-- Update this README with a description
+**Those belong in the separate agent examples repository.**

data/examples/basic_chat.rb

@@ -0,0 +1,33 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example: Basic /chat usage
+# Demonstrates client transport layer - stateful message handling
+
+require_relative "../lib/ollama_client"
+
+client = Ollama::Client.new
+
+# Simple chat message
+response = client.chat_raw(
+  messages: [{ role: "user", content: "Say hello." }],
+  allow_chat: true
+)
+
+puts "Response: #{response.message.content}"
+puts "Role: #{response.message.role}"
+
+# Multi-turn conversation
+messages = [
+  { role: "user", content: "What is Ruby?" }
+]
+
+response1 = client.chat_raw(messages: messages, allow_chat: true)
+puts "\nFirst response: #{response1.message.content}"
+
+# Continue conversation
+messages << { role: "assistant", content: response1.message.content }
+messages << { role: "user", content: "Tell me more about its use cases" }
+
+response2 = client.chat_raw(messages: messages, allow_chat: true)
+puts "\nSecond response: #{response2.message.content}"

data/examples/basic_generate.rb

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example: Basic /generate usage with schema validation
+# Demonstrates client transport layer - stateless, deterministic JSON output
+
+require_relative "../lib/ollama_client"
+
+client = Ollama::Client.new
+
+# Define schema for structured output
+schema = {
+  "type" => "object",
+  "required" => ["status"],
+  "properties" => {
+    "status" => { "type" => "string" }
+  }
+}
+
+# Generate structured JSON response
+result = client.generate(
+  prompt: "Output a JSON object with a single key 'status' and value 'ok'.",
+  schema: schema
+)
+
+puts "Result: #{result.inspect}"
+puts "Status: #{result['status']}" # => "ok"
+
+# The result is guaranteed to match your schema!