ollama_chat 0.0.20 → 0.0.21

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f42ba971131695901f87aea1e9b7c99a41781a61acfae487e812c5c3f185aa01
-  data.tar.gz: b27f7e733b13c3f0023c189fc7be8ac9a1efab943ef562ad5c322e6ad085c7c6
+  metadata.gz: 91a8452d2970be06a595b83e8dfdc4ee8be0388b37171967ef884139ad97b492
+  data.tar.gz: 116ca9055525145d36a65abc5d38341a603fbc62ccf4d52257876ddaa3a3f0d9
 SHA512:
-  metadata.gz: 393146c6eb88e53e056ef5b303076c0584cb8f28f32db4e37b44dd24a845bc86c2987239f31cbfd600906030af004f020e68e4a30491945be250704353b3a567
-  data.tar.gz: b9ab5d2f1ab4d9abf34da61e341304fcf0f1a7fd7fe5e14eb3819ea41f37e3394102b4990a71bf7abd6641b181ef1cf2e40d90fd47e5e3f5665ee081bfb32568
+  metadata.gz: 710139d1db7d25ed49218eaf6c22f61cea64352bbd2d8d1c418ccaba67f190c6157b14d8c5ec41da18e83669177310143b0e3683d5df7b2d7e9c68e3edf72df7
+  data.tar.gz: ef6f2705cfacb4c4523ead9e3361ce980aef227e06b6bc3a7a639d6e492d82cbd03f6c1ca4b82383b29cb95d740d9b815fff3d5c57336baf5f885e1e43e81277

data/VERSION

@@ -1 +1 @@
-0.0.20
+0.0.21

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
@@ -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
@@ -479,6 +590,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 +619,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 +675,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 +691,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 +714,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/source_fetching.rb

@@ -1,4 +1,13 @@
 module OllamaChat::SourceFetching
+  # The http_options method prepares HTTP options for requests based on
+  # configuration settings.
+  # It determines whether SSL peer verification should be disabled for a given
+  # URL and whether a proxy should be used, then returns a hash of options.
+  #
+  # @param url [ String ] the URL for which HTTP options are being prepared
+  #
+  # @return [ Hash ] a hash containing HTTP options such as ssl_verify_peer and
+  # proxy settings
   def http_options(url)
     options = {}
     if ssl_no_verify = config.ssl_no_verify?
@@ -11,6 +20,13 @@ module OllamaChat::SourceFetching
     options
   end
 
+  # The fetch_source method retrieves content from various source types
+  # including commands, URLs, and file paths. It processes the source based on
+  # its type and yields a temporary file handle for further processing.
+  #
+  # @param source [ String ] the source identifier which can be a command, URL, or file path
+  #
+  # @yield [ tmp ]
   def fetch_source(source, &block)
     case source
     when %r(\A!(.*))
@@ -36,18 +52,38 @@ module OllamaChat::SourceFetching
         block.(tmp)
       end
     else
-      raise "invalid source"
+      raise "invalid source #{source.inspect}"
     end
   rescue => e
     STDERR.puts "Cannot fetch source #{source.to_s.inspect}: #{e.class} #{e}\n#{e.backtrace * ?\n}"
   end
 
+
+  # Adds an image to the images collection from the given source IO and source
+  # identifier.
+  #
+  # This method takes an IO object containing image data and associates it with
+  # a source, creating an Ollama::Image instance and adding it to the images
+  # array.
+  #
+  # @param images [Array] The collection of images to which the new image will be added
+  # @param source_io [IO] The input stream containing the image data
+  # @param source [String, #to_s] The identifier or path for the source of the image
   def add_image(images, source_io, source)
     STDERR.puts "Adding #{source_io&.content_type} image #{source.to_s.inspect}."
     image = Ollama::Image.for_io(source_io, path: source.to_s)
     (images << image).uniq!
   end
 
