ollama_chat 0.0.20 → 0.0.22

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f42ba971131695901f87aea1e9b7c99a41781a61acfae487e812c5c3f185aa01
-  data.tar.gz: b27f7e733b13c3f0023c189fc7be8ac9a1efab943ef562ad5c322e6ad085c7c6
+  metadata.gz: bffe3cc2184b33a1dec71799752eeb90f9f89f1120644195c138d4b0f2c61f67
+  data.tar.gz: 0024f487568be42097d48d44bc75284bd3bf756035e1aff01492c6ee509d7754
 SHA512:
-  metadata.gz: 393146c6eb88e53e056ef5b303076c0584cb8f28f32db4e37b44dd24a845bc86c2987239f31cbfd600906030af004f020e68e4a30491945be250704353b3a567
-  data.tar.gz: b9ab5d2f1ab4d9abf34da61e341304fcf0f1a7fd7fe5e14eb3819ea41f37e3394102b4990a71bf7abd6641b181ef1cf2e40d90fd47e5e3f5665ee081bfb32568
+  metadata.gz: 14128bc440a4698b8ddda93d46f94ad43b756a028f4a11680703000d6b21410ff346d989112bbee3cb62af487382b398ab68e4c07a463b347d35d4faefaf22dd
+  data.tar.gz: 1a6b94ea5e570c50f3549f36f44a3cc3a8698837c7d1e66bc211d8139361d98d845807775e90162213453fe53d2bd20209383f2306cbf408a8c58b1a2ed02a93

data/CHANGES.md

@@ -1,5 +1,21 @@
 # Changes
 
+## 2025-08-11 v0.0.21
+
+* **Vim Integration**: The `/vim` command allows users to insert the last chat
+  message into a Vim server, improving workflow integration. It uses
+  `--servername` and `--remote-send` to insert text at the cursor position and
+  automatically indents based on the current column.
+* **Improved Documentation**: Comprehensive documentation has been added to
+  various modules and classes, making it easier for developers to understand
+  and use the gem's features.
+* **Model Selection Logic**: When only a single model is available, the code
+  now automatically selects that model instead of showing a prompt, improving
+  usability.
+* **Configuration Handling**: Configuration file error handling has been
+  updated to use `STDERR` for output, ensuring errors are displayed
+  appropriately.
+
 ## 2025-08-11 v0.0.20
 
 ### Documentation

data/README.md

@@ -191,6 +191,14 @@ The `ollama_chat_send` command now supports additional parameters to enhance fun
   $ echo "$response"
   ```
 
+- **Source Parsing (`-p`)**: Enables automatic parsing of URLs, file paths, and
+  similar tokens in input content. When enabled, the system will attempt to
+  resolve and include external resources.
+
+  ```bash
+  $ echo "Visit https://example.com for more info" | ollama_chat_send -p
+  ```
+
 - **Help (`-h` or `--help`)**: Displays usage information and available options.
 
   ```bash

data/VERSION

@@ -1 +1 @@
-0.0.20
+0.0.22

data/bin/ollama_chat_send

@@ -5,7 +5,7 @@ require 'tins/go'
 include Tins::GO
 
 
-opts = go 'f:rth', ARGV
+opts = go 'f:rtph', ARGV
 
 def usage(rc = 0)
   puts <<~EOT
@@ -14,6 +14,7 @@ def usage(rc = 0)
     Options:
       -r         Wait for the response from Ollama Chat and output it
       -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
       -h         Show this help message
 
@@ -30,7 +31,7 @@ begin
          else
            opts[?r] ? :socket_input_with_response : :socket_input
          end
