ollama-ruby 1.4.0 → 1.6.0

data/lib/ollama/commands/pull.rb

@@ -1,18 +1,89 @@
+# The command method creates a command method for the Ollama client
+#
+# Defines a new command method that corresponds to an Ollama API endpoint. The
+# command method can be invoked with parameters and an optional handler to
+# process responses. It determines which handler to use based on whether the
+# command supports streaming and the presence of an explicit handler.
+#
+# @param name [ Symbol ] the name of the command to define
+# @param default_handler [ Class ] the default handler class to use when no explicit handler is provided
+# @param stream_handler [ Class, nil ] the handler class to use for streaming responses, if applicable
+#
+# @note Create Command `name`, if `stream` was true, set `stream_handler`
+# as default, otherwise `default_handler`.
+#
+# @return [ self ] returns the receiver after defining the command method
 class Ollama::Commands::Pull
   include Ollama::DTO
 
+  # The path method returns the API endpoint path for pull requests.
+  #
+  # This class method provides the specific URL path used to interact with the
+  # Ollama API's pull endpoint. It is utilized internally by the command
+  # structure to determine the correct API route for downloading models from a
+  # remote registry.
+  #
+  # @return [ String ] the API endpoint path '/api/pull' for pull requests
   def self.path
     '/api/pull'
   end
 
+  # The initialize method sets up a new instance with streaming enabled by default.
+  #
+  # This method is responsible for initializing a new object instance and
+  # configuring it with a default setting that enables streaming behavior.
+  # It is typically called during the object creation process to establish
+  # the initial state of the instance.
+  #
+  # @param model [ String ] the name of the model to be pushed
+  # @param insecure [ TrueClass, FalseClass, nil ] whether to allow insecure
+  #        connections, or nil to use default
+  # @param stream [ TrueClass, FalseClass ] whether to enable streaming for
+  #        the operation, defaults to true
   def initialize(model:, insecure: nil, stream: true)
     @model, @insecure, @stream = model, insecure, stream
   end
 
-  attr_reader :model, :insecure, :stream
+  # The model attribute reader returns the model name associated with the object.
+  #
+  # @return [ String ] the name of the model used by the command instance
+  attr_reader :model
 
+  # The insecure attribute reader returns the insecure connection setting
+  # associated with the object.
+  #
+  # @return [ TrueClass, FalseClass, nil ] the insecure flag indicating whether
+  #         insecure connections are allowed, or nil if not set
+  attr_reader :insecure
+
+  # The stream attribute reader returns the streaming behavior setting
+  # associated with the object.
+  #
+  # @return [ TrueClass, FalseClass ] the streaming behavior flag, indicating
+  #         whether streaming is enabled for the command execution
+  attr_reader :stream
+
+  # The client attribute writer allows setting the client instance associated
+  # with the object.
+  #
+  # This method assigns the client that will be used to perform requests and
+  # handle responses for this command. It is typically called internally when a
+  # command is executed through a client instance.
+  #
+  # @attr_writer [ Ollama::Client ] the assigned client instance
   attr_writer :client
 
+  # The perform method executes a command request using the specified handler.
+  #
+  # This method initiates a request to the Ollama API endpoint associated with
+  # the command, utilizing the client instance to send the request and process
+  # responses through the provided handler. It handles both streaming and
+  # non-streaming scenarios based on the command's configuration.
+  #
+  # @param handler [ Ollama::Handler ] the handler object responsible for processing API
+  # responses
+  #
+  # @return [ self ] returns the current instance after initiating the request
   def perform(handler)
     @client.request(method: :post, path: self.class.path, body: to_json, stream:, handler:)
   end

data/lib/ollama/commands/push.rb

@@ -1,18 +1,82 @@
+# A command class that represents the push API endpoint for Ollama.
+#
+# This class is used to interact with the Ollama API's push endpoint, which
+# uploads a model to a remote registry. It inherits from the base command
+# structure and provides the necessary functionality to execute push requests
+# for model deployment.
+#
+# @example Pushing a model to a remote registry
+#   push = ollama.push(model: 'user/llama3.1')
 class Ollama::Commands::Push
   include Ollama::DTO
 
