ollama-client 0.2.0

data/examples/advanced_edge_cases.rb

@@ -0,0 +1,241 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Advanced Example: Edge Cases and Boundary Testing
+# Demonstrates: Empty responses, malformed schemas, extreme values, special characters
+
+require "json"
+require_relative "../lib/ollama_client"
+
+class EdgeCaseTester
+  def initialize(client:)
+    @client = client
+  end
+
+  def test_empty_prompt
+    puts "Test 1: Empty prompt"
+    schema = {
+      "type" => "object",
+      "properties" => {
+        "response" => { "type" => "string" }
+      }
+    }
+
+    begin
+      result = @client.generate(prompt: "", schema: schema)
+      puts "  ✅ Handled empty prompt: #{result.inspect[0..100]}"
+    rescue Ollama::Error => e
+      puts "  ❌ Error: #{e.class} - #{e.message}"
+    end
+    puts
+  end
+
+  def test_very_long_prompt
+    puts "Test 2: Very long prompt (10KB+)"
+    long_prompt = "Repeat this sentence. " * 500
+    schema = {
+      "type" => "object",
+      "properties" => {
+        "summary" => { "type" => "string" }
+      }
+    }
+
+    begin
+      @client.generate(prompt: long_prompt, schema: schema)
+      puts "  ✅ Handled long prompt (#{long_prompt.length} chars)"
+    rescue Ollama::Error => e
+      puts "  ❌ Error: #{e.class} - #{e.message}"
+    end
+    puts
+  end
+
+  def test_special_characters
+    puts "Test 3: Special characters in prompt"
+    special_prompt = "Analyze: !@#$%^&*()_+-=[]{}|;':\",./<>?`~"
+    schema = {
+      "type" => "object",
+      "properties" => {
+        "analysis" => { "type" => "string" }
+      }
+    }
+
+    begin
+      @client.generate(prompt: special_prompt, schema: schema)
+      puts "  ✅ Handled special characters"
+    rescue Ollama::Error => e
+      puts "  ❌ Error: #{e.class} - #{e.message}"
+    end
+    puts
+  end
+
+  def test_unicode_characters
+    puts "Test 4: Unicode characters"
+    unicode_prompt = "Analyze: 你好世界 🌍 🚀 émojis and spéciál chäracters"
+    schema = {
+      "type" => "object",
+      "properties" => {
+        "analysis" => { "type" => "string" }
+      }
+    }
+
+    begin
+      @client.generate(prompt: unicode_prompt, schema: schema)
+      puts "  ✅ Handled unicode characters"
+    rescue Ollama::Error => e
+      puts "  ❌ Error: #{e.class} - #{e.message}"
+    end
+    puts
+  end
+
+  def test_minimal_schema
+    puts "Test 5: Minimal schema (no required fields)"
+    schema = {
+      "type" => "object",
+      "additionalProperties" => true
+    }
+
+    begin
+      result = @client.generate(
+        prompt: "Return any JSON object",
+        schema: schema
+      )
+      puts "  ✅ Handled minimal schema: #{result.keys.join(', ')}"
+    rescue Ollama::Error => e
+      puts "  ❌ Error: #{e.class} - #{e.message}"
+    end
+    puts
+  end
+
+  def test_strict_schema
+    puts "Test 6: Strict schema with many constraints"
+    strict_schema = {
+      "type" => "object",
+      "required" => ["id", "name", "values"],
+      "properties" => {
+        "id" => {
+          "type" => "integer",
+          "minimum" => 1,
+          "maximum" => 1000
+        },
+        "name" => {
+          "type" => "string",
+          "minLength" => 3,
+          "maxLength" => 20,
+          "pattern" => "^[A-Za-z0-9_]+$"
+        },
+        "values" => {
+          "type" => "array",
+          "minItems" => 2,
+          "maxItems" => 5,
+          "items" => {
+            "type" => "number",
+            "minimum" => 0,
+            "maximum" => 100
+          }
+        }
+      }
+    }
+
+    begin
+      prompt_text = "Generate a valid object with id (1-1000), " \
+                    "name (3-20 alphanumeric chars), " \
+                    "and values (2-5 numbers 0-100)"
+      result = @client.generate(
+        prompt: prompt_text,
+        schema: strict_schema
+      )
+      puts "  ✅ Handled strict schema"
+      puts "     ID: #{result['id']}, Name: #{result['name']}, Values: #{result['values']}"
+    rescue Ollama::Error => e
+      puts "  ❌ Error: #{e.class} - #{e.message}"
+    end
+    puts
+  end
+
+  def test_nested_arrays
+    puts "Test 7: Deeply nested arrays"
+    nested_schema = {
+      "type" => "object",
+      "properties" => {
+        "matrix" => {
+          "type" => "array",
+          "items" => {
+            "type" => "array",
+            "items" => {
+              "type" => "array",
+              "items" => { "type" => "integer" }
+            }
+          }
+        }
+      }
+    }
+
+    begin
+      @client.generate(
+        prompt: "Generate a 2x2x2 matrix of integers",
+        schema: nested_schema
+      )
+      puts "  ✅ Handled nested arrays"
+    rescue Ollama::Error => e
+      puts "  ❌ Error: #{e.class} - #{e.message}"
+    end
+    puts
+  end
+
+  def test_enum_constraints
+    puts "Test 8: Strict enum constraints"
+    enum_schema = {
+      "type" => "object",
+      "required" => ["status", "priority"],
+      "properties" => {
+        "status" => {
+          "type" => "string",
+          "enum" => ["pending", "in_progress", "completed", "failed"]
+        },
+        "priority" => {
+          "type" => "string",
+          "enum" => ["low", "medium", "high", "urgent"]
+        }
+      }
+    }
+
+    begin
+      result = @client.generate(
+        prompt: "Choose a status and priority from the allowed values",
+        schema: enum_schema
+      )
+      puts "  ✅ Handled enum constraints: status=#{result['status']}, priority=#{result['priority']}"
+    rescue Ollama::Error => e
+      puts "  ❌ Error: #{e.class} - #{e.message}"
+    end
+    puts
+  end
+
+  def run_all_tests
+    puts "=" * 60
+    puts "Edge Case Testing Suite"
+    puts "=" * 60
+    puts
+
+    test_empty_prompt
+    test_very_long_prompt
+    test_special_characters
+    test_unicode_characters
+    test_minimal_schema
+    test_strict_schema
+    test_nested_arrays
+    test_enum_constraints
+
+    puts "=" * 60
+    puts "Edge case testing complete!"
+    puts "=" * 60
+  end
+end
+
+# Run tests
+if __FILE__ == $PROGRAM_NAME
+  client = Ollama::Client.new
+  tester = EdgeCaseTester.new(client: client)
+  tester.run_all_tests
+end
+

