ollama-client 0.2.1 → 0.2.3

data/lib/ollama/dto.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+require "json"
+require "set"
+
+module Ollama
+  # A module that provides a foundation for data transfer objects (DTOs) within
+  # the Ollama library.
+  #
+  # The DTO module includes common functionality for converting objects to and
+  # from JSON, handling attribute management, and providing utility methods for
+  # processing arrays and hashes. It serves as a base for various command
+  # and data structures used in communicating with the Ollama API.
+  #
+  # @example Using DTO functionality in a command class
+  #   class MyCommand
+  #     include Ollama::DTO
+  #     attr_reader :name, :value
+  #     def initialize(name:, value:)
+  #       @name, @value = name, value
+  #     end
+  #   end
+  module DTO
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.instance_variable_set(:@attributes, Set.new)
+    end
+
+    # Class-level helpers for DTO attribute tracking.
+    module ClassMethods
+      # The attributes accessor reads and writes the attributes instance variable.
+      #
+      # @return [Set] the set of attributes stored in the instance variable
+      def attributes
+        @attributes ||= Set.new
+      end
+
+      def attributes=(value)
+        @attributes = value
+      end
+
+      # The from_hash method creates a new instance of the class by converting a
+      # hash into keyword arguments.
+      #
+      # This method is typically used to instantiate objects from JSON data or
+      # other hash-based sources, transforming the hash keys to symbols and
+      # passing them as keyword arguments to the constructor.
+      #
+      # @param hash [Hash] a hash containing the attributes for the new instance
+      # @return [self] a new instance of the class initialized with the hash data
+      def from_hash(hash)
+        new(**hash.transform_keys(&:to_sym))
+      end
+
+      # The attr_reader method extends the functionality of the standard
+      # attr_reader by also registering the declared attributes in the class's
+      # attributes set.
+      #
+      # @param names [Array<Symbol>] one or more attribute names to be declared
+      #   as readable and registered
+      def attr_reader(*names)
+        super
+        attributes.merge(names.map(&:to_sym))
+      end
+
+      # The attr_accessor method extends the functionality of the standard
+      # attr_accessor by also registering the declared attributes in the class's
+      # attributes set.
+      #
+      # @param names [Array<Symbol>] one or more attribute names to be declared
+      #   as readable and registered
+      def attr_accessor(*names)
+        super
+        attributes.merge(names.map(&:to_sym))
+      end
+    end
+
+    # The as_array_of_hashes method converts an object into an array of hashes.
+    #
+    # If the object responds to to_hash, it wraps the result in an array.
+    # If the object responds to to_ary, it maps each element to a hash and
+    # returns the resulting array.
+    #
+    # @param obj [Object] the object to be converted
+    # @return [Array<Hash>, nil] an array of hashes if the conversion was
+    #   possible, or nil otherwise
+    def as_array_of_hashes(obj)
+      if obj.respond_to?(:to_hash)
+        [obj.to_hash]
+      elsif obj.respond_to?(:to_ary)
+        obj.to_ary.map(&:to_hash)
+      end
+    end
+
+    # The as_hash method converts an object to a hash representation.
+    #
+    # If the object responds to to_hash, it returns the result of that method call.
+    # If the object does not respond to to_hash, it returns nil.
+    #
+    # @param obj [Object] the object to be converted to a hash
+    # @return [Hash, nil] the hash representation of the object or nil if the
+    #   object does not respond to to_hash
+    def as_hash(obj)
+      obj&.to_hash
+    end
+
+    # The as_array method converts an object into an array representation.
+    #
+    # If the object is nil, it returns nil.
+    # If the object responds to to_ary, it calls to_ary and returns the result.
+    # Otherwise, it wraps the object in an array and returns it.
+    #
+    # @param obj [Object] the object to be converted to an array
+    # @return [Array, nil] an array containing the object or its elements, or
+    #   nil if the input is nil
+    def as_array(obj)
+      if obj.nil?
+        obj
+      elsif obj.respond_to?(:to_ary)
+        obj.to_ary
+      else
+        [obj]
+      end
+    end
+
+    # The as_json method converts the object's attributes into a JSON-compatible
+    # hash.
+    #
+    # This method gathers all defined attributes of the object and constructs a
+    # hash representation, excluding any nil values or empty collections.
+    #
+    # @param _ignored [Array] ignored arguments
+    # @return [Hash] a hash containing the object's non-nil and non-empty attributes
+    def as_json(*_ignored)
+      self.class.attributes.each_with_object({}) do |attr, hash|
+        value = send(attr)
+        next if value.nil?
+
+        # Check if it's an empty collection (responds to size and size is 0)
+        next if value.respond_to?(:size) && value.empty?
+
+        hash[attr] = value
+      end
+    end
+
+    # The == method compares two objects for equality based on their JSON representation.
+    #
+    # This method checks if the JSON representation of the current object is
+    # equal to the JSON representation of another object.
+    #
+    # @param other [Object] the object to compare against
+    # @return [TrueClass, FalseClass] true if both objects have identical JSON
+    #   representations, false otherwise
+    def ==(other)
+      return false unless other.is_a?(self.class)
+
+      as_json == other.as_json
+    end
+
+    alias to_hash as_json
+
+    # The empty? method checks whether the object has any attributes defined.
+    #
+    # This method determines if the object contains no attributes by checking
+    # if its hash representation is empty. It is typically used to verify
+    # if an object, such as a DTO, has been initialized with any values.
+    #
+    # @return [TrueClass, FalseClass] true if the object has no attributes,
+    #   false otherwise
+    def empty?
+      to_hash.empty?
+    end
+
+    # The to_json method converts the object's JSON representation into a JSON
+    # string format.
+    #
+    # This method utilizes the object's existing as_json representation and
+    # applies the standard JSON serialization to produce a formatted JSON string
+    # output.
+    #
+    # @param args [Array] pass-through args
+    # @return [String] a JSON string representation of the object
+    def to_json(*args)
+      as_json.to_json(*args)
+    end
+  end
+end