+  # The path method returns the API endpoint path for push requests.
+  #
+  # This class method provides the specific URL path used to interact with the
+  # Ollama API's push endpoint. It is utilized internally by the command
+  # structure to determine the correct API route for uploading models to a
+  # remote registry.
+  #
+  # @return [ String ] the API endpoint path '/api/push' for push requests
   def self.path
     '/api/push'
   end
 
+  # The initialize method sets up a new instance with streaming enabled by default.
+  #
+  # This method is responsible for initializing a new object instance and
+  # configuring it with a default setting that enables streaming behavior.
+  # It is typically called during the object creation process to establish
+  # the initial state of the instance.
+  #
+  # @param model [ String ] the name of the model to be pushed
+  # @param insecure [ TrueClass, FalseClass, nil ] whether to allow insecure
+  #        connections, or nil to use default
+  # @param stream [ TrueClass, FalseClass ] whether to enable streaming for
+  #        the operation, defaults to true
   def initialize(model:, insecure: nil, stream: true)
     @model, @insecure, @stream = model, insecure, stream
   end
 
-  attr_reader :model, :insecure, :stream
+  # The model attribute reader returns the model name associated with the object.
+  #
+  # @return [ String ] the name of the model to be pushed
+  attr_reader :model
 
+  # The insecure attribute reader returns the insecure connection setting
+  # associated with the object.
+  #
+  # @return [ TrueClass, FalseClass, nil ] the insecure flag indicating whether
+  #         insecure connections are allowed, or nil if not set
+  attr_reader :insecure
+
+  # The stream attribute reader returns the streaming behavior setting
+  # associated with the object.
+  #
+  # @return [ TrueClass, FalseClass ] the streaming behavior flag, indicating
+  #         whether streaming is enabled for the command execution
+  attr_reader :stream
+
+  # The client attribute writer allows setting the client instance associated
+  # with the object.
+  #
+  # This method assigns the client that will be used to perform requests and
+  # handle responses for this command. It is typically called internally when a
+  # command is executed through a client instance.
+  #
+  # @attr_writer [ Ollama::Client ] the assigned client instance
   attr_writer :client
 
+  # The perform method executes a command request using the specified handler.
+  #
+  # This method initiates a request to the Ollama API endpoint associated with
+  # the command, utilizing the client instance to send the request and process
+  # responses through the provided handler. It handles both streaming and
+  # non-streaming scenarios based on the command's configuration.
+  #
+  # @param handler [ Ollama::Handler ] the handler object responsible for processing API responses
+  #
+  # @return [ self ] returns the current instance after initiating the request
   def perform(handler)
     @client.request(method: :post, path: self.class.path, body: to_json, stream:, handler:)
   end

data/lib/ollama/commands/show.rb

@@ -1,19 +1,82 @@
+# A command class that represents the show API endpoint for Ollama.
+#
+# This class is used to interact with the Ollama API's show endpoint, which
+# retrieves detailed information about a specific model. It inherits from the
+# base command structure and provides the necessary functionality to execute
+# show requests for model details.
+#
+# @example Retrieving detailed information about a model
+#   show = ollama.show(model: 'llama3.1')
+#   show.model_info # => hash containing model details
 class Ollama::Commands::Show
   include Ollama::DTO
 
+  # The path method returns the API endpoint path for show requests.
+  #
+  # This class method provides the specific URL path used to interact with the
+  # Ollama API's show endpoint. It is utilized internally by the command
+  # structure to determine the correct API route for retrieving detailed
+  # information about a specific model.
+  #
+  # @return [ String ] the API endpoint path '/api/show' for show requests
   def self.path
     '/api/show'
   end
 
