ollama_chat 0.0.24 → 0.0.26

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 905c1baa33dc4adfae423a2d7e026e6cb266bde4d629476f96767440d26d7e62
-  data.tar.gz: ab371250b1fe5cfbd0957ce22d40887658c7a11cb52beb2940ecf3cd99bf88ac
+  metadata.gz: f12c83374034666d30f5b8fdbe2e6b4f4b652ff9b418affee5117bc0d6e67fcc
+  data.tar.gz: f1ce7fca104f94ee159b1d6add90fcff3792d9e2a741d7d1f6f3cf3741646fd0
 SHA512:
-  metadata.gz: b372485a4e39a47583f30391bf036a2e193d75d9dd233d07cdc506c68a5119c5e2d11bce7ad081f6eae5988b4cf967ba001d6f232d26655d9ac0c0917cf0878e
-  data.tar.gz: 2d708c9eb72e6bfd4df164aa91509b6305d1956322b81d58c49431d8d3296d6c5a2f64001962e2fefb1edcf80c2d858fceb13a7781ab21a76e8512ae4bd440eb
+  metadata.gz: 2b6ec1e765aa5bf46200b5f308eea5b690674ebc296afcf240689385cabc91009da8145ee04b568296a7cff65d57c03e5c0c49fd38393a90abc9e659d6d4e9b2
+  data.tar.gz: c9a3db643d6efad021153f9c6cfad22f57696607354e21ca6a48dc5d3f454cf372327f31598542a1d70ad6e3fcdc4ca81b3a69c17e6c3b95dfc558a30aefc5d7

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,31 @@
+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 lib", tags: %w[ project_structure ]
+  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
+
+  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 lib", 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,25 @@
+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 lib", tags: %w[ project_structure ]
+  end
+
+  namespace "lib" do
+    Dir['lib/**/*.rb'].each do |filename|
+      file filename, tags: 'lib'
+    end
+  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,94 @@
+
+# YARD Documentation Example
+
+**You**, as an AI assistant, are tasked with generating only YARD documentation
+comments for Ruby code, not executable code itself.
+
+## Your Documentation Responsibilities
+
+When generating Ruby documentation, you must:
+
+### 1. **Generate Only Documentation Comments**
+- Provide `#` prefixed comment blocks only
+- Do not generate actual method bodies or class implementations
+- Do not include executable code like `def`, `class`, `attr_reader`, etc.
+- Focus solely on the documentation portions
+
+### 2. **Follow the Exact Structure from Example**
+Here are the documentation comments from the Document class:
+
+```ruby
+# Represents a generic document in a document management system.
+# @example How to create a document
+#   document = Document.new('Hello World')
+class Document
+  # @!attribute [r] title
+  #   @return [String]
+  attr_reader :title
+
+  # @!attribute [w] description
+  #   @return [String]
+  attr_writer :description
+
+  # @!attribute [rw] sections
+  #   @api private
+  #   @return [Array<Section>]
+  attr_accessor :sections
+
+  # Initializes a new Document instance.
+  # @note This method should be called with care.
+  #
+  # @param title [String] the title of the document
+  # @param description [String] the description of the document
+  # @param options [Hash] additional configuration options
+  # @option options [Boolean] :editable whether the document can be edited
+  # @yieldparam [String] content The content of the document.
+  # @yieldreturn [String] Returns a modified content.
+  #
+  # @raise [ArgumentError] if the title is nil
+  #
+  # @return [Document] a new Document instance
+  def initialize(title, description, options = {})
+    # Do NOT generate executable code
+  end
+
+  # Edits the document content.
+  #
+  # @overload edit(new_content)
+  #   @param new_content [String] the new content for the document
+  #   @return [Boolean] true if editing was successful, false otherwise
+  #
+  # @overload edit
+  #   @yield Gives a block to process the current content.
+  #   @yieldreturn [String] Returns the new content after processing.
+  #   @return [Boolean] true if editing was successful, false otherwise
+  #
+  # @deprecated Use `modify` method instead.
+  def edit(new_content = nil)
+    # Do NOT generate executable code
+  end
+
+  # @todo Implement a proper save mechanism
+  def save
+    # Do NOT generate executable code
+  end
+
+  # Views the document
+  #
+  # @example Viewing the document title
+  #   document.view_title #=> "Sample Document"
+  #
+  # @see #edit
+  # @return [String] the title of the document
+  def view_title
+    # Do NOT generate executable code
+  end
+end
+```
+
+## Key Rule
+
+**DO NOT GENERATE ANY EXECUTABLE CODE** - only documentation comments that
+would be placed above actual Ruby methods and classes. The example shows what
+the documentation comments should look like, not the actual executable Ruby
+code.

