ollama-client 1.3.0 → 1.4.0

data/examples/structured_tools.rb

@@ -0,0 +1,90 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example: Using Structured Tool Definitions
+# Demonstrates explicit Tool classes for type-safe tool schemas
+
+require "json"
+require_relative "../lib/ollama_client"
+require_relative "../lib/ollama/agent/executor"
+
+puts "\n=== STRUCTURED TOOLS EXAMPLE ===\n"
+
+client = Ollama::Client.new
+
+# Define tools with explicit schemas using Tool classes
+location_property = Ollama::Tool::Function::Parameters::Property.new(
+  type: "string",
+  description: "The city and state, e.g. San Francisco, CA"
+)
+
+unit_property = Ollama::Tool::Function::Parameters::Property.new(
+  type: "string",
+  description: "The unit to return temperature in",
+  enum: %w[celsius fahrenheit]
+)
+
+weather_parameters = Ollama::Tool::Function::Parameters.new(
+  type: "object",
+  properties: {
+    location: location_property,
+    unit: unit_property
+  },
+  required: %w[location unit]
+)
+
+weather_function = Ollama::Tool::Function.new(
+  name: "get_current_weather",
+  description: "Get the current weather for a location",
+  parameters: weather_parameters
+)
+
+weather_tool = Ollama::Tool.new(
+  type: "function",
+  function: weather_function
+)
+
+# Define the actual callable
+weather_callable = lambda do |location:, unit:|
+  {
+    location: location,
+    unit: unit,
+    temperature: unit == "celsius" ? "22" : "72",
+    condition: "sunny"
+  }
+end
+
+# Use structured tool definition with callable
+tools = {
+  "get_current_weather" => {
+    tool: weather_tool,
+    callable: weather_callable
+  }
+}
+
+# Alternative: Simple callable (auto-inferred schema)
+# This still works for backward compatibility - just pass the callable directly
+simple_tools = {
+  "get_time" => lambda do |timezone: "UTC"|
+    { timezone: timezone, time: Time.now.utc.iso8601 }
+  end
+}
+
+# Combine both approaches
+# Simple callables can be passed directly (auto-inferred)
+all_tools = tools.merge(simple_tools)
+
+executor = Ollama::Agent::Executor.new(client, tools: all_tools)
+
+begin
+  answer = executor.run(
+    system: "You are a helpful assistant. Use tools when needed.",
+    user: "What's the weather in Paris, France? Use celsius."
+  )
+
+  puts "\nAnswer: #{answer}"
+rescue Ollama::Error => e
+  puts "Error: #{e.message}"
+end
+
+puts "\n=== DONE ===\n"

data/examples/tool_calling_direct.rb

@@ -0,0 +1,101 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example: Direct Tool Calling (matching ollama-ruby pattern)
+# Demonstrates using Tool objects directly with chat()
+
+require "json"
+require_relative "../lib/ollama_client"
+require_relative "../lib/ollama/agent/messages"
+
+puts "\n=== DIRECT TOOL CALLING EXAMPLE ===\n"
+
+client = Ollama::Client.new
+
+# Define tool using Tool classes (matching ollama-ruby pattern)
+tool = Ollama::Tool.new(
+  type: "function",
+  function: Ollama::Tool::Function.new(
+    name: "get_current_weather",
+    description: "Get the current weather for a location",
+    parameters: Ollama::Tool::Function::Parameters.new(
+      type: "object",
+      properties: {
+        location: Ollama::Tool::Function::Parameters::Property.new(
+          type: "string",
+          description: "The location to get the weather for, e.g. San Francisco, CA"
+        ),
+        temperature_unit: Ollama::Tool::Function::Parameters::Property.new(
+          type: "string",
+          description: "The unit to return the temperature in, either 'celsius' or 'fahrenheit'",
+          enum: %w[celsius fahrenheit]
+        )
+      },
+      required: %w[location temperature_unit]
+    )
+  )
+)
+
+# Create message
+def message(location)
+  Ollama::Agent::Messages.user("What is the weather today in #{location}?")
+end
+
+puts "\n--- Using chat() to access tool_calls ---"
+
+# chat() always returns a full Ollama::Response — message.tool_calls is
+# populated whenever the model calls a tool. tools: takes an array.
+response = client.chat(
+  model: "llama3.1:8b",
+  messages: [message("The City of Love")],
+  tools: [tool]
+)
+
+# Access tool_calls from response (using method access like ollama-ruby)
+tool_calls = response.message&.tool_calls
+if tool_calls && !tool_calls.empty?
+  puts "\nTool calls detected:"
+  tool_calls.each do |call|
+    name = call.name
+    args = call.arguments
+    puts "  - #{name}: #{args}"
+  end
+else
+  puts "\nNo tool calls in response"
+  puts "Response: #{response.message&.content}"
+end
+
+# You can also use hash access if preferred:
+# tool_calls = response.to_h.dig("message", "tool_calls")
+
+puts "\n--- Multiple tools (array) ---"
+
+# You can also pass an array of tools
+tool2 = Ollama::Tool.new(
+  type: "function",
+  function: Ollama::Tool::Function.new(
+    name: "get_time",
+    description: "Get the current time",
+    parameters: Ollama::Tool::Function::Parameters.new(
+      type: "object",
+      properties: {},
+      required: []
+    )
+  )
+)
+
+response2 = client.chat(
+  model: "llama3.1:8b",
+  messages: [Ollama::Agent::Messages.user("What time is it? Use the get_time tool.")],
+  tools: [tool, tool2] # Array of Tool objects
+)
+
+tool_calls2 = response2.message&.tool_calls
+if tool_calls2 && !tool_calls2.empty?
+  puts "\nTool calls from multiple tools:"
+  tool_calls2.each do |call|
+    puts "  - #{call.name}"
+  end
+end
+
+puts "\n=== DONE ===\n"

