ollama-ruby 1.4.0 → 1.6.0

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

data/lib/ollama/commands/embed.rb

@@ -1,20 +1,101 @@
+# A command class that represents the embed API endpoint for Ollama.
+#
+# This class is used to interact with the Ollama API's embed endpoint, which
+# generates embeddings for text input using a specified model. It inherits from
+# the base command structure and provides the necessary functionality to execute
+# embedding requests for generating vector representations of text.
+#
+# @example Generating embeddings for a single text
+#   embed = ollama.embed(model: 'all-minilm', input: 'Why is the sky blue?')
+#
+# @example Generating embeddings for multiple texts
+#   embed = ollama.embed(model: 'all-minilm', input: ['Why is the sky blue?', 'Why is the grass green?'])
 class Ollama::Commands::Embed
   include Ollama::DTO
 
+  # The path method returns the API endpoint path for embed requests.
+  #
+  # This class method provides the specific URL path used to interact with the
+  # Ollama API's embed endpoint. It is utilized internally by the command
+  # structure to determine the correct API route for generating embeddings.
+  #
+  # @return [ String ] the API endpoint path '/api/embed' for embed requests
   def self.path
     '/api/embed'
   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 parameters required for embedding operations. It sets
+  # up the model, input text(s), and optional parameters while explicitly
+  # disabling streaming since embedding operations are typically non-streaming.
+  #
+  # @param model [ String ] the name of the model to use for generating embeddings
+  # @param input [ String, Array<String> ] the text input(s) to generate embeddings for
+  # @param options [ Ollama::Options, nil ] optional configuration parameters for the model
+  # @param truncate [ Boolean, nil ] whether to truncate the input if it exceeds context length
+  # @param keep_alive [ String, nil ] duration to keep the model loaded in memory
   def initialize(model:, input:, options: nil, truncate: nil, keep_alive: nil)
     @model, @input, @options, @truncate, @keep_alive =
       model, input, options, truncate, keep_alive
     @stream = false
   end
 
-  attr_reader :model, :input, :options, :truncate, :keep_alive, :stream
+  # The model attribute reader returns the model name associated with the object.
+  #
+  # @return [ String ] the name of the model used by the command instance
+  attr_reader :model
 
+  # The input attribute reader returns the text input(s) associated with the object.
+  #
+  # @return [ String, Array<String> ] the text input(s) to generate embeddings for
+  attr_reader :input
+
+  # The options attribute reader returns the model configuration options associated with the object.
+  #
+  # @return [ Ollama::Options, nil ] optional configuration parameters for the model
+  attr_reader :options
+
+  # The truncate attribute reader returns the truncate setting associated with the object.
+  #
+  # @return [ Boolean, nil ] whether to truncate the input if it exceeds context length
+  attr_reader :truncate
+
+  # 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 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 embed 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 embed endpoint,
+  # utilizing the client instance to send the request and process responses
+  # through the provided handler. It handles non-streaming scenarios since
+  # embedding 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/embeddings.rb

@@ -1,19 +1,90 @@
+# A command class that represents the embeddings API endpoint for Ollama.
+#
+# This class is used to interact with the Ollama API's embeddings endpoint, which
+# generates embeddings for text input using a specified model. It inherits from
+# the base command structure and provides the necessary functionality to execute
+# embedding requests for generating vector representations of text.
+#
+# @example Generating embeddings for a prompt
+#   embeddings = ollama.embeddings(model: 'mxbai-embed-large', prompt: 'The sky is blue because of rayleigh scattering')
 class Ollama::Commands::Embeddings
   include Ollama::DTO
 
+  # The path method returns the API endpoint path for embeddings requests.
+  #
+  # This class method provides the specific URL path used to interact with the
+  # Ollama API's embeddings endpoint. It is utilized internally by the command
+  # structure to determine the correct API route for generating embeddings.
+  #
+  # @return [ String ] the API endpoint path '/api/embeddings' for embeddings requests
   def self.path
     '/api/embeddings'
   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 parameters required for embedding operations. It sets
+  # up the model, prompt text, and optional parameters while explicitly
+  # disabling streaming since embedding operations are typically non-streaming.
+  #
+  # @param model [ String ] the name of the model to use for generating embeddings
+  # @param prompt [ String ] the text prompt to generate embeddings for
+  # @param options [ Ollama::Options, nil ] optional configuration parameters for the model
+  # @param keep_alive [ String, nil ] duration to keep the model loaded in memory
   def initialize(model:, prompt:, options: nil, keep_alive: nil)
     @model, @prompt, @options, @keep_alive, @stream =
       model, prompt, options, keep_alive, false
   end
 