data/.gitignore

@@ -6,5 +6,6 @@
 Gemfile.lock
 corpus
 coverage
+doc
 pkg
 tags

data/CHANGES.md

@@ -1,5 +1,44 @@
 # Changes
 
+## 2025-08-27 v0.0.26
+
+- Enhanced `/last` command to support numeric argument, allowing users to
+  specify the number of messages to display
+- Configured tests to protect environment variables by using `protect_env:
+  true` option and direct `ENV` manipulation
+- Refactored spec helper with modularized `AssetHelpers`, `StubOllamaServer`,
+  and `ProtectEnvVars` modules for better organization
+- Improved code clarity and added comprehensive documentation across multiple
+  modules including `OllamaChat`, `Chat`, `MessageList`, and others
+- Added detailed class-level documentation for `OllamaChatConfig` with examples
+- Included documentation for the `Parsing`, `Vim`, `MessageFormat`,
+  `KramdownANSI`, `Information`, `UserAgent`, and `History` modules
+- Improved cache hit message formatting and wording for better user experience
+
+## 2025-08-18 v0.0.25
+
+- Integrated `context_spook` gem as development dependency
+- Added new context files: `.contexts/full.rb`, `.contexts/info.rb`, and
+  `.contexts/lib.rb`
+- Updated `ollama-ruby` dependency version constraint from `~> 1.2` to `~> 1.6`
+- Bumped **tins** dependency from ~> **1.34** to ~> **1.41**
+- Refactored `web` method in `chat.rb` to conditionally handle embeddings
+- Split web prompt templates into `web_embed` and `web_import`
+- Moved cache check message to display before cache retrieval
+- Fixed `show_last` behavior for empty lists with comprehensive tests
+- Added nil check to `kramdown_ansi_parse` method to prevent `NoMethodError`
+- Added documentation comments to `OllamaChat::Clipboard`,
+  `OllamaChat::Dialog`, `OllamaChat::Utils::Chooser`, and
+  `OllamaChat::Utils::FileArgument` modules
+- Added new command line option `-d DIR` to specify runtime directory for
+  socket file
+- Updated `OllamaChat::ServerSocket.send_to_server_socket` method to accept
+  `runtime_dir` parameter
+- Modified `create_socket_server` method to use provided `runtime_dir` when
+  creating Unix socket server
+- Updated help text to document the new `-d` option
+- Added separate context for `runtime_dir` parameter testing in spec
+
 ## 2025-08-17 v0.0.24
 
 - Updated `kramdown-ansi` dependency version constraint from **0.0** to **0.1**

data/README.md

@@ -153,7 +153,7 @@ The following commands can be given inside the chat, if prefixed by a `/`:
 /stream                         toggle stream output
 /location                       toggle location submission
 /voice [change]                 toggle voice output or change the voice
-/last                           show the last system/assistant message
+/last [n]                       show the last n / 1 system/assistant message
 /list [n]                       list the last n / all conversation exchanges
 /clear [what]                   clear what=messages|links|history|tags|all
 /clobber                        clear the conversation, links, and collection
@@ -177,6 +177,7 @@ The following commands can be given inside the chat, if prefixed by a `/`:
 /load filename                  load conversation messages
 /output filename                save last response to filename
 /pipe command                   write last response to command's stdin
+/vim                            insert the last message into a vim server
 /quit                           to quit
 /help                           to view this help
 ```
@@ -227,6 +228,14 @@ The `ollama_chat_send` command now supports additional parameters to enhance fun
   $ echo "Visit https://example.com for more info" | ollama_chat_send -p
   ```
 
