ollama-ruby 1.4.0 → 1.6.0

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

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),