ollama-ruby 1.4.0 → 1.6.0

data/lib/ollama/client/configuration/config.rb

@@ -1,25 +1,136 @@
 require 'ollama/json_loader'
 
+# A module that provides configuration management capabilities for the Ollama
+# client.
+#
+# This module extends the client with functionality to manage and apply
+# configuration settings such as base URL, timeouts, and output streams. It
+# allows for flexible initialization of client instances using either direct
+# parameters or pre-defined configuration objects, supporting both programmatic
+# and file-based configuration approaches.
+#
+# @example Configuring a client with a hash of attributes
+#   config = Ollama::Client::Config[base_url: 'http://localhost:11434']
+#   client = Ollama::Client.configure_with(config)
+#
+# @example Loading configuration from a JSON file
+#   config = Ollama::Client::Config.load_from_json('path/to/config.json')
+#   client = Ollama::Client.configure_with(config)
 module Ollama::Client::Configuration
+
+
+  # A class that encapsulates configuration settings for Ollama clients.
+  #
+  # This class provides a structured way to define and manage various
+  # configuration options that can be used when initializing Ollama client
+  # instances. It includes properties for setting the base URL, output stream,
+  # and timeout values.
+  #
+  # @example Creating a configuration object
+  #   config = Ollama::Client::Config[
+  #     base_url: 'http://localhost:11434',
+  #     output: $stdout,
+  #     connect_timeout: 15,
+  #     read_timeout: 300
+  #   ]
+  #
+  # @example Loading configuration from a JSON file
+  #   config = Ollama::Client::Config.load_from_json('path/to/config.json')
   class Config
     extend Ollama::JSONLoader
 
+    # The initialize method sets up a new configuration instance with the
+    # specified attributes.
+    #
+    # This method is responsible for initializing a new
+    # Ollama::Client::Configuration::Config instance by processing various
+    # configuration options. It iterates through the provided attributes and
+    # assigns them to corresponding setter methods, then ensures that the
+    # output stream is set to $stdout if no output was specified.
+    #
+    # @param attributes [ Hash ] a hash containing the configuration attributes to be set
+    #
+    # @return [ Ollama::Client::Configuration::Config ] returns the initialized configuration instance
     def initialize(**attributes)
       attributes.each { |k, v| send("#{k}=", v) }
       self.output ||= $stdout
     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
 
-    attr_accessor :base_url, :output, :connect_timeout, :read_timeout,
-      :write_timeout, :debug, :user_agent
+    # The base_url attribute accessor allows reading and setting the base URL
+    # of the Ollama API endpoint.
+    #
+    # @attr [ URI ] the new base URL to be set for API requests
+    attr_accessor :base_url
+
+    # The output attribute accessor allows reading and setting the output stream
+    # used for handling responses and messages.
+    #
+    # @attr [ IO ] the new output stream to be set for response handling
+    attr_accessor :output
+
+    # The connect_timeout attribute accessor allows reading and setting the
+    # connection timeout value.
+    #
+    # @attr [ Integer, nil ] the new connection timeout value to be set
+    attr_accessor :connect_timeout
+
+    # The read_timeout attribute accessor allows reading and setting the read
+    # timeout value.
+    #
+    # @attr [ Integer, nil ] the new read timeout value to be set
+    attr_accessor :read_timeout
+
+    # The write_timeout attribute accessor allows reading and setting the write
+    # timeout value.
+    #
+    # @attr [ Integer, nil ] the new write timeout value to be set
+    attr_accessor :write_timeout
+
+    # The debug attribute accessor allows reading and setting the debug flag.
+    #
+    # @attr [ Boolean, nil ] the new debug flag value to be set
+    attr_accessor :debug
+
+    # The user_agent attribute accessor allows reading and setting the user
+    # agent string used for making requests to the Ollama API.
+    #
+    # @attr [ String, nil ] the new user agent string to be set for API requests
+    attr_accessor :user_agent
   end
 
   extend Tins::Concern
 