data/lib/ollama/embeddings.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+require_relative "errors"
+
+module Ollama
+  # Embeddings API helper for semantic search and RAG in agents
+  #
+  # This is a helper module used internally by Client.
+  # Use client.embeddings.embed() instead of instantiating this directly.
+  class Embeddings
+    def initialize(config)
+      @config = config
+    end
+
+    # Generate embeddings for text input(s)
+    #
+    # @param model [String] Embedding model name (e.g., "all-minilm")
+    # @param input [String, Array<String>] Single text or array of texts
+    # @return [Array<Float>, Array<Array<Float>>] Embedding vector(s)
+    def embed(model:, input:)
+      uri = URI("#{@config.base_url}/api/embeddings")
+      req = Net::HTTP::Post.new(uri)
+      req["Content-Type"] = "application/json"
+
+      body = {
+        model: model,
+        input: input
+      }
+
+      req.body = body.to_json
+
+      res = Net::HTTP.start(
+        uri.hostname,
+        uri.port,
+        read_timeout: @config.timeout,
+        open_timeout: @config.timeout
+      ) { |http| http.request(req) }
+
+      handle_http_error(res, requested_model: model) unless res.is_a?(Net::HTTPSuccess)
+
+      response_body = JSON.parse(res.body)
+      embedding = response_body["embedding"]
+
+      # Return single array for single input, or array of arrays for multiple inputs
+      if input.is_a?(Array)
+        # Ollama returns single embedding array even for multiple inputs
+        # We need to check the response structure
+        if embedding.is_a?(Array) && embedding.first.is_a?(Array)
+          embedding
+        else
+          # Single embedding returned, wrap it
+          [embedding]
+        end
+      else
+        embedding
+      end
+    rescue JSON::ParserError => e
+      raise InvalidJSONError, "Failed to parse embeddings response: #{e.message}"
+    rescue Net::ReadTimeout, Net::OpenTimeout
+      raise TimeoutError, "Request timed out after #{@config.timeout}s"
+    rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH, SocketError => e
+      raise Error, "Connection failed: #{e.message}"
+    end
+
+    private
+
+    def handle_http_error(res, requested_model: nil)
+      status_code = res.code.to_i
+      raise NotFoundError.new(res.message, requested_model: requested_model) if status_code == 404
+
+      raise HTTPError.new("HTTP #{res.code}: #{res.message}", status_code)
+    end
+  end
+end

