ollama-ruby 1.5.0 → 1.6.0

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

data/lib/ollama/handlers/concern.rb

@@ -1,29 +1,87 @@
 require 'tins/concern'
 require 'tins/implement'
 
+# A module that defines the common interface and behavior for all response
+# handlers used with Ollama client commands.
+#
+# Handlers are responsible for processing responses from the Ollama API
+# according to specific logic, such as printing output, collecting results, or
+# displaying progress. This module establishes the foundational structure that
+# all handler classes must implement to be compatible with the client's command
+# execution flow.
 module Ollama::Handlers::Concern
   extend Tins::Concern
   extend Tins::Implement
 
+  # The initialize method sets up a new handler instance with the specified
+  # output destination.
+  #
+  # @param output [ IO ] the output stream to be used for handling responses, defaults to $stdout
   def initialize(output: $stdout)
     @output = output
   end
 
+  # The output attribute reader returns the output stream used by the client.
+  #
+  # @return [ IO ] the output stream, typically $stdout, to which responses and
+  #         messages are written
   attr_reader :output
 
+  # 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, such as Collector or
+  # Single handlers.
+  #
+  # @return [ Ollama::Response, Array<Ollama::Response>, nil ] the result of the handler operation,
+  #         which may be a single response, an array of responses, or nil
+  #         depending on the handler type and the command execution
   attr_reader :result
 
-  implement :call
 
+  # The implement :call, :subclass line enforces that any class including this
+  # concern must implement a `call` instance method. This creates a contract
+  # that ensures all handler implementations will have the required interface
+  # for processing Ollama API responses. The :subclass parameter indicates this
+  # validation occurs at the subclass level rather than the module level,
+  # meaning concrete classes inheriting from this concern must provide their
+  # own implementation of the call method. This is a form of compile-time
+  # interface checking that helps prevent runtime errors when handlers are
+  # expected to be callable with response objects.
+  implement :call, :subclass
+
+  # The to_proc method converts the handler instance into a proc object.
+  #
+  # This method returns a lambda that takes a response parameter and calls the
+  # handler's call method with that response, enabling the handler to be used
+  # in contexts where a proc is expected.
+  #
+  # @return [ Proc ] a proc that wraps the handler's call method for response
+  # processing
   def to_proc
     -> response { call(response) }
   end
 
-  module ClassMethods
+  class_methods do
+    # The call method invokes the handler's call method with the provided
+    # response.
+    #
+    # @param response [ Ollama::Response ] the response object to be processed by the
+    # handler
+    #
+    # @return [ self ] returns the handler instance itself after processing the
+    # response
     def call(response)
       new.call(response)
     end
 
+    # The to_proc method converts the handler class into a proc object.
+    #
+    # This method creates a new instance of the handler and returns its to_proc
+    # representation, enabling the handler class to be used in contexts where a
+    # proc is expected.
+    #
+    # @return [ Proc ] a proc that wraps the handler's call method for response processing
     def to_proc
       new.to_proc
     end

data/lib/ollama/handlers/dump_json.rb

@@ -1,6 +1,26 @@
+# A handler that outputs JSON representations of responses to the specified
+# output stream.
+#
+# This class is designed to serialize and display API responses in JSON format,
+# making it easy to inspect the raw data returned by Ollama commands. It
+# implements the standard handler interface and can be used with any command
+# that supports response processing.
+#
+# @example Using the DumpJSON handler to output response data as JSON
+#   ollama.generate(model: 'llama3.1', prompt: 'Hello World', &DumpJSON)
 class Ollama::Handlers::DumpJSON
   include Ollama::Handlers::Concern
 
+  # The call method processes a response by outputting its JSON representation.
+  #
+  # This method takes a response object and serializes it into a formatted JSON
+  # string, which is then written to the specified output stream. It is
+  # designed to provide detailed inspection of API responses in a
+  # human-readable format.
+  #
+  # @param response [ Ollama::Response ] the response object to be serialized and output
+  #
+  # @return [ self ] returns the handler instance itself after processing the response
   def call(response)
     @output.puts JSON::pretty_generate(response, allow_nan: true, max_nesting: false)
     self

data/lib/ollama/handlers/dump_yaml.rb

@@ -1,6 +1,28 @@
+# A handler that outputs YAML representations of responses to the specified
+# output stream.
+#
+# This class is designed to serialize and display API responses in YAML format,
+# making it easy to inspect the raw data returned by Ollama commands. It
+# implements the standard handler interface and can be used with any command
+# that supports response processing.
+#
+# @example Using the DumpYAML handler to output response data as YAML
+#   ollama.generate(model: 'llama3.1', prompt: 'Hello World', &DumpYAML)
 class Ollama::Handlers::DumpYAML
   include Ollama::Handlers::Concern
 
