ollama-ruby 1.4.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d7010b648d380dea2bb5fcfd89597af4abbb37e064905dce4e393162d9896ef5
-  data.tar.gz: ea8df217db7e0ddd70df548820c3abc73c7efa233af56ccde171dbaa087a9a92
+  metadata.gz: 4a174884d564679a1043d7a7efe61bdcdb9924e692e75918ca59d11c7af02509
+  data.tar.gz: fce0f1c512683a77fe1c074a9ea6f839432652de6e5ba2e8ae5b368f6c4febd9
 SHA512:
-  metadata.gz: 4ac32ac4fd527aa94f11b50fe72c0d22a4d326368d2d7655d090a4af9e3fea466f478574c2c0ce2d70ef1394e7f3da8709ee5f76fdbf9672004d91850d45245d
-  data.tar.gz: cfe22940814d91e3755cfc0d83b662db4ff505ac7b00980915eeaa51f63ff3b06a8a240cd926dbcf798d27c558c20c768a6f19e99119497e220c1e8fd1fd30f9
+  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,44 @@
 # 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
+  clarify argument types:
+  * Added support for `-c ` option to specify client configuration as JSON
+  * Updated documentation to clarify which arguments expect JSON input
+  * Replaced direct client initialization with `configure_with` method for
+    better maintainability
+* Update documentation for `ollama_cli` script:
+  * Reorganized usage instructions for clarity
+  * Added descriptions for new options: `-c ` and `-H `
+  * Clarified which arguments expect JSON input:
+    - `-M OPTIONS`: model options in JSON format
+    - `-s SYSTEM` and `-p PROMPT`: plain text inputs
+  * Improved formatting for better readability
+* Add `ollama_browse` to Rakefile executable tasks
+
 ## 2025-07-17 v1.4.0
 
 * **New CLI Tool**: Added `bin/ollama_browse` for exploring model tags and

data/README.md

@@ -350,26 +350,22 @@ To use `ollama_cli`, simply run it from the command line and follow the usage
 instructions:
 
 ```bash
-ollama_cli [OPTIONS]
-```
-
-The available options are:
-
-* `-u URL`: The Ollama base URL. Can be set as an environment variable
-  `OLLAMA_URL`.
-* `-m MODEL`: The Ollama model to chat with. Defaults to `llama3.1` if not
-  specified.
-* `-M OPTIONS`: The Ollama model options to use. Can be set as an environment
-  variable `OLLAMA_MODEL_OPTIONS`.
-* `-s SYSTEM`: The system prompt to use as a file. Can be set as an environment
-  variable `OLLAMA_SYSTEM`.
-* `-p PROMPT`: The user prompt to use as a file. If it contains `%{stdin}`, it
-  will be substituted with the standard input. If not given, stdin will be used
-  as the prompt.
-* `-P VARIABLE`: Sets a prompt variable, e.g. `foo=bar`. Can be used multiple
-  times.
-* `-H HANDLER`: The handler to use for the response. Defaults to `Print`.
-* `-S`: Use streaming for generation.
+Usage: ollama_cli [OPTIONS]
+
+  -u URL         the ollama base url, $OLLAMA_URL
+  -c CLIENT      the ollama client config (JSON), $OLLAMA_CLIENT
+  -m MODEL       the ollama model to chat with, $OLLAMA_MODEL
+  -M OPTIONS     the ollama model options (JSON), $OLLAMA_MODEL_OPTIONS
+  -s SYSTEM      the system prompt as plain text, $OLLAMA_SYSTEM
+  -p PROMPT      the user prompt as plain text, $OLLAMA_PROMPT
+                 if it contains %{stdin} it is substituted by stdin input
+  -P VARIABLE    sets prompt var %{foo} to "bar" if VARIABLE is foo=bar
+  -H HANDLER     the handler to use for the response, defaults to ChatStart
+  -S             use streaming for generation
+  -T             use thinking for generation
+  -h             this help
+
+```
 
 #### Environment Variables
 
@@ -377,10 +373,11 @@ The following environment variables can be set to customize the behavior of
 `ollama_cli`:
 
 * `OLLAMA_URL`: The Ollama base URL.
+* `OLLAMA_CLIENT`: The client config (JSON).
 * `OLLAMA_MODEL`: The Ollama model to chat with.
-* `OLLAMA_MODEL_OPTIONS`: The Ollama model options to use.
-* `OLLAMA_SYSTEM`: The system prompt to use as a file.
-* `OLLAMA_PROMPT`: The user prompt to use as a file.
+* `OLLAMA_MODEL_OPTIONS`: The Ollama model options (JSON).
+* `OLLAMA_SYSTEM`: The system prompt to use as plain text.
+* `OLLAMA_PROMPT`: The user prompt to use as plain text.
 
 #### Debug Mode
 
@@ -405,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,17 +16,17 @@ 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'
+  executables << 'ollama_console' << 'ollama_update' << 'ollama_cli' << 'ollama_browse'
 
   required_ruby_version  '~> 3.1'
 
   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,16 +80,21 @@ 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]
 
       -u URL         the ollama base url, $OLLAMA_URL
+      -c CLIENT      the ollama client config (JSON), $OLLAMA_CLIENT
       -m MODEL       the ollama model to chat with, $OLLAMA_MODEL
-      -M OPTIONS     the ollama model options to use, $OLLAMA_MODEL_OPTIONS
-      -s SYSTEM      the system prompt to use as a file, $OLLAMA_SYSTEM
-      -p PROMPT      the user prompt to use as a file, $OLLAMA_PROMPT
+      -M OPTIONS     the ollama model options (JSON), $OLLAMA_MODEL_OPTIONS
+      -s SYSTEM      the system prompt as plain text, $OLLAMA_SYSTEM
+      -p PROMPT      the user prompt as plain text, $OLLAMA_PROMPT
                      if it contains %{stdin} it is substituted by stdin input
       -P VARIABLE    sets prompt var %{foo} to "bar" if VARIABLE is foo=bar
       -H HANDLER     the handler to use for the response, defaults to ChatStart
@@ -83,11 +106,15 @@ def usage
   exit 0
 end
 
-opts = go 'u:m:M:s:p:P:H:STh', defaults: { ?H => 'ChatStart', ?M => '{}' }
+opts = go 'u:m:M:s:p:P:H:c:STh', defaults: { ?H => 'ChatStart' }
 
 opts[?h] and usage
 
-base_url = opts[?u] || ENV['OLLAMA_URL'] || 'http://%s' % ENV.fetch('OLLAMA_HOST')
+base_url  = opts[?u] || ENV['OLLAMA_URL'] || 'http://%s' % ENV.fetch('OLLAMA_HOST')
+client_config = Client::Config[
+  { base_url: } |
+  JSON(get_file_argument(opts[?c], default: ENV['OLLAMA_CLIENT']).full? || '{}')
+]
 model    = opts[?m] || ENV.fetch('OLLAMA_MODEL', 'llama3.1')
 options  = Ollama::Options.from_hash(JSON(
   get_file_argument(opts[?M], default: ENV['OLLAMA_MODEL_OPTIONS'])
@@ -98,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
@@ -127,7 +159,7 @@ handler = case
             handler
           end
 
-Client.new(base_url:, read_timeout: 120).generate(
+Client.configure_with(client_config).generate(
   model:,
   system:,
   prompt:,

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)