+  # The initialize method sets up a new instance with streaming disabled.
+  #
+  # This method is responsible for initializing a new object instance and
+  # configuring it with a default setting that disables streaming behavior.
+  # It is typically called during the object creation process to establish
+  # the initial state of the instance.
+  #
+  # @param model [ String ] the name of the model to be used @param verbose [
+  # TrueClass, FalseClass, nil ] whether to enable verbose output, or nil to
+  # use default
   def initialize(model:, verbose: nil)
     @model, @verbose = model, verbose
     @stream = false
   end
 
-  attr_reader :model, :verbose, :stream
+  # The model attribute reader returns the model name associated with the object.
+  #
+  # @return [ String ] the name of the model used by the command instance
+  attr_reader :model
 
+  # The verbose attribute reader returns the verbose setting associated with
+  # the object.
+  #
+  # @return [ TrueClass, FalseClass, nil ] the verbose flag indicating whether
+  #         verbose output is enabled, or nil if not set
+  attr_reader :verbose
+
+  # The stream attribute reader returns the streaming behavior setting
+  # associated with the object.
+  #
+  # @return [ TrueClass, FalseClass ] the streaming behavior flag, indicating
+  #         whether streaming is enabled for the command execution
+  attr_reader :stream
+
+  # The client attribute writer allows setting the client instance associated
+  # with the object.
+  #
+  # This method assigns the client that will be used to perform requests and
+  # handle responses for this command. It is typically called internally when a
+  # command is executed through a client instance.
+  #
+  # @attr_writer [ Ollama::Client ] the assigned client instance
   attr_writer :client
 
+  # The perform method executes a command request using the specified handler.
+  #
+  # This method initiates a request to the Ollama API endpoint associated with
+  # the command, utilizing the client instance to send the request and process
+  # responses through the provided handler. It handles both streaming and
+  # non-streaming scenarios based on the command's configuration.
+  #
+  # @param handler [ Ollama::Handler ] the handler object responsible for processing API responses
+  #
+  # @return [ self ] returns the current instance after initiating the request
   def perform(handler)
     @client.request(method: :post, path: self.class.path, body: to_json, stream:, handler:)
   end

data/lib/ollama/commands/tags.rb

@@ -1,18 +1,68 @@
+# A command class that represents the tags API endpoint for Ollama.
+#
+# This class is used to interact with the Ollama API's tags endpoint, which
+# retrieves information about locally available models. It inherits from the
+# base command structure and provides the necessary functionality to execute
+# tag listing requests.
+#
+# @example Retrieving a list of local models
+#   tags = ollama.tags
+#   tags.models # => array of model information hashes
 class Ollama::Commands::Tags
+
+  # The path method returns the API endpoint path for tag listing requests.
+  #
+  # This class method provides the specific URL path used to interact with the
+  # Ollama API's tags endpoint. It is utilized internally by the command
+  # structure to determine the correct API route for retrieving information
+  # about locally available models.
+  #
+  # @return [ String ] the API endpoint path '/api/tags' for tag listing requests
   def self.path
     '/api/tags'
   end
 
+  # The initialize method sets up a new instance with streaming disabled.
+  #
+  # This method is responsible for initializing a new object instance and
+  # configuring it with a default setting that disables streaming behavior. It
+  # is typically called during the object creation process to establish the
+  # initial state of the instance.
+  #
+  # @param parameters [ Hash ] a hash containing initialization parameters
   def initialize(**parameters)
     parameters.empty? or raise ArgumentError,
       "Invalid parameters: #{parameters.keys * ' '}"
     @stream = false
   end
 
+  # The stream attribute reader returns the streaming behavior setting
+  # associated with the object.
+  #
+  # @return [ TrueClass, FalseClass ] the streaming behavior flag, indicating
+  # whether streaming is enabled for the command execution
   attr_reader :stream
 
+  # The client attribute writer allows setting the client instance associated
+  # with the object.
+  #
+  # This method assigns the client that will be used to perform requests and
+  # handle responses for this command. It is typically called internally when a
+  # command is executed through a client instance.
+  #
+  # @attr_writer [ Ollama::Client ] the assigned client instance
   attr_writer :client
 
