ollama-ruby 1.5.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f22498af2b68b25f11d486872f46a42ad16b94244d3f0a9cb7df9e436056894
-  data.tar.gz: aa154d720f3df668020bdf39d38c7964e7081cabcfa4daec761ebb3809bfa57f
+  metadata.gz: 4a174884d564679a1043d7a7efe61bdcdb9924e692e75918ca59d11c7af02509
+  data.tar.gz: fce0f1c512683a77fe1c074a9ea6f839432652de6e5ba2e8ae5b368f6c4febd9
 SHA512:
-  metadata.gz: a32fb5d1bd7dd225c8917c8e43b43f9983eb85c971fbe01f4993f9b0131761d467a93658d2cf50ca5db1d44da6ea20ad6885aded8a5747ea259ab3d4c261c6b2
-  data.tar.gz: 067ca2f5c9c7de901732aae837dc151e023751a935952e4c0533dd50124610c367fc6149e16c096724077bb0c8f9f0781028f7dd108a32dfd4cdf1b533af9040
+  metadata.gz: 1d9d8c43b1bc35626c97b6974d80894890e4b76dbbcc021ded7db22eed54d2bf0e82cb163a0fde53bfddda5ff8ecd34773929f29bc49efbc8b34b0823e376045
+  data.tar.gz: 0fc66f6d378a9cc0e31bb130d5cb8fa0f6b847b8cb30328bf3b0713483272d5eae6edcf5bf139a2d565e27de9b89722176806e9656e45242f8102c24c804ad9d

data/.contexts/code_comment.rb

@@ -0,0 +1,25 @@
+context do
+  namespace "lib" do
+    Dir['lib/**/*.rb'].each do |filename|
+      file filename, tags: 'lib'
+    end
+  end
+
+  namespace "spec" do
+    Dir['spec/**/*.rb'].each do |filename|
+      file filename, tags: 'spec'
+    end
+  end
+
+  file 'README.md', tags: 'documentation'
+
+  file '.contexts/yard.md', tags: [ 'yard', 'cheatsheet' ]
+
+  meta guidelins: <<~EOT
+    # Guidelines for creating YARD documentation
+
+    - Look into the file, with tags yard and cheatsheet for how comment ruby
+      constructs.
+    - In comments above initialize methods never omit @return
+  EOT
+end

data/.contexts/full.rb

@@ -0,0 +1,43 @@
+context do
+  variable project_name: Pathname.pwd.basename
+
+  variable project_version: File.read('VERSION').chomp
+
+  variable branch: `git rev-parse --abbrev-ref HEAD`.chomp
+
+  namespace "structure" do
+    command "tree", tags: %w[ project_structure ]
+  end
+
+  namespace "bin" do
+    Dir['bin/**/*'].each do |filename|
+      file filename, tags: 'bin'
+    end
+  end
+
+  namespace "lib" do
+    Dir['lib/**/*.rb'].each do |filename|
+      file filename, tags: 'lib'
+    end
+  end
+
+  namespace "spec" do
+    Dir['spec/**/*.rb'].each do |filename|
+      file filename, tags: 'spec'
+    end
+  end
+
+  namespace "gems" do
+    file Dir['*.gemspec'].first
+    file 'Gemfile'
+    file 'Gemfile.lock'
+  end
+
+  file 'Rakefile',  tags: 'gem_hadar'
+
+  file 'README.md', tags: 'documentation'
+
+  meta ruby: RUBY_DESCRIPTION
+
+  meta code_coverage: json('coverage/coverage_context.json')
+end

data/.contexts/info.rb

@@ -0,0 +1,17 @@
+context do
+  variable project_name: Pathname.pwd.basename
+
+  variable project_version: File.read('VERSION').chomp
+
+  variable branch: `git rev-parse --abbrev-ref HEAD`.chomp
+
+  namespace "structure" do
+    command "tree", tags: %w[ project_structure ]
+  end
+
+  file 'Rakefile',  tags: 'gem_hadar'
+
+  file 'README.md', tags: 'documentation'
+
+  meta ruby: RUBY_DESCRIPTION
+end

data/.contexts/lib.rb

@@ -0,0 +1,27 @@
+context do
+  variable branch: `git rev-parse --abbrev-ref HEAD`.chomp
+
+  namespace "structure" do
+    command "tree", tags: %w[ project_structure ]
+  end
+
+  namespace "lib" do
+    Dir['lib/**/*.rb'].each do |filename|
+      file filename, tags: 'lib'
+    end
+  end
+
+  namespace "gems" do
+    file Dir['*.gemspec'].first
+    file 'Gemfile'
+    file 'Gemfile.lock'
+  end
+
+  file 'Rakefile',  tags: 'gem_hadar'
+
+  file 'README.md', tags: 'documentation'
+
+  meta ruby: RUBY_DESCRIPTION
+
+  meta code_coverage: json('coverage/coverage_context.json')
+end