-  attr_reader :model, :prompt, :options, :keep_alive, :stream
+  # The model attribute reader returns the model name associated with the object.
+  #
+  # @return [ String ] the name of the model used by the command instance
+  attr_reader :model
 
+  # The prompt attribute reader returns the text prompt associated with the object.
+  #
+  # @return [ String ] the text prompt to generate embeddings for
+  attr_reader :prompt
+
+  # The options attribute reader returns the model configuration options associated with the object.
+  #
+  # @return [ Ollama::Options, nil ] optional configuration parameters for the model
+  attr_reader :options
+
+  # 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 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 embeddings 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 embeddings endpoint,
+  # utilizing the client instance to send the request and process responses
+  # through the provided handler. It handles non-streaming scenarios since
+  # embeddings 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/generate.rb

@@ -1,20 +1,136 @@
+# A command class that represents the generate API endpoint for Ollama.
+#
+# This class is used to interact with the Ollama API's generate endpoint, which
+# generates text completions using a specified model. It inherits from the base
+# command structure and provides the necessary functionality to execute
+# generation requests for text completion tasks.
+#
+# @example Generating a text completion
+#   generate = ollama.generate(model: 'llama3.1', prompt: 'Why is the sky blue?')
+#
+# @example Generating with streaming enabled
+#   generate = ollama.generate(model: 'llama3.1', prompt: 'Why is the sky blue?', stream: true)
 class Ollama::Commands::Generate
   include Ollama::DTO
 
+  # The path method returns the API endpoint path for generate requests.
+  #
+  # This class method provides the specific URL path used to interact with the
+  # Ollama API's generate endpoint. It is utilized internally by the command
+  # structure to determine the correct API route for text generation operations.
+  #
+  # @return [ String ] the API endpoint path '/api/generate' for generate requests
   def self.path
     '/api/generate'
   end
 
+  # The initialize method sets up a new instance with default streaming behavior.
+  #
+  # This method is responsible for initializing a Generate command object with
+  # all the necessary parameters for text generation. It handles optional
+  # parameters and ensures proper data types (e.g., converting images to arrays).
+  #
+  # @param model [ String ] the name of the model to use for generation
+  # @param prompt [ String ] the text prompt to generate completions for
+  # @param suffix [ String, nil ] optional suffix to append to the generated text
+  # @param images [ Ollama::Image, Array<Ollama::Image>, nil ] optional image(s) to include in the request
+  # @param format [ String, nil ] optional format specification for the response
+  # @param options [ Ollama::Options, nil ] optional configuration parameters for the model
+  # @param system [ String, nil ] optional system message to set context for generation
+  # @param template [ String, nil ] optional template to use for formatting the prompt
+  # @param context [ Array<Integer>, nil ] optional context vector for continuation
+  # @param stream [ Boolean, nil ] whether to stream responses (default: false)
+  # @param raw [ Boolean, nil ] whether to return raw output without formatting
+  # @param keep_alive [ String, nil ] duration to keep the model loaded in memory
+  # @param think [ Boolean, nil ] whether to enable thinking mode for generation
   def initialize(model:, prompt:, suffix: nil, images: nil, format: nil, options: nil, system: nil, template: nil, context: nil, stream: nil, raw: nil, keep_alive: nil, think: nil)
     @model, @prompt, @suffix, @images, @format, @options, @system, @template, @context, @stream, @raw, @keep_alive, @think =
       model, prompt, suffix, (Array(images) if images), format, options, system, template, context, stream, raw, keep_alive, think
   end
 
-  attr_reader :model, :prompt, :suffix, :images, :format, :options, :system,
-    :template, :context, :stream, :raw, :keep_alive, :think
+  # The model attribute reader returns the model name associated with the generate command.
+  #
+  # @return [ String ] the name of the model used for generation
+  attr_reader :model
 
