ollama-ruby 1.5.0 → 1.6.0

data/lib/ollama/handlers/progress.rb

@@ -1,10 +1,23 @@
 require 'infobar'
 require 'tins/unit'
 
+# A handler that displays progress information for streaming operations.
+#
+# This class is designed to provide visual feedback during long-running
+# operations such as model creation, pulling, or pushing. It uses a progress
+# bar to show the current status and estimated time remaining, making it easier
+# to monitor the progress of these operations in terminal environments.
+#
+# @example Displaying progress for a model creation operation
+#   ollama.create(model: 'my-model', stream: true, &Progress)
 class Ollama::Handlers::Progress
   include Ollama::Handlers::Concern
   include Term::ANSIColor
 
+  # The initialize method sets up a new handler instance with the specified
+  # output destination and initializes internal state for progress tracking.
+  #
+  # @param output [ IO ] the output stream to be used for handling responses, defaults to $stdout
   def initialize(output: $stdout)
     super
     @current     = 0
@@ -12,6 +25,20 @@ class Ollama::Handlers::Progress
     @last_status = nil
   end
 
+  # The call method processes a response by updating progress information and
+  # displaying status updates.
+  #
+  # This method handles the display of progress information for streaming
+  # operations by updating the progress bar with current completion status,
+  # handling status changes, and displaying any error messages that occur
+  # during the operation. It manages internal state to track progress and
+  # ensures proper formatting of output.
+  #
+  # @param response [ Ollama::Response ] the response object containing
+  # progress information
+  #
+  # @return [ self ] returns the handler instance itself after processing the
+  # response
   def call(response)
     infobar.display.output = @output
     if status = response.status
@@ -40,6 +67,17 @@ class Ollama::Handlers::Progress
 
   private
 