+  # The call method processes a response by outputting its YAML representation.
+  #
+  # This method takes a response object and serializes it into YAML format,
+  # writing the result to the configured output stream. It is designed to
+  # handle API responses that need to be displayed or logged in a structured
+  # YAML format for debugging or inspection purposes.
+  #
+  # @param response [ Ollama::Response ] the response object to be serialized
+  # and output
+  #
+  # @return [ self ] returns the handler instance itself after processing the
+  # response
   def call(response)
     @output.puts Psych.dump(response)
     self

data/lib/ollama/handlers/markdown.rb

@@ -1,10 +1,25 @@
 require 'term/ansicolor'
 require 'kramdown/ansi'
 
+# A handler that processes responses by rendering them as ANSI-markdown output.
+#
+# This class is designed to display streaming or non-streaming responses in a
+# formatted markdown style using ANSI escape codes for terminal rendering.
+# It supports both continuous and single-message display modes, making it
+# suitable for interactive terminal applications where styled text output is
+# desired.
+#
+# @example Displaying a response as markdown
+#   ollama.generate(model: 'llama3.1', prompt: 'Hello World', &Markdown)
 class Ollama::Handlers::Markdown
   include Ollama::Handlers::Concern
   include Term::ANSIColor
 
+  # The initialize method sets up a new handler instance with the specified
+  # output destination and streaming behavior.
+  #
+  # @param output [ IO ] the output stream to be used for handling responses, defaults to $stdout
+  # @param stream [ TrueClass, FalseClass ] whether to enable streaming mode, defaults to true
   def initialize(output: $stdout, stream: true)
     super(output:)
     @stream      = stream
@@ -12,6 +27,19 @@ class Ollama::Handlers::Markdown
     @content     = ''
   end
 
+  # The call method processes a response by rendering its content as
+  # ANSI-markdown.
+  #
+  # This method handles the display of response content in a formatted markdown
+  # style using ANSI escape codes for terminal rendering. It supports both
+  # streaming and non-streaming modes, allowing for continuous updates or
+  # single-message display.
+  #
+  # @param response [ Ollama::Response ] the response object containing content
+  # to be rendered
+  #
+  # @return [ self ] returns the handler instance itself after processing the
+  # response
   def call(response)
     if content = response.response || response.message&.content
       if @stream

data/lib/ollama/handlers/nop.rb

@@ -1,6 +1,26 @@
+# A handler that performs no operation on responses.
+#
+# The NOP (No Operation) handler is used when it's necessary to pass a handler
+# object to a command without actually processing or displaying the responses.
+# It implements the required interface for response handling but takes no
+# action when called, making it useful for scenarios where a handler is
+# required by the API but no specific processing is desired.
+#
+# @example Using the NOP handler
+#   ollama.generate(model: 'llama3.1', prompt: 'Hello World', &NOP)
 class Ollama::Handlers::NOP
   include Ollama::Handlers::Concern
 
+  # The call method processes a response and returns the handler instance.
+  #
+  # This method is intended to be overridden by concrete handler
+  # implementations to define specific behavior for handling API responses. It
+  # serves as the core interface for response processing within the handler
+  # pattern.
+  #
+  # @param response [ Ollama::Response ] the response object to be processed by the handler
+  #
+  # @return [ self ] returns the handler instance itself after processing the response
   def call(response)
     self
   end

data/lib/ollama/handlers/print.rb

@@ -1,11 +1,38 @@
+# A handler that prints response content to the output stream.
+#
+# The Print handler is designed to output text responses from Ollama API
+# commands to a specified output stream. It extracts content from responses and
+# displays it directly, making it useful for interactive terminal applications
+# where immediate feedback is desired.
+#
+# @example Using the Print handler with a chat command
+#   ollama.chat(model: 'llama3.1', messages:, &Print)
+#
+# @example Using the Print handler with a generate command
+#   ollama.generate(model: 'llama3.1', prompt: 'Hello World', &Print)
 class Ollama::Handlers::Print
   include Ollama::Handlers::Concern
 
+  # The initialize method sets up a new handler instance with the specified
+  # output destination and enables synchronous writing to the output stream.
+  #
+  # @param output [ IO ] the output stream to be used for handling responses, defaults to $stdout
   def initialize(output: $stdout)
     super
     @output.sync = true
   end
 
+  # The call method processes a response by printing its content to the output
+  # stream.
+  #
+  # This method extracts content from the response object and prints it to the
+  # configured output stream. If the response indicates completion, it adds a
+  # newline character after printing. The method returns the handler instance
+  # itself to allow for method chaining.
+  #
+  # @param response [ Ollama::Response ] the response object to be processed
+  #
+  # @return [ self ] returns the handler instance after processing the response
   def call(response)
     if content = response.response || response.message&.content
       @output.print content