ollama-client 0.2.0

data/examples/advanced_performance_testing.rb

@@ -0,0 +1,186 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Advanced Example: Performance Testing and Observability
+# Demonstrates: Latency measurement, throughput testing, error rate tracking, concurrent requests
+
+require "json"
+require "benchmark"
+require "time"
+require_relative "../lib/ollama_client"
+
+class PerformanceMonitor
+  def initialize(client:)
+    @client = client
+    @metrics = {
+      calls: [],
+      errors: [],
+      latencies: []
+    }
+  end
+
+  def measure_call(prompt:, schema:)
+    start_time = Time.now
+
+    begin
+      result = @client.generate(prompt: prompt, schema: schema)
+      latency = (Time.now - start_time) * 1000 # Convert to milliseconds
+
+      @metrics[:calls] << {
+        success: true,
+        latency_ms: latency,
+        timestamp: Time.now.iso8601
+      }
+      @metrics[:latencies] << latency
+
+      { success: true, result: result, latency_ms: latency }
+    rescue Ollama::Error => e
+      latency = (Time.now - start_time) * 1000
+      @metrics[:calls] << {
+        success: false,
+        latency_ms: latency,
+        error: e.class.name,
+        timestamp: Time.now.iso8601
+      }
+      @metrics[:errors] << { error: e.class.name, message: e.message, latency_ms: latency }
+
+      { success: false, error: e, latency_ms: latency }
+    end
+  end
+
+  def run_throughput_test(prompt:, schema:, iterations: 10)
+    puts "🚀 Running throughput test (#{iterations} iterations)..."
+    results = []
+
+    total_time = Benchmark.realtime do
+      iterations.times do |i|
+        print "  #{i + 1}/#{iterations}... "
+        result = measure_call(prompt: prompt, schema: schema)
+        results << result
+        puts result[:success] ? "✓" : "✗"
+      end
+    end
+
+    {
+      total_time: total_time,
+      iterations: iterations,
+      throughput: iterations / total_time,
+      results: results
+    }
+  end
+
+  def run_latency_test(prompt:, schema:, iterations: 10)
+    puts "⏱️  Running latency test (#{iterations} iterations)..."
+    latencies = []
+
+    iterations.times do |i|
+      print "  #{i + 1}/#{iterations}... "
+      result = measure_call(prompt: prompt, schema: schema)
+      if result[:success]
+        latencies << result[:latency_ms]
+        puts "#{result[:latency_ms].round(2)}ms"
+      else
+        puts "ERROR"
+      end
+    end
+
+    {
+      latencies: latencies,
+      min: latencies.min,
+      max: latencies.max,
+      avg: latencies.sum / latencies.length,
+      median: latencies.sort[latencies.length / 2],
+      p95: latencies.sort[(latencies.length * 0.95).to_i],
+      p99: latencies.sort[(latencies.length * 0.99).to_i]
+    }
+  end
+
+  def display_metrics
+    puts "\n" + "=" * 60
+    puts "Performance Metrics"
+    puts "=" * 60
+
+    total_calls = @metrics[:calls].length
+    successful = @metrics[:calls].count { |c| c[:success] }
+    failed = total_calls - successful
+
+    puts "Total calls: #{total_calls}"
+    puts "Successful: #{successful} (#{(successful.to_f / total_calls * 100).round(2)}%)"
+    puts "Failed: #{failed} (#{(failed.to_f / total_calls * 100).round(2)}%)"
+
+    if @metrics[:latencies].any?
+      latencies = @metrics[:latencies]
+      puts "\nLatency Statistics (ms):"
+      puts "  Min: #{latencies.min.round(2)}"
+      puts "  Max: #{latencies.max.round(2)}"
+      puts "  Avg: #{(latencies.sum / latencies.length).round(2)}"
+      puts "  Median: #{latencies.sort[latencies.length / 2].round(2)}"
+      puts "  P95: #{latencies.sort[(latencies.length * 0.95).to_i].round(2)}"
+      puts "  P99: #{latencies.sort[(latencies.length * 0.99).to_i].round(2)}"
+    end
+
+    return unless @metrics[:errors].any?
+
+    puts "\nErrors by type:"
+    error_counts = @metrics[:errors].group_by { |e| e[:error] }
+    error_counts.each do |error_type, errors|
+      puts "  #{error_type}: #{errors.length}"
+    end
+  end
+
+  def export_metrics(filename: "metrics.json")
+    File.write(filename, JSON.pretty_generate(@metrics))
+    puts "\n📊 Metrics exported to #{filename}"
+  end
+end
+
+# Run performance tests
+if __FILE__ == $PROGRAM_NAME
+  # Use longer timeout for performance testing
+  config = Ollama::Config.new
+  config.timeout = 60 # 60 seconds for complex operations
+  client = Ollama::Client.new(config: config)
+  monitor = PerformanceMonitor.new(client: client)
+
+  schema = {
+    "type" => "object",
+    "required" => ["response"],
+    "properties" => {
+      "response" => { "type" => "string" }
+    }
+  }
+
+  puts "=" * 60
+  puts "Performance Testing Suite"
+  puts "=" * 60
+
+  # Test 1: Latency
+  latency_results = monitor.run_latency_test(
+    prompt: "Respond with a simple acknowledgment",
+    schema: schema,
+    iterations: 5
+  )
+
+  puts "\nLatency Results:"
+  puts "  Average: #{latency_results[:avg].round(2)}ms"
+  puts "  P95: #{latency_results[:p95].round(2)}ms"
+  puts "  P99: #{latency_results[:p99].round(2)}ms"
+
+  # Test 2: Throughput
+  throughput_results = monitor.run_throughput_test(
+    prompt: "Count to 5",
+    schema: schema,
+    iterations: 5
+  )
+
+  puts "\nThroughput Results:"
+  puts "  Total time: #{throughput_results[:total_time].round(2)}s"
+  puts "  Throughput: #{throughput_results[:throughput].round(2)} calls/sec"
+
+  # Display all metrics
+  monitor.display_metrics
+
+  # Export metrics
+  monitor.export_metrics
+end
+