+  # The message method formats progress information into a descriptive string.
+  #
+  # This method takes current and total values and creates a formatted progress
+  # message that includes the current value, total value, time elapsed,
+  # estimated time remaining, and the current rate of progress.
+  #
+  # @param current [ Integer ] the current progress value
+  # @param total [ Integer ] the total progress value
+  #
+  # @return [ String ] a formatted progress message containing current status,
+  #         time information, and estimated completion details
   def message(current, total)
     progress = '%s/%s' % [ current, total ].map {
       Tins::Unit.format(_1, format: '%.2f %U')

data/lib/ollama/handlers/say.rb

@@ -1,8 +1,29 @@
 require 'shellwords'
 
+# A handler that uses the system's say command to speak response content.
+#
+# The Say handler is designed to convert text responses from Ollama API
+# commands into audible speech using the operating system's native
+# text-to-speech capabilities. It supports customization of voice and
+# interactive modes, making it suitable for applications where audio feedback
+# is preferred over visual display.
+#
+# @example Using the Say handler with a custom voice
+#   ollama.generate(model: 'llama3.1', prompt: 'Hello World', &Say.new(voice: 'Alex'))
+#
+# @example Using the Say handler in interactive mode
+#   ollama.generate(model: 'llama3.1', prompt: 'Hello World', &Say.new(interactive: true))
 class Ollama::Handlers::Say
   include Ollama::Handlers::Concern
 
+  # The initialize method sets up a new handler instance with the specified
+  # output destination and configures voice and interactive settings for
+  # text-to-speech functionality.
+  #
+  # @param output [ IO, nil ] the output stream to be used for handling responses, defaults to nil
+  # @param voice [ String ] the voice to be used for speech synthesis, defaults to 'Samantha'
+  # @param interactive [ TrueClass, FalseClass, String, nil ] the interactive
+  # mode setting for speech synthesis, defaults to nil
   def initialize(output: nil, voice: 'Samantha', interactive: nil)
     @voice       = voice
     @interactive = interactive
@@ -13,10 +34,28 @@ class Ollama::Handlers::Say
     end
   end
 
+  # The voice attribute reader returns the voice associated with the object.
+  #
+  # @return [ String ] the voice value stored in the instance variable
   attr_reader :voice
 
+  # The interactive attribute reader returns the interactive mode setting
+  # associated with the object.
+  #
+  # @return [ TrueClass, FalseClass, String, nil ] the interactive mode value
+  # stored in the instance variable
   attr_reader :interactive
 
+  # The call method processes a response by printing its content to the output stream.
+  #
+  # This method handles the display of response content by extracting text from the response object
+  # and writing it to the configured output stream. It manages the output stream state, reopening it
+  # if necessary when it has been closed, and ensures proper handling of streaming responses by
+  # closing the output stream when the response indicates completion.
+  #
+  # @param response [ Ollama::Response ] the response object containing content to be printed
+  #
+  # @return [ self ] returns the handler instance itself after processing the response
   def call(response)
     if @output.closed?
       wait_output_pid
@@ -32,18 +71,45 @@ class Ollama::Handlers::Say
 
   private
 
+  # The open_output method creates a new IO object for handling speech output.
+  #
+  # This method initializes a pipe to the system's say command, configuring it
+  # with the specified voice and interactive settings. It returns an IO object
+  # that can be used to write text content which will be converted to speech by
+  # the operating system.
+  #
+  # @return [ IO ] an IO object connected to the say command for text-to-speech conversion
   def open_output
     io = IO.popen(Shellwords.join(command(voice:, interactive:)), 'w')
     io.sync = true
     io
   end
 
+  # The wait_output_pid method waits for the output process to complete.
+  #
+  # This method checks if there is an active output process ID and waits for it
+  # to finish execution. It uses non-blocking wait to avoid hanging the main
+  # thread.
+  # If the process has already terminated, it handles the Errno::ECHILD
+  # exception gracefully without raising an error.
   def wait_output_pid
     @output_pid or return
     Process.wait(@output_pid, Process::WNOHANG | Process::WUNTRACED)
   rescue Errno::ECHILD
   end
 
+  # The command method constructs a say command array with specified voice and
+  # interactive options.
+  #
+  # This method builds an array representing a system command for the 'say'
+  # utility, incorporating the provided voice and interactive settings to
+  # configure text-to-speech behavior.
+  #
+  # @param voice [ String ] the voice to be used for speech synthesis
+  # @param interactive [ TrueClass, FalseClass, String, nil ] the interactive
+  # mode setting for speech synthesis
+  #
+  # @return [ Array<String> ] an array containing the command and its arguments
   def command(voice:, interactive:)
     command = [ 'say' ]
     voice and command.concat([ '-v', voice ])

data/lib/ollama/handlers/single.rb

@@ -1,16 +1,51 @@
+# A handler that collects responses and returns either a single response or an
+# array of responses.
+#
+# The Single handler is designed to accumulate responses during command
+# execution and provides a result that is either the single response when only
+# one is present, or the complete array of responses when multiple are
+# collected.
+#
+# @example Using the Single handler to collect a single response
+#   ollama.generate(model: 'llama3.1', prompt: 'Hello World', &Single)
 class Ollama::Handlers::Single
   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 either
+  # a single response when only one result is present, or the complete array
+  # of responses when multiple results are collected.
+  #
+  # @return [ Ollama::Response, Array<Ollama::Response>, nil ] the collected response data,
+  #         which may be a single response, an array of responses, or nil
+  #         if no responses were collected
   def result
     @array.size <= 1 ? @array.first : @array
   end

data/lib/ollama/handlers.rb

@@ -1,3 +1,12 @@
+# A module that groups together various handler classes used to process
+# responses from the Ollama API.
+#
+# Handlers are responsible for defining how API responses should be processed, displayed, or stored.
+# They implement a common interface that allows them to be passed as arguments to client commands,
+# providing flexibility in how response data is handled.
+#
+# @example Using a handler with a client command
+#   ollama.generate(model: 'llama3.1', prompt: 'Hello World', &Print)
 module Ollama::Handlers
 end
 

data/lib/ollama/image.rb

@@ -1,30 +1,87 @@
 require 'base64'
 
+# Ollama::Image
+#
+# Represents an image object that can be used in messages sent to the Ollama API.
+# The Image class provides methods to create image objects from various sources
+# including base64 encoded strings, file paths, IO objects, and raw string data.
+#
+# @example Creating an image from a file path
+#   image = Ollama::Image.for_filename('path/to/image.jpg')
+#
+# @example Creating an image from a base64 string
+#   image = Ollama::Image.for_base64('base64encodedstring', path: 'image.jpg')
+#
+# @example Creating an image from a string
+#   image = Ollama::Image.for_string('raw image data')
+#
+# @example Creating an image from an IO object
+#   File.open('path/to/image.jpg', 'rb') do |io|
+#     image = Ollama::Image.for_io(io, path: 'image.jpg')
+#   end
 class Ollama::Image
+  # Initializes a new Image object with the provided data.
+  #
+  # @param data [ String ] the image data to store in the object
   def initialize(data)
     @data = data
   end
 
+  # The path attribute stores the file path associated with the image object.
+  #
+  # @return [ String, nil ] the path to the image file, or nil if not set
   attr_accessor :path
 
+  # The data attribute reader returns the image data stored in the object.
+  #
+  # @return [ String ] the raw image data contained within the image object
   attr_reader :data
 
   class << self
+    # Creates a new Image object from base64 encoded data.
+    #
+    # @param data [ String ] the base64 encoded image data
+    # @param path [ String, nil ] the optional file path associated with the image
+    #
+    # @return [ Ollama::Image ] a new Image instance initialized with the
+    # provided data and path
     def for_base64(data, path: nil)
       obj = new(data)
       obj.path = path
       obj
     end
 
+    # Creates a new Image object from a string by encoding it to base64.
+    #
+    # @param string [ String ] the raw string data to be converted into an image
+    # @param path [ String, nil ] the optional file path associated with the image
+    #
+    # @return [ Ollama::Image ] a new Image instance initialized with the
+    # encoded string data and optional path
     def for_string(string, path: nil)
       for_base64(Base64.encode64(string), path:)
     end
 
+    # Creates a new Image object from an IO object by reading its contents and
+    # optionally setting a path.
+    #
+    # @param io [ IO ] the IO object to read image data from
+    # @param path [ String, nil ] the optional file path associated with the image
+    #
+    # @return [ Ollama::Image ] a new Image instance initialized with the IO
+    # object's data and optional path
     def for_io(io, path: nil)
       path ||= io.path
       for_string(io.read, path:)
     end
 
+    # Creates a new Image object from a file path by opening the file in binary
+    # mode and passing it to the for_io method.
+    #
+    # @param path [ String ] the file system path to the image file
+    #
+    # @return [ Ollama::Image ] a new Image instance initialized with the
+    # contents of the file at the specified path
     def for_filename(path)
       File.open(path, 'rb') { |io| for_io(io, path:) }
     end
@@ -32,10 +89,20 @@ class Ollama::Image
     private :new
   end
 
+  # The == method compares two Image objects for equality based on their data
+  # contents.
+  #
+  # @param other [ Ollama::Image ] the other Image object to compare against
+  #
+  # @return [ TrueClass, FalseClass ] true if both Image objects have identical
+  # data, false otherwise
   def ==(other)
     @data == other.data
   end
 
+  # The to_s method returns the raw image data stored in the Image object.
+  #
+  # @return [ String ] the raw image data contained within the image object
   def to_s
     @data
   end

data/lib/ollama/json_loader.rb

@@ -1,4 +1,21 @@
+# A module that provides functionality for loading configuration data from JSON
+# files.
+#
+# This module extends classes with a method to load configuration attributes
+# from a JSON file, making it easy to initialize objects with settings stored
+# in external files.
+
+# @example Loading configuration from a JSON file
+#   config = MyConfigClass.load_from_json('path/to/config.json')
 module Ollama::JSONLoader
+  # The load_from_json method loads configuration data from a JSON file.
+  #
+  # This method reads the specified JSON file and uses its contents to
+  # initialize a new instance of the class by passing the parsed data
+  # as keyword arguments to the constructor.
+  #
+  # @param path [ String ] the filesystem path to the JSON configuration file
+  # @return [ self ] a new instance of the class initialized with the JSON data
   def load_from_json(path)
     json = File.read(path)
     new(**config_hash = JSON.parse(json, symbolize_names: true))

data/lib/ollama/message.rb

@@ -1,8 +1,53 @@
+# Ollama::Message
+#
+# Represents a message object used in communication with the Ollama API.
+# This class encapsulates the essential components of a message, including
+# the role of the sender, the content of the message, optional thinking
+# content, associated images, and tool calls.
+#
+# @example Creating a basic message
+#   message = Ollama::Message.new(
+#     role: 'user',
+#     content: 'Hello, world!'
+#   )
+#
+# @example Creating a message with additional attributes
+#   image = Ollama::Image.for_filename('path/to/image.jpg')
+#   message = Ollama::Message.new(
+#     role: 'user',
+#     content: 'Look at this image',
+#     images: [image]
+#   )
 class Ollama::Message
   include Ollama::DTO
 
-  attr_reader :role, :content, :thinking, :images
+  # The role attribute reader returns the role associated with the message.
+  #
+  # @return [ String ] the role of the message sender, such as 'user' or 'assistant'
+  attr_reader :role
 
+  # The content attribute reader returns the textual content of the message.
+  #
+  # @return [ String ] the content of the message
+  attr_reader :content
+
+  # The thinking attribute reader returns the thinking content associated with the message.
+  #
+  # @return [ String, nil ] the thinking content of the message, or nil if not set
+  attr_reader :thinking
+
+  # The images attribute reader returns the image objects associated with the message.
+  #
+  # @return [ Array<Ollama::Image>, nil ] an array of image objects, or nil if no images are associated with the message
+  attr_reader :images
+
+  # The initialize method sets up a new Message instance with the specified attributes.
+  #
+  # @param role [ String ] the role of the message sender, such as 'user' or 'assistant'
+  # @param content [ String ] the textual content of the message
+  # @param thinking [ String, nil ] optional thinking content for the message
+  # @param images [ Ollama::Image, Array<Ollama::Image>, nil ] optional image objects associated with the message
+  # @param tool_calls [ Hash, Array<Hash>, nil ] optional tool calls made in the message
   def initialize(role:, content:, thinking: nil, images: nil, tool_calls: nil, **)
     @role, @content, @thinking, @images, @tool_calls =
       role, content, thinking, (Array(images) if images),

data/lib/ollama/options.rb

@@ -1,7 +1,21 @@
 require 'ollama/json_loader'
 
-# Options are explained in the parameters for the modelfile:
-# https://github.com/ollama/ollama/blob/main/docs/modelfile.md#parameter
+# A class that encapsulates configuration options for Ollama models.
+#
+# This class provides a structured way to define and manage various parameters
+# that can be passed to Ollama models during generation or chat operations. It
+# includes type validation to ensure that option values conform to expected
+# data types, making it easier to work with model configurations
+# programmatically.
+#
+# @example Creating an Options object with specific settings
+#   options = Ollama::Options.new(
+#     temperature: 0.7,
+#     num_ctx: 8192,
+#     top_p: 0.9
+#   )
+#
+# [Options are explained in the parameters for the modelfile.](https://github.com/ollama/ollama/blob/main/docs/modelfile.md#parameter)
 class Ollama::Options
   include Ollama::DTO
   extend Ollama::JSONLoader
@@ -69,6 +83,17 @@ class Ollama::Options
     end
   }
 