-  module ClassMethods
+  class_methods do
+    # The configure_with method initializes a new client instance using the
+    # provided configuration object.
+
+    # This method takes a configuration object and uses its attributes to set
+    # up a new Ollama::Client instance. It extracts individual configuration
+    # parameters from the input object and passes them to the client's
+    # constructor, allowing for flexible initialization based on pre-defined
+    # settings.
+
+    # @param config [ Ollama::Client::Configuration::Config ] the configuration
+    # object containing client settings
+    #
+    # @return [ Ollama::Client ] a new client instance configured with the
+    # provided settings
     def configure_with(config)
       new(
         base_url:        config.base_url,

data/lib/ollama/client/doc.rb

@@ -1,5 +1,15 @@
 require 'term/ansicolor'
 
+# A class that generates documentation links for Ollama API commands.
+#
+# This class is responsible for creating human-readable documentation
+# references for various Ollama API endpoints. It maps command names to their
+# corresponding documentation URLs, providing easy access to API documentation
+# for developers working with the Ollama client.
+#
+# @example Generating a documentation link for a command
+#   doc = Ollama::Client::Doc.new(:generate)
+#   puts doc.to_s # => hyperlink to generate command documentation
 class Ollama::Client::Doc
   include Term::ANSIColor
 
@@ -22,6 +32,14 @@ class Ollama::Client::Doc
     )[name]
   end
 
+  # The to_s method converts the documentation object to a string representation.
+  #
+  # This method generates a human-readable string that includes a hyperlink to the
+  # corresponding Ollama API documentation for the command, if a URL is available.
+  # The resulting string can be used for display purposes or logging.
+  #
+  # @return [ String ] a string representation containing the formatted documentation link
+  #                     or an empty string if no URL is defined for the command
   def to_s
     (hyperlink(@url) { @name } if @url).to_s
   end

data/lib/ollama/client.rb

@@ -1,3 +1,16 @@
+# A class that serves as the main entry point for interacting with the Ollama API.
+#
+# The Client class provides methods to communicate with an Ollama server, handling
+# various API endpoints such as chat, generate, create, and model management commands.
+# It manages configuration settings like base URL, timeouts, and output streams,
+# and supports different response handlers for processing API results.
+#
+# @example Initializing a client with a base URL
+#   client = Ollama::Client.new(base_url: 'http://localhost:11434')
+#
+# @example Configuring a client using a configuration object
+#   config = Ollama::Client::Config[base_url: 'http://localhost:11434']
+#   client = Ollama::Client.configure_with(config)
 class Ollama::Client
 end
 require 'ollama/client/doc'
@@ -12,6 +25,22 @@ class Ollama::Client
 
   annotate :doc
 
+  # The initialize method sets up a new client instance with the specified configuration parameters.
+  #
+  # This method is responsible for initializing a new Ollama::Client instance by processing
+  # various configuration options including the base URL, output stream, timeouts, and debug settings.
+  # It handles default values for the base URL by falling back to an environment variable,
+  # validates that the base URL is a valid HTTP or HTTPS URI, and extracts SSL verification
+  # settings from query parameters. The method also sets up instance variables for all
+  # configuration options, making them available for use in subsequent client operations.
+  #
+  # @param base_url [ String, nil ] the base URL of the Ollama API endpoint, defaults to nil
+  # @param output [ IO ] the output stream to be used for handling responses, defaults to $stdout
+  # @param connect_timeout [ Integer, nil ] the connection timeout value in seconds, defaults to nil
+  # @param read_timeout [ Integer, nil ] the read timeout value in seconds, defaults to nil
+  # @param write_timeout [ Integer, nil ] the write timeout value in seconds, defaults to nil
+  # @param debug [ Boolean, nil ] the debug flag indicating whether debug output is enabled, defaults to nil
+  # @param user_agent [ String, nil ] the user agent string to be used for API requests, defaults to nil
   def initialize(base_url: nil, output: $stdout, connect_timeout: nil, read_timeout: nil, write_timeout: nil, debug: nil, user_agent: nil)
     base_url.nil? and base_url = ENV.fetch('OLLAMA_URL') do
       raise ArgumentError,
@@ -27,14 +56,39 @@ class Ollama::Client
       base_url, output, connect_timeout, read_timeout, write_timeout, debug, user_agent
   end
 