+  # The perform method executes a command request using the specified handler.
+  #
+  # This method initiates a request to the Ollama API endpoint associated with
+  # the command, utilizing the client instance to send the request and process
+  # responses through the provided handler. It handles both streaming and
+  # non-streaming scenarios based on the command's configuration.
+  #
+  # @param handler [ Ollama::Handlers ] the handler object responsible for processing API responses
+  #
+  # @return [ self ] returns the current instance after initiating the request
   def perform(handler)
     @client.request(method: :get, path: self.class.path, stream:, handler:)
   end

data/lib/ollama/commands/version.rb

@@ -1,16 +1,65 @@
+
+# A command class that represents the version API endpoint for Ollama.
+#
+# This class is used to interact with the Ollama API's version endpoint,
+# which retrieves information about the Ollama server's version. It inherits
+# from the base command structure and provides the necessary functionality
+# to execute version requests.
+#
+# @example Retrieving the Ollama server version
+#   version = ollama.version
+#   puts version[:version] # => "0.1.0" or similar version string
 class Ollama::Commands::Version
+  # The path method returns the API endpoint path for version requests.
+  #
+  # This class method provides the specific URL path used to interact with the
+  # Ollama API's version endpoint. It is utilized internally by the command
+  # structure to determine the correct API route for version-related
+  # operations.
+  #
+  # @return [ String ] the API endpoint path '/api/version' for version
+  # requests
   def self.path
     '/api/version'
   end
 
-  def initialize()
+  # The initialize method sets up a new instance with streaming disabled.
+  #
+  # This method is responsible for initializing a new object instance and
+  # configuring it with a default setting that disables streaming behavior.
+  # It is typically called during the object creation process to establish
+  # the initial state of the instance.
+  def initialize
     @stream = false
   end
 
+  # The stream attribute reader returns the streaming behavior setting
+  # associated with the object.
+  #
+  # @return [ TrueClass, FalseClass ] the streaming behavior flag, indicating
+  # whether streaming is enabled for the command execution
   attr_reader :stream
 
+  # The client attribute writer allows setting the client instance associated
+  # with the object.
+  #
+  # This method assigns the client that will be used to perform requests and
+  # handle responses for this command. It is typically called internally when a
+  # command is executed through a client instance.
+  #
+  # @attr_writer [ Ollama::Client ] the assigned client instance
   attr_writer :client
 
+  # The perform method executes a command request using the specified handler.
+  #
+  # This method initiates a request to the Ollama API endpoint associated with
+  # the command, utilizing the client instance to send the request and process
+  # responses through the provided handler. It handles both streaming and
+  # non-streaming scenarios based on the command's configuration.
+  #
+  # @param handler [ Ollama::Handler ] the handler object responsible for processing API responses
+  #
+  # @return [ self ] returns the current instance after initiating the request
   def perform(handler)
     @client.request(method: :get, path: self.class.path, stream:, handler:)
   end

data/lib/ollama/dto.rb

@@ -1,3 +1,19 @@
+# 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 class 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 Ollama::DTO
   extend Tins::Concern
 
@@ -5,19 +21,49 @@ module Ollama::DTO
     self.attributes = Set.new
   end
 
-  module ClassMethods
+  class_methods do
+    # The attributes accessor reads and writes the attributes instance
+    # variable.
+    #
+    # @return [ Set ] the set of attributes stored in the instance variable
     attr_accessor :attributes
 
+    # 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
   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 ]
@@ -26,10 +72,29 @@ module Ollama::DTO
     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
@@ -40,21 +105,53 @@ module Ollama::DTO
     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.
+  #
+  # @return [ Hash ] a hash containing the object's non-nil and non-empty attributes
   def as_json(*)
     self.class.attributes.each_with_object({}) { |a, h| h[a] = send(a) }.
       reject { _2.nil? || _2.ask_and_send(:size) == 0 }
   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)
     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.
+  #
+  # @return [ String ] a JSON string representation of the object
   def to_json(*)
     as_json.to_json(*)
   end

data/lib/ollama/errors.rb

@@ -1,14 +1,64 @@
 module Ollama
