ollama-client 0.2.1 → 0.2.3

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/dhan_console

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../examples/dhan_console"

data/exe/ollama-client

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

data/lib/ollama/agent/executor.rb

@@ -72,8 +72,12 @@ module Ollama
             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
+            tool_entry = @tools[name]
+            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)
@@ -99,20 +103,58 @@ module Ollama
 
       def tool_definitions
         @tools.keys.sort.map do |name|
-          {
-            type: "function",
-            function: {
-              name: name,
-              description: "Tool: #{name}",
-              parameters: {
-                "type" => "object",
-                "additionalProperties" => true
+          tool_entry = @tools[name]
+
+          # 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|
@@ -137,12 +179,62 @@ module Ollama
       end
 
       def invoke_tool(callable, args_hash)
-        sym_args = args_hash.transform_keys { |k| k.to_s.to_sym }
+        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
 
-        # Prefer keyword invocation (common for Ruby tools), fall back to a single hash.
-        callable.call(**sym_args)
-      rescue ArgumentError
+      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)
@@ -152,6 +244,15 @@ module Ollama
       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/client.rb

@@ -6,6 +6,8 @@ require "json"
 require_relative "errors"
 require_relative "schema_validator"
 require_relative "config"
+require_relative "embeddings"
+require_relative "response"
 
 module Ollama
   # Main client class for interacting with Ollama API
@@ -16,8 +18,16 @@ module Ollama
       @uri = URI("#{@config.base_url}/api/generate")
       @chat_uri = URI("#{@config.base_url}/api/chat")
       @base_uri = URI(@config.base_url)
+      @embeddings = Embeddings.new(@config)
     end
 
+    # Access embeddings API
+    #
+    # Example:
+    #   client = Ollama::Client.new
+    #   embedding = client.embeddings.embed(model: "all-minilm", input: "What is Ruby?")
+    attr_reader :embeddings
+
     # Chat API method matching JavaScript ollama.chat() interface
     # Supports structured outputs via format parameter
     #
@@ -27,18 +37,16 @@ module Ollama
     # @param model [String] Model name (overrides config.model)
     # @param messages [Array<Hash>] Array of message hashes with :role and :content
     # @param format [Hash, nil] JSON Schema for structured outputs
+    # @param tools [Tool, Array<Tool>, Array<Hash>, nil] Tool definition(s) - can be Tool object(s) or hash(es)
     # @param options [Hash, nil] Additional options (temperature, top_p, etc.)
     # @param strict [Boolean] If true, requires explicit opt-in and disables retries on schema violations
     # @param include_meta [Boolean] If true, returns hash with :data and :meta keys
     # @return [Hash] Parsed and validated JSON response matching the format schema
     # rubocop:disable Metrics/MethodLength
     # rubocop:disable Metrics/ParameterLists
-    def chat(messages:, model: nil, format: nil, options: {}, strict: false, allow_chat: false, return_meta: false)
-      unless allow_chat || strict
-        raise Error,
-              "chat() is intentionally gated because it is easy to misuse inside agents. " \
-              "Prefer generate(). If you really want chat(), pass allow_chat: true (or strict: true)."
-      end
+    def chat(messages:, model: nil, format: nil, tools: nil, options: {}, strict: false, allow_chat: false,
+             return_meta: false)
+      ensure_chat_allowed!(allow_chat: allow_chat, strict: strict, method_name: "chat")
 
       attempts = 0
       @current_schema = format # Store for validation
@@ -47,42 +55,26 @@ module Ollama
       begin
         attempts += 1
         attempt_started_at = monotonic_time
-        raw = call_chat_api(model: model, messages: messages, format: format, tools: nil, options: options)
+        normalized_tools = normalize_tools(tools)
+        raw = call_chat_api(model: model, messages: messages, format: format, tools: normalized_tools, options: options)
         attempt_latency_ms = elapsed_ms(attempt_started_at)
 
-        emit_response_hook(
-          raw,
-          {
-            endpoint: "/api/chat",
-            model: model || @config.model,
-            attempt: attempts,
-            attempt_latency_ms: attempt_latency_ms
-          }
-        )
+        emit_response_hook(raw, chat_response_meta(model: model, attempt: attempts,
+                                                   attempt_latency_ms: attempt_latency_ms))
 
-        parsed = parse_json_response(raw)
+        empty_response = empty_chat_response(raw: raw,
+                                             return_meta: return_meta,
+                                             model: model,
+                                             attempts: attempts,
+                                             started_at: started_at)
+        return empty_response unless empty_response.nil?
 
-        # CRITICAL: If format is provided, free-text output is forbidden
-        if format
-          if parsed.nil? || parsed.empty?
-            raise SchemaViolationError,
-                  "Empty or nil response when format schema is required"
-          end
-
-          SchemaValidator.validate!(parsed, format)
-        end
+        parsed = parse_json_response(raw)
+        validate_chat_format!(parsed: parsed, format: format)
 
         return parsed unless return_meta
 
-        {
-          "data" => parsed,
-          "meta" => {
-            "endpoint" => "/api/chat",
-            "model" => model || @config.model,
-            "attempts" => attempts,
-            "latency_ms" => elapsed_ms(started_at)
-          }
-        }
+        chat_response_with_meta(data: parsed, model: model, attempts: attempts, started_at: started_at)
       rescue NotFoundError => e
         enhanced_error = enhance_not_found_error(e)
         raise enhanced_error
@@ -112,17 +104,13 @@ module Ollama
     # @param model [String] Model name (overrides config.model)
     # @param messages [Array<Hash>] Array of message hashes with :role and :content
     # @param format [Hash, nil] JSON Schema for structured outputs (validates message.content JSON when present)
-    # @param tools [Array<Hash>, nil] Tool definitions (OpenAI-style schema) sent to Ollama
+    # @param tools [Tool, Array<Tool>, Array<Hash>, nil] Tool definition(s) - can be Tool object(s) or hash(es)
     # @param options [Hash, nil] Additional options (temperature, top_p, etc.)
-    # @return [Hash] Full parsed JSON response body from Ollama
+    # @return [Hash] Full parsed JSON response body from Ollama with access to message.tool_calls
     # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/ParameterLists
     def chat_raw(messages:, model: nil, format: nil, tools: nil, options: {}, strict: false, allow_chat: false,
                  return_meta: false, stream: false, &on_chunk)
-      unless allow_chat || strict
-        raise Error,
-              "chat_raw() is intentionally gated because it is easy to misuse inside agents. " \
-              "Prefer generate(). If you really want chat_raw(), pass allow_chat: true (or strict: true)."
-      end
+      ensure_chat_allowed!(allow_chat: allow_chat, strict: strict, method_name: "chat_raw")
 
       attempts = 0
       @current_schema = format # Store for validation
@@ -131,18 +119,20 @@ module Ollama
       begin
         attempts += 1
         attempt_started_at = monotonic_time
+        normalized_tools = normalize_tools(tools)
         raw_body =
           if stream
             call_chat_api_raw_stream(
               model: model,
               messages: messages,
               format: format,
-              tools: tools,
+              tools: normalized_tools,
               options: options,
               &on_chunk
             )
           else
-            call_chat_api_raw(model: model, messages: messages, format: format, tools: tools, options: options)
+            call_chat_api_raw(model: model, messages: messages, format: format, tools: normalized_tools,
+                              options: options)
           end
         attempt_latency_ms = elapsed_ms(attempt_started_at)
 
@@ -176,10 +166,13 @@ module Ollama
           SchemaValidator.validate!(parsed_content, format)
         end
 
-        return parsed_body unless return_meta
+        # Wrap in Response object for method access (e.g., response.message&.tool_calls)
+        response_obj = Response.new(parsed_body)
+
+        return response_obj unless return_meta
 
         {
-          "data" => parsed_body,
+          "data" => response_obj,
           "meta" => {
             "endpoint" => "/api/chat",
             "model" => model || @config.model,
@@ -213,7 +206,7 @@ module Ollama
     end
     # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/ParameterLists
 
-    def generate(prompt:, schema:, strict: false, return_meta: false)
+    def generate(prompt:, schema:, model: nil, strict: false, return_meta: false)
       attempts = 0
       @current_schema = schema # Store for prompt enhancement
       started_at = monotonic_time
@@ -221,14 +214,14 @@ module Ollama
       begin
         attempts += 1
         attempt_started_at = monotonic_time
-        raw = call_api(prompt)
+        raw = call_api(prompt, model: model)
         attempt_latency_ms = elapsed_ms(attempt_started_at)
 
         emit_response_hook(
           raw,
           {
             endpoint: "/api/generate",
-            model: @config.model,
+            model: model || @config.model,
             attempt: attempts,
             attempt_latency_ms: attempt_latency_ms
           }
@@ -246,7 +239,7 @@ module Ollama
           "data" => parsed,
           "meta" => {
             "endpoint" => "/api/generate",
-            "model" => @config.model,
+            "model" => model || @config.model,
             "attempts" => attempts,
             "latency_ms" => elapsed_ms(started_at)
           }
@@ -274,8 +267,8 @@ module Ollama
     end
     # rubocop:enable Metrics/MethodLength
 
-    def generate_strict!(prompt:, schema:, return_meta: false)
-      generate(prompt: prompt, schema: schema, strict: true, return_meta: return_meta)
+    def generate_strict!(prompt:, schema:, model: nil, return_meta: false)
+      generate(prompt: prompt, schema: schema, model: model, strict: true, return_meta: return_meta)
     end
 
     # Lightweight server health check.
@@ -355,6 +348,75 @@ module Ollama
 
     private
 
+    def ensure_chat_allowed!(allow_chat:, strict:, method_name:)
+      return if allow_chat || strict
+
+      raise Error,
+            "#{method_name}() is intentionally gated because it is easy to misuse inside agents. " \
+            "Prefer generate(). If you really want #{method_name}(), pass allow_chat: true (or strict: true)."
+    end
+
+    # Normalize tools to array of hashes for API
+    # Supports: Tool object, Array of Tool objects, Array of hashes, or nil
+    def normalize_tools(tools)
+      return nil if tools.nil?
+
+      # Single Tool object
+      return [tools.to_h] if tools.is_a?(Tool)
+
+      # Array of tools
+      if tools.is_a?(Array)
+        return tools.map { |t| t.is_a?(Tool) ? t.to_h : t }
+      end
+
+      # Already a hash (shouldn't happen, but handle gracefully)
+      tools
+    end
+
+    def chat_response_meta(model:, attempt:, attempt_latency_ms:)
+      {
+        endpoint: "/api/chat",
+        model: model || @config.model,
+        attempt: attempt,
+        attempt_latency_ms: attempt_latency_ms
+      }
+    end
+
+    def empty_chat_response(raw:, return_meta:, model:, attempts:, started_at:)
+      return nil unless raw.nil? || raw.empty?
+      return "" unless return_meta
+
+      {
+        "data" => "",
+        "meta" => {
+          "endpoint" => "/api/chat",
+          "model" => model || @config.model,
+          "attempts" => attempts,
+          "latency_ms" => elapsed_ms(started_at),
+          "note" => "Empty content (likely tool_calls only - use chat_raw() to access tool_calls)"
+        }
+      }
+    end
+
+    def validate_chat_format!(parsed:, format:)
+      return unless format
+      raise SchemaViolationError, "Empty or nil response when format schema is required" if parsed.nil? || parsed.empty?
+
+      SchemaValidator.validate!(parsed, format)
+    end
+
+    def chat_response_with_meta(data:, model:, attempts:, started_at:)
+      {
+        "data" => data,
+        "meta" => {
+          "endpoint" => "/api/chat",
+          "model" => model || @config.model,
+          "attempts" => attempts,
+          "latency_ms" => elapsed_ms(started_at)
+        }
+      }
+    end
+
     def handle_http_error(res, requested_model: nil)
       status_code = res.code.to_i
       requested_model ||= @config.model
@@ -577,13 +639,13 @@ module Ollama
       raise Error, "Connection failed: #{e.message}"
     end
 
-    def call_api(prompt)
+    def call_api(prompt, model: nil)
       req = Net::HTTP::Post.new(@uri)
       req["Content-Type"] = "application/json"
 
       # Build request body
       body = {
-        model: @config.model,
+        model: model || @config.model,
         prompt: prompt,
         stream: false,
         temperature: @config.temperature,
@@ -607,7 +669,7 @@ module Ollama
         open_timeout: @config.timeout
       ) { |http| http.request(req) }
 
-      handle_http_error(res) unless res.is_a?(Net::HTTPSuccess)
+      handle_http_error(res, requested_model: model || @config.model) unless res.is_a?(Net::HTTPSuccess)
 
       body = JSON.parse(res.body)
       body["response"]
@@ -659,6 +721,7 @@ module Ollama
 
     # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity, Metrics/BlockLength
     def call_chat_api_raw_stream(model:, messages:, format:, tools:, options:)
+      # tools should already be normalized by caller
       req = Net::HTTP::Post.new(@chat_uri)
       req["Content-Type"] = "application/json"
 

data/lib/ollama/config.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "json"
+
 module Ollama
   # Configuration class with safe defaults for agent-grade usage
   #
@@ -25,5 +27,39 @@ module Ollama
       @num_ctx = 8192
       @on_response = nil
     end
+
+    # Load configuration from JSON file (useful for production deployments)
+    #
+    # @param path [String] Path to JSON config file
+    # @return [Config] New Config instance
+    #
+    # Example JSON:
+    #   {
+    #     "base_url": "http://localhost:11434",
+    #     "model": "llama3.1:8b",
+    #     "timeout": 30,
+    #     "retries": 3,
+    #     "temperature": 0.2,
+    #     "top_p": 0.9,
+    #     "num_ctx": 8192
+    #   }
+    def self.load_from_json(path)
+      data = JSON.parse(File.read(path))
+      config = new
+
+      config.base_url = data["base_url"] if data.key?("base_url")
+      config.model = data["model"] if data.key?("model")
+      config.timeout = data["timeout"] if data.key?("timeout")
+      config.retries = data["retries"] if data.key?("retries")
+      config.temperature = data["temperature"] if data.key?("temperature")
+      config.top_p = data["top_p"] if data.key?("top_p")
+      config.num_ctx = data["num_ctx"] if data.key?("num_ctx")
+
+      config
+    rescue JSON::ParserError => e
+      raise Error, "Failed to parse config JSON: #{e.message}"
+    rescue Errno::ENOENT
+      raise Error, "Config file not found: #{path}"
+    end
   end
 end