ollama-ruby 1.5.0 → 1.6.0

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

data/lib/ollama/commands/create.rb

@@ -1,20 +1,131 @@
+# A command class that represents the create API endpoint for Ollama.
+#
+# This class is used to interact with the Ollama API's create endpoint, which
+# creates a new model based on a modelfile or existing model. It inherits from
+# the base command structure and provides the necessary functionality to execute
+# model creation requests.
+#
+# @example Creating a new model from an existing model
+#   create = ollama.create(model: 'llama3.1-wopr', from: 'llama3.1', system: 'You are WOPR from WarGames')
+#
+# @example Creating a model with files and parameters
+#   create = ollama.create(
+#     model: 'my-model',
+#     from: 'llama3.1',
+#     files: { 'modelfile' => 'FROM llama3.1\nPARAMETER temperature 0.7' },
+#     parameters: Ollama::Options.new(temperature: 0.7, num_ctx: 8192)
+#   )
 class Ollama::Commands::Create
   include Ollama::DTO
 
+  # The path method returns the API endpoint path for create requests.
+  #
+  # This class method provides the specific URL path used to interact with the
+  # Ollama API's create endpoint. It is utilized internally by the command
+  # structure to determine the correct API route for creating new models.
+  #
+  # @return [ String ] the API endpoint path '/api/create' for create requests
   def self.path
     '/api/create'
   end
 
+  # The initialize method sets up a new instance with streaming enabled by default.
+  #
+  # This method is responsible for initializing a new object instance and
+  # configuring it with parameters required for model creation. It sets up the
+  # model name, source model (if any), files, adapters, template, license,
+  # system prompt, parameters, messages, and streaming behavior.
+  #
+  # @param model [ String ] the name of the new model to be created
+  # @param from [ String, nil ] the base model to create from (e.g., 'llama3.1')
+  # @param files [ Hash, nil ] file contents for the modelfile and other files
+  # @param adapters [ Hash, nil ] adapter files to use for quantization
+  # @param template [ String, nil ] the template to use for the model
+  # @param license [ String, Array<String>, nil ] the license(s) for the model
+  # @param system [ String, nil ] the system prompt to use for the model
+  # @param parameters [ Ollama::Options, nil ] configuration parameters for the model
+  # @param messages [ Array<Ollama::Message>, nil ] initial conversation messages
+  # @param stream [ TrueClass, FalseClass ] whether to enable streaming for the operation, defaults to true
+  # @param quantize [ String, nil ] quantization method to use (e.g., 'Q4_0')
   def initialize(model:, from: nil, files: nil, adapters: nil, template: nil, license: nil, system: nil, parameters: nil, messages: nil, stream: true, quantize: nil)
     @model, @from, @files, @adapters, @license, @system, @parameters, @messages, @stream, @quantize =
       model, from, as_hash(files), as_hash(adapters), as_array(license), system,
       as_hash(parameters), as_array_of_hashes(messages), stream, quantize
   end
 
-  attr_reader :model, :from, :files, :adapters, :license, :system, :parameters, :messages, :stream, :quantize
+  # The model attribute reader returns the model name associated with the object.
+  #
+  # @return [ String ] the name of the new model to be created
+  attr_reader :model
 
+  # The from attribute reader returns the base model name associated with the object.
+  #
+  # @return [ String, nil ] the base model to create from (e.g., 'llama3.1')
+  attr_reader :from
+
+  # The files attribute reader returns the file contents associated with the object.
+  #
+  # @return [ Hash, nil ] file contents for the modelfile and other files
+  attr_reader :files
+
+  # The adapters attribute reader returns the adapter files associated with the object.
+  #
+  # @return [ Hash, nil ] adapter files to use for quantization
+  attr_reader :adapters
+
+  # The license attribute reader returns the license(s) associated with the object.
+  #
+  # @return [ String, Array<String>, nil ] the license(s) for the model
+  attr_reader :license
+
+  # The system attribute reader returns the system prompt associated with the object.
+  #
+  # @return [ String, nil ] the system prompt to use for the model
+  attr_reader :system
+
+  # The parameters attribute reader returns the model configuration parameters associated with the object.
+  #
+  # @return [ Ollama::Options, nil ] configuration parameters for the model
+  attr_reader :parameters
+
+  # The messages attribute reader returns the initial conversation messages associated with the object.
+  #
+  # @return [ Array<Ollama::Message>, nil ] initial conversation messages
+  attr_reader :messages
+
+  # 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 (defaults to true for create commands)
+  attr_reader :stream
+
+  # The quantize attribute reader returns the quantization method associated with the object.
+  #
+  # @return [ String, nil ] quantization method to use (e.g., 'Q4_0')
+  attr_reader :quantize
+
+  # 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 create 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/delete.rb

@@ -1,18 +1,70 @@
+# A command class that represents the delete API endpoint for Ollama.
+#
+# This class is used to interact with the Ollama API's delete endpoint, which
+# removes a specified model from the local system. It inherits from the base
+# command structure and provides the necessary functionality to execute delete
+# requests for model removal.
+#
+# @example Deleting a local model
+#   delete = ollama.delete(model: 'user/llama3.1')
 class Ollama::Commands::Delete
   include Ollama::DTO
 
+  # The path method returns the API endpoint path for delete requests.
+  #
+  # This class method provides the specific URL path used to interact with the
+  # Ollama API's delete endpoint. It is utilized internally by the command
+  # structure to determine the correct API route for removing models from local storage.
+  #
+  # @return [ String ] the API endpoint path '/api/delete' for delete requests
   def self.path
     '/api/delete'
   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 model name to be deleted. It explicitly disables
+  # streaming since delete operations are typically non-streaming.
+  #
+  # @param model [ String ] the name of the model to be deleted
   def initialize(model:)
     @model, @stream = model, false
   end
 
-  attr_reader :model, :stream
+  # The model attribute reader returns the model name associated with the object.
+  #
+  # @return [ String ] the name of the model to be deleted
+  attr_reader :model
 
+  # 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 delete 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 DELETE request to the Ollama API's delete endpoint,
+  # utilizing the client instance to send the request and process responses
+  # through the provided handler. It handles non-streaming scenarios since
+  # delete 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: :delete, path: self.class.path, body: to_json, stream:, handler:)
   end