+  # The [] method creates a new instance of the class using a hash of attributes.
+  #
+  # This class method provides a convenient way to instantiate an object by
+  # passing a hash containing the desired attribute values. It converts the
+  # hash keys to symbols and forwards them as keyword arguments to the
+  # constructor.
+  #
+  # @param value [ Hash ] a hash containing the attribute names and their values
+  #
+  # @return [ self ] a new instance of the class initialized with the provided
+  # attributes
   def self.[](value)
     new(**value.to_h)
   end

data/lib/ollama/response.rb

@@ -1,4 +1,21 @@
+# A subclass of JSON::GenericObject that represents responses from the Ollama API.
+#
+# This class serves as a specialized response object that extends
+# JSON::GenericObject to provide structured access to API response data. It
+# maintains the ability to convert to JSON format while preserving the response
+# data in a hash-like structure.
+#
+# @example Accessing response data
+#   response = Ollama::Response.new(key: 'value')
+#   response[:key] # => 'value'
 class Ollama::Response < JSON::GenericObject
+  # 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.
+  #
+  # @note This removes "json_class" attribute from hash for responses.
+  # @return [ Hash ] a hash containing the object's non-nil and non-empty attributes
   def as_json(*)
     to_hash
   end

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

@@ -1,8 +1,48 @@
+# A class that represents a single property within the parameters specification
+# for a tool function.
+#
+# This class encapsulates the definition of an individual parameter, including
+# its data type, descriptive text, and optional enumeration values that define
+# valid inputs.
+#
+# @example Creating a property with type and description
+#   property = Ollama::Tool::Function::Parameters::Property.new(
+#     type: 'string',
+#     description: 'The location to get weather for'
+#   )
+#
+# @example Creating a property with an enumeration of valid values
+#   property = Ollama::Tool::Function::Parameters::Property.new(
+#     type: 'string',
+#     description: 'Temperature unit',
+#     enum: %w[celsius fahrenheit]
+#   )
 class Ollama::Tool::Function::Parameters::Property
   include Ollama::DTO
 