data/examples/tool_dto_example.rb

@@ -0,0 +1,94 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example: Tool DTO (Data Transfer Object) functionality
+# Demonstrates serialization, deserialization, and equality
+
+require "json"
+require_relative "../lib/ollama_client"
+
+puts "\n=== TOOL DTO EXAMPLE ===\n"
+
+# Create a tool definition
+location_prop = Ollama::Tool::Function::Parameters::Property.new(
+  type: "string",
+  description: "The city name"
+)
+
+unit_prop = Ollama::Tool::Function::Parameters::Property.new(
+  type: "string",
+  description: "Temperature unit",
+  enum: %w[celsius fahrenheit]
+)
+
+params = Ollama::Tool::Function::Parameters.new(
+  type: "object",
+  properties: {
+    location: location_prop,
+    unit: unit_prop
+  },
+  required: %w[location unit]
+)
+
+function = Ollama::Tool::Function.new(
+  name: "get_weather",
+  description: "Get weather for a location",
+  parameters: params
+)
+
+tool = Ollama::Tool.new(type: "function", function: function)
+
+# 1. Serialize to JSON
+puts "\n--- Serialization ---"
+json_str = tool.to_json
+puts "JSON: #{json_str}"
+
+# 2. Deserialize from hash
+puts "\n--- Deserialization ---"
+hash = JSON.parse(json_str)
+deserialized_tool = Ollama::Tool.from_hash(hash)
+puts "Deserialized tool name: #{deserialized_tool.function.name}"
+
+# 3. Equality comparison
+puts "\n--- Equality ---"
+puts "Original == Deserialized: #{tool == deserialized_tool}"
+
+# 4. Nested deserialization
+puts "\n--- Nested Deserialization ---"
+function_hash = {
+  "name" => "get_time",
+  "description" => "Get current time",
+  "parameters" => {
+    "type" => "object",
+    "properties" => {
+      "timezone" => {
+        "type" => "string",
+        "description" => "Timezone (e.g., UTC, EST)"
+      }
+    },
+    "required" => []
+  }
+}
+
+deserialized_function = Ollama::Tool::Function.from_hash(function_hash)
+puts "Deserialized function: #{deserialized_function.name}"
+puts "Parameters type: #{deserialized_function.parameters.type}"
+
+# 5. Property deserialization
+puts "\n--- Property Deserialization ---"
+prop_hash = {
+  "type" => "string",
+  "description" => "City name",
+  "enum" => %w[paris london tokyo]
+}
+
+deserialized_prop = Ollama::Tool::Function::Parameters::Property.from_hash(prop_hash)
+puts "Property type: #{deserialized_prop.type}"
+puts "Property enum: #{deserialized_prop.enum.inspect}"
+
+# 6. Empty check
+puts "\n--- Empty Check ---"
+empty_params = Ollama::Tool::Function::Parameters.new(type: "object", properties: {}, required: [])
+puts "Empty params? #{empty_params.empty?}"
+
+puts "\n=== DONE ===\n"

data/exe/ollama-client

@@ -163,7 +163,9 @@ module OllamaCLI
   def self.build_client(model = nil)
     config = Ollama::Config.new
     config.base_url = ENV["OLLAMA_BASE_URL"] if ENV["OLLAMA_BASE_URL"]
