ollama-client 0.2.0

data/examples/tool_calling_pattern.rb

@@ -0,0 +1,266 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example: Tool Calling Pattern (as documented in README)
+# Demonstrates the correct architecture: LLM outputs intent, agent executes tools
+# This matches the pattern shown in README.md lines 430-500
+
+require "json"
+require_relative "../lib/ollama_client"
+
+# Tool Registry - stores available tools
+class ToolRegistry
+  def initialize
+    @tools = {}
+  end
+
+  def register(name, tool)
+    @tools[name] = tool
+  end
+
+  def fetch(name)
+    @tools.fetch(name) { raise "Tool '#{name}' not found. Available: #{@tools.keys.join(', ')}" }
+  end
+
+  def available
+    @tools.keys
+  end
+end
+
+# Base Tool class
+class Tool
+  attr_reader :name, :description
+
+  def initialize(name:, description:)
+    @name = name
+    @description = description
+  end
+
+  def call(input:, context:)
+    raise NotImplementedError, "Subclass must implement #call"
+  end
+end
+
+# Example Tools
+class SearchTool < Tool
+  def initialize
+    super(name: "search", description: "Search for information")
+  end
+
+  def call(input:, context: nil) # rubocop:disable Lint/UnusedMethodArgument
+    query = input["query"] || "default"
+    # In real code, this would call your search API
+    {
+      query: query,
+      results: [
+        "Result 1 for: #{query}",
+        "Result 2 for: #{query}",
+        "Result 3 for: #{query}"
+      ],
+      count: 3
+    }
+  end
+end
+
+class CalculateTool < Tool
+  def initialize
+    super(name: "calculate", description: "Perform calculations")
+  end
+
+  def call(input:, context: nil) # rubocop:disable Lint/UnusedMethodArgument
+    operation = input["operation"] || "add"
+    a = input["a"] || 0
+    b = input["b"] || 0
+
+    result = case operation
+             when "add" then a + b
+             when "subtract" then a - b
+             when "multiply" then a * b
+             when "divide" then b.zero? ? "Error: Division by zero" : a / b
+             else "Unknown operation: #{operation}"
+             end
+
+    {
+      operation: operation,
+      operands: { a: a, b: b },
+      result: result
+    }
+  end
+end
+
+class StoreTool < Tool
+  def initialize
+    super(name: "store", description: "Store data")
+    @storage = {}
+  end
+
+  def call(input:, context: nil) # rubocop:disable Lint/UnusedMethodArgument
+    key = input["key"] || "default"
+    value = input["value"] || {}
+    @storage[key] = value
+
+    {
+      key: key,
+      stored: true,
+      message: "Data stored successfully"
+    }
+  end
+end
+
+# Tool Router - matches README example exactly
+class ToolRouter
+  def initialize(llm:, registry:)
+    @llm = llm # Ollama::Client instance
+    @registry = registry
+  end
+
+  def step(prompt:, context: {})
+    # LLM outputs intent (not execution)
+    decision = @llm.generate(
+      prompt: prompt,
+      schema: {
+        "type" => "object",
+        "required" => ["action"],
+        "properties" => {
+          "action" => { "type" => "string" },
+          "input" => { "type" => "object" }
+        }
+      }
+    )
+
+    return { done: true } if decision["action"] == "finish"
+
+    # Agent executes tool (deterministic)
+    tool = @registry.fetch(decision["action"])
+    output = tool.call(input: decision["input"] || {}, context: context)
+
+    { tool: tool.name, output: output }
+  end
+end
+
+# Example usage
+if __FILE__ == $PROGRAM_NAME
+  puts "=" * 60
+  puts "Tool Calling Pattern Example"
+  puts "=" * 60
+  puts
+
+  # Setup
+  client = Ollama::Client.new
+  registry = ToolRegistry.new
+
+  # Register tools
+  registry.register("search", SearchTool.new)
+  registry.register("calculate", CalculateTool.new)
+  registry.register("store", StoreTool.new)
+
+  # Create router
+  router = ToolRouter.new(llm: client, registry: registry)
+
+  puts "Available tools: #{registry.available.join(', ')}"
+  puts
+
+  # Example 1: Search
+  puts "─" * 60
+  puts "Example 1: Search Tool"
+  puts "─" * 60
+  begin
+    result = router.step(
+      prompt: "User wants to search for 'Ruby programming'. Use the search tool with query 'Ruby programming'.",
+      context: {}
+    )
+
+    if result[:done]
+      puts "✅ Workflow complete"
+    else
+      puts "Tool: #{result[:tool]}"
+      puts "Output: #{JSON.pretty_generate(result[:output])}"
+    end
+  rescue Ollama::Error => e
+    puts "❌ Error: #{e.message}"
+  rescue StandardError => e
+    puts "❌ Error: #{e.class}: #{e.message}"
+  end
+
+  puts
+
+  # Example 2: Calculate
+  puts "─" * 60
+  puts "Example 2: Calculate Tool"
+  puts "─" * 60
+  begin
+    result = router.step(
+      prompt: "User wants to calculate 15 * 7. Use the calculate tool with operation 'multiply', a=15, b=7.",
+      context: {}
+    )
+
+    if result[:done]
+      puts "✅ Workflow complete"
+    else
+      puts "Tool: #{result[:tool]}"
+      puts "Output: #{JSON.pretty_generate(result[:output])}"
+    end
+  rescue Ollama::Error => e
+    puts "❌ Error: #{e.message}"
+  rescue StandardError => e
+    puts "❌ Error: #{e.class}: #{e.message}"
+  end
+
+  puts
+
+  # Example 3: Store
+  puts "─" * 60
+  puts "Example 3: Store Tool"
+  puts "─" * 60
+  begin
+    result = router.step(
+      prompt: "User wants to store data with key 'user_preferences' and value {'theme': 'dark'}. Use the store tool.",
+      context: {}
+    )
+
+    if result[:done]
+      puts "✅ Workflow complete"
+    else
+      puts "Tool: #{result[:tool]}"
+      puts "Output: #{JSON.pretty_generate(result[:output])}"
+    end
+  rescue Ollama::Error => e
+    puts "❌ Error: #{e.message}"
+  rescue StandardError => e
+    puts "❌ Error: #{e.class}: #{e.message}"
+  end
+
+  puts
+
+  # Example 4: Finish
+  puts "─" * 60
+  puts "Example 4: Finish Action"
+  puts "─" * 60
+  begin
+    result = router.step(
+      prompt: "The task is complete. Use action 'finish'.",
+      context: {}
+    )
+
+    if result[:done]
+      puts "✅ Workflow complete"
+    else
+      puts "Tool: #{result[:tool]}"
+      puts "Output: #{JSON.pretty_generate(result[:output])}"
+    end
+  rescue Ollama::Error => e
+    puts "❌ Error: #{e.message}"
+  rescue StandardError => e
+    puts "❌ Error: #{e.class}: #{e.message}"
+  end
+
+  puts
+  puts "=" * 60
+  puts "Pattern demonstrated:"
+  puts "  1. LLM outputs structured intent (via ollama-client)"
+  puts "  2. Agent validates and routes to tool"
+  puts "  3. Tool executes deterministically (pure Ruby)"
+  puts "  4. Results returned to agent"
+  puts "=" * 60
+end
+