-  attr_reader :type, :description, :enum
+  # The type attribute reader returns the type associated with the object.
+  #
+  # @return [ String ] the type value stored in the instance variable
+  attr_reader :type
 
+  # The description attribute reader returns the description associated with
+  # the object.
+  #
+  # @return [ String ] the description value stored in the instance variable
+  attr_reader :description
+
+  # The enum attribute reader returns the enumeration values associated with the object.
+  #
+  # @return [ Array<String>, nil ] an array of valid string values that the
+  # property can take, or nil if not set
+  attr_reader :enum
+
+  # The initialize method sets up a new Property instance with the specified
+  # attributes.
+  #
+  # @param type [ String ] the data type of the property
+  # @param description [ String ] a detailed explanation of what the property represents
+  # @param enum [ Array<String>, nil ] an optional array of valid values that the property can take
   def initialize(type:, description:, enum: nil)
     @type, @description, @enum = type, description, Array(enum)
   end

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

@@ -1,8 +1,47 @@
+# A class that represents the parameters specification for a tool function in
+# Ollama API interactions.
+#
+# This class encapsulates the structure required for defining the parameters
+# that a function tool accepts. It includes the type of parameter object, the
+# properties of each parameter, and which parameters are required.
+#
+# @example Creating a parameters specification for a tool function
+#   property = Ollama::Tool::Function::Parameters::Property.new(
+#     type: 'string',
+#     description: 'The location to get weather for'
+#   )
+#   parameters = Ollama::Tool::Function::Parameters.new(
+#     type: 'object',
+#     properties: { location: property },
+#     required: %w[location]
+#   )
 class Ollama::Tool::Function::Parameters
   include Ollama::DTO
 