-  response = OllamaChat::ServerSocket.send_to_server_socket(STDIN.read, type:, config:)
+  response = OllamaChat::ServerSocket.send_to_server_socket(STDIN.read, type:, config:, 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

@@ -34,6 +34,33 @@ class OllamaChat::Chat
   include OllamaChat::History
   include OllamaChat::ServerSocket
 
+  # Initializes a new OllamaChat::Chat instance with the given command-line
+  # arguments.
+  #
+  # Sets up the chat environment including configuration parsing, Ollama client
+  # initialization, model selection, system prompt handling, document
+  # processing setup, and history management. This method handles all the
+  # bootstrapping necessary to create a functional chat session that can
+  # communicate with an Ollama server and process various input types including
+  # text, documents, web content, and images.
+  #
+  # The initialization process includes parsing command-line options using
+  # Tins::GO for robust argument handling, setting up the Ollama client with
+  # configurable timeouts (connect, read, write), validating Ollama API version
+  # compatibility (requires >= 0.9.0 for features used), configuring model
+  # selection based on command-line or configuration defaults, initializing
+  # system prompts from files or inline content, setting up document processing
+  # pipeline with embedding capabilities through Documentrix::Documents,
+  # creating message history management through OllamaChat::MessageList,
+  # initializing cache systems for document embeddings, setting up
+  # voice support and image handling for multimodal interactions, enabling
+  # optional server socket functionality for remote input, and handling
+  # configuration errors with interactive recovery mechanisms.
+  #
+  # @param argv [Array<String>] Command-line arguments to parse (defaults to ARGV.dup)
+  #
+  # @raise [ArgumentError] If the Ollama API version is less than 0.9.0, indicating
+  #   incompatibility with required API features
   def initialize(argv: ARGV.dup)
     @opts               = go 'f:u:m:s:c:C:D:MESVh', argv
     @opts[?h] and exit usage
@@ -80,28 +107,66 @@ class OllamaChat::Chat
     fix_config(e)
   end
 
+  # The ollama reader returns the Ollama API client instance.
+  #
+  # @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
+  # object instance and subsequent calls will return the same
+  # Documentrix::Documents instance.
+  #
+  # @return [Documentrix::Documents] A Documentrix::Documents object containing
+  # all documents associated with this instance
   attr_reader :documents
 
+  # Returns the messages set for this object, initializing it lazily if needed.
+  #
+  # The messages set is memoized, meaning it will only be created once per
+  # object instance and subsequent calls will return the same
+  # OllamaChat::MessageList instance.
+  #
+  # @return [OllamaChat::MessageList] A MessageList object containing all
+  # messages associated with this instance
   attr_reader :messages
 
+  # Returns the links set for this object, initializing it lazily if needed.
+  #
+  # The links set is memoized, meaning it will only be created once per object
+  # instance and subsequent calls will return the same Set instance.
+  #
+  # @return [Set] A Set object containing all links associated with this instance
   def links
     @links ||= Set.new
   end
 
   class << self
+    # The config attribute accessor provides read and write access to the
+    # configuration object associated with this instance.
     attr_accessor :config
   end
 
+  # The config= method assigns a new configuration object to the class.
+  #
+  # @param config [ ComplexConfig::Settings ] the configuration object to be set
   def config=(config)
     self.class.config = config
   end
 
+  # The config method returns the configuration object associated with the
+  # class.
+  #
+  # @return [ ComplexConfig::Settings ] the configuration instance
   def config
     self.class.config
   end
 
+  # The start method initializes the chat session by displaying information and
+  # conversation history, then prompts the user for input to begin interacting
+  # with the chat.
   def start
     info
     if messages.size > 1
@@ -152,7 +217,7 @@ class OllamaChat::Chat
       :next
     when %r(^/drop(?:\s+(\d*))?$)
       messages.drop($1)
-      messages.list_conversation(2)
+      messages.show_last
       :next
     when %r(^/model$)
       @model = choose_model('', @model)
@@ -235,7 +300,7 @@ class OllamaChat::Chat
       if messages.save_conversation(filename)
         STDOUT.puts "Saved conversation to #{filename.inspect}."
       else
-        STDOUT.puts "Saving conversation to #{filename.inspect} failed."
+        STDERR.puts "Saving conversation to #{filename.inspect} failed."
       end
       :next
     when %r(^/links(?:\s+(clear))?$)
@@ -250,7 +315,7 @@ class OllamaChat::Chat
       if success
         STDOUT.puts "Loaded conversation from #{filename.inspect}."
       else
-        STDOUT.puts "Loading conversation from #{filename.inspect} failed."
+        STDERR.puts "Loading conversation from #{filename.inspect} failed."
       end
       :next
     when %r(^/pipe\s+(.+)$)
@@ -259,6 +324,13 @@ class OllamaChat::Chat
     when %r(^/output\s+(.+)$)
       output($1)
       :next
+    when %r(^/vim(?:\s+(.+))?$)
+      if message = messages.last
+        OllamaChat::Vim.new($1).insert message.content
+      else
+        STDERR.puts "Warning: No message found to insert into Vim"
+      end
+      :next
     when %r(^/config$)
       display_config
       :next
@@ -274,6 +346,14 @@ 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.
+  #
+  # @param count [ String ] the number of URLs to search for
+  # @param query [ String ] the search query string
+  #
+  # @return [ String ] the formatted prompt string containing the query and summarized results
   def web(count, query)
     urls            = search_web(query, count.to_i) or return :next
     urls.each do |url|
@@ -285,6 +365,16 @@ class OllamaChat::Chat
     config.prompts.web % { query:, results: }
   end
 
+  # The manage_links method handles operations on a collection of links, such
+  # as displaying them or clearing specific entries.
+  #
+  # It supports two main commands: 'clear' and nil (default).
+  # When the command is 'clear', it presents an interactive menu to either
+  # clear all links or individual links.
+  # When the command is nil, it displays the current list of links with
+  # hyperlinks.
+  #
+  # @param command [ String, nil ] the operation to perform on the links
   def manage_links(command)
     case command
     when 'clear'
@@ -322,10 +412,14 @@ class OllamaChat::Chat
     end
   end
 
+  # The clean method clears various parts of the chat session based on the
+  # specified parameter.
+  #
+  # @param what [ String, nil ] the type of data to clear, defaults to
+  # 'messages' if nil
   def clean(what)
-    what = 'messages' if what.nil?
     case what
-    when 'messages'
+    when 'messages', nil
       messages.clear
       STDOUT.puts "Cleared messages."
     when 'links'
@@ -350,6 +444,11 @@ class OllamaChat::Chat
     end
   end
 
+  # The display_config method renders the configuration and displays it using a
+  # pager.
+  # It determines an appropriate pager command based on environment variables
+  # and available system commands, then uses Kramdown::ANSI::Pager to show the
+  # formatted configuration output.
   def display_config
     default_pager = ENV['PAGER'].full?
     if fallback_pager = `which less`.chomp.full? || `which more`.chomp.full?
@@ -365,6 +464,18 @@ class OllamaChat::Chat
     end
   end
 
+  # The interact_with_user method manages the interactive loop for user input
+  # and chat processing.
+  # It handles reading user input, processing commands, managing messages, and
+  # communicating with the Ollama server.
+  # The method supports command completion, prefilling prompts, socket input
+  # handling, and various chat features including embedding context and voice
+  # support.
+  # It processes user input through command handling, content parsing, and
+  # message formatting before sending requests to the Ollama server.
+  # The method also handles server socket messages, manages chat history, and
+  # ensures proper cleanup and configuration handling throughout the
+  # interaction.
   def interact_with_user
     loop do
       @parse_content = true
@@ -384,8 +495,9 @@ class OllamaChat::Chat
         end
       rescue Interrupt
         if message = server_socket_message
-          type    = message.type.full?(:to_sym) || :socket_input
-          content = message.content
+          type           = message.type.full?(:to_sym) || :socket_input
+          content        = message.content
+          @parse_content = message.parse
           STDOUT.puts color(112) { "Received a server socket message. Processing now…" }
         else
           raise
@@ -479,6 +591,13 @@ class OllamaChat::Chat
 
   private
 
+  # The setup_documents method initializes the document processing pipeline by
+  # configuring the embedding model and database connection.
+  # It then loads specified documents into the system and returns the
+  # configured document collection.
+  #
+  # @return [ Documentrix::Documents, NULL ] the initialized document
+  # collection if embedding is enabled, otherwise NULL
   def setup_documents
     if embedding.on?
       @embedding_model         = config.embedding.model.name
@@ -501,10 +620,35 @@ class OllamaChat::Chat
       add_documents_from_argv(document_list)
       @documents
     else
-      Tins::NULL
+      NULL
     end
   end
 
+  # Adds documents from command line arguments to the document collection
+  #
+  # Processes a list of document paths or URLs, handling both local files and
+  # remote resources.
+  #
+  # @param document_list [Array<String>] List of document paths or URLs to process
+  #
+  # @return [void]
+  #
+  # @example Adding local files
+  #   add_documents_from_argv(['/path/to/file1.txt', '/path/to/file2.pdf'])
+  #
+  # @example Adding remote URLs
+  #   add_documents_from_argv(['https://example.com/page1', 'http://example.com/page2'])
+  #
+  # @example Mixed local and remote
+  #   add_documents_from_argv(['/local/file.txt', 'https://remote.com/document'])
+  #
+  # @note Empty entries in the document list will trigger a collection clear operation
+  # @note Documents are processed in batches of 25 to manage memory usage
+  # @note Progress is reported to STDOUT during processing
+  #
+  # @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}}."
@@ -532,6 +676,11 @@ class OllamaChat::Chat
     end
   end
 
+  # The setup_cache method initializes and returns a Redis cache instance with
+  # expiring keys if a Redis URL is configured.
+  #
+  # @return [ Documentrix::Documents::RedisCache, nil ] the configured Redis
+  # cache instance or nil if no URL is set.
   def setup_cache
     if url = config.redis.expiring.url?
       ex = config.redis.expiring.ex?.to_i
@@ -543,6 +692,14 @@ class OllamaChat::Chat
     end
   end
 
+  # The fix_config method handles configuration file errors by informing the
+  # user about the exception and prompting them to fix it.
+  # It then executes a diff tool to compare the current config file with the
+  # default one.
+  # This method exits the program after handling the configuration error
+  #
+  # @param exception [ Exception ] the exception that occurred while reading
+  # the config file
   def fix_config(exception)
     STDOUT.puts "When reading the config file, a #{exception.class} "\
       "exception was caught: #{exception.message.inspect}"
@@ -558,6 +715,17 @@ class OllamaChat::Chat
     end
   end
 
+  # Enables tab completion for chat commands within the interactive session
+  #
+  # Temporarily replaces the current Reline completion procedure with a custom
+  # one that provides command completion based on the chat help message.
+  #
+  # @param block [Proc] The block to execute with enhanced tab completion enabled
+  #
+  # @return [Object] The return value of the executed block
+  #
+  # @see display_chat_help_message
+  # @see Reline.completion_proc
   def enable_command_completion(&block)
     old = Reline.completion_proc
     commands = display_chat_help_message.scan(/^\s*(\S+)/).inject(&:concat)

data/lib/ollama_chat/dialog.rb

@@ -32,11 +32,14 @@ module OllamaChat::Dialog
                end
     models = ollama.tags.models.sort_by(&:name).map { |m| model_with_size(m) }
     selector and models = models.grep(selector)
-    model = if cli_model == ''
-              OllamaChat::Utils::Chooser.choose(models) || current_model
-            else
-              cli_model || current_model
-            end
+    model =
+      if models.size == 1
+        models.first
+      elsif cli_model == ''
+        OllamaChat::Utils::Chooser.choose(models) || current_model
+      else
+        cli_model || current_model
+      end
   ensure
     STDOUT.puts green { "Connecting to #{model}@#{ollama.base_url} now…" }
   end

data/lib/ollama_chat/follow_chat.rb

@@ -60,6 +60,13 @@ class OllamaChat::FollowChat
 
   private
 
+  # The ensure_assistant_response_exists method ensures that the last message
+  # in the conversation is from the assistant role.
+  #
+  # If the last message is not from an assistant, it adds a new assistant
+  # message with empty content and optionally includes thinking content if the
+  # chat's think mode is enabled. It also updates the user display variable to
+  # reflect the assistant's message type and styling.
   def ensure_assistant_response_exists
     if @messages&.last&.role != 'assistant'
       @messages << Message.new(
@@ -72,6 +79,12 @@ class OllamaChat::FollowChat
     end
   end
 
+  # The update_last_message method appends the content of a response to the
+  # last message in the conversation. It also appends thinking content to the
+  # last message if thinking is enabled and thinking content is present.
+  #
+  # @param response [ Object ] the response object containing message content
+  # and thinking
   def update_last_message(response)
     @messages.last.content << response.message&.content
     if @chat.think.on? and response_thinking = response.message&.thinking.full?
@@ -79,6 +92,13 @@ class OllamaChat::FollowChat
     end
   end
 
+  # The display_formatted_terminal_output method formats and outputs the
+  # terminal content by processing the last message's content and thinking,
+  # then prints it to the output. It handles markdown parsing and annotation
+  # based on chat settings, and ensures proper formatting with clear screen and
+  # move home commands. The method takes into account whether markdown and
+  # thinking modes are enabled to determine how to process and display the
+  # content.
   def display_formatted_terminal_output
     content, thinking = @messages.last.content, @messages.last.thinking
     if @chat.markdown.on?
@@ -95,6 +115,14 @@ class OllamaChat::FollowChat
     ].compact))
   end
 