data/examples/complete_workflow.rb

@@ -0,0 +1,235 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Complete example showing how to use structured outputs in a real workflow
+# This demonstrates the full cycle: schema definition -> LLM call -> using the result
+
+require "json"
+require_relative "../lib/ollama_client"
+
+# Example: Task Planning Agent
+# The LLM decides what action to take, and we execute it
+
+class TaskPlanner
+  def initialize(client:)
+    @client = client
+    @task_schema = {
+      "type" => "object",
+      "required" => ["action", "reasoning", "confidence", "next_step"],
+      "properties" => {
+        "action" => {
+          "type" => "string",
+          "description" => "The action to take",
+          "enum" => ["search", "calculate", "store", "retrieve", "finish"]
+        },
+        "reasoning" => {
+          "type" => "string",
+          "description" => "Why this action was chosen"
+        },
+        "confidence" => {
+          "type" => "number",
+          "minimum" => 0,
+          "maximum" => 1,
+          "description" => "Confidence in this decision"
+        },
+        "next_step" => {
+          "type" => "string",
+          "description" => "What to do next"
+        },
+        "parameters" => {
+          "type" => "object",
+          "description" => "Parameters needed for the action"
+        }
+      }
+    }
+  end
+
+  def plan(context:)
+    puts "🤔 Planning next action..."
+    puts "Context: #{context}\n\n"
+
+    begin
+      result = @client.generate(
+        prompt: "Given this context: #{context}\n\nDecide the next action to take.",
+        schema: @task_schema
+      )
+
+      # The result is guaranteed to match our schema
+      display_decision(result)
+      execute_action(result)
+
+      result
+    rescue Ollama::SchemaViolationError => e
+      puts "❌ Invalid response structure: #{e.message}"
+      puts "   This shouldn't happen with format parameter, but we handle it gracefully"
+      nil
+    rescue Ollama::Error => e
+      puts "❌ Error: #{e.message}"
+      nil
+    end
+  end
+
+  private
+
+  def display_decision(result)
+    puts "📋 Decision:"
+    puts "   Action: #{result['action']}"
+    puts "   Reasoning: #{result['reasoning']}"
+    puts "   Confidence: #{(result['confidence'] * 100).round}%"
+    puts "   Next Step: #{result['next_step']}"
+    puts "   Parameters: #{JSON.pretty_generate(result['parameters'] || {})}\n"
+  end
+
+  def execute_action(result)
+    case result["action"]
+    when "search"
+      query = result.dig("parameters", "query") || "default"
+      puts "🔍 Executing search: #{query}"
+      # In real code, you'd call your search function here
+      puts "   → Search results would appear here\n"
+
+    when "calculate"
+      operation = result.dig("parameters", "operation") || "unknown"
+      puts "🧮 Executing calculation: #{operation}"
+      # In real code, you'd call your calculator here
+      puts "   → Calculation result would appear here\n"
+
+    when "store"
+      key = result.dig("parameters", "key") || "unknown"
+      puts "💾 Storing data with key: #{key}"
+      # In real code, you'd save to your storage
+      puts "   → Data stored successfully\n"
+
+    when "retrieve"
+      key = result.dig("parameters", "key") || "unknown"
+      puts "📂 Retrieving data with key: #{key}"
+      # In real code, you'd fetch from your storage
+      puts "   → Data retrieved successfully\n"
+
+    when "finish"
+      puts "✅ Task complete!\n"
+
+    else
+      puts "⚠️ Unknown action: #{result['action']}\n"
+    end
+  end
+end
+
+# Example: Data Analyzer
+# The LLM analyzes data and returns structured insights
+
+class DataAnalyzer
+  def initialize(client:)
+    @client = client
+    @analysis_schema = {
+      "type" => "object",
+      "required" => ["summary", "confidence", "key_points"],
+      "properties" => {
+        "summary" => {
+          "type" => "string",
+          "description" => "Brief summary of the analysis"
+        },
+        "confidence" => {
+          "type" => "number",
+          "minimum" => 0,
+          "maximum" => 1
+        },
+        "key_points" => {
+          "type" => "array",
+          "items" => { "type" => "string" },
+          "minItems" => 1,
+          "maxItems" => 5
+        },
+        "sentiment" => {
+          "type" => "string",
+          "enum" => ["positive", "neutral", "negative"]
+        },
+        "recommendations" => {
+          "type" => "array",
+          "items" => { "type" => "string" }
+        }
+      }
+    }
+  end
+
+  def analyze(data:)
+    puts "📊 Analyzing data..."
+    puts "Data: #{data}\n\n"
+
+    begin
+      result = @client.generate(
+        prompt: "Analyze this data and provide insights: #{data}",
+        schema: @analysis_schema
+      )
+
+      display_analysis(result)
+      make_recommendations(result)
+
+      result
+    rescue Ollama::Error => e
+      puts "❌ Error: #{e.message}"
+      nil
+    end
+  end
+
+  private
+
+  def display_analysis(result)
+    puts "📈 Analysis Results:"
+    puts "   Summary: #{result['summary']}"
+    puts "   Confidence: #{(result['confidence'] * 100).round}%"
+    puts "   Sentiment: #{result['sentiment']}"
+    puts "\n   Key Points:"
+    result["key_points"].each_with_index do |point, i|
+      puts "     #{i + 1}. #{point}"
+    end
+
+    if result["recommendations"] && !result["recommendations"].empty?
+      puts "\n   Recommendations:"
+      result["recommendations"].each_with_index do |rec, i|
+        puts "     #{i + 1}. #{rec}"
+      end
+    end
+    puts
+  end
+
+  def make_recommendations(result)
+    if result["confidence"] > 0.8 && result["sentiment"] == "positive"
+      puts "✅ High confidence positive analysis - safe to proceed"
+    elsif result["confidence"] < 0.5
+      puts "⚠️ Low confidence - manual review recommended"
+    elsif result["sentiment"] == "negative"
+      puts "⚠️ Negative sentiment detected - investigate further"
+    end
+    puts
+  end
+end
+
+# Main execution
+if __FILE__ == $PROGRAM_NAME
+  client = Ollama::Client.new
+
+  puts "=" * 60
+  puts "Example 1: Task Planning Agent"
+  puts "=" * 60
+  puts
+
+  planner = TaskPlanner.new(client: client)
+  planner.plan(context: "User wants to know the weather in Paris")
+
+  puts "\n" + "=" * 60
+  puts "Example 2: Data Analysis"
+  puts "=" * 60
+  puts
+
+  analyzer = DataAnalyzer.new(client: client)
+  analyzer.analyze(
+    data: "Sales increased 25% this quarter. Customer satisfaction is at 4.8/5. " \
+          "Revenue: $1.2M. New customers: 150."
+  )
+
+  puts "=" * 60
+  puts "Examples complete!"
+  puts "=" * 60
+end
+