-  attr_reader :type, :properties, :required
+  # The type attribute reader returns the type associated with the object.
+  #
+  # @return [ String ] the type value stored in the instance variable
+  attr_reader :type
 
+  # The properties attribute reader returns the properties associated with the
+  # object.
+  #
+  # @return [ Hash ] the properties hash, or nil if not set
+  attr_reader :properties
+
+  # The required attribute reader returns the required parameter values
+  # associated with the object.
+  #
+  # @return [ Array<String>, nil ] an array of required parameter names, or nil
+  # if not set
+  attr_reader :required
+
+  # The initialize method sets up a new Parameters instance with the specified
+  # attributes.
+  #
+  # @param type [ String ] the type of parameter object
+  # @param properties [ Hash ] the properties of each parameter
+  # @param required [ Array<String> ] the names of required parameters
   def initialize(type:, properties:, required:)
     @type, @properties, @required =
       type, Hash(properties).transform_values(&:to_hash), Array(required)

data/lib/ollama/tool/function.rb

@@ -1,8 +1,51 @@
+# A class that represents a function definition for tool usage in Ollama API
+# interactions.
+#
+# This class encapsulates the structure required for defining functions that
+# can be passed to models to enable function calling capabilities. It includes
+# the function's name, description, parameters specification, and list of
+# required parameters.
+#
+# @example Creating a function definition for a tool
+#   function = Ollama::Tool::Function.new(
+#     name: 'get_current_weather',
+#     description: 'Get the current weather for a location',
+#     parameters: parameters,
+#     required: %w[location]
+#   )
 class Ollama::Tool::Function
   include Ollama::DTO
 