+  # The eval_stats method processes response statistics and formats them into a
+  # colored, readable string output.
+  #
+  # @param response [ Object ] the response object containing evaluation metrics
+  #
+  # @return [ String ] a formatted string with statistical information about
+  # the evaluation process including durations, counts, and rates, styled with
+  # colors and formatting
   def eval_stats(response)
     eval_duration        = response.eval_duration / 1e9
     prompt_eval_duration = response.prompt_eval_duration / 1e9
@@ -113,11 +141,19 @@ class OllamaChat::FollowChat
     }
   end
 
+  # The output_eval_stats method outputs evaluation statistics to the specified
+  # output stream.
+  #
+  # @param response [ Object ] the response object containing evaluation data
   def output_eval_stats(response)
     response.done or return
     @output.puts "", eval_stats(response)
   end
 
+  # The debug_output method conditionally outputs the response object using jj
+  # when debugging is enabled.
+  #
+  # @param response [ Object ] the response object to be outputted
   def debug_output(response)
     OllamaChat::Chat.config.debug and jj response
   end

data/lib/ollama_chat/information.rb

@@ -116,6 +116,7 @@ module OllamaChat::Information
       /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
     EOT

data/lib/ollama_chat/ollama_chat_config/default_config.yml

@@ -39,6 +39,7 @@ document_policy: importing
 think: false
 embedding:
   enabled: true