data/examples/advanced_error_handling.rb

@@ -0,0 +1,200 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Advanced Example: Comprehensive Error Handling and Recovery Patterns
+# Demonstrates: All error types, retry strategies, fallback mechanisms, observability
+
+require "json"
+require_relative "../lib/ollama_client"
+
+class ResilientAgent
+  def initialize(client:)
+    @client = client
+    @stats = {
+      total_calls: 0,
+      successes: 0,
+      retries: 0,
+      failures: 0,
+      errors_by_type: {}
+    }
+  end
+
+  # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+  def execute_with_resilience(prompt:, schema:, max_attempts: 3)
+    @stats[:total_calls] += 1
+    attempt = 0
+
+    loop do
+      attempt += 1
+      puts "\n📞 Attempt #{attempt}/#{max_attempts}"
+
+      begin
+        result = @client.generate(prompt: prompt, schema: schema)
+        @stats[:successes] += 1
+        puts "✅ Success on attempt #{attempt}"
+        return { success: true, result: result, attempts: attempt }
+      rescue Ollama::NotFoundError => e
+        @stats[:failures] += 1
+        @stats[:errors_by_type]["NotFoundError"] ||= 0
+        @stats[:errors_by_type]["NotFoundError"] += 1
+
+        puts "❌ Model not found: #{e.message}"
+        puts "   Suggestions: #{e.suggestions.join(', ')}" if e.suggestions && !e.suggestions.empty?
+        # Don't retry 404s
+        return { success: false, error: e, error_type: "NotFoundError", attempts: attempt }
+      rescue Ollama::HTTPError => e
+        @stats[:failures] += 1
+        @stats[:errors_by_type]["HTTPError"] ||= 0
+        @stats[:errors_by_type]["HTTPError"] += 1
+
+        puts "❌ HTTP Error (#{e.status_code}): #{e.message}"
+        if e.retryable?
+          @stats[:retries] += 1
+          puts "   → Retryable, will retry..."
+          if attempt > max_attempts
+            return { success: false, error: e, error_type: "HTTPError", retryable: true,
+                     attempts: attempt }
+          end
+
+          sleep(2**attempt) # Exponential backoff
+          next
+        else
+          puts "   → Non-retryable, aborting"
+          return { success: false, error: e, error_type: "HTTPError", retryable: false, attempts: attempt }
+        end
+      rescue Ollama::TimeoutError => e
+        @stats[:failures] += 1
+        @stats[:errors_by_type]["TimeoutError"] ||= 0
+        @stats[:errors_by_type]["TimeoutError"] += 1
+
+        puts "⏱️  Timeout: #{e.message}"
+        @stats[:retries] += 1
+        return { success: false, error: e, error_type: "TimeoutError", attempts: attempt } unless attempt < max_attempts
+
+        puts "   → Retrying with exponential backoff..."
+        sleep(2**attempt)
+        next
+      rescue Ollama::SchemaViolationError => e
+        @stats[:failures] += 1
+        @stats[:errors_by_type]["SchemaViolationError"] ||= 0
+        @stats[:errors_by_type]["SchemaViolationError"] += 1
+
+        puts "🔴 Schema violation: #{e.message}"
+        # Schema violations are usually not worth retrying (model issue)
+        # But we could try with a simpler schema as fallback
+        unless attempt < max_attempts
+          return { success: false, error: e, error_type: "SchemaViolationError", attempts: attempt }
+        end
+
+        puts "   → Attempting with simplified schema..."
+        simplified_schema = create_fallback_schema(schema)
+        return execute_with_resilience(
+          prompt: prompt,
+          schema: simplified_schema,
+          max_attempts: 1
+        )
+      rescue Ollama::InvalidJSONError => e
+        @stats[:failures] += 1
+        @stats[:errors_by_type]["InvalidJSONError"] ||= 0
+        @stats[:errors_by_type]["InvalidJSONError"] += 1
+
+        puts "📄 Invalid JSON: #{e.message}"
+        @stats[:retries] += 1
+        unless attempt < max_attempts
+          return { success: false, error: e, error_type: "InvalidJSONError", attempts: attempt }
+        end
+
+        puts "   → Retrying..."
+        sleep(1)
+        next
+      rescue Ollama::RetryExhaustedError => e
+        @stats[:failures] += 1
+        @stats[:errors_by_type]["RetryExhaustedError"] ||= 0
+        @stats[:errors_by_type]["RetryExhaustedError"] += 1
+
+        puts "🔄 Retries exhausted: #{e.message}"
+        return { success: false, error: e, error_type: "RetryExhaustedError", attempts: attempt }
+      rescue Ollama::Error => e
+        @stats[:failures] += 1
+        @stats[:errors_by_type]["Error"] ||= 0
+        @stats[:errors_by_type]["Error"] += 1
+
+        puts "❌ General error: #{e.message}"
+        return { success: false, error: e, error_type: "Error", attempts: attempt }
+      rescue StandardError => e
+        @stats[:failures] += 1
+        @stats[:errors_by_type]["StandardError"] ||= 0
+        @stats[:errors_by_type]["StandardError"] += 1
+
+        puts "💥 Unexpected error: #{e.class}: #{e.message}"
+        return { success: false, error: e, error_type: "StandardError", attempts: attempt }
+      end
+    end
+  end
+  # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+  def create_fallback_schema(_original_schema)
+    # Create a minimal fallback schema
+    {
+      "type" => "object",
+      "additionalProperties" => true
+    }
+  end
+
+  def display_stats
+    puts "\n" + "=" * 60
+    puts "Execution Statistics"
+    puts "=" * 60
+    puts "Total calls: #{@stats[:total_calls]}"
+    puts "Successes: #{@stats[:successes]}"
+    puts "Failures: #{@stats[:failures]}"
+    puts "Retries: #{@stats[:retries]}"
+    success_rate = @stats[:total_calls].positive? ? (@stats[:successes].to_f / @stats[:total_calls] * 100).round(2) : 0
+    puts "Success rate: #{success_rate}%"
+    puts "\nErrors by type:"
+    @stats[:errors_by_type].each do |type, count|
+      puts "  #{type}: #{count}"
+    end
+  end
+end
+
+# Test scenarios
+if __FILE__ == $PROGRAM_NAME
+  client = Ollama::Client.new
+  agent = ResilientAgent.new(client: client)
+
+  schema = {
+    "type" => "object",
+    "required" => ["status", "message"],
+    "properties" => {
+      "status" => { "type" => "string" },
+      "message" => { "type" => "string" }
+    }
+  }
+
+  puts "=" * 60
+  puts "Test 1: Normal execution"
+  puts "=" * 60
+  result1 = agent.execute_with_resilience(
+    prompt: "Respond with status 'ok' and a greeting message",
+    schema: schema
+  )
+  puts "Result: #{result1[:success] ? 'SUCCESS' : 'FAILED'}"
+
+  puts "\n" + "=" * 60
+  puts "Test 2: Invalid model (should trigger NotFoundError)"
+  puts "=" * 60
+  # Temporarily use invalid model
+  invalid_client = Ollama::Client.new(
+    config: Ollama::Config.new.tap { |c| c.model = "nonexistent-model:999" }
+  )
+  invalid_agent = ResilientAgent.new(client: invalid_client)
+  result2 = invalid_agent.execute_with_resilience(
+    prompt: "Test",
+    schema: schema
+  )
+  puts "Result: #{result2[:success] ? 'SUCCESS' : 'FAILED'}"
+
+  agent.display_stats
+end
+