data/.contexts/yard.md

@@ -0,0 +1,93 @@
+# YARD CHEATSHEET http://yardoc.org
+
+## May 2020 - updated fork: https://gist.github.com/phansch/db18a595d2f5f1ef16646af72fe1fb0e
+
+cribbed from http://pastebin.com/xgzeAmBn
+
+Templates to remind you of the options and formatting for the different types of objects you might
+want to document using YARD.
+
+## Modules
+
+    # Namespace for classes and modules that handle serving documentation over HTTP
+    # @since 0.6.0
+
+## Classes
+
+    # Abstract base class for CLI utilities. Provides some helper methods for
+    # the option parser
+    #
+    # @author Full Name
+    # @abstract
+    # @since 0.6.0
+    # @attr [Types] attribute_name a full description of the attribute
+    # @attr_reader [Types] name description of a readonly attribute
+    # @attr_writer [Types] name description of writeonly attribute
+    # @deprecated Describe the reason or provide alt. references here
+
+## Methods
+
+    # An alias to {Parser::SourceParser}'s parsing method
+    #
+    # @author Donovan Bray
+    #
+    # @see http://example.com Description of URL
+    # @see SomeOtherClass#method
+    #
+    # @deprecated Use {#my_new_method} instead of this method because
+    #   it uses a library that is no longer supported in Ruby 1.9.
+    #   The new method accepts the same parameters.
+    #
+    # @abstract
+    # @private
+    #
+    # @param opts [Hash] the options to create a message with.
+    # @option opts [String] :subject The subject
+    # @option opts [String] :from ('nobody') From address
+    # @option opts [String] :to Recipient email
+    # @option opts [String] :body ('') The email's body
+    #
+    # @param (see User#initialize)
+    # @param [OptionParser] opts the option parser object
+    # @param [Array<String>] args the arguments passed from input. This
+    #   array will be modified.
+    # @param [Array<String, Symbol>] list the list of strings and symbols.
+    #
+    # The options parsed out of the commandline.
+    # Default options are:
+    #   :format => :dot
+    #
+    # @example Reverse a string
+    #   "mystring.reverse" #=> "gnirtsym"
+    #
+    # @example Parse a glob of files
+    #   YARD.parse('lib/**/*.rb')
+    #
+    # @raise [ExceptionClass] description
+    #
+    # @return [optional, types, ...] description
+    # @return [true] always returns true
+    # @return [void]
+    # @return [String, nil] the contents of our object or nil
+    #   if the object has not been filled with data.
+    #
+    # We don't care about the "type" here:
+    # @return the object
+    #
+    # @return [String, #read] a string or object that responds to #read
+    # @return description here with no types
+
+## Anywhere
+
+    # @todo Add support for Jabberwocky service
+    #   There is an open source Jabberwocky library available
+    #   at http://somesite.com that can be integrated easily
+    #   into the project.
+
+## Blocks
+
+    # for block {|a, b, c| ... }
+    # @yield [a, b, c] Description of block
+    #
+    # @yieldparam [optional, types, ...] argname description
+    # @yieldreturn [optional, types, ...] description

data/CHANGES.md

@@ -1,5 +1,27 @@
 # Changes
 
+## 2025-08-18 v1.6.0
+
+- Added **context_spook** gem as development dependency for documentation management
+and introduced new context files for project structure documentation in
+`.contexts/` directory
+- Modified `bin/ollama_cli` to use `named_placeholders` and
+  `named_placeholders_interpolate` methods for prompt variable interpolation
+- Added default value handling for missing prompt variables in `bin/ollama_cli`
+- Removed default value `{ ?M => '{}' }` for the `?M` option in command line parser
+- Displayed Ollama server version in bold and base URL with hyperlink formatting
+- Used `Term::ANSIColor` for styled output in connection status message
+- Updated `gem_hadar` development dependency to **2.0**
+- Replaced manual SimpleCov configuration with `GemHadar::SimpleCov.start`
+- Enhanced `parse_json` method in `Ollama::Client` to handle
+  `JSON::ParserError` exceptions gracefully with warnings
+- Updated `Ollama::Client` spec to test error handling behavior for invalid
+  JSON input
+- Replaced `RSpec.describe` with `describe` for cleaner test syntax
+- Added `ollama_browse` utility documentation to README.md
+- Improved nil comparison syntax in tests
+- Reset `OLLAMA_URL` environment variable after client spec tests
+
 ## 2025-07-21 v1.5.0
 
 * Update `ollama_cli` script to handle client configuration via JSON and