+  paused: false
   model:
     name: mxbai-embed-large
     embedding_length: 1024

data/lib/ollama_chat/server_socket.rb

@@ -1,24 +1,48 @@
 module OllamaChat::ServerSocket
   class << self
-    # The send_to_server_socket method sends content to the server socket and returns
-    # the response if type is :socket_input_with_response, otherwise it returns nil.
-
-    # @param content [ String ] the message to be sent to the server
-    # @param type [ Symbol ] the type of message being sent (default: :socket_input)
+    # The send_to_server_socket method transmits a message to a Unix domain
+    # socket server for processing by the Ollama Chat client.
+    #
+    # This method creates a socket server instance using the provided
+    # configuration, prepares a message with the given content, type, and parse
+    # flag, then sends it either as a simple transmission or with a response
+    # expectation depending on the message type. It is used to enable
+    # communication between external processes and the chat session via a named
+    # Unix socket.
     #
-    # @return [ String, NilClass ] the response from the server if type is
-    #   :socket_input_with_response, otherwise nil.
-    def send_to_server_socket(content, config:, type: :socket_input)
+    # @param content [ String ] the message content to be sent
+    # @param config [ ComplexConfig::Settings ] the configuration object containing server settings
+    # @param type [ Symbol ] the type of message transmission, defaults to :socket_input
+    # @param parse [ TrueClass, FalseClass ] whether to parse the response, defaults to false
+    #
+    # @return [ UnixSocks::Message, nil ] the response from transmit_with_response if type
+    # is :socket_input_with_response, otherwise nil
+    def send_to_server_socket(content, config:, type: :socket_input, parse: false)
       server  = create_socket_server(config:)