data/exe/ollama-client

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "ollama/client"

data/lib/ollama/agent/executor.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "messages"
+
+module Ollama
+  module Agent
+    # Stateful executor-style agent using /api/chat + tool-calling loop.
+    #
+    # The LLM never executes tools. It can only request tool calls; this class
+    # executes Ruby callables and feeds results back as role: "tool" messages.
+    class Executor
+      attr_reader :messages
+
+      def initialize(client, tools:, max_steps: 20, stream: nil)
+        @client = client
+        @tools = tools || {}
+        @max_steps = max_steps
+        @stream = stream
+        @messages = []
+      end
+
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity, Metrics/BlockLength
+      def run(system:, user:)
+        @messages = [
+          Messages.system(system),
+          Messages.user(user)
+        ]
+
+        last_assistant_content = nil
+
+        @max_steps.times do
+          @stream&.emit(:state, state: :assistant_streaming)
+
+          response =
+            if @stream
+              @client.chat_raw(
+                messages: @messages,
+                tools: tool_definitions,
+                allow_chat: true,
+                stream: true
+              ) do |chunk|
+                delta = chunk.dig("message", "content")
+                @stream.emit(:token, text: delta.to_s) if delta && !delta.to_s.empty?
+
+                calls = chunk.dig("message", "tool_calls")
+                if calls.is_a?(Array)
+                  calls.each do |call|
+                    name = dig(call, %w[function name]) || call["name"]
+                    @stream.emit(:tool_call_detected, name: name, data: call) if name
+                  end
+                end
+              end
+            else
+              @client.chat_raw(messages: @messages, tools: tool_definitions, allow_chat: true)
+            end
+
+          message = response["message"] || {}
+          content = message["content"]
+          tool_calls = message["tool_calls"]
+
+          # Preserve the assistant turn in history (including tool_calls if present).
+          @messages << Messages.assistant(content.to_s, tool_calls: tool_calls) if content || tool_calls
+          last_assistant_content = content if content && !content.empty?
+
+          break if tool_calls.nil? || tool_calls.empty?
+
+          tool_calls.each do |call|
+            name = dig(call, %w[function name]) || call["name"]
+            raise Ollama::Error, "Tool call missing function name: #{call.inspect}" if name.nil? || name.empty?
+
+            args = dig(call, %w[function arguments])
+            args_hash = normalize_arguments(args)
+
+            callable = @tools[name]
+            raise Ollama::Error, "Tool '#{name}' not found. Available: #{@tools.keys.sort.join(", ")}" unless callable
+
+            @stream&.emit(:state, state: :tool_executing)
+            result = invoke_tool(callable, args_hash)
+            tool_content = encode_tool_result(result)
+
+            tool_call_id = call["id"] || call["tool_call_id"]
+            @messages << Messages.tool(content: tool_content, name: name, tool_call_id: tool_call_id)
+            @stream&.emit(:state, state: :tool_result_injected)
+          end
+        end
+
+        if last_assistant_content.nil?
+          raise Ollama::Error,
+                "Executor exceeded max_steps=#{@max_steps} (possible infinite tool loop)"
+        end
+
+        @stream&.emit(:final, text: last_assistant_content.to_s)
+        last_assistant_content
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity, Metrics/BlockLength
+
+      private
+
+      def tool_definitions
+        @tools.keys.sort.map do |name|
+          {
+            type: "function",
+            function: {
+              name: name,
+              description: "Tool: #{name}",
+              parameters: {
+                "type" => "object",
+                "additionalProperties" => true
+              }
+            }
+          }
+        end
+      end
+
+      def dig(obj, path)
+        cur = obj
+        path.each do |k|
+          return nil unless cur.is_a?(Hash)
+
+          cur = cur[k] || cur[k.to_sym]
+        end
+        cur
+      end
+
+      def normalize_arguments(args)
+        return {} if args.nil? || args == ""
+        return args if args.is_a?(Hash)
+
+        if args.is_a?(String)
+          JSON.parse(args)
+        else
+          {}
+        end
+      rescue JSON::ParserError => e
+        raise Ollama::InvalidJSONError, "Failed to parse tool arguments JSON: #{e.message}. Arguments: #{args.inspect}"
+      end
+
+      def invoke_tool(callable, args_hash)
+        sym_args = args_hash.transform_keys { |k| k.to_s.to_sym }
+
+        # Prefer keyword invocation (common for Ruby tools), fall back to a single hash.
+        callable.call(**sym_args)
+      rescue ArgumentError
+        callable.call(args_hash)
+      end
+
+      def encode_tool_result(result)
+        return result if result.is_a?(String)
+
+        JSON.generate(result)
+      rescue JSON::GeneratorError
+        result.to_s
+      end
+    end
+  end
+end