data/README.md

@@ -402,6 +402,60 @@ The `-S` option enables streaming for generation. This allows the model to
 generate text in chunks, rather than waiting for the entire response to be
 generated.
 
+### `ollama_browse`
+
+The `ollama_browse` executable is a utility for exploring model tags and their
+associated metadata directly from your command line. It allows you to quickly
+view details such as file sizes, context windows, and digests for different
+versions of a model hosted on the Ollama platform.
+
+#### Usage
+
+```bash
+Usage: ollama_browse MODEL
+
+MODEL is the Ollama model name (e.g., 'deepseek-v3')
+```
+
+To use `ollama_browse`, specify the model you wish to explore:
+
+```bash
+ollama_browse deepseek-v3
+```
+
+#### Output
+
+The script will display information about different versions of the specified
+model, including:
+
+- **Digest**: A unique identifier for the model version.
+- **File Size**: The size of the model file.
+- **Context Window**: The maximum context length supported by the model.
+- **Tags**: Different tags associated with the model version.
+
+Example output for `deepseek-v3`:
+
+```bash
+Model: https://ollama.com/library/deepseek-v3
+5da0e2d4a9e0 404GB 4K
+ · deepseek-v3:latest
+ · deepseek-v3:671blatest
+ · deepseek-v3:671b-q4_K_M
+96061c74c1a5 713GB 4K
+ · deepseek-v3:671b-q8_0
+7770bf5a5ed8 1.3TB 4K
+ · deepseek-v3:671b-fp16
+```
+
+This output shows:
+- Different versions of the `deepseek-v3` model.
+- Each version's digest, file size, and context window.
+- Associated tags for each version, which you can click to view more details on
+  the Ollama website.
+
+**Note:** Tags are grouped by their corresponding digests, allowing users to
+easily identify equivalent versions of a model.
+
 ### ollama\_chat
 
 This is a chat client that allows you to connect to an Ollama server and engage

data/Rakefile

@@ -16,7 +16,7 @@ GemHadar do
     '.yardoc', 'doc', 'tags', 'errors.lst', 'cscope.out', 'coverage', 'tmp',
     'yard'
   package_ignore '.all_images.yml', '.tool-versions', '.gitignore', 'VERSION',
-     '.rspec', *Dir.glob('.github/**/*', File::FNM_DOTMATCH)
+    '.rspec', '.github', '.contexts'
   readme      'README.md'
 
   executables << 'ollama_console' << 'ollama_update' << 'ollama_cli' << 'ollama_browse'
@@ -26,7 +26,7 @@ GemHadar do
   dependency             'excon',                 '~> 1.0'
   dependency             'infobar',               '~> 0.8'
   dependency             'json',                  '~> 2.0'
-  dependency             'tins',                  '~> 1.34'
+  dependency             'tins',                  '~> 1.41'
   dependency             'term-ansicolor',        '~> 1.11'
   dependency             'kramdown-ansi',         '~> 0.0', '>= 0.0.1'
   dependency             'ostruct',               '~> 0.0'
@@ -36,6 +36,7 @@ GemHadar do
   development_dependency 'webmock'
   development_dependency 'debug'
   development_dependency 'simplecov'
+  development_dependency 'context_spook'
 
   licenses << 'MIT'
 

data/bin/ollama_cli

@@ -9,17 +9,35 @@ require 'json'
 require 'tmpdir'
 
 module Ollama::Handlers
+  # A handler that starts a chat session and prints the initial response.
+  #
+  # @example
+  #   chat(model: 'llama3.1', messages: message, &ChatStart)
   class ChatStart
     include Ollama::Handlers::Concern
 
+    # The initialize method sets up a new Markdown handler instance with the
+    # specified output.
+    #
+    # @param output [IO] the output stream to write markdown content to,
+    # defaults to $stdout
     def initialize(output: $stdout)
       super
       @output.sync = true
       @content     = ''
     end
 
+    # The content attribute reader returns the textual content of the message.
+    #
+    # @return [ String ] the content of the message
     attr_reader :content
 
+    # The call method processes a response by appending its content to an
+    # internal buffer and output stream. It also appends a newline and flushes
+    # the output when the response indicates completion.
+    #
+    # @param response [Object] the response object to process
+    # @return [self] returns itself to allow for method chaining
     def call(response)
       if content = response.response
         @content << content
@@ -62,7 +80,11 @@ def get_file_argument(path_or_content, default: nil)
   end
 end
 