+  # The prompt attribute reader returns the text prompt used for generation.
+  #
+  # @return [ String ] the text prompt to generate completions for
+  attr_reader :prompt
+
+  # The suffix attribute reader returns any suffix that was appended to the generated text.
+  #
+  # @return [ String, nil ] optional suffix to append to the generated text
+  attr_reader :suffix
+
+  # The images attribute reader returns image objects associated with the generate command.
+  #
+  # @return [ Array<Ollama::Image>, nil ] array of image objects, or nil if none provided
+  attr_reader :images
+
+  # The format attribute reader returns the format specification for the response.
+  #
+  # @return [ String, nil ] optional format specification for the response
+  attr_reader :format
+
+  # The options attribute reader returns configuration parameters for the model.
+  #
+  # @return [ Ollama::Options, nil ] optional configuration parameters for the model
+  attr_reader :options
+
+  # The system attribute reader returns the system message that sets context for generation.
+  #
+  # @return [ String, nil ] optional system message to set context for generation
+  attr_reader :system
+
+  # The template attribute reader returns the template used for formatting the prompt.
+  #
+  # @return [ String, nil ] optional template to use for formatting the prompt
+  attr_reader :template
+
+  # The context attribute reader returns the context vector for continuation.
+  #
+  # @return [ Array<Integer>, nil ] optional context vector for continuation
+  attr_reader :context
+
+  # The stream attribute reader returns whether responses will be streamed.
+  #
+  # @return [ Boolean, nil ] whether to stream responses (default: false)
+  attr_reader :stream
+
+  # The raw attribute reader returns whether raw output without formatting should be returned.
+  #
+  # @return [ Boolean, nil ] whether to return raw output without formatting
+  attr_reader :raw
+
+  # The keep_alive attribute reader returns the duration to keep the model loaded in memory.
+  #
+  # @return [ String, nil ] duration to keep the model loaded in memory
+  attr_reader :keep_alive
+
+  # The think attribute reader returns whether thinking mode is enabled for generation.
+  #
+  # @return [ Boolean, nil ] whether to enable thinking mode for generation
+  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 the generate command using the specified handler.
+  #
+  # This method sends a POST request to the Ollama API's generate endpoint with
+  # the command parameters serialized as JSON. It delegates to the client's request
+  # method for actual HTTP communication.
+  #
+  # @param handler [ Ollama::Handler ] the handler to process responses from the API
+  # @return [ void ]
   def perform(handler)
     @client.request(method: :post, path: self.class.path, body: to_json, stream:, handler:)
   end

data/lib/ollama/commands/ps.rb

@@ -1,18 +1,73 @@
+# A command class that represents the ps API endpoint for Ollama.
+#
+# This class is used to interact with the Ollama API's ps endpoint, which
+# retrieves information about running models. It inherits from the base command
+# structure and provides the necessary functionality to execute ps requests
+# for monitoring active model processes.
+#
+# @example Retrieving information about running models
+#   ps = ollama.ps
+#   ps.models # => array of running model information
 class Ollama::Commands::Ps
+  # The path method returns the API endpoint path for ps requests.
+  #
+  # This class method provides the specific URL path used to interact with the
+  # Ollama API's ps endpoint. It is utilized internally by the command
+  # structure to determine the correct API route for retrieving information
+  # about running models.
+  #
+  # @return [ String ] the API endpoint path '/api/ps' for ps requests
   def self.path
     '/api/ps'
   end
 
+  # The initialize method sets up a new instance with streaming disabled.
+  #
+  # This method is responsible for initializing a new object instance and
+  # configuring it with a default setting that disables streaming behavior.
+  # It is typically called during the object creation process to establish
+  # the initial state of the instance.
+  #
+  # @param parameters [ Hash ] a hash containing initialization parameters
+  #                           (must be empty for this command)
+  #
+  # @raise [ ArgumentError ] if any parameters are provided (ps endpoint
+  #                           does not accept parameters)
   def initialize(**parameters)
     parameters.empty? or raise ArgumentError,
       "Invalid parameters: #{parameters.keys * ' '}"
     @stream = false
   end
 
+  # The stream attribute reader returns the streaming behavior setting
+  # associated with the object.
+  #
+  # @return [ TrueClass, FalseClass ] the streaming behavior flag, indicating
+  #         whether streaming is enabled for the command execution
+  #         (always false for ps 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 GET request to the Ollama API's ps endpoint,
+  # utilizing the client instance to send the request and process responses
+  # through the provided handler. It handles non-streaming scenarios since
+  # ps 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: :get, path: self.class.path, stream:, handler:)
   end