ollama_chat 0.0.19 → 0.0.21

data/lib/ollama_chat/message_format.rb

@@ -1,8 +1,20 @@
 module OllamaChat::MessageFormat
+  # The message_type method determines the appropriate message icon based on
+  # whether images are present.
+  #
+  # @param images [ Array ] an array of images
+  #
+  # @return [ String ] returns 📸 if images are present, 📨 otherwise
   def message_type(images)
     images.present? ? ?📸 : ?📨
   end
 
+  # The think_annotate method processes a string and conditionally annotates it
+  # with a thinking emoji if the think feature is enabled.
+  #
+  # @param block [ Proc ] a block that returns a string to be processed
+  #
+  # @return [ String, nil ] the annotated string with a thinking emoji if enabled, otherwise nil
   def think_annotate(&block)
     string = block.()
     string.to_s.size == 0 and return
@@ -11,6 +23,12 @@ module OllamaChat::MessageFormat
     end
   end
 
+  # The talk_annotate method processes a string output by a block and
+  # conditionally adds annotation.
+  #
+  # @param block [ Proc ] a block that returns a string to be processed
+  #
+  # @return [ String, nil ] the annotated string if it has content, otherwise nil
   def talk_annotate(&block)
     string = block.()
     string.to_s.size == 0 and return

data/lib/ollama_chat/message_output.rb

@@ -1,4 +1,12 @@
 module OllamaChat::MessageOutput
+  # The pipe method forwards the last assistant message to a command's standard
+  # input.
+  #
+  # @param cmd [ String ] the command to which the output should be piped
+  #
+  # @return [ OllamaChat::Chat ] returns self
+  # @return [ nil ] returns nil if the command is not provided or if there is
+  # no assistant message
   def pipe(cmd)
     cmd.present? or return
     if message = @messages.last and message.role == 'assistant'
@@ -21,10 +29,19 @@ module OllamaChat::MessageOutput
     end
   end
 
+  # The output method writes the last assistant message to a file.
+  #
+  # @param filename [ String ] the path to the file where the output should be written
+  #
+  # @return [ Chat ] returns self on success, nil on failure
+  #
+  # @see write_file_unless_exist
+  #
+  # @note If no assistant message is available, an error message is printed to stderr.
   def output(filename)
     if message = @messages.last and message.role == 'assistant'
       begin
-        write_file_unless_exist(filename)
+        write_file_unless_exist(filename, message)
         STDOUT.puts "Last response was written to #{filename.inspect}."
         self
       rescue => e
@@ -37,7 +54,15 @@ module OllamaChat::MessageOutput
 
   private
 
-  def write_file_unless_exist(filename)
+  # The write_file_unless_exist method creates a new file with the specified
+  # message content, but only if a file with that name does not already exist.
+  #
+  # @param filename [ String ] the path of the file to be created
+  # @param message [ Ollama::Message ] the message object containing the content to write
+  #
+  # @return [ TrueClass ] if the file was successfully created
+  # @return [ nil ] if the file already exists and was not created
+  def write_file_unless_exist(filename, message)
     if File.exist?(filename)
       STDERR.puts "File #{filename.inspect} already exists. Choose another filename."
       return
@@ -47,4 +72,4 @@ module OllamaChat::MessageOutput
     end
     true
   end
-  end
+end

data/lib/ollama_chat/model_handling.rb

@@ -1,5 +1,4 @@
 module OllamaChat::ModelHandling
-
   # The model_present? method checks if the specified Ollama model is available.
   #
   # @param model [ String ] the name of the Ollama model

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/ollama_chat_config.rb

@@ -9,6 +9,15 @@ class OllamaChat::OllamaChatConfig
 
   DEFAULT_CONFIG = File.read(DEFAULT_CONFIG_PATH)
 
+  # The initialize method sets up the configuration file path and ensures the
+  # cache directory exists.
+  # It attempts to load configuration from the specified filename or uses a
+  # default path.
+  # If the configuration file is missing and the default path is used, it
+  # creates the necessary directory structure and writes a default
+  # configuration file.
+  #
+  # @param filename [ String, nil ] the path to the configuration file
   def initialize(filename = nil)
     @filename = filename || default_path
     unless File.directory?(cache_dir_path)