-# Outputs usage information for the `ollama_cli`.
+# The usage method displays the command-line usage information for the
+# ollama_cli executable.
+#
+# This method prints out a formatted help message that describes all available
+# options and their expected arguments for using the ollama_cli tool.
 def usage
   puts <<~EOT
     Usage: #{File.basename($0)} [OPTIONS]
@@ -84,7 +106,7 @@ def usage
   exit 0
 end
 
-opts = go 'u:m:M:s:p:P:H:c:STh', defaults: { ?H => 'ChatStart', ?M => '{}' }
+opts = go 'u:m:M:s:p:P:H:c:STh', defaults: { ?H => 'ChatStart' }
 
 opts[?h] and usage
 
@@ -103,13 +125,18 @@ prompt   = get_file_argument(opts[?p], default: ENV['OLLAMA_PROMPT'])
 if prompt.nil?
   prompt = STDIN.read
 else
-  vars = prompt.scan(/%\{([^}]+)\}/).inject([], &:concat).uniq.map(&:to_sym)
+  vars = prompt.named_placeholders
   stdin = (STDIN.read if vars.include?(:stdin)).to_s
   values = opts[?P].to_a.inject({ stdin: }) { |h, pair|
     n, v = pair.split(?=, 2)
     h.merge(n.to_sym => v)
   }
-  prompt = prompt % values
+  default = -> v {
+    msg = "prompt var #{v.inspect} not set"
+    STDERR.puts msg
+    "[#{msg}]"
+  }
+  prompt = prompt.named_placeholders_interpolate(values, default:)
 end
 
 if ENV['DEBUG'].to_i == 1

data/bin/ollama_console

@@ -5,10 +5,24 @@ include Ollama
 require 'irb'
 require 'irb/history'
 
+# The base_url method returns the Ollama API base URL.
+#
+# It first checks for the OLLAMA_URL environment variable.
+# If not set, it defaults to 'http://' followed by the OLLAMA_HOST environment variable.
+#
+# @return [ String ] the base URL for the Ollama API
 def base_url
   ENV['OLLAMA_URL'] || 'http://%s' % ENV.fetch('OLLAMA_HOST')
 end
 
+# The ollama method provides access to a configured Ollama client instance.
+#
+# This method initializes and returns a singleton instance of the Ollama client,
+# using the base URL specified in the base_url parameter. If an instance already
+# exists, it returns the cached version instead of creating a new one.
+#
+# @param base_url [ String ] the base URL for the Ollama API endpoint
+# @return [ Ollama::Client ] a configured Ollama client instance
 def ollama
   $ollama ||= Client.new(base_url:)
 end
@@ -21,5 +35,9 @@ if io = IRB.conf[:MAIN_CONTEXT].io and io.support_history_saving?
   io.load_history
   at_exit { io.save_history }
 end
+puts "Now connected to ollama server, version %s, at %s" % [
+  Term::ANSIColor.bold { ollama.version.version },
+  Term::ANSIColor.hyperlink(ollama.base_url) { ollama.base_url },
+]
 ollama.help
 IRB.irb nil, ollama

data/lib/ollama/client/command.rb

@@ -1,9 +1,35 @@
+# A module that provides command definition capabilities for the Ollama client.
+#
+# This module extends the client with the ability to define and execute API
+# commands by creating method definitions that correspond to Ollama API
+# endpoints. It handles the creation of command methods with appropriate
+# default and streaming handlers, and manages the execution flow for these
+# commands.
+#
+# @example Defining a custom command
+#   class MyClient
+#     include Ollama::Client::Command
+#     command(:custom, default_handler: Single, stream_handler: Collector)
+#   end
 module Ollama::Client::Command
   extend Tins::Concern
 
-  module ClassMethods
-    # Create Command `name`, if `stream` was true, set `stream_handler` as
-    # default, otherwise `default_handler`.
+  class_methods do
+    # Creates a command method for the Ollama client
+    #
+    # Defines a new command method that corresponds to an Ollama API endpoint.
+    # The command method can be invoked with parameters and an optional handler
+    # to process responses. It determines which handler to use based on whether
+    # the command supports streaming and the presence of an explicit handler.
+    #
+    # @param name [ Symbol ] the name of the command to define
+    # @param default_handler [ Class ] the default handler class to use when no explicit handler is provided
+    # @param stream_handler [ Class, nil ] the handler class to use for streaming responses, if applicable
+    #
+    # @note Create Command `name`, if `stream` was true, set `stream_handler`
+    # as default, otherwise `default_handler`.
+    #
+    # @return [ self ] returns the receiver after defining the command method
     def command(name, default_handler:, stream_handler: nil)
       klass = Ollama::Commands.const_get(name.to_s.camelize)
       doc Ollama::Client::Doc.new(name)

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