+
+  # A module that groups together various error classes used by the Ollama client.
+  #
+  # This module serves as a namespace for custom exception types that are raised
+  # when errors occur during interactions with the Ollama API, providing more
+  # specific information about the nature of the problem.
   module Errors
+    # The base error class for Ollama-related exceptions.
+    #
+    # This class serves as the parent class for all custom exceptions raised by the Ollama library.
+    # It provides a common foundation for error handling within the gem, allowing developers to
+    # rescue specific Ollama errors or the general error type when interacting with the Ollama API.
     class Error < StandardError
     end
 
+    # Ollama error class for handling cases where a requested resource is not
+    # found.
+    #
+    # This exception is raised when the Ollama API returns a 404 status code,
+    # indicating that the requested model or resource could not be located.
+    #
+    # @example Handling a not found error
+    #   begin
+    #     ollama.show(model: 'nonexistent-model')
+    #   rescue Ollama::Errors::NotFoundError
+    #     puts "Model was not found"
+    #   end
     class NotFoundError < Error
     end
 
+    # Ollama error class for handling timeout errors when communicating with
+    # the Ollama API.
+    #
+    # This exception is raised when a request to the Ollama API times out
+    # during connection, reading, or writing operations. It inherits from
+    # Ollama::Errors::Error and provides specific handling for timeout-related
+    # issues.
+    #
+    # @example Handling a timeout error
+    #   begin
+    #     ollama.generate(model: 'llama3.1', prompt: 'Hello World')
+    #   rescue Ollama::Errors::TimeoutError
+    #     puts "Request timed out, consider increasing timeouts"
+    #   end
     class TimeoutError < Error
     end
 
+    # Ollama error class for handling socket errors when communicating with the Ollama API.
+    #
+    # This exception is raised when a socket-level error occurs while
+    # attempting to connect to or communicate with the Ollama API.
+    # It inherits from Ollama::Errors::Error and provides specific handling for
+    # network-related issues that prevent successful API communication.
+    #
+    # @example Handling a socket error
+    #   begin
+    #     ollama.generate(model: 'llama3.1', prompt: 'Hello World')
+    #   rescue Ollama::Errors::SocketError
+    #     puts "Network connection failed"
+    #   end
     class SocketError < Error
     end
   end

data/lib/ollama/handlers/collector.rb

@@ -1,16 +1,50 @@
+# A handler that collects responses into an array and returns the array as the result.
+#
+# The Collector handler is designed to accumulate all responses during command execution
+# and provide access to the complete collection of responses through its result method.
+# It is typically used when multiple responses are expected and need to be processed
+# together rather than individually.
+#
+# @example Using the Collector handler to gather all responses
+#   responses = ollama.generate(model: 'llama3.1', prompt: 'Hello World', &Collector)
+#   # responses will contain an array of all response objects received
 class Ollama::Handlers::Collector
   include Ollama::Handlers::Concern
 
+  # The initialize method sets up a new handler instance with the specified
+  # output destination and initializes an empty array for collecting responses.
+  #
+  # @param output [ IO ] the output stream to be used for handling responses,
+  # defaults to $stdout
   def initialize(output: $stdout)
     super
     @array = []
   end
 
+  # The call method processes a response by appending it to an internal array.
+  #
+  # This method is responsible for handling individual responses during command
+  # execution by storing them in an internal array for later retrieval. It
+  # supports method chaining by returning the handler instance itself after
+  # processing.
+  #
+  # @param response [ Ollama::Response ] the response object to be processed and stored
+  #
+  # @return [ self ] returns the handler instance itself after processing the response
   def call(response)
     @array << response
     self
   end
 
+  # The result method returns the collected response data from handler
+  # operations.
+  #
+  # This method provides access to the accumulated results after a command has
+  # been executed with a handler that collects responses. It returns the
+  # internal array containing all responses that were processed by the handler.
+  #
+  # @return [ Array<Ollama::Response>, nil ] the array of collected response objects,
+  #         or nil if no responses were collected
   def result
     @array
   end