+  # The import_source method processes and imports content from a given source,
+  # displaying information about the document type and returning a formatted
+  # string that indicates the import result along with the parsed content.
+  #
+  # @param source_io [ IO ] the input stream containing the document content
+  # @param source [ String ] the source identifier or path
+  #
+  # @return [ String ] a formatted message indicating the import result and the
+  # parsed content
   def import_source(source_io, source)
     source        = source.to_s
     document_type = source_io&.content_type.full? { |ct| italic { ct } + ' ' }
@@ -56,6 +92,16 @@ module OllamaChat::SourceFetching
     "Imported #{source.inspect}:\n\n#{source_content}\n\n"
   end
 
+  # Imports content from the specified source and processes it.
+  #
+  # This method fetches content from a given source (command, URL, or file) and
+  # passes the resulting IO object to the import_source method for processing.
+  #
+  # @param source [String] The source identifier which can be a command, URL,
+  # or file path
+  #
+  # @return [String, nil] A formatted message indicating the import result and
+  #                       parsed content, #   or nil if the operation fails
   def import(source)
     fetch_source(source) do |source_io|
       content = import_source(source_io, source) or return
@@ -64,6 +110,16 @@ module OllamaChat::SourceFetching
     end
   end
 
+
+  # Summarizes content from the given source IO and source identifier.
+  #
+  # This method takes an IO object containing document content and generates a
+  # summary based on the configured prompt template and word count.
+  #
+  # @param source_io [IO] The input stream containing the document content to summarize
+  # @param source [String, #to_s] The identifier or path for the source of the content
+  # @param words [Integer, nil] The target number of words for the summary (defaults to 100)
+  # @return [String, nil] The formatted summary message or nil if content is empty or cannot be processed
   def summarize_source(source_io, source, words: nil)
     STDOUT.puts "Summarizing #{italic { source_io&.content_type }} document #{source.to_s.inspect} now."
     words = words.to_i
@@ -73,6 +129,15 @@ module OllamaChat::SourceFetching
     config.prompts.summarize % { source_content:, words: }
   end
 
+
+  # Summarizes content from the specified source.
+  #
+  # This method fetches content from a given source (command, URL, or file) and
+  # generates a summary using the summarize_source method.
+  #
+  # @param source [String] The source identifier which can be a command, URL, or file path
+  # @param words [Integer, nil] The target number of words for the summary (defaults to 100)
+  # @return [String, nil] The formatted summary message or nil if the operation fails
   def summarize(source, words: nil)
     fetch_source(source) do |source_io|
       content = summarize_source(source_io, source, words:) or return
@@ -81,6 +146,19 @@ module OllamaChat::SourceFetching
     end
   end
 
+
+  # Embeds content from the given source IO and source identifier.
+  #
+  # This method processes document content by splitting it into chunks using
+  # various splitting strategies (Character, RecursiveCharacter, Semantic) and
+  # adds the chunks to a document store for embedding.
+  #
+  # @param source_io [IO] The input stream containing the document content to embed
+  # @param source [String, #to_s] The identifier or path for the source of the content
+  # @param count [Integer, nil] An optional counter for tracking processing order
+  #
+  # @return [Array, String, nil] The embedded chunks or processed content, or
+  # nil if embedding is disabled or fails
   def embed_source(source_io, source, count: nil)
     @embedding.on? or return parse_source(source_io)
     m = "Embedding #{italic { source_io&.content_type }} document #{source.to_s.inspect}."
@@ -127,6 +205,18 @@ module OllamaChat::SourceFetching
     @documents.add(inputs, source:, batch_size: config.embedding.batch_size?)
   end
 
+
+  # Embeds content from the specified source.
+  #
+  # This method fetches content from a given source (command, URL, or file) and
+  # processes it for embedding using the embed_source method. If embedding is
+  # disabled, it falls back to generating a summary instead.
+  #
+  # @param source [String] The source identifier which can be a command, URL,
+  # or file path
+  #
+  # @return [String, nil] The formatted embedding result or summary message, or
+  # nil if the operation fails
   def embed(source)
     if @embedding.on?
       STDOUT.puts "Now embedding #{source.to_s.inspect}."