data/examples/advanced_multi_step_agent.rb

@@ -0,0 +1,258 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Advanced Example: Multi-Step Agent with Complex Decision Making
+# Demonstrates: Nested schemas, state management, error recovery, confidence thresholds
+
+require "json"
+require_relative "../lib/ollama_client"
+
+class MultiStepAgent
+  def initialize(client:)
+    @client = client
+    @state = {
+      steps_completed: [],
+      data_collected: {},
+      errors: []
+    }
+
+    # Complex nested schema for decision making
+    @decision_schema = {
+      "type" => "object",
+      "required" => ["step", "action", "reasoning", "confidence", "next_steps"],
+      "properties" => {
+        "step" => {
+          "type" => "integer",
+          "description" => "Current step number in the workflow"
+        },
+        "action" => {
+          "type" => "object",
+          "required" => ["type", "parameters"],
+          "properties" => {
+            "type" => {
+              "type" => "string",
+              "enum" => ["collect", "analyze", "transform", "validate", "complete"]
+            },
+            "parameters" => {
+              "type" => "object",
+              "additionalProperties" => true
+            }
+          }
+        },
+        "reasoning" => {
+          "type" => "string",
+          "description" => "Why this action was chosen"
+        },
+        "confidence" => {
+          "type" => "number",
+          "minimum" => 0,
+          "maximum" => 1
+        },
+        "next_steps" => {
+          "type" => "array",
+          "items" => {
+            "type" => "string"
+          },
+          "minItems" => 0,
+          "maxItems" => 5
+        },
+        "risk_assessment" => {
+          "type" => "object",
+          "properties" => {
+            "level" => {
+              "type" => "string",
+              "enum" => ["low", "medium", "high"]
+            },
+            "factors" => {
+              "type" => "array",
+              "items" => { "type" => "string" }
+            }
+          }
+        }
+      }
+    }
+  end
+
+  def execute_workflow(goal:)
+    puts "🚀 Starting multi-step workflow"
+    puts "Goal: #{goal}\n\n"
+
+    max_steps = 10
+    step_count = 0
+
+    loop do
+      step_count += 1
+      break if step_count > max_steps
+
+      puts "─" * 60
+      puts "Step #{step_count}/#{max_steps}"
+      puts "─" * 60
+
+      context = build_context(goal: goal)
+
+      begin
+        decision = @client.generate(
+          prompt: build_prompt(goal: goal, context: context),
+          schema: @decision_schema
+        )
+
+        # Validate confidence threshold
+        if decision["confidence"] < 0.5
+          puts "⚠️  Low confidence (#{(decision["confidence"] * 100).round}%) - requesting manual review"
+          break
+        end
+
+        display_decision(decision)
+        result = execute_action(decision)
+
+        # Update state
+        @state[:steps_completed] << {
+          step: decision["step"],
+          action: decision["action"]["type"],
+          result: result
+        }
+
+        # Check if workflow is complete
+        if decision["action"]["type"] == "complete"
+          puts "\n✅ Workflow completed successfully!"
+          break
+        end
+
+        # Handle risk
+        if decision["risk_assessment"] && decision["risk_assessment"]["level"] == "high"
+          puts "⚠️  High risk detected - proceeding with caution"
+        end
+      rescue Ollama::SchemaViolationError => e
+        puts "❌ Schema violation: #{e.message}"
+        @state[:errors] << { step: step_count, error: "schema_violation", message: e.message }
+        break
+      rescue Ollama::RetryExhaustedError => e
+        puts "❌ Retries exhausted: #{e.message}"
+        @state[:errors] << { step: step_count, error: "retry_exhausted", message: e.message }
+        break
+      rescue Ollama::Error => e
+        puts "❌ Error: #{e.message}"
+        @state[:errors] << { step: step_count, error: "general", message: e.message }
+        # Try to recover or break
+        break if step_count > 3 # Don't loop forever
+      end
+
+      puts
+      sleep 0.5 # Small delay for readability
+    end
+
+    display_summary
+    @state
+  end
+
+  private
+
+  def build_context(_goal:)
+    {
+      steps_completed: @state[:steps_completed].map { |s| s[:action] },
+      data_collected: @state[:data_collected].keys,
+      error_count: @state[:errors].length
+    }
+  end
+
+  def build_prompt(goal:, context:)
+    <<~PROMPT
+      Goal: #{goal}
+
+      Workflow State:
+      - Steps completed: #{context[:steps_completed].join(", ") || "none"}
+      - Data collected: #{context[:data_collected].join(", ") || "none"}
+      - Errors encountered: #{context[:error_count]}
+
+      Analyze the current state and decide the next action.
+      Consider:
+      1. What data still needs to be collected?
+      2. What analysis is needed?
+      3. What validation is required?
+      4. When should the workflow complete?
+
+      Provide a structured decision with high confidence (>0.7) if possible.
+    PROMPT
+  end
+
+  def display_decision(decision)
+    puts "\n📋 Decision:"
+    puts "   Step: #{decision['step']}"
+    puts "   Action: #{decision['action']['type']}"
+    puts "   Reasoning: #{decision['reasoning']}"
+    puts "   Confidence: #{(decision['confidence'] * 100).round}%"
+    if decision["risk_assessment"]
+      puts "   Risk Level: #{decision['risk_assessment']['level']}"
+      if decision["risk_assessment"]["factors"]
+        puts "   Risk Factors: #{decision['risk_assessment']['factors'].join(', ')}"
+      end
+    end
+    return unless decision["next_steps"] && !decision["next_steps"].empty?
+
+    puts "   Next Steps: #{decision['next_steps'].join(' → ')}"
+  end
+
+  def execute_action(decision)
+    action_type = decision["action"]["type"]
+    params = decision["action"]["parameters"] || {}
+
+    case action_type
+    when "collect"
+      data_key = params["data_type"] || "unknown"
+      puts "   📥 Collecting: #{data_key}"
+      @state[:data_collected][data_key] = "collected_at_#{Time.now.to_i}"
+      { status: "collected", key: data_key }
+
+    when "analyze"
+      target = params["target"] || "data"
+      puts "   🔍 Analyzing: #{target}"
+      { status: "analyzed", target: target, insights: "analysis_complete" }
+
+    when "transform"
+      transformation = params["type"] || "default"
+      puts "   🔄 Transforming: #{transformation}"
+      { status: "transformed", type: transformation }
+
+    when "validate"
+      validation_type = params["type"] || "general"
+      puts "   ✓ Validating: #{validation_type}"
+      { status: "validated", type: validation_type }
+
+    when "complete"
+      puts "   ✅ Completing workflow"
+      { status: "complete" }
+
+    else
+      { status: "unknown_action" }
+    end
+  end
+
+  def display_summary
+    puts "\n" + "=" * 60
+    puts "Workflow Summary"
+    puts "=" * 60
+    puts "Steps completed: #{@state[:steps_completed].length}"
+    puts "Data collected: #{@state[:data_collected].keys.join(', ') || 'none'}"
+    puts "Errors: #{@state[:errors].length}"
+    return unless @state[:errors].any?
+
+    puts "\nErrors:"
+    @state[:errors].each do |error|
+      puts "  Step #{error[:step]}: #{error[:error]} - #{error[:message]}"
+    end
+  end
+end
+
+# Run example
+if __FILE__ == $PROGRAM_NAME
+  # Use longer timeout for multi-step workflows
+  config = Ollama::Config.new
+  config.timeout = 60 # 60 seconds for complex operations
+  client = Ollama::Client.new(config: config)
+
+  agent = MultiStepAgent.new(client: client)
+  agent.execute_workflow(
+    goal: "Collect user data, analyze patterns, validate results, and generate report"
+  )
+end
+