-  attr_reader :name, :description, :parameters, :required
+  # The name attribute reader returns the name associated with the object.
+  #
+  # @return [ String ] the name value stored in the instance variable
+  attr_reader :name
 
+  # The description attribute reader returns the description associated with
+  # the object.
+  #
+  # @return [ String ] the description value stored in the instance variable
+  attr_reader :description
+
+  # The parameters attribute reader returns the parameters associated with the
+  # object.
+  #
+  # @return [ Hash, nil ] the parameters hash, or nil if not set
+  attr_reader :parameters
+
+  # The required attribute reader returns the required parameter values
+  # associated with the object.
+  #
+  # @return [ Array<String>, nil ] an array of required parameter names, or nil if not set
+  attr_reader :required
+
+  # The initialize method sets up a new Tool::Function instance with the
+  # specified attributes.
+  #
+  # @param name [ String ] the name of the function
+  # @param description [ String ] a brief description of what the function does
+  # @param parameters [ Hash, nil ] optional parameters specification for the function
+  # @param required [ Array<String>, nil ] optional array of required parameter names
   def initialize(name:, description:, parameters: nil, required: nil)
     @name, @description, @parameters, @required =
       name, description, (Hash(parameters) if parameters),

data/lib/ollama/tool.rb

@@ -1,8 +1,44 @@
+# Represents a tool definition used in interactions with the Ollama API.
+# This class encapsulates the structure required for defining tools that can be
+# passed to models to enable function calling capabilities. It includes the type
+# of tool and the associated function definition, which specifies the tool's name,
+# description, parameters, and required fields.
+#
+# @example Creating a tool with a function definition
+#   tool = Ollama::Tool.new(
+#     type: 'function',
+#     function: Ollama::Tool::Function.new(
+#       name: 'get_current_weather',
+#       description: 'Get the current weather for a location',
+#       parameters: Ollama::Tool::Function::Parameters.new(
+#         type: 'object',
+#         properties: { location: property },
+#         required: %w[location]
+#       )
+#     )
+#   )
 class Ollama::Tool
   include Ollama::DTO
 
-  attr_reader :type, :function
+  # The type attribute reader returns the type associated with the tool.
+  #
+  # @return [ String ] the type of tool, typically 'function' for function
+  # calling capabilities
+  attr_reader :type
 
+  # The function attribute reader returns the function definition associated
+  # with the tool.
+  #
+  # @return [ Hash ] the function definition as a hash, containing details such
+  # as the function's name, description, parameters, and required fields
+  attr_reader :function
+
+  # The initialize method sets up a new Tool instance with the specified type
+  # and function.
+  #
+  # @param type [ String ] the type of tool being created
+  # @param function [ Ollama::Tool::Function ] the function definition
+  # associated with the tool
   def initialize(type:, function:)
     @type, @function = type, function.to_hash
   end