@@ -27,30 +36,62 @@ class OllamaChat::OllamaChatConfig
     end
   end
 
+  # The filename reader returns the name of the file associated with this instance.
   attr_reader :filename
 
+  # The config reader returns the configuration object for the chat instance.
+  #
+  # @return [ ComplexConfig::Settings ] the configuration object
   attr_reader :config
 
+  # The default_config_path method returns the path to the default
+  # configuration file.
+  #
+  # @return [ String ] the path to the default configuration file
   def default_config_path
     DEFAULT_CONFIG_PATH
   end
 
+  # The default_path method constructs the full path to the default
+  # configuration file.
+  #
+  # @return [ Pathname ] a Pathname object representing the path to the
+  # config.yml file within the configuration directory
   def default_path
     config_dir_path + 'config.yml'
   end
 
+  # The config_dir_path method returns the path to the ollama_chat
+  # configuration directory by combining the XDG config home directory with the
+  # 'ollama_chat' subdirectory.
+  #
+  # @return [ Pathname ] the pathname object representing the configuration
+  # directory
   def config_dir_path
     XDG.new.config_home + 'ollama_chat'
   end
 
+  # The cache_dir_path method returns the path to the ollama_chat cache
+  # directory within the XDG cache home directory.
+  #
+  # @return [ Pathname ] the pathname object representing the cache directory path
   def cache_dir_path
     XDG.new.cache_home + 'ollama_chat'
   end
 
+  # The database_path method constructs the full path to the documents database
+  # file by joining the cache directory path with the filename 'documents.db'.
+  #
+  # @return [ Pathname ] the full path to the documents database file
   def database_path
     cache_dir_path + 'documents.db'
   end
 
+  # The diff_tool method returns the preferred diff tool command.
+  # It checks for the DIFF_TOOL environment variable and falls back to
+  # 'vimdiff' if not set.
+  #
+  # @return [ String ] the command name of the diff tool to be used
   def diff_tool
     ENV.fetch('DIFF_TOOL', 'vimdiff')
   end

data/lib/ollama_chat/parsing.rb

@@ -1,4 +1,11 @@
 module OllamaChat::Parsing
+  # The parse_source method processes different types of input sources and
+  # converts them into a standardized text representation.
+  #
+  # @param source_io [IO] the input source to be parsed
+  #
+  # @return [ String, nil ] the parsed content as a string or nil if the
+  # content type is not supported
   def parse_source(source_io)
     case source_io&.content_type
     when 'text/html'
@@ -28,6 +35,16 @@ module OllamaChat::Parsing
     end
   end
 
+  # The parse_csv method processes CSV content from an input source and
+  # converts it into a formatted string representation.
+  # It iterates through each row of the CSV, skipping empty rows, and
+  # constructs a structured output where each row's fields are formatted with
+  # indentation and separated by newlines. The resulting string includes double
+  # newlines between rows for readability.
+  #
+  # @param source_io [ IO ] the input source containing CSV data
+  #
+  # @return [ String ] a formatted string representation of the CSV content
   def parse_csv(source_io)
     result = +''
     CSV.table(File.new(source_io), col_sep: ?,).each do |row|
@@ -40,6 +57,18 @@ module OllamaChat::Parsing
     result
   end
 
+  # The parse_rss method processes an RSS feed source and converts it into a
+  # formatted text representation.
+  # It extracts the channel title and iterates through each item in the feed to
+  # build a structured output.
+  # The method uses the RSS parser to handle the source input and formats the
+  # title, link, publication date, and description of each item into a readable
+  # text format with markdown-style headers and links.
+  #
+  # @param source_io [IO] the input stream containing the RSS feed data
+  #
+  # @return [String] a formatted string representation of the RSS feed with
+  # channel title and item details
   def parse_rss(source_io)
     feed = RSS::Parser.parse(source_io, false, false)
     title = <<~EOT
@@ -58,6 +87,18 @@ module OllamaChat::Parsing
     end
   end
 
+  # The parse_atom method processes an Atom feed from the provided IO source
+  # and converts it into a formatted text representation.
+  # It extracts the feed title and iterates through each item to build a
+  # structured output containing titles, links, and update dates.
+  #
+  # The content of each item is converted using reverse_markdown for better
+  # readability.
+  #
+  # @param source_io [IO] the input stream containing the Atom feed data
+  #
+  # @return [String] a formatted string representation of the Atom feed with
+  # title, items, links, update dates, and content
   def parse_atom(source_io)
     feed = RSS::Parser.parse(source_io, false, false)
     title = <<~EOT
