ollama-ruby 1.14.0 → 1.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d07a44fbcf79c2fcab881a2e2f2bcbcd42c18d040498e7988abb77e3aa97a6f5
-  data.tar.gz: 4ab66fbf6953ca66c3235eb9512ce38b53371d5f2178603ff678d94b30fa9551
+  metadata.gz: e83f50382169132ae2774add6050e16e36bd9af29b5aca839007c0d48f0c51c0
+  data.tar.gz: 5b1d915ea8bbf426d4f2ae08556533e1c78e4483857a8d649b96e9f668857491
 SHA512:
-  metadata.gz: '08433690e167532e8a98c81b212cb6a82a96329121f376379c56abf5ecfae2e7e11d96ba40875357b6a83796fe018db4b9a3b5148711860400cdbbe290c0e2c1'
-  data.tar.gz: bdf0161b3c9ba895ff79927bcd515f346c1582cebddc86f14d7077a16ad39c907a406d1db8a056ac0a7d1f19bdaf58468cbb4acab56d5618112fe875199da540
+  metadata.gz: 9b0e7e583bcf8baa2fa5050ba84e1b94b890ed3d2fa8b871c72bb3a4dcf15f64ecebb6e665a6e7e49dc0f08e030cf5f5db5d0874f42f7f2f917572e03ed24672
+  data.tar.gz: edae6c2a87f761b36fa0615073a999ba16451a3558a67d1d114f7cf510cdafaf44062ced275d21f1ea807c3badd0e3ae9d5fa4fc0b62cb8358bdf78bcbca9f44

data/CHANGES.md

@@ -1,5 +1,24 @@
 # Changes
 
+## 2025-12-04 v1.15.0
+
+- Added documentation for `ollama_ps` executable utility in README
+- Implemented `usage` method in `ollama_ps` script with `-h` flag support
+- Enhanced `ollama_ps` script with improved CLI using `Tins::GO`
+- Added support for `-f json` and `-f yaml` output formats in `ollama_ps`
+- Refactored `ollama_ps` into `fetch_ps_models`, `interpret_models`, and
+  `ps_table` functions
+- Implemented dynamic table headings and safe navigation (`&.`) for optional
+  model fields
+- Added `-I IMAGE` flag to `ollama_cli` for sending images to visual models
+- Enabled multiple image file support with repeated `-I` flag usage
+- Integrated image handling with `Ollama::Image` infrastructure
+- Added debug mode (-d) and version info (-i) options to `ollama_cli`
+  documentation
+- Updated README.md with image support documentation and usage examples
+- Updated command-line usage help text to document new `-I` option
+- Maintained backward compatibility with existing `ollama_cli` functionality
+
 ## 2025-12-03 v1.14.0
 
 - Added `as_json` method to `Ollama::Image` class that returns base64 string

data/README.md

@@ -365,8 +365,11 @@ Usage: ollama_cli [OPTIONS]
                  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
+  -I IMAGE       image is sent to the (visual) model (can be used many times)
   -S             use streaming for generation
   -T             use thinking for generation