data/lib/ollama/agent/messages.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Ollama
+  module Agent
+    # Small helpers for building chat message hashes.
+    module Messages
+      def self.system(content)
+        { role: "system", content: content.to_s }
+      end
+
+      def self.user(content)
+        { role: "user", content: content.to_s }
+      end
+
+      def self.assistant(content, tool_calls: nil)
+        msg = { role: "assistant", content: content.to_s }
+        msg[:tool_calls] = tool_calls if tool_calls
+        msg
+      end
+
+      # Tool results are sent back as role: "tool".
+      # Some APIs require `tool_call_id` to associate results with calls.
+      def self.tool(content:, name: nil, tool_call_id: nil)
+        msg = { role: "tool", content: content.to_s }
+        msg[:name] = name if name
+        msg[:tool_call_id] = tool_call_id if tool_call_id
+        msg
+      end
+    end
+  end
+end

data/lib/ollama/agent/planner.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "messages"
+
+module Ollama
+  module Agent
+    # Stateless planner-style agent using /api/generate.
+    #
+    # Intended for planning, classification, routing, and deterministic structured outputs.
+    class Planner
+      ANY_JSON_SCHEMA = {
+        "anyOf" => [
+          { "type" => "object", "additionalProperties" => true },
+          { "type" => "array" },
+          { "type" => "string" },
+          { "type" => "number" },
+          { "type" => "integer" },
+          { "type" => "boolean" },
+          { "type" => "null" }
+        ]
+      }.freeze
+
+      def initialize(client)
+        @client = client
+      end
+
+      # @param prompt [String]
+      # @param context [Hash, nil]
+      # @param schema [Hash, nil]
+      # @return [Object] Parsed JSON (Hash/Array/String/Number/Boolean/Nil)
+      def run(prompt:, context: nil, schema: nil)
+        full_prompt = prompt.to_s
+
+        if context && !context.empty?
+          full_prompt = "#{full_prompt}\n\nContext (JSON):\n#{JSON.pretty_generate(context)}"
+        end
+
+        @client.generate(
+          prompt: full_prompt,
+          schema: schema || ANY_JSON_SCHEMA,
+          strict: true
+        )
+      end
+    end
+  end
+end