data/lib/ollama/options.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Ollama
+  # Options class for model parameters with basic type checking
+  #
+  # Provides type-safe access to Ollama model options.
+  # Useful for agents that need to adjust model behavior dynamically.
+  #
+  # Example:
+  #   options = Ollama::Options.new(temperature: 0.7, top_p: 0.95)
+  #   client.generate(prompt: "...", schema: {...}, options: options.to_h)
+  class Options
+    VALID_KEYS = %i[temperature top_p top_k num_ctx repeat_penalty seed].freeze
+
+    attr_reader :temperature, :top_p, :top_k, :num_ctx, :repeat_penalty, :seed
+
+    def initialize(**options)
+      unknown_keys = options.keys - VALID_KEYS
+      raise ArgumentError, "Unknown options: #{unknown_keys.join(", ")}" if unknown_keys.any?
+
+      VALID_KEYS.each do |key|
+        assign_option(key, options[key])
+      end
+    end
+
+    def temperature=(value)
+      validate_numeric_range(value, 0.0, 2.0, "temperature")
+      @temperature = value
+    end
+
+    def top_p=(value)
+      validate_numeric_range(value, 0.0, 1.0, "top_p")
+      @top_p = value
+    end
+
+    def top_k=(value)
+      validate_integer_min(value, 1, "top_k")
+      @top_k = value
+    end
+
+    def num_ctx=(value)
+      validate_integer_min(value, 1, "num_ctx")
+      @num_ctx = value
+    end
+
+    def repeat_penalty=(value)
+      validate_numeric_range(value, 0.0, 2.0, "repeat_penalty")
+      @repeat_penalty = value
+    end
+
+    def seed=(value)
+      validate_integer(value, "seed")
+      @seed = value
+    end
+
+    # Convert to hash for API calls
+    def to_h
+      hash = {}
+      hash[:temperature] = @temperature if @temperature
+      hash[:top_p] = @top_p if @top_p
+      hash[:top_k] = @top_k if @top_k
+      hash[:num_ctx] = @num_ctx if @num_ctx
+      hash[:repeat_penalty] = @repeat_penalty if @repeat_penalty
+      hash[:seed] = @seed if @seed
+      hash
+    end
+
+    private
+
+    def assign_option(name, value)
+      return if value.nil?
+
+      public_send("#{name}=", value)
+    end
+
+    def validate_numeric_range(value, min, max, name)
+      return if value.nil?
+
+      raise ArgumentError, "#{name} must be numeric, got #{value.class}" unless value.is_a?(Numeric)
+
+      return if value.between?(min, max)
+
+      raise ArgumentError, "#{name} must be between #{min} and #{max}, got #{value}"
+    end
+
+    def validate_integer_min(value, min, name)
+      return if value.nil?
+
+      raise ArgumentError, "#{name} must be an integer, got #{value.class}" unless value.is_a?(Integer)
+
+      return if value >= min
+
+      raise ArgumentError, "#{name} must be >= #{min}, got #{value}"
+    end
+
+    def validate_integer(value, name)
+      return if value.nil?
+
+      return if value.is_a?(Integer)
+
+      raise ArgumentError, "#{name} must be an integer, got #{value.class}"
+    end
+  end
+end