@@ -76,11 +117,26 @@ module OllamaChat::Parsing
     end
   end
 
+  # The pdf_read method extracts text content from a PDF file by reading all
+  # pages.
+  #
+  # @param io [IO] the input stream containing the PDF data
+  #
+  # @return [String] the concatenated text content from all pages in the PDF
   def pdf_read(io)
     reader = PDF::Reader.new(io)
     reader.pages.inject(+'') { |result, page| result << page.text }
   end
 
+
+  # Reads and processes PDF content using Ghostscript for conversion
+  #
+  # This method takes an IO object containing PDF data, processes it through
+  # Ghostscript's pdfwrite device, and returns the processed PDF content.
+  # If Ghostscript is not available in the system path, it outputs an error message.
+  #
+  # @param io [IO] An IO object containing PDF data to be processed
+  # @return [String, nil] The processed PDF content as a string, or nil if processing fails
   def ps_read(io)
     gs = `which gs`.chomp
     if gs.present?
@@ -102,6 +158,15 @@ module OllamaChat::Parsing
     end
   end
 
+  # The reverse_markdown method converts HTML content into Markdown format.
+  #
+  # This method processes HTML input and transforms it into equivalent
+  # Markdown, using specific conversion options to ensure compatibility and
+  # formatting.
+  #
+  # @param html [ String ] the HTML string to be converted
+  #
+  # @return [ String ] the resulting Markdown formatted string
   def reverse_markdown(html)
     ReverseMarkdown.convert(
       html,
@@ -111,6 +176,17 @@ module OllamaChat::Parsing
     )
   end
 
+  # Parses content and processes embedded resources based on document policy
+  #
+  # This method analyzes input content for URLs, tags, and file references,
+  # fetches referenced resources, and processes them according to the current
+  # document policy. It supports different processing modes for various content
+  # types.
+  #
+  # @param content [String] The input content string to parse
+  # @param images [Array] An array to collect image references (will be cleared)
+  # @return [Array<String, Documentrix::Utils::Tags>] Returns an array containing
+  #   the processed content string and tags object if any tags were found
   def parse_content(content, images)
     images.clear
     tags = Documentrix::Utils::Tags.new valid_tag: /\A#*([\w\]\[]+)/

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}."

data/lib/ollama_chat/switches.rb

@@ -6,28 +6,56 @@ module OllamaChat::Switches
       alias_method :on?, :value
     end
 
+    # The off? method returns true if the switch is in the off state, false
+    # otherwise.
+    #
+    # @return [ TrueClass, FalseClass ] indicating whether the switch is off
     def off?
       !on?
     end
 
+    # The show method outputs the current value of the message to standard
+    # output.
+    #
+    # @return [ void ]
     def show
       STDOUT.puts @msg[value]
     end
   end
 
   class Switch
-    def initialize(name, msg:, config:)
-      @value = [ false, true ].include?(config) ? config : !!config.send("#{name}?")
+    # The initialize method sets up the switch with a default value and
+    # message.
+    #
+    # @param msg [ Hash ] a hash containing true and false messages
+    # @param value [ Object ] the default state of the switch
+    #
+    # @return [ void ]
+    def initialize(msg:, value:)
+      @value = !!value
       @msg   = msg
     end
 
+    # The value reader returns the current value of the attribute.
     attr_reader :value
 
+    # The set method assigns a boolean value to the instance variable @value
+    # and optionally displays it.
+    #
+    # @param value [ Object ] the value to be converted to a boolean and
+    # assigned
+    # @param show [ TrueClass, FalseClass ] determines whether to display the
+    # value after setting
     def set(value, show: false)
       @value = !!value
       show && self.show
     end
 
+    # The toggle method switches the current value of the instance variable and
+    # optionally displays it.
+    #
+    # @param show [ TrueClass, FalseClass ] determines whether to show the
+    # value after toggling
     def toggle(show: true)
       @value = !@value
       show && self.show
@@ -37,11 +65,17 @@ module OllamaChat::Switches
   end
 
   class CombinedSwitch