+- **Runtime Directory (`-d`)**: Specifies the directory where the Unix socket
+  file of `ollama_chat` was created, if you want to send to a specific
+  `ollama_chat`.
+
+  ```bash
+  $ echo "Hello world" | ollama_chat_send -d /tmp/my_runtime_dir -r
+  ```
+
 - **Help (`-h` or `--help`)**: Displays usage information and available options.
 
   ```bash

data/Rakefile

@@ -21,7 +21,7 @@ GemHadar do
 
   test_dir    'spec'
   ignore      '.*.sw[pon]', 'pkg', 'Gemfile.lock', '.AppleDouble', '.bundle',
-    '.yardoc', 'tags', 'corpus', 'coverage', '/config/searxng/*'
+    '.yardoc', 'doc', 'tags', 'corpus', 'coverage', '/config/searxng/*'
 
   readme      'README.md'
 
@@ -30,7 +30,7 @@ GemHadar do
   executables << 'ollama_chat' << 'ollama_chat_send'
 
   dependency             'excon',                 '~> 1.0'
-  dependency             'ollama-ruby',           '~> 1.2'
+  dependency             'ollama-ruby',           '~> 1.6'
   dependency             'documentrix',           '~> 0.0', '>= 0.0.2'
   dependency             'unix_socks',            '>= 0.0.1'
   dependency             'rss',                   '~> 0.3'
@@ -41,7 +41,7 @@ GemHadar do
   dependency             'xdg'
   dependency             'kramdown-ansi',         '~> 0.1'
   dependency             'complex_config',        '~> 0.22', '>= 0.22.2'
-  dependency             'tins',                  '~> 1.34'
+  dependency             'tins',                  '~> 1.41'
   dependency             'search_ui',             '~> 0.0'
   dependency             'amatch',                '~> 0.4.1'
   dependency             'pdf-reader',            '~> 2.0'
@@ -52,6 +52,7 @@ GemHadar do
   development_dependency 'webmock'
   development_dependency 'debug'
   development_dependency 'simplecov'
+  development_dependency 'context_spook'
 
   licenses << 'MIT'
   

data/VERSION

@@ -1 +1 @@
-0.0.24
+0.0.26

data/bin/ollama_chat_send

@@ -5,7 +5,7 @@ require 'tins/go'
 include Tins::GO
 
 
-opts = go 'f:rtph', ARGV
+opts = go 'f:d:rtph', ARGV
 
 def usage(rc = 0)
   puts <<~EOT
@@ -16,6 +16,7 @@ def usage(rc = 0)
       -t         Send input as terminal input including commands, e. g. /import
       -p         Send input with source parsing enabled (defaults to disabled)
       -f CONFIG  file to read
+      -d DIR     the runtime directory to look for the socket file
       -h         Show this help message
 
     Send data to a running Ollame Chat client via standard input.
@@ -31,7 +32,13 @@ begin
          else
            opts[?r] ? :socket_input_with_response : :socket_input
          end
-  response = OllamaChat::ServerSocket.send_to_server_socket(STDIN.read, type:, config:, parse: !!opts[?p])
+  response = OllamaChat::ServerSocket.send_to_server_socket(
+    STDIN.read,
+    type:,
+    config:,
+    runtime_dir: opts[?d],
+    parse: !!opts[?p]
+  )
   type == :socket_input_with_response and puts response.content
 rescue => e
   warn "Caught #{e.class}: #{e}"

data/lib/ollama_chat/chat.rb

@@ -17,6 +17,20 @@ require 'xdg'
 require 'socket'
 require 'shellwords'
 
+# A chat client for interacting with Ollama models through a terminal
+# interface.
+#
+# The Chat class provides a complete command-line interface for chatting with
+# language models via the Ollama API. It handles configuration management,
+# message history, document processing, web searching, and various interactive
+# features including voice output, markdown rendering, and embedding
+# capabilities.
+#
+# @example Initializing a chat session
+#   chat = OllamaChat::Chat.new(argv: ['-m', 'llama3.1'])
+#
+# @example Starting an interactive chat
+#   chat.start
 class OllamaChat::Chat
   include Tins::GO
   include Term::ANSIColor
@@ -114,7 +128,6 @@ class OllamaChat::Chat
   # @return [Ollama::Client] the configured Ollama API client
   attr_reader :ollama
 
-
   # Returns the documents set for this object, initializing it lazily if needed.
   #
   # The documents set is memoized, meaning it will only be created once per
@@ -205,11 +218,12 @@ class OllamaChat::Chat
       end
       :next
     when %r(^/list(?:\s+(\d*))?$)
-      last = 2 * $1.to_i if $1
-      messages.list_conversation(last)
+      n = 2 * $1.to_i if $1
+      messages.list_conversation(n)
       :next
-    when %r(^/last$)
-      messages.show_last
+    when %r(^/last(?:\s+(\d*))?$)
+      n = $1.to_i if $1
+      messages.show_last(n)
       :next
     when %r(^/clear(?:\s+(messages|links|history|tags|all))?$)
       clean($1)
@@ -348,23 +362,34 @@ class OllamaChat::Chat
     end
   end
 
-  # The web method searches for URLs based on a query and processes them by
-  # fetching, embedding, and summarizing their content, then formats the
-  # results into a prompt string.
+  # The web method performs a web search and processes the results based on
+  # embedding configuration.
+  #
+  # It searches for the given query using the configured search engine and
+  # processes up to the specified number of URLs. If embeddings are enabled, it
+  # embeds each result and interpolates the query into the web_embed prompt.
+  # Otherwise, it imports each result and interpolates both the query and
+  # results into the web_import prompt.
   #
-  # @param count [ String ] the number of URLs to search for
+  # @param count [ String ] the maximum number of search results to process
   # @param query [ String ] the search query string
   #
-  # @return [ String ] the formatted prompt string containing the query and summarized results
+  # @return [ String, Symbol ] the interpolated prompt content or :next if no URLs were found
   def web(count, query)
-    urls            = search_web(query, count.to_i) or return :next
-    urls.each do |url|
-      fetch_source(url) { |url_io| embed_source(url_io, url) }
+    urls = search_web(query, count.to_i) or return :next
+    if @embedding.on?
+      prompt = config.prompts.web_embed
+      urls.each do |url|
+        fetch_source(url) { |url_io| embed_source(url_io, url) }
+      end
+      prompt.named_placeholders_interpolate({query:})
+    else
+      prompt = config.prompts.web_import
+      results = urls.each_with_object('') do |url, content|
+        import(url).full? { |c| content << c }
+      end
+      prompt.named_placeholders_interpolate({query:, results:})
     end
-    urls_summarized = urls.map { summarize(_1) }
-    results = urls.zip(urls_summarized).
-      map { |u, s| "%s as \n:%s" % [ u, s ] } * "\n\n"
-    config.prompts.web % { query:, results: }
   end
 
   # The manage_links method handles operations on a collection of links, such
@@ -650,7 +675,6 @@ class OllamaChat::Chat
   #
   # @see fetch_source
   # @see embed_source
-  # @see documents.clear
   def add_documents_from_argv(document_list)
     if document_list.any?(&:empty?)
       STDOUT.puts "Clearing collection #{bold{documents.collection}}."

data/lib/ollama_chat/clipboard.rb

@@ -1,3 +1,15 @@
+# A module that provides clipboard functionality for copying and pasting chat
+# messages.
+#
+# This module enables users to copy the last assistant message to the system
+# clipboard and paste content from input, facilitating easy transfer of
+# conversation content between different applications and contexts.
+#
+# @example Copying a message to clipboard
+#   chat.copy_to_clipboard
+#
+# @example Pasting content from input
+#   content = chat.paste_from_input
 module OllamaChat::Clipboard
   # Copy the last assistant's message to the system clipboard.
   #

data/lib/ollama_chat/dialog.rb

@@ -1,3 +1,20 @@
+# A module that provides interactive selection and configuration functionality
+# for OllamaChat.
+#
+# The Dialog module encapsulates various helper methods for choosing models,
+# system prompts, document policies, and voices, as well as displaying
+# information and managing chat sessions. It leverages user interaction
+# components like choosers and prompts to enable dynamic configuration during
+# runtime.
+#
+# @example Selecting a model from available options
+#   chat.choose_model('-m llama3.1', 'llama3.1')
+#
+# @example Changing the system prompt
+#   chat.change_system_prompt('default_prompt', system: '?sherlock')
+#
+# @example Choosing a document policy
+#   chat.choose_document_policy
 module OllamaChat::Dialog
   # The model_with_size method formats a model's size for display
   # by creating a formatted string that includes the model name and its size

data/lib/ollama_chat/document_cache.rb

@@ -1,20 +1,38 @@
+# Module for handling document caching and retrieval using embedding
+# similarity.
+#
+# This module provides methods to configure cache backends and manage document
+# storage with semantic search capabilities. It integrates with Documentrix's
+# document management system to enable efficient storage, retrieval, and
+# similarity-based searching of documents using vector embeddings.
 module OllamaChat::DocumentCache
-  # The document_cache_class method returns the cache class specified in the
-  # configuration.
+  # Retrieves the cache class specified in the configuration.
   #
-  # @return [ Class ] the cache class defined by the config.cache setting
+  # This method resolves the cache class name from the application's
+  # configuration to dynamically load the appropriate cache implementation.
+  #
+  # @return [Class] The cache class referenced by the configuration's cache
+  # setting.
+  # @raise [NameError] If the configured cache class name does not correspond
+  # to an existing constant.
   def document_cache_class
     Object.const_get(config.cache)
   end
 
-  # The configure_cache method determines the appropriate cache class to use
-  # for document storage.
-  # It checks if the -M option was specified to use MemoryCache, otherwise it
-  # attempts to use the configured cache class.
-  # If an error occurs during this process, it falls back to using MemoryCache
-  # and reports the error.
+  # Configures and returns the appropriate cache class based on command-line
+  # options.
+  #
+  # Determines which cache implementation to use based on command-line flags: -
+  # If the `-M` flag is set, uses {Documentrix::Documents::MemoryCache} -
+  # Otherwise, resolves and returns the cache class specified in configuration
+  #
+  # Falls back to {Documentrix::Documents::MemoryCache} if configuration
+  # resolution fails.
   #
-  # @return [ Class ] the selected cache class to be used for document caching
+  # @return [Class] The selected cache class for document storage and
+  # retrieval.
+  # @raise [StandardError] If there is an error resolving the configured cache
+  # class, logs the error to standard error and falls back to MemoryCache.
   def configure_cache
     if @opts[?M]
       Documentrix::Documents::MemoryCache

data/lib/ollama_chat/follow_chat.rb

@@ -1,3 +1,15 @@
+# A class that handles chat responses and manages the flow of conversation
+# between the user and Ollama models.
+#
+# This class is responsible for processing Ollama API responses, updating
+# message history, displaying formatted output to the terminal, and managing
+# voice synthesis for spoken responses. It acts as a handler for streaming
+# responses and ensures proper formatting and display of both regular content
+# and thinking annotations.
+#
+# @example Processing a chat response
+#   follow_chat = OllamaChat::FollowChat.new(chat: chat_instance, messages: message_list)
+#   follow_chat.call(response)
 class OllamaChat::FollowChat
   include Ollama
   include Ollama::Handlers::Concern
@@ -6,10 +18,13 @@ class OllamaChat::FollowChat
 
   # Initializes a new instance of OllamaChat::FollowChat.
   #
-  # @param [OllamaChat::Chat] chat The chat object, which represents the conversation context.
-  # @param [#to_a] messages A collection of message objects, representing the conversation history.
+  # @param [OllamaChat::Chat] chat The chat object, which represents the
+  # conversation context.
+  # @param [#to_a] messages A collection of message objects, representing the
+  # conversation history.
   # @param [String] voice (optional) to speek with if any.
-  # @param [IO] output (optional) The output stream where terminal output should be printed. Defaults to STDOUT.
+  # @param [IO] output (optional) The output stream where terminal output
+  # should be printed. Defaults to STDOUT.
   #
   # @return [OllamaChat::FollowChat] A new instance of OllamaChat::FollowChat.
   def initialize(chat:, messages:, voice: nil, output: STDOUT)
@@ -23,7 +38,8 @@ class OllamaChat::FollowChat
 
   # Returns the conversation history (an array of message objects).
   #
-  # @return [OllamaChat::MessageList<Ollama::Message>] The array of messages in the conversation.
+  # @return [OllamaChat::MessageList<Ollama::Message>] The array of messages in
+  # the conversation.
   attr_reader :messages
 
   # Invokes the chat flow based on the provided Ollama server response.
@@ -32,15 +48,18 @@ class OllamaChat::FollowChat
   # about the user input and the assistant's response.
   #
   # If the response indicates an assistant message, this method:
-  #   1. Ensures that an assistant response exists in the message history (if not already present).
-  #   2. Updates the last message with the new content and thinking (if applicable).
+  #   1. Ensures that an assistant response exists in the message history (if
+  #      not already present).
+  #   2. Updates the last message with the new content and thinking (if
+  #      applicable).
   #   3. Displays the formatted terminal output for the user.
   #   4. Outputs the voice response (if configured).
   #
   # Regardless of whether an assistant message is present, this method also
   # outputs evaluation statistics (if applicable).
   #
-  # @param [Ollama::Response] response The parsed JSON response from the Ollama server.
+  # @param [Ollama::Response] response The parsed JSON response from the Ollama
+  # server.
   #
   # @return [OllamaChat::FollowChat] The current instance for method chaining.
   def call(response)