+  # The output attribute accessor allows reading and setting the output stream
+  # used for handling responses and messages.
+  #
+  # @attr [ IO ] the output stream, typically $stdout, to which responses and
+  #         messages are written
   attr_accessor :output
 
+  # The base_url attribute reader returns the base URL used for making requests to the Ollama API.
+  #
+  # @return [ URI ] the base URL configured for API requests
   attr_reader :base_url
 
+  # The ssl_verify_peer? method checks whether SSL peer verification is enabled.
+  #
+  # This method returns a boolean value indicating if the client should verify
+  # the SSL certificate of the Ollama server during communication. It converts
+  # the internal SSL verification flag to a boolean value for easy checking.
+  #
+  # @return [ TrueClass, FalseClass ] true if SSL peer verification is enabled,
+  #         false otherwise
   def ssl_verify_peer?
     !!@ssl_verify_peer
   end
 
+  # Defines a command method with its associated command class and handlers.
+  #
+  # This is an example of Ruby's metaprogramming capabilities where we dynamically
+  # create methods that delegate to specific command classes. The client supports
+  # many commands including chat, generate, tags, show, create, copy, delete,
+  # pull, push, embed, embeddings, ps, and version.
+  #
+  # @example Generated command method
+  #   client.chat(model: 'llama3.1', messages: [{role: 'user', content: 'Hello'}])
   command(:chat, default_handler: Single, stream_handler: Collector)
 
   command(:generate, default_handler: Single, stream_handler: Collector)
@@ -61,15 +115,45 @@ class Ollama::Client
 
   command(:version, default_handler: Single)
 
+  # The commands method retrieves and sorts the documented commands available
+  # in the client.
+  #
+  # This method extracts all command annotations from the class, sorts them by
+  # their names, and returns an array containing only the command names in
+  # alphabetical order.
+  #
+  # @return [ Array<String> ] an array of command names sorted alphabetically
   def commands
     doc_annotations.sort_by(&:first).transpose.last
   end
 
   doc Doc.new(:help)
+  # The help method displays a list of available commands to the output stream.
+  #
+  # This method retrieves the sorted list of documented commands from the client
+  # and outputs them as a comma-separated string to the configured output stream.
+  # It is typically used to provide users with information about which commands
+  # are available for execution through the client interface.
   def help
     @output.puts "Commands: %s" % commands.join(?,)
   end
 
+  # The request method sends an HTTP request to the Ollama API and processes
+  # responses through a handler.
+  #
+  # This method constructs an HTTP request to the specified API endpoint,
+  # handling both streaming and non-streaming responses. It manages different
+  # HTTP status codes, including success (200), not found (404), and other
+  # error cases. The method also includes comprehensive error handling for
+  # network-related issues such as socket errors and timeouts.
+  #
+  # @param method [ Symbol ] the HTTP method to use for the request (:get, :post, :delete)
+  # @param path [ String ] the API endpoint path to request
+  # @param handler [ Ollama::Handler ] the handler object responsible for processing API responses
+  # @param body [ String, nil ] the request body content, if applicable
+  # @param stream [ TrueClass, FalseClass, nil ] whether to enable streaming for the operation
+  #
+  # @return [ Ollama::Client ] returns the client instance itself after initiating the request
   def request(method:, path:, handler:, body: nil, stream: nil)
     url = @base_url + path
     responses = Enumerator.new do |yielder|
@@ -105,14 +189,28 @@ class Ollama::Client
     raise Ollama::Errors::Error, "Caught #{e.class} #{e.message.inspect} for #{url.to_s.inspect}"
   end
 
+  # The inspect method returns a string representation of the client instance.
+  #
+  # This method provides a human-readable description of the client object,
+  # including its class name and the base URL it is configured to use.
+  #
+  # @return [ String ] a string representation in the format "#<Ollama::Client@http://localhost:11434>"
   def inspect
-    "#<#{self.class}@#{@base_url.to_s}>"
+    "#<#{self.class}@#{@base_url}>"
   end
 
   alias to_s inspect
 
   private
 