+  -d             enable debug mode
+  -i             display ollama server version information
   -h             this help
 
 ```
@@ -385,8 +388,8 @@ The following environment variables can be set to customize the behavior of
 
 #### Debug Mode
 
-If the `DEBUG` environment variable is set to `1`, `ollama_cli` will print out
-the values of various variables, including the base URL, model, system prompt,
+If the `ollama_cli` is given the `-d` option it will print out the values of
+various variables, including the base URL, model, system prompt,
 and options. This can be useful for debugging purposes.
 
 #### Handler Options
@@ -406,6 +409,26 @@ 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.
 
+#### Image Support
+
+The `ollama_cli` tool supports sending images to visual models. This enables
+multimodal interactions where you can provide visual context to language
+models.
+
+**Basic Usage:**
+```bash
+ollama_cli -m llava -I image.jpg -p "Describe what you see in this image"
+```
+
+**Multiple Images:**
+```bash
+ollama_cli -m qwen3-vl -I image1.jpg -I image2.png -p "Compare these images"
+```
+
+This feature works with visual language models such as `llava`, `llava-llama3`,
+and `bakllava`. The image support integrates seamlessly with existing
+functionality and follows the same patterns as other features in the library.
+
 ### `ollama_browse`
 
 The `ollama_browse` executable is a utility for exploring model tags and their
@@ -460,7 +483,76 @@ This output shows:
 **Note:** Tags are grouped by their corresponding digests, allowing users to
 easily identify equivalent versions of a model.
 
-### ollama\_chat
+### `ollama_ps`
+
+The `ollama_ps` executable is a utility script that displays information about
+running Ollama models in a formatted table. It queries the Ollama API's
+`/api/ps` endpoint and presents running models with detailed information
+including:
+
+* Model name and ID
+* Memory usage (size and processor allocation)
+* Context window length
+* Parameter count and quantization level
+* Time until expiration
+
+#### Usage
+
+```bash
+Usage: ollama_ps [OPTIONS]
+
+  -f FORMAT      output format: json, yaml, or table (default)
+  -h             this help
+```
+
+#### Environment Variables
+
+The following environment variables can be set to customize the behavior of `ollama_ps`:
+
+* `OLLAMA_URL`: The Ollama base URL.
+* `OLLAMA_HOST`: The Ollama host (used if `OLLAMA_URL` is not set).
+
+#### Output
+
+The script displays a formatted table with columns:
+
+* **NAME** - Model name
+* **ID** - Truncated model digest
+* **SIZE** - Human-readable model size
+* **PROCESSOR** - CPU/GPU allocation percentage
+* **CONTEXT** - Context window size
+* **PARAMS** - Parameter count (e.g., 30.5B, 23M)
+* **QUANT** - Quantization level (e.g., Q4_K_M, F16)
+* **UNTIL** - Time until model expiration
+
+Example output:
+```
+╭────────────────────┬──────────────┬──────────┬───────────┬───────────┬────────┬────────┬────────────╮
+│ NAME               │ ID           │ SIZE     │ PROCESSOR │ CONTEXT   │ PARAMS │ QUANT  │ UNTIL      │
+╞════════════════════╪══════════════╪══════════╪═══════════╪═══════════╪════════╪════════╪════════════╡
+│ qwen3-coder:latest │ 06c1097efce0 │ 28.08 GB │ 100% GPU  │ 195.31 KB │  30.5B │ Q4_K_M │ 0+23:38:37 │
+├────────────────────┼──────────────┼──────────┼───────────┼───────────┼────────┼────────┼────────────┤
+│ all-minilm:latest  │ 1b226e2802db │ 43.28 MB │ 100% GPU  │ 256.00 B  │    23M │    F16 │ 0+23:38:31 │
+╰────────────────────┴──────────────┴──────────┴───────────┴───────────┴────────┴────────┴────────────╯
+```
+
+The script supports different output formats:
+* **table** (default): Formatted table output (when no `-f` flag is provided)
+* **json**: JSON formatted output
+* **yaml**: YAML formatted output
+
+Example usage:
+```bash
+ollama_ps -f json
+ollama_ps -f yaml
+OLLAMA_URL=http://localhost:11434 ollama_ps
+```
+
+The `ollama_ps` utility is particularly useful for monitoring running models,
+checking resource usage, and managing model lifecycles in development and
+production environments.
+
+### `ollama_chat`
 
 This is a chat client that allows you to connect to an Ollama server and engage
 in conversations with Large Language Models (LLMs). It can be installed using
@@ -469,6 +561,7 @@ the following command:
 ```bash
 gem install ollama-chat
 ```
+- Set default format to **table** when no `-f` flag is provided
 
 Once installed, you can run `ollama_chat` from your terminal or command prompt.
 This will launch a chat interface where you can interact with an LLM.

data/bin/ollama_cli

@@ -122,6 +122,7 @@ def usage
                      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
+      -I IMAGE       image is sent to the (visual) model (can be used many times)
       -S             use streaming for generation
       -T             use thinking for generation
       -d             enable debug mode
@@ -132,7 +133,7 @@ def usage
   exit 0
 end
 
-opts = go 'u:m:M:s:p:P:H:c:STdih', defaults: { ?H => 'ChatStart' }
+opts = go 'u:m:M:s:p:P:H:c:I:STdih', defaults: { ?H => 'ChatStart' }
 
 opts[?h] and usage
 
@@ -150,6 +151,7 @@ options = if model_options.is_a?(Hash)
           end
 system = get_file_argument(opts[?s], default: ENV['OLLAMA_SYSTEM'])
 prompt = get_file_argument(opts[?p], default: ENV['OLLAMA_PROMPT'])
+images = opts[?I].to_a.map { Ollama::Image.for_filename(_1) }
 
 ollama = Client.configure_with(client_config)
 
@@ -200,6 +202,7 @@ ollama.generate(
   system:,
   prompt:,
   options:,
+  images: images,
   stream: !!opts[?S],
   think: !!opts[?T],
   &handler

data/bin/ollama_ps

@@ -34,6 +34,26 @@
 require 'ollama'
 include Ollama
 require 'terminal-table'
+require 'tins'
+include Tins::GO
+
+# The usage method displays the command-line usage information for the
+# application.
+#
+# This method prints a formatted help message to the standard output, showing
+# the available command-line options and their descriptions, and then exits the
+# program. It is typically called when the user requests help or when invalid
+# arguments are provided.
+def usage
+  puts <<~EOT
+    Usage: #{File.basename($0)} [OPTIONS]
+
+      -f FORMAT      output format: json, yaml, or table (default)
+      -h             this help
+
+  EOT
+  exit 0
+end
 
 # The base_url method returns the Ollama API base URL.
 #
@@ -97,44 +117,88 @@ def format_processor(size_vram, size_total)
   end
 end
 
-# The ps method retrieves and displays information about running models in a
-# formatted table.
+# The fetch_ps_models method retrieves information about running models from an
+# Ollama server.
 #
-# This method creates a new Ollama client instance, fetches the list of running
-# models, and presents the information in a structured table format showing
-# model details such as name, ID, size, processor information, context length,
-# parameters, quantization level, and expiration time.
+# This method creates a new Ollama client instance using the provided base URL,
+# executes a ps command to fetch details about currently running models, and
+# returns the array of model information if any models are running.
 #
-# @param base_url [ String, nil ] the base URL of the Ollama API endpoint, defaults to nil
-def ps
+# @return [ Array<Hash>, nil ] an array of model information hashes if models
+#   are running, or nil if no models are currently running
+def fetch_ps_models
   ollama = Client.new(base_url:)
   result = ollama.ps
   models = result.models
   models.empty? and return
+  models
+end
+
+# The interpret_models method processes an array of model objects into a
+# standardized hash format.
+#
+# This method transforms model data into a consistent structure with specific
+# keys including name, id, size, processor, context, params, quant, and until.
+#
+# @param models [ Array ] an array of model objects to be processed
+#
+# @return [ Array<Hash> ] an array of hashes containing standardized model information
+def interpret_models(models)
+  names = %w[ name id size processor context params quant until ]
+  models.map do |model|
+    hash = {}
+    names.zip(
+      [
+        model.name,
+        model.digest[0, 12],
+        format_bytes(model.size),
+        format_processor(model.size_vram, model.size),
+        format_bytes(model.context_length),
+        model.details&.parameter_size || 'n/a',
+        model.details&.quantization_level || 'n/a',
+        format_expiry(model.expires_at),
+      ]
+    ) do |n, v|
+      hash[n] = v
+    end
+    hash
+  end
+end
 
+# The ps_table method displays a formatted table of model information.
+#
+# This method takes an array of model hashes and presents them in a formatted
+# table with aligned columns, using Unicode box-drawing characters for borders.
+# It formats the size, parameters, and quantization columns to be right-aligned
+# for better readability.
+#
+# @param models [ Array<Hash> ] an array of hashes containing model information
+def ps_table(models)
   table = Terminal::Table.new
   table.style = {
     all_separators: true,
     border:         :unicode_round,
   }
-  headings = %w[ NAME ID SIZE PROCESSOR CONTEXT PARAMS QUANT UNTIL ]
+  headings = models.first.keys.map(&:upcase)
   table.headings = headings
-  models.each do |model|
-    table << [
-      model.name,
-      model.digest[0, 12],
-      format_bytes(model.size),
-      format_processor(model.size_vram, model.size),
-      format_bytes(model.context_length),
-      model.details&.parameter_size || 'n/a',
-      model.details&.quantization_level || 'n/a',
-      format_expiry(model.expires_at),
-    ]
-  end
+  models.each { |model| table << model.values }
   table.align_column(headings.index("SIZE"), :right)
   table.align_column(headings.index("PARAMS"), :right)
   table.align_column(headings.index("QUANT"), :right)
   puts table
 end
 
-ps
+opts = go 'f:h'
+
+opts[?h] and usage
+
+models = fetch_ps_models or exit
+
+case opts[?f]
+when 'json'
+  puts JSON.pretty_generate(interpret_models(models))
+when 'yaml'
+  YAML.dump(interpret_models(models), STDOUT)
+else
+  ps_table(interpret_models(models))
+end

data/lib/ollama/version.rb

@@ -1,6 +1,6 @@
 module Ollama
   # Ollama version
-  VERSION         = '1.14.0'
+  VERSION         = '1.15.0'
   VERSION_ARRAY   = VERSION.split('.').map(&:to_i) # :nodoc:
   VERSION_MAJOR   = VERSION_ARRAY[0] # :nodoc:
   VERSION_MINOR   = VERSION_ARRAY[1] # :nodoc:

data/ollama-ruby.gemspec

@@ -1,9 +1,9 @@
 # -*- encoding: utf-8 -*-
-# stub: ollama-ruby 1.14.0 ruby lib
+# stub: ollama-ruby 1.15.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "ollama-ruby".freeze
-  s.version = "1.14.0".freeze
+  s.version = "1.15.0".freeze
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib".freeze]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ollama-ruby
 version: !ruby/object:Gem::Version
-  version: 1.14.0
+  version: 1.15.0
 platform: ruby
 authors:
 - Florian Frank