+    # The initialize method sets up the switch with a value and message.
+    #
+    # @param value [ Object ] the value to be stored
+    # @param msg [ Hash ] the message hash containing true and false keys
     def initialize(value:, msg:)
       @value = value
       @msg   = msg
     end
 
+    # The value method returns the result of calling the stored proc with no
+    # arguments.
     def value
       @value.()
     end
@@ -49,26 +83,61 @@ module OllamaChat::Switches
     include CheckSwitch
   end
 
+  # The think method returns the current state of the stream switch.
+  #
+  # @return [ OllamaChat::Switches::Switch ] the stream switch instance
   attr_reader :stream
 
+  # The think method returns the current state of the thinking switch.
+  #
+  # @return [ OllamaChat::Switches::Switch ] the thinking switch instance
   attr_reader :think
 
+  # The markdown attribute reader returns the markdown switch object.
+  # The voice reader returns the voice switch instance.
+  #
+  # @return [ OllamaChat::Switches::Switch ] the markdown switch instance
   attr_reader :markdown
 
+  # The voice reader returns the voice switch instance.
+  #
+  # @return [ OllamaChat::Switches::Switch ] the voice switch instance
   attr_reader :voice
 
+  # The embedding attribute reader returns the embedding switch object.
+  #
+  # @return [ OllamaChat::Switches::CombinedSwitch ] the embedding switch
+  # instance
   attr_reader :embedding
 
+  # The embedding_enabled reader returns the embedding enabled switch instance.
+  #
+  # @return [ OllamaChat::Switches::Switch ] the embedding enabled switch
+  # instance
   attr_reader :embedding_enabled
 
+  # The embedding_paused method returns the current state of the embedding pause flag.
+  #
+  # @return [ OllamaChat::Switches::Switch ] the embedding pause flag switch instance
   attr_reader :embedding_paused
 
+  # The location method returns the current location setting.
+  #
+  # @return [ OllamaChat::Switches::Switch ] the location setting object
   attr_reader :location
 
+  # The setup_switches method initializes various switches for configuring the
+  # application's behavior.
+  #
+  # This method creates and configures multiple switch objects that control
+  # different aspects of the application, such as streaming, thinking, markdown
+  # output, voice output, embedding, and location settings.
+  #
+  # @param config [ ComplexConfig::Settings ] the configuration object
+  # containing settings for the switches
   def setup_switches(config)
     @stream = Switch.new(
-      :stream,
-      config:,
+      value: config.stream,
       msg: {
         true  => "Streaming enabled.",
         false => "Streaming disabled.",
@@ -76,8 +145,7 @@ module OllamaChat::Switches
     )
 
     @think = Switch.new(
-      :think,
-      config:,
+      value: config.think,
       msg: {
         true  => "Thinking enabled.",
         false => "Thinking disabled.",
@@ -85,8 +153,7 @@ module OllamaChat::Switches
     )
 
     @markdown = Switch.new(
-      :markdown,
-      config:,
+      value: config.markdown,
       msg: {
         true  => "Using #{italic{'ANSI'}} markdown to output content.",
         false => "Using plaintext for outputting content.",
@@ -94,8 +161,7 @@ module OllamaChat::Switches
     )
 
     @voice = Switch.new(
-      :stream,
-      config: config.voice,
+      value: config.voice.enabled,
       msg: {
         true  => "Voice output enabled.",
         false => "Voice output disabled.",
@@ -103,8 +169,7 @@ module OllamaChat::Switches
     )
 
     @embedding_enabled = Switch.new(
-      :embedding_enabled,
-      config:,
+      value: config.embedding.enabled,
       msg: {
         true  => "Embedding enabled.",
         false => "Embedding disabled.",
@@ -112,8 +177,7 @@ module OllamaChat::Switches
     )
 
     @embedding_paused = Switch.new(
-      :embedding_paused,
-      config:,
+      value: config.embedding.paused,
       msg: {
         true  => "Embedding paused.",
         false => "Embedding resumed.",
@@ -129,8 +193,7 @@ module OllamaChat::Switches
     )
 
     @location = Switch.new(
-      :location,
-      config: config.location.enabled,
+      value: config.location.enabled,
       msg: {
         true  => "Location and localtime enabled.",
         false => "Location and localtime disabled.",