ollama-client 0.2.0

data/TESTING.md

@@ -0,0 +1,286 @@
+# Testing Guide
+
+This document explains how to test the `ollama-client` gem comprehensively.
+
+## Test Structure
+
+The test suite is organized into focused spec files:
+
+- `spec/ollama/client_spec.rb` - Basic client initialization and parameter validation
+- `spec/ollama/client_generate_spec.rb` - Comprehensive tests for `generate()` method
+- `spec/ollama/client_chat_spec.rb` - Comprehensive tests for `chat()` method
+- `spec/ollama/client_list_models_spec.rb` - Tests for `list_models()` method
+- `spec/ollama/client_model_suggestions_spec.rb` - Tests for model suggestion feature
+- `spec/ollama/errors_spec.rb` - Tests for all error classes
+- `spec/ollama/config_spec.rb` - Config class tests (in client_spec.rb)
+- `spec/ollama/schema_validator_spec.rb` - Schema validation tests (in client_spec.rb)
+
+## Running Tests
+
+### Run All Tests
+```bash
+bundle exec rspec
+```
+
+### Run Specific Test File
+```bash
+bundle exec rspec spec/ollama/client_generate_spec.rb
+```
+
+### Run with Documentation Format
+```bash
+bundle exec rspec --format documentation
+```
+
+### Run Specific Test
+```bash
+bundle exec rspec spec/ollama/client_generate_spec.rb:45
+```
+
+### Run Tests Matching a Pattern
+```bash
+bundle exec rspec -e "retry"
+```
+
+## Testing Strategy
+
+### 1. HTTP Mocking with WebMock
+
+All HTTP requests are mocked using [WebMock](https://github.com/bblimke/webmock). This allows us to:
+- Test without a real Ollama server
+- Test error scenarios reliably
+- Test retry logic deterministically
+- Run tests in CI/CD without external dependencies
+
+**Example:**
+```ruby
+stub_request(:post, "http://localhost:11434/api/generate")
+  .to_return(status: 200, body: { response: '{"test":"value"}' }.to_json)
+```
+
+### 2. Test Coverage Areas
+
+#### ✅ Success Cases
+- Successful API calls return parsed JSON
+- Schema validation passes
+- Config defaults are applied correctly
+- Model overrides work
+- Options are merged correctly
+
+#### ✅ 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
+
+#### ✅ Retry Logic
+- Retries up to `config.retries` times
+- Only retries retryable errors (5xx, 408, 429)
+- Raises `RetryExhaustedError` after max retries
+- Succeeds if retry succeeds
+
+#### ✅ Edge Cases
+- JSON wrapped in markdown code blocks
+- Plain JSON responses
+- Empty model lists
+- Missing response fields
+- Malformed JSON
+
+#### ✅ Model Suggestions
+- Suggests similar models on 404
+- Fuzzy matching on model names
+- Limits suggestions to 5 models
+- Handles model listing failures gracefully
+
+## Writing New Tests
+
+### Basic Test Structure
+
+```ruby
+RSpec.describe Ollama::Client, "#method_name" do
+  let(:client) { described_class.new(config: config) }
+  let(:config) do
+    Ollama::Config.new.tap do |c|
+      c.base_url = "http://localhost:11434"
+      c.model = "test-model"
+    end
+  end
+
+  before do
+    WebMock.disable_net_connect!(allow_localhost: false)
+  end
+
+  after do
+    WebMock.reset!
+  end
+
+  it "does something" do
+    stub_request(:post, "http://localhost:11434/api/generate")
+      .to_return(status: 200, body: { response: '{}' }.to_json)
+
+    result = client.generate(prompt: "test", schema: { "type" => "object" })
+    expect(result).to eq({})
+  end
+end
+```
+
+### Testing Retry Logic
+
+```ruby
+it "retries on 500 errors" do
+  stub_request(:post, "http://localhost:11434/api/generate")
+    .to_return(status: 500, body: "Internal Server Error")
+    .times(config.retries + 1)
+
+  expect do
+    client.generate(prompt: "test", schema: schema)
+  end.to raise_error(Ollama::RetryExhaustedError)
+
+  expect(WebMock).to have_requested(:post, "http://localhost:11434/api/generate")
+    .times(config.retries + 1)
+end
+```
+
+### Testing Success After Retry
+
+```ruby
+it "succeeds on retry" do
+  stub_request(:post, "http://localhost:11434/api/generate")
+    .to_return(
+      { status: 500, body: "Internal Server Error" },
+      { status: 200, body: { response: '{"test":"value"}' }.to_json }
+    )
+
+  result = client.generate(prompt: "test", schema: schema)
+  expect(result).to eq("test" => "value")
+  expect(WebMock).to have_requested(:post, "http://localhost:11434/api/generate").twice
+end
+```
+
+### Testing Error Details
+
+```ruby
+it "raises error with correct details" do
+  stub_request(:post, "http://localhost:11434/api/generate")
+    .to_return(status: 404, body: "Not Found")
+
+  expect do
+    client.generate(prompt: "test", schema: schema)
+  end.to raise_error(Ollama::NotFoundError) do |error|
+    expect(error.requested_model).to eq("test-model")
+    expect(error.status_code).to eq(404)
+  end
+end
+```
+
+## Integration Tests (Optional)
+
+For integration tests that hit a real Ollama server, create a separate spec file:
+
+```ruby
+# spec/integration/ollama_client_integration_spec.rb
+RSpec.describe "Ollama Client Integration", :integration do
+  # Skip if OLLAMA_URL is not set
+  before(:all) do
+    skip "Set OLLAMA_URL environment variable to run integration tests" unless ENV["OLLAMA_URL"]
+  end
+
+  let(:client) do
+    config = Ollama::Config.new
+    config.base_url = ENV["OLLAMA_URL"] || "http://localhost:11434"
+    Ollama::Client.new(config: config)
+  end
+
+  it "can generate structured output" do
+    schema = {
+      "type" => "object",
+      "required" => ["test"],
+      "properties" => { "test" => { "type" => "string" } }
+    }
+
+    result = client.generate(
+      prompt: "Return a JSON object with test='hello'",
+      schema: schema
+    )
+
+    expect(result["test"]).to eq("hello")
+  end
+end
+```
+
+Run integration tests separately:
+```bash
+bundle exec rspec --tag integration
+```
+
+## Test Coverage Metrics
+
+To check test coverage, add `simplecov`:
+
+```ruby
+# spec/spec_helper.rb
+require "simplecov"
+SimpleCov.start
+```
+
+Then run:
+```bash
+bundle exec rspec
+open coverage/index.html
+```
+
+## Continuous Integration
+
+The test suite is designed to run in CI without external dependencies:
+- All tests use WebMock (no real Ollama server needed)
+- Tests are deterministic and fast
+- No flaky network-dependent tests
+
+## Best Practices
+
+1. **Always mock HTTP requests** - Don't make real network calls in unit tests
+2. **Test error paths** - Ensure all error scenarios are covered
+3. **Test retry logic** - Verify retries work correctly
+4. **Test edge cases** - JSON parsing, empty responses, etc.
+5. **Keep tests focused** - One assertion per test when possible
+6. **Use descriptive test names** - "it 'retries on 500 errors'"
+7. **Reset WebMock** - Always reset in `after` blocks
+
+## Debugging Tests
+
+### See WebMock Requests
+```ruby
+puts WebMock::RequestRegistry.instance.requested_signatures
+```
+
+### Inspect Stubbed Requests
+```ruby
+stub = stub_request(:post, "http://localhost:11434/api/generate")
+  .with { |req| puts req.body }
+  .to_return(status: 200, body: { response: '{}' }.to_json)
+```
+
+### Allow Real Requests (for debugging)
+```ruby
+WebMock.allow_net_connect!
+```
+
+## Common Issues
+
+### "Real HTTP connections are disabled"
+- Make sure `WebMock.disable_net_connect!` is called in `before` block
+- Check that all requests are properly stubbed
+
+### "Unregistered request"
+- The request URL or method doesn't match the stub
+- Check the exact URL being called
+- Use `WebMock.allow_net_connect!` temporarily to see the real request
+
+### Tests are flaky
+- Ensure WebMock is reset in `after` blocks
+- Don't share state between tests
+- Use `let` instead of instance variables
+

data/examples/advanced_complex_schemas.rb

@@ -0,0 +1,363 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Advanced Example: Complex Nested Schemas and Validation
+# Demonstrates: Deep nesting, arrays of objects, conditional validation, real-world data structures
+
+require "json"
+require_relative "../lib/ollama_client"
+
+# Example 1: Financial Analysis Schema
+class FinancialAnalyzer
+  def initialize(client:)
+    @client = client
+    @schema = {
+      "type" => "object",
+      "required" => ["analysis_date", "summary", "metrics", "recommendations"],
+      "properties" => {
+        "analysis_date" => {
+          "type" => "string",
+          "format" => "date-time"
+        },
+        "summary" => {
+          "type" => "string",
+          "minLength" => 50,
+          "maxLength" => 500
+        },
+        "metrics" => {
+          "type" => "object",
+          "required" => ["revenue", "profit_margin", "growth_rate"],
+          "properties" => {
+            "revenue" => {
+              "type" => "number",
+              "minimum" => 0
+            },
+            "profit_margin" => {
+              "type" => "number",
+              "minimum" => 0,
+              "maximum" => 100
+            },
+            "growth_rate" => {
+              "type" => "number"
+            },
+            "trend" => {
+              "type" => "string",
+              "enum" => ["increasing", "stable", "decreasing"]
+            }
+          }
+        },
+        "recommendations" => {
+          "type" => "array",
+          "minItems" => 1,
+          "maxItems" => 10,
+          "items" => {
+            "type" => "object",
+            "required" => ["action", "priority", "rationale"],
+            "properties" => {
+              "action" => {
+                "type" => "string"
+              },
+              "priority" => {
+                "type" => "string",
+                "enum" => ["low", "medium", "high", "critical"]
+              },
+              "rationale" => {
+                "type" => "string"
+              },
+              "estimated_impact" => {
+                "type" => "object",
+                "properties" => {
+                  "revenue_impact" => {
+                    "type" => "number"
+                  },
+                  "risk_level" => {
+                    "type" => "string",
+                    "enum" => ["low", "medium", "high"]
+                  }
+                }
+              }
+            }
+          }
+        },
+        "risk_factors" => {
+          "type" => "array",
+          "items" => {
+            "type" => "object",
+            "required" => ["factor", "severity"],
+            "properties" => {
+              "factor" => { "type" => "string" },
+              "severity" => {
+                "type" => "string",
+                "enum" => ["low", "medium", "high", "critical"]
+              },
+              "mitigation" => { "type" => "string" }
+            }
+          }
+        }
+      }
+    }
+  end
+
+  def analyze(data:)
+    prompt = <<~PROMPT
+      Analyze this financial data: #{data}
+
+      Return JSON with: summary (50-500 chars), metrics (revenue, profit_margin, growth_rate, trend),
+      recommendations array (action, priority, rationale), and optional risk_factors array.
+    PROMPT
+
+    @client.generate(prompt: prompt, schema: @schema)
+  end
+end
+
+# Example 2: Code Review Schema
+class CodeReviewer
+  def initialize(client:)
+    @client = client
+    @schema = {
+      "type" => "object",
+      "required" => ["overall_score", "issues", "suggestions"],
+      "properties" => {
+        "overall_score" => {
+          "type" => "integer",
+          "minimum" => 0,
+          "maximum" => 100
+        },
+        "issues" => {
+          "type" => "array",
+          "items" => {
+            "type" => "object",
+            "required" => ["type", "severity", "location", "description"],
+            "properties" => {
+              "type" => {
+                "type" => "string",
+                "enum" => ["bug", "security", "performance", "style", "maintainability"]
+              },
+              "severity" => {
+                "type" => "string",
+                "enum" => ["low", "medium", "high", "critical"]
+              },
+              "location" => {
+                "type" => "object",
+                "properties" => {
+                  "file" => { "type" => "string" },
+                  "line" => { "type" => "integer" },
+                  "column" => { "type" => "integer" }
+                }
+              },
+              "description" => { "type" => "string" },
+              "suggestion" => { "type" => "string" }
+            }
+          }
+        },
+        "suggestions" => {
+          "type" => "array",
+          "items" => {
+            "type" => "object",
+            "required" => ["category", "description"],
+            "properties" => {
+              "category" => {
+                "type" => "string",
+                "enum" => ["refactoring", "optimization", "documentation", "testing"]
+              },
+              "description" => { "type" => "string" },
+              "priority" => {
+                "type" => "string",
+                "enum" => ["low", "medium", "high"]
+              }
+            }
+          }
+        },
+        "strengths" => {
+          "type" => "array",
+          "items" => { "type" => "string" }
+        },
+        "estimated_effort" => {
+          "type" => "object",
+          "properties" => {
+            "hours" => { "type" => "number", "minimum" => 0 },
+            "complexity" => {
+              "type" => "string",
+              "enum" => ["simple", "moderate", "complex"]
+            }
+          }
+        }
+      }
+    }
+  end
+
+  def review(code:)
+    prompt = <<~PROMPT
+      Review this Ruby code: #{code}
+
+      Return JSON with: overall_score (0-100), issues array (type, severity, location, description),
+      suggestions array (category, description, priority), optional strengths array, optional estimated_effort.
+    PROMPT
+
+    @client.generate(prompt: prompt, schema: @schema)
+  end
+end
+
+# Example 3: Research Paper Analysis Schema
+class ResearchAnalyzer
+  def initialize(client:)
+    @client = client
+    @schema = {
+      "type" => "object",
+      "required" => ["title", "key_findings", "methodology", "citations"],
+      "properties" => {
+        "title" => { "type" => "string" },
+        "key_findings" => {
+          "type" => "array",
+          "minItems" => 3,
+          "maxItems" => 10,
+          "items" => {
+            "type" => "object",
+            "required" => ["finding", "significance"],
+            "properties" => {
+              "finding" => { "type" => "string" },
+              "significance" => {
+                "type" => "string",
+                "enum" => ["low", "medium", "high", "breakthrough"]
+              },
+              "evidence" => { "type" => "string" }
+            }
+          }
+        },
+        "methodology" => {
+          "type" => "object",
+          "required" => ["type", "description"],
+          "properties" => {
+            "type" => {
+              "type" => "string",
+              "enum" => ["experimental", "observational", "theoretical", "computational", "mixed"]
+            },
+            "description" => { "type" => "string" },
+            "limitations" => {
+              "type" => "array",
+              "items" => { "type" => "string" }
+            }
+          }
+        },
+        "citations" => {
+          "type" => "array",
+          "items" => {
+            "type" => "object",
+            "required" => ["author", "title", "year"],
+            "properties" => {
+              "author" => { "type" => "string" },
+              "title" => { "type" => "string" },
+              "year" => {
+                "type" => "integer",
+                "minimum" => 1900,
+                "maximum" => 2100
+              },
+              "relevance" => {
+                "type" => "string",
+                "enum" => ["low", "medium", "high"]
+              }
+            }
+          }
+        },
+        "reproducibility_score" => {
+          "type" => "number",
+          "minimum" => 0,
+          "maximum" => 1
+        }
+      }
+    }
+  end
+
+  def analyze(paper_text:)
+    prompt = <<~PROMPT
+      Analyze this research paper: #{paper_text}
+
+      Return JSON with: title, key_findings array (3-10 items: finding, significance, evidence),
+      methodology (type, description, limitations), citations array (author, title, year, relevance),
+      optional reproducibility_score (0-1).
+    PROMPT
+
+    @client.generate(prompt: prompt, schema: @schema)
+  end
+end
+
+# Run examples
+if __FILE__ == $PROGRAM_NAME
+  # Use longer timeout for complex schemas
+  config = Ollama::Config.new
+  config.timeout = 60 # 60 seconds for complex operations
+  client = Ollama::Client.new(config: config)
+
+  puts "=" * 60
+  puts "Example 1: Financial Analysis"
+  puts "=" * 60
+  financial_data = <<~DATA
+    Q4 2024 Financial Report:
+    - Revenue: $2.5M (up 15% from Q3)
+    - Operating expenses: $1.8M
+    - Net profit: $700K
+    - Customer base: 5,000 (up 20%)
+    - Churn rate: 2% (down from 3%)
+  DATA
+
+  analyzer = FinancialAnalyzer.new(client: client)
+  begin
+    puts "⏳ Analyzing financial data (this may take 30-60 seconds)..."
+    result = analyzer.analyze(data: financial_data)
+    puts JSON.pretty_generate(result)
+  rescue Ollama::TimeoutError => e
+    puts "⏱️  Timeout: #{e.message}"
+    puts "   Try increasing timeout or using a faster model"
+  rescue Ollama::Error => e
+    puts "❌ Error: #{e.message}"
+  end
+
+  puts "\n" + "=" * 60
+  puts "Example 2: Code Review"
+  puts "=" * 60
+  code_sample = <<~RUBY
+    def calculate_total(items)
+      total = 0
+      items.each do |item|
+        total += item.price
+      end
+      total
+    end
+  RUBY
+
+  reviewer = CodeReviewer.new(client: client)
+  begin
+    puts "⏳ Reviewing code (this may take 30-60 seconds)..."
+    result = reviewer.review(code: code_sample)
+    puts JSON.pretty_generate(result)
+  rescue Ollama::TimeoutError => e
+    puts "⏱️  Timeout: #{e.message}"
+    puts "   Try increasing timeout or using a faster model"
+  rescue Ollama::Error => e
+    puts "❌ Error: #{e.message}"
+  end
+
+  puts "\n" + "=" * 60
+  puts "Example 3: Research Paper Analysis"
+  puts "=" * 60
+  paper_abstract = <<~TEXT
+    This study investigates the impact of machine learning on financial forecasting.
+    We analyzed 10 years of market data using neural networks and found a 23% improvement
+    in prediction accuracy. The methodology involved training on historical data and
+    validating on out-of-sample periods. Key limitations include data quality and
+    model interpretability challenges.
+  TEXT
+
+  research_analyzer = ResearchAnalyzer.new(client: client)
+  begin
+    puts "⏳ Analyzing research paper (this may take 30-60 seconds)..."
+    result = research_analyzer.analyze(paper_text: paper_abstract)
+    puts JSON.pretty_generate(result)
+  rescue Ollama::TimeoutError => e
+    puts "⏱️  Timeout: #{e.message}"
+    puts "   Try increasing timeout or using a faster model"
+  rescue Ollama::Error => e
+    puts "❌ Error: #{e.message}"
+  end
+end
+