+  # The headers method constructs and returns a hash of HTTP headers.
+  #
+  # This method generates a set of standard HTTP headers required for making
+  # requests to the Ollama API, including the User-Agent and Content-Type. It
+  # uses the instance's configured user agent or falls back to the class-level
+  # user agent if none is set.
+  #
+  # @return [ Hash ] a hash containing the HTTP headers with keys 'User-Agent' and 'Content-Type'
   def headers
     {
       'User-Agent'   => @user_agent || self.class.user_agent,
@@ -120,10 +218,29 @@ class Ollama::Client
     }
   end
 
+  # The user_agent method generates a formatted user agent string for API requests.
+  #
+  # This method creates a user agent identifier that combines the class name
+  # with the library version, which is used to identify the client making
+  # requests to the Ollama API.
+  #
+  # @return [ String ] a formatted user agent string in the format "Ollama::Client/1.2.3"
   def self.user_agent
     '%s/%s' % [ self, Ollama::VERSION ]
   end
 
+  # The excon method creates and returns a new Excon client instance configured
+  # with the receiver's timeout and debugging settings.
+  #
+  # This method constructs an Excon client object using the provided URL and
+  # configures it with connection, read, and write timeouts, SSL verification
+  # settings, and debug mode based on the instance variables of the receiver.
+  # It compacts the parameters hash to remove any nil values before passing
+  # them to Excon.new.
+  #
+  # @param url [ String ] the URL to be used for the Excon client
+  #
+  # @return [ Excon ] a new Excon client instance configured with the specified parameters
   def excon(url)
     params = {
       connect_timeout: @connect_timeout,
@@ -135,9 +252,21 @@ class Ollama::Client
     Excon.new(url, params)
   end
 
+  # The parse_json method attempts to parse a JSON string into a structured
+  # object.
+  #
+  # This method takes a string containing JSON data and converts it into a Ruby
+  # object using the JSON.parse method. It specifies Ollama::Response as the
+  # object class to ensure that the parsed data is wrapped in the appropriate
+  # response structure.
+  #
+  # @param string [ String ] the JSON string to be parsed
+  #
+  # @return [ Ollama::Response, nil ] the parsed JSON object or nil if parsing fails
   def parse_json(string)
     JSON.parse(string, object_class: Ollama::Response)
-  rescue JSON::ParserError
+  rescue JSON::ParserError => e
+    warn "Caught #{e.class}: #{e}"
     return
   end
 end

data/lib/ollama/commands/chat.rb

@@ -1,20 +1,115 @@
+# A command class that represents the chat API endpoint for Ollama.
+#
+# This class is used to interact with the Ollama API's chat endpoint, which
+# generates conversational responses using a specified model. It inherits from
+# the base command structure and provides the necessary functionality to execute
+# chat requests for interactive conversations with language models.
+#
+# @example Initiating a chat conversation
+#   messages = [
+#     Ollama::Message.new(role: 'user', content: 'Hello, how are you?'),
+#     Ollama::Message.new(role: 'assistant', content: 'I am doing well, thank you!')
+#   ]
+#   chat = ollama.chat(model: 'llama3.1', stream: true, messages:)
 class Ollama::Commands::Chat
   include Ollama::DTO
 
+  # The path method returns the API endpoint path for chat requests.
+  #
+  # This class method provides the specific URL path used to interact with the
+  # Ollama API's chat endpoint. It is utilized internally by the command
+  # structure to determine the correct API route for conversational interactions.
+  #
+  # @return [ String ] the API endpoint path '/api/chat' for chat requests
   def self.path
     '/api/chat'
   end
 
+  # The initialize method sets up a new instance with streaming behavior.
+  #
+  # This method is responsible for initializing a new object instance and
+  # configuring it with parameters required for chat interactions. It sets up
+  # the model, conversation messages, tools, format, options, streaming behavior,
+  # keep-alive duration, and thinking mode.
+  #
+  # @param model [ String ] the name of the model to use for chat responses
+  # @param messages [ Array<Ollama::Message>, Hash, nil ] conversation history with roles and content
+  # @param tools [ Array<Ollama::Tool>, Hash, nil ] tools available for function calling
+  # @param format [ String, nil ] response format (e.g., 'json')
+  # @param options [ Ollama::Options, nil ] configuration parameters for the model
+  # @param stream [ TrueClass, FalseClass, nil ] whether to enable streaming for the operation
+  # @param keep_alive [ String, nil ] duration to keep the model loaded in memory
+  # @param think [ Boolean, nil ] whether to enable thinking mode for reasoning
   def initialize(model:, messages:, tools: nil, format: nil, options: nil, stream: nil, keep_alive: nil, think: nil)
     @model, @messages, @tools, @format, @options, @stream, @keep_alive, @think =
       model, as_array_of_hashes(messages), as_array_of_hashes(tools),
       format, options, stream, keep_alive, think
   end
 
-  attr_reader :model, :messages, :tools, :format, :options, :stream, :keep_alive, :think
+  # The model attribute reader returns the model name associated with the object.
+  #
+  # @return [ String ] the name of the model to use for chat responses
+  attr_reader :model
 
+  # The messages attribute reader returns the conversation history associated with the object.
+  #
+  # @return [ Array<Ollama::Message>, nil ] conversation history with roles and content
+  attr_reader :messages
+
+  # The tools attribute reader returns the available tools associated with the object.
+  #
+  # @return [ Array<Ollama::Tool>, nil ] tools available for function calling
+  attr_reader :tools
+
+  # The format attribute reader returns the response format associated with the object.
+  #
+  # @return [ String, nil ] response format (e.g., 'json')
+  attr_reader :format
+
+  # The options attribute reader returns the model configuration parameters associated with the object.
+  #
+  # @return [ Ollama::Options, nil ] configuration parameters for the model
+  attr_reader :options
+
+  # The stream attribute reader returns the streaming behavior setting
+  # associated with the object.
+  #
+  # @return [ TrueClass, FalseClass, nil ] the streaming behavior flag, indicating whether
+  #         streaming is enabled for the command execution (nil by default)
+  attr_reader :stream
+
+  # The keep_alive attribute reader returns the keep-alive duration associated with the object.
+  #
+  # @return [ String, nil ] duration to keep the model loaded in memory
+  attr_reader :keep_alive
+
+  # The think attribute reader returns the thinking mode setting associated with the object.
+  #
+  # @return [ Boolean, nil ] whether thinking mode is enabled for reasoning
+  attr_reader :think
+
+  # 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 POST request to the Ollama API's chat endpoint,
+  # 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/copy.rb

@@ -1,18 +1,76 @@
+# A command class that represents the copy API endpoint for Ollama.
+#
+# This class is used to interact with the Ollama API's copy endpoint, which
+# creates a copy of an existing model with a new name. It inherits from the base
+# command structure and provides the necessary functionality to execute copy
+# requests for model duplication.
+#
+# @example Copying a model to a new name
+#   copy = ollama.copy(source: 'llama3.1', destination: 'user/llama3.1')
 class Ollama::Commands::Copy
   include Ollama::DTO
 
+  # The path method returns the API endpoint path for copy requests.
+  #
+  # This class method provides the specific URL path used to interact with the
+  # Ollama API's copy endpoint. It is utilized internally by the command
+  # structure to determine the correct API route for duplicating models.
+  #
+  # @return [ String ] the API endpoint path '/api/copy' for copy requests
   def self.path
     '/api/copy'
   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 the source and destination model names. It explicitly
+  # disables streaming since copy operations are typically non-streaming.
+  #
+  # @param source [ String ] the name of the source model to be copied
+  # @param destination [ String ] the name of the new model to be created
   def initialize(source:, destination:)
     @source, @destination, @stream = source, destination, false
   end
 
-  attr_reader :source, :destination, :stream
+  # The source attribute reader returns the source model name associated with the object.
+  #
+  # @return [ String ] the name of the source model to be copied
+  attr_reader :source
 
+  # The destination attribute reader returns the destination model name associated with the object.
+  #
+  # @return [ String ] the name of the new model to be created
+  attr_reader :destination
+
+  # The stream attribute reader returns the streaming behavior setting
+  # associated with the object.
+  #
+  # @return [ FalseClass ] the streaming behavior flag, indicating whether
+  #         streaming is enabled for the command execution (always false for copy commands)
+  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 POST request to the Ollama API's copy endpoint,
+  # utilizing the client instance to send the request and process responses
+  # through the provided handler. It handles non-streaming scenarios since
+  # copy commands do not support streaming.
+  #
+  # @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