-      message = { content:, type: }
+      message = { content:, type:, parse: }
       if type.to_sym == :socket_input_with_response
-         return server.transmit_with_response(message)
+        server.transmit_with_response(message)
       else
-         server.transmit(message)
-         nil
+        server.transmit(message)
+        nil
       end
     end
 
+    # The create_socket_server method constructs and returns a Unix domain
+    # socket server instance for communication with the Ollama Chat client.
+    #
+    # This method initializes a UnixSocks::Server object configured to listen
+    # for incoming messages on a named socket file. It supports specifying a
+    # custom runtime directory for the socket, which is useful for isolating
+    # multiple instances or environments. If no runtime directory is provided
+    # in the configuration, it defaults to using the standard system location
+    # for Unix domain sockets.
+    #
+    # @param config [ComplexConfig::Settings] the configuration object
+    # containing server settings
+    #
+    # @return [UnixSocks::Server] a configured Unix domain socket server
+    # instance ready to receive messages
     def create_socket_server(config:)
       if runtime_dir = config.server_socket_runtime_dir
         UnixSocks::Server.new(socket_name: 'ollama_chat.sock', runtime_dir:)
@@ -37,9 +61,6 @@ module OllamaChat::ServerSocket
   # messages in the background. When a message is received, it updates the
   # instance variable `server_socket_message` and sends an interrupt signal
   # to the current process in order to handle the message.
-  #
-  # @return [ nil ] This method does not return any value, it only sets up the
-  # server socket and kills the process when a message is received.
   def init_server_socket
     server = OllamaChat::ServerSocket.create_socket_server(config:)
     server.receive_in_background do |message|