data/lib/ollama/response.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ollama
+  # Response wrapper for chat_raw() that provides method access to response data
+  #
+  # Example:
+  #   response = client.chat_raw(...)
+  #   response.message&.tool_calls  # Access tool_calls
+  #   response.message&.content     # Access content
+  class Response
+    def initialize(data)
+      @data = data
+    end
+
+    # Access the message object
+    def message
+      msg = @data["message"] || @data[:message]
+      return nil unless msg
+
+      Message.new(msg)
+    end
+
+    # Access raw data as hash
+    def to_h
+      @data
+    end
+
+    # Delegate other methods to underlying hash
+    def method_missing(method, ...)
+      return super unless @data.respond_to?(method)
+
+      @data.public_send(method, ...)
+    end
+
+    def respond_to_missing?(method, include_private = false)
+      @data.respond_to?(method, include_private) || super
+    end
+
+    # Message wrapper for accessing message fields
+    class Message
+      def initialize(data)
+        @data = data
+      end
+
+      def content
+        @data["content"] || @data[:content]
+      end
+
+      def tool_calls
+        calls = @data["tool_calls"] || @data[:tool_calls]
+        return [] unless calls
+
+        calls.map { |call| ToolCall.new(call) }
+      end
+
+      def role
+        @data["role"] || @data[:role]
+      end
+
+      def to_h
+        @data
+      end
+
+      # ToolCall wrapper for accessing tool call fields
+      class ToolCall
+        def initialize(data)
+          @data = data
+        end
+
+        def id
+          @data["id"] || @data[:id] || @data["tool_call_id"] || @data[:tool_call_id]
+        end
+
+        def function
+          func = @data["function"] || @data[:function]
+          return nil unless func
+
+          Function.new(func)
+        end
+
+        def name
+          function&.name
+        end
+
+        def arguments
+          function&.arguments
+        end
+
+        def to_h
+          @data
+        end
+
+        # Function wrapper for accessing function fields
+        class Function
+          def initialize(data)
+            @data = data
+          end
+
+          def name
+            @data["name"] || @data[:name]
+          end
+
+          def arguments
+            args = @data["arguments"] || @data[:arguments]
+            return {} unless args
+
+            args.is_a?(String) ? JSON.parse(args) : args
+          rescue JSON::ParserError
+            {}
+          end
+
+          def to_h
+            @data
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ollama/tool/function/parameters/property.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require_relative "../../../dto"
+
+module Ollama
+  # Tool, Function, and Parameters classes are defined in previous files
+  # This file adds Property class to Parameters
+  class Tool
+    class Function
+      class Parameters
+        # A single property within the parameters specification
+        #
+        # Defines an individual parameter with its type, description, and
+        # optional enumeration of valid values.
+        #
+        # Example:
+        #   property = Ollama::Tool::Function::Parameters::Property.new(
+        #     type: 'string',
+        #     description: 'The location to get weather for'
+        #   )
+        #
+        # Example with enum:
+        #   property = Ollama::Tool::Function::Parameters::Property.new(
+        #     type: 'string',
+        #     description: 'Temperature unit',
+        #     enum: %w[celsius fahrenheit]
+        #   )
+        #
+        #   # Deserialize from hash
+        #   property = Ollama::Tool::Function::Parameters::Property.from_hash({ type: 'string', ... })
+        class Property
+          include DTO
+
+          attr_reader :type, :description, :enum
+
+          def initialize(type:, description:, enum: nil)
+            @type = type.to_s
+            @description = description.to_s
+            @enum = enum ? Array(enum).map(&:to_s) : nil
+          end
+
+          # Create instance from hash
+          #
+          # @param hash [Hash] Hash with type, description, and optional enum keys
+          # @return [Property] New Property instance
+          def self.from_hash(hash)
+            normalized = hash.transform_keys(&:to_sym)
+            new(
+              type: normalized[:type] || normalized["type"],
+              description: normalized[:description] || normalized["description"],
+              enum: normalized[:enum] || normalized["enum"]
+            )
+          end
+
+          def to_h
+            hash = {
+              "type" => @type,
+              "description" => @description
+            }
+            hash["enum"] = @enum if @enum && !@enum.empty?
+            hash
+          end
+
+          # Override as_json to use explicit attributes instead of tracked ones
+          def as_json(*_ignored)
+            to_h
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ollama/tool/function/parameters.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require_relative "../../dto"
+
+module Ollama
+  # Tool and Function classes are defined in tool.rb and tool/function.rb
+  # This file adds Parameters class to Function
+  class Tool
+    # Function metadata and schema for tool calls.
+    class Function
+      # Parameters specification for a tool function
+      #
+      # Defines the structure of parameters that a function tool accepts.
+      # This matches JSON Schema format used by Ollama's tool calling API.
+      #
+      # Example:
+      #   parameters = Ollama::Tool::Function::Parameters.new(
+      #     type: 'object',
+      #     properties: {
+      #       location: Ollama::Tool::Function::Parameters::Property.new(
+      #         type: 'string',
+      #         description: 'The location to get weather for'
+      #       )
+      #     },
+      #     required: %w[location]
+      #   )
+      #
+      #   # Deserialize from hash
+      #   parameters = Ollama::Tool::Function::Parameters.from_hash({ type: 'object', ... })
+      class Parameters
+        include DTO
+
+        attr_reader :type, :properties, :required
+
+        def initialize(type:, properties: {}, required: [])
+          @type = type.to_s
+          @properties = normalize_properties(properties)
+          @required = Array(required).map(&:to_s)
+        end
+
+        # Create instance from hash
+        #
+        # @param hash [Hash] Hash with type, properties, and optional required keys
+        # @return [Parameters] New Parameters instance
+        def self.from_hash(hash)
+          normalized = hash.transform_keys(&:to_sym)
+          props_hash = normalized[:properties] || normalized["properties"] || {}
+
+          properties = props_hash.transform_values do |value|
+            case value
+            when Hash
+              Property.from_hash(value)
+            when Property
+              value
+            else
+              raise Error, "Invalid property type: #{value.class}. Use Property or Hash"
+            end
+          end
+
+          new(
+            type: normalized[:type] || normalized["type"],
+            properties: properties,
+            required: normalized[:required] || normalized["required"] || []
+          )
+        end
+
+        def to_h
+          hash = { "type" => @type }
+          hash["properties"] = @properties.transform_values(&:to_h) unless @properties.empty?
+          hash["required"] = @required unless @required.empty?
+          hash
+        end
+
+        # Override as_json to use explicit attributes instead of tracked ones
+        def as_json(*_ignored)
+          to_h
+        end
+
+        private
+
+        def normalize_properties(props)
+          return {} if props.nil? || props.empty?
+
+          props.transform_values do |value|
+            case value
+            when Property
+              value
+            when Hash
+              Property.from_hash(value)
+            else
+              raise Error, "Invalid property type: #{value.class}. Use Property or Hash"
+            end
+          end
+        end
+      end
+
+      # Load Property class after Parameters is fully defined
+      require_relative "parameters/property"
+    end
+  end
+end