-    config.api_key = ENV["OLLAMA_API_KEY"] if ENV["OLLAMA_API_KEY"]
+    config.api_keys = ENV.fetch("OLLAMA_API_KEYS", nil) if ENV.fetch("OLLAMA_API_KEYS", nil)
+    config.api_key = ENV.fetch("OLLAMA_API_KEY", nil) if config.api_keys.empty? && ENV.fetch("OLLAMA_API_KEY", nil)
+    config.enable_multi_key_concurrency = Ollama::Config.truthy_env?(ENV.fetch("ENABLE_MULTI_KEY_CONCURRENCY", nil))
     config.model = model if model
     Ollama::Client.new(config: config)
   end
@@ -201,6 +203,8 @@ module OllamaCLI
       Environment:
         OLLAMA_BASE_URL  Override base URL (default: http://localhost:11434)
         OLLAMA_API_KEY   Optional Bearer token for Ollama Cloud (https://ollama.com)
+        OLLAMA_API_KEYS  Optional comma-separated Bearer token pool for 429 failover
+        ENABLE_MULTI_KEY_CONCURRENCY  Set true/1 to distribute initial keys across threads
     USAGE
   end
 end

data/lib/ollama/agent/executor.rb

@@ -0,0 +1,243 @@
+# 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
+      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 = request_chat
+
+          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.map(&:to_h)) if content || !tool_calls.empty?
+          last_assistant_content = content if content && !content.empty?
+
+          break if tool_calls.empty?
+
+          tool_calls.each do |call|
+            name = call.name
+            raise Ollama::Error, "Tool call missing function name: #{call.inspect}" if name.nil? || name.empty?
+
+            args_hash = call.arguments.is_a?(Hash) ? call.arguments : {}
+
+            tool_entry = @tools[name] || @tools[name.to_sym]
+            raise Ollama::Error, "Tool '#{name}' not found. Available: #{@tools.keys.sort.join(", ")}" unless tool_entry
+
+            # Extract callable from tool entry
+            callable = extract_callable(tool_entry)
+            raise Ollama::Error, "Tool '#{name}' has no associated callable" 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
+            @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
+
+      private
+
+      def request_chat
+        hooks = streaming_hooks
+        @client.chat(messages: @messages, tools: tool_definitions, stream: !hooks.nil?, hooks: hooks || {})
+      end
+
+      def streaming_hooks
+        return nil unless @stream
+
+        {
+          on_token: lambda { |delta, _logprobs = nil|
+            @stream.emit(:token, text: delta.to_s) if delta && !delta.to_s.empty?
+          },
+          on_tool_call: lambda { |call|
+            name = dig(call, %w[function name]) || call["name"]
+            @stream.emit(:tool_call_detected, name: name, data: call) if name
+          }
+        }
+      end
+
+      def tool_definitions
+        @tools.keys.sort.map do |key|
+          name = key.to_s
+          tool_entry = @tools[key]
+
+          # Support both explicit Tool objects and callables
+          # Tool objects are schema definitions only
+          if tool_entry.is_a?(Ollama::Tool)
+            tool_entry.to_h
+          elsif tool_entry.is_a?(Hash) && tool_entry[:tool].is_a?(Ollama::Tool)
+            # Format: { tool: Tool, callable: proc }
+            tool_entry[:tool].to_h
+          else
+            # Auto-infer from callable signature (default)
+            callable = tool_entry.is_a?(Hash) ? tool_entry[:callable] : tool_entry
+            parameters = infer_parameters(callable)
+            {
+              type: "function",
+              function: {
+                name: name,
+                description: "Tool: #{name}",
+                parameters: parameters
+              }
+            }
+          end
+        end
+      end
+
+      def infer_parameters(callable)
+        return { "type" => "object", "additionalProperties" => true } unless callable.respond_to?(:parameters)
+
+        params = callable.parameters
+        return { "type" => "object", "additionalProperties" => true } if params.empty?
+
+        properties = {}
+        required = []
+
+        params.each do |type, name|
+          next unless name # Skip anonymous parameters
+
+          param_name = name.to_s
+          properties[param_name] = { "type" => "string", "description" => "Parameter: #{param_name}" }
+
+          # Required if it's a required keyword argument (:keyreq) or required positional (:req)
+          required << param_name if %i[keyreq req].include?(type)
+        end
+
+        schema = { "type" => "object" }
+        schema["properties"] = properties unless properties.empty?
+        schema["required"] = required unless required.empty?
+        schema["additionalProperties"] = false if properties.any?
+
+        schema
+      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 invoke_tool(callable, args_hash)
+        sym_args = normalize_parameter_names(args_hash)
+        keyword_result = call_with_keywords(callable, sym_args)
+        return keyword_result[:value] if keyword_result[:success]
+
+        call_with_positional(callable, args_hash)
+      end
+
+      def normalize_parameter_names(args_hash)
+        args_hash.transform_keys { |k| k.to_s.to_sym }
+      end
+
+      def apply_parameter_aliases(args, callable)
+        return args unless callable.respond_to?(:parameters)
+
+        param_names = callable.parameters.map { |_type, name| name }
+        aliased = args.dup
+
+        # Common aliases: directory -> path, file -> path, filename -> path
+        if param_names.include?(:path) && !aliased.key?(:path)
+          if aliased.key?(:directory)
+            aliased[:path] = aliased.delete(:directory)
+          elsif aliased.key?(:file)
+            aliased[:path] = aliased.delete(:file)
+          elsif aliased.key?(:filename)
+            aliased[:path] = aliased.delete(:filename)
+          end
+        end
+
+        aliased
+      end
+
+      def call_with_keywords(callable, sym_args)
+        { success: true, value: callable.call(**sym_args) }
+      rescue ArgumentError => e
+        return { success: false } unless missing_keyword_error?(e)
+
+        aliased_args = apply_parameter_aliases(sym_args, callable)
+        return { success: false } if aliased_args == sym_args
+
+        begin
+          { success: true, value: callable.call(**aliased_args) }
+        rescue ArgumentError
+          { success: false }
+        end
+      end
+
+      def call_with_positional(callable, args_hash)
+        callable.call(args_hash)
+      rescue ArgumentError => e
+        raise ArgumentError,
+              "Tool invocation failed: #{e.message}. Arguments provided: #{args_hash.inspect}. " \
+              "Ensure the tool call includes all required parameters."
+      end
+
+      def missing_keyword_error?(error)
+        error.message.include?("required keyword") || error.message.include?("missing keyword")
+      end
+
+      def encode_tool_result(result)
+        return result if result.is_a?(String)
+
+        JSON.generate(result)
+      rescue JSON::GeneratorError
+        result.to_s
+      end
+
+      def extract_callable(tool_entry)
+        case tool_entry
+        when Proc, Method
+          tool_entry
+        when Hash
+          tool_entry[:callable] || tool_entry["callable"]
+        end
+      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,45 @@
+# 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
+
+        full_prompt = "#{full_prompt}\n\nContext (JSON):\n#{JSON.pretty_generate(context)}" if context && !context.empty?
+
+        @client.generate(
+          prompt: full_prompt,
+          schema: schema || ANY_JSON_SCHEMA,
+          strict: true
+        )
+      end
+    end
+  end
+end

data/lib/ollama/api_key_pool.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Ollama
+  # Thread-safe immutable API key pool for rate-limit failover.
+  #
+  # The pool never mutates the configured key list after construction. Request
+  # state is represented as a short-lived context hash so retry counters and
+  # rotation offsets remain isolated to the caller's execution path.
+  class ApiKeyPool
+    attr_reader :keys
+
+    # @param keys [Array<String>] API keys in configured priority order
+    # @param concurrency_enabled [Boolean] whether initial keys should be distributed round-robin
+    def initialize(keys, concurrency_enabled: false)
+      @keys = keys.map(&:to_s).map(&:strip).reject(&:empty?).freeze
+      @concurrency_enabled = concurrency_enabled
+      @mutex = Mutex.new
+      @next_index = 0
+    end
+
+    # @return [Integer] number of configured keys
+    def size
+      @keys.size
+    end
+
+    # @return [Boolean] true when no keys are configured
+    def empty?
+      @keys.empty?
+    end
+
+    # Build request-local rotation context.
+    #
+    # @return [Hash] isolated context for one logical request attempt
+    def request_context
+      { start_index: initial_index }
+    end
+
+    # Resolve a key from a request-local context and rotation offset.
+    #
+    # @param context [Hash]
+    # @param offset [Integer]
+    # @return [String, nil]
+    def key_for(context, offset: 0)
+      return nil if empty?
+
+      @keys[(context.fetch(:start_index) + offset) % size]
+    end
+
+    private
+
+    def initial_index
+      return 0 unless @concurrency_enabled
+
+      @mutex.synchronize do
+        current = @next_index
+        @next_index = (@next_index + 1) % size if size.positive?
+        current
+      end
+    end
+  end
+end