ollama_chat 0.0.20 → 0.0.22

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

data/lib/ollama_chat/utils/cache_fetcher.rb

@@ -1,10 +1,24 @@
 require 'digest/md5'
 
 class OllamaChat::Utils::CacheFetcher
+  # The initialize method sets up the cache instance variable for the object.
+  #
+  # @param cache [ Object ] the cache object to be stored
+  #
+  # @return [ void ]
   def initialize(cache)
     @cache = cache
   end
 
+  # The get method retrieves cached content by key and yields it as an IO object.
+  # It first checks if the body and content type are present in the cache.
+  # If both are found, it creates a StringIO object from the body,
+  # extends it with HeaderExtension, sets the content type,
+  # and then yields the IO object to the provided block.
+  #
+  # @param url [ String ] the URL used as a key for caching
+  #
+  # @yield [ io ] yields the cached IO object if found
   def get(url, &block)
     block or raise ArgumentError, 'require block argument'
     body         = @cache[key(:body, url)]
@@ -19,6 +33,13 @@ class OllamaChat::Utils::CacheFetcher
     end
   end
 
+  # The put method stores the body and content type of an IO object in the
+  # cache using a URL-based key.
+  #
+  # @param url [ String ] the URL used to generate the cache key
+  # @param io [ StringIO, Tempfile ] the IO object containing the body and content type
+  #
+  # @return [ CacheFetcher ] returns itself to allow for method chaining
   def put(url, io)
     io.rewind
     body = io.read
@@ -32,6 +53,15 @@ class OllamaChat::Utils::CacheFetcher
 
   private
 
+  # The key method generates a unique identifier by combining a type prefix
+  # with a URL digest.
+  # It returns a string that consists of the type, a hyphen, and the MD5 hash
+  # of the URL.
+  #
+  # @param type [ String ] the type prefix for categorizing the key
+  # @param url [ String ] the URL to be hashed
+  #
+  # @return [ String ] a hyphen-separated string of the type and URL's MD5 digest
   def key(type, url)
     [ type, Digest::MD5.hexdigest(url) ] * ?-
   end

data/lib/ollama_chat/utils/fetcher.rb

@@ -7,10 +7,22 @@ require 'ollama_chat/utils/cache_fetcher'
 
 class OllamaChat::Utils::Fetcher
   module HeaderExtension
+    # The content_type method accesses the content type attribute of the object.
+    #
+    # @return [ String ] the content type of the object.
     attr_accessor :content_type
 
+    # The ex accessor is used to get or set the expiry value in seconds.
     attr_accessor :ex
 
+    # The failed method creates a StringIO object with a text/plain content type.
+    #
+    # This method is used to generate a failed response object that can be used
+    # when an operation does not succeed. It initializes a new StringIO object
+    # and extends it with the current class, setting its content type to
+    # text/plain.
+    #
+    # @return [ StringIO ] a StringIO object with text/plain content type
     def self.failed
       object = StringIO.new.extend(self)
       object.content_type = MIME::Types['text/plain'].first
@@ -20,6 +32,22 @@ class OllamaChat::Utils::Fetcher
 
   class RetryWithoutStreaming < StandardError; end
 
+  # The get method retrieves content from a URL, using caching when available.
+  # It processes the URL with optional headers and additional options,
+  # then yields a temporary file containing the retrieved content.
+  # If caching is enabled and content is found in the cache,
+  # it returns the cached result instead of fetching again.
+  # The method handles both cached and fresh fetches,
+  # ensuring that cache is updated when new content is retrieved.
+  #
+  # @param url [ String ] the URL to fetch content from
+  # @param headers [ Hash ] optional headers to include in the request
+  # @param options [ Hash ] additional options for the fetch operation
+  #
+  # @yield [ tmp ]
+  #
+  # @return [ Object ] the result of the block execution
+  # @return [ nil ] if no block is given or if the fetch fails
   def self.get(url, headers: {}, **options, &block)
     cache = options.delete(:cache) and
       cache = OllamaChat::Utils::CacheFetcher.new(cache)
@@ -38,6 +66,9 @@ class OllamaChat::Utils::Fetcher
     end
   end
 
+  # The normalize_url method processes a URL by converting it to a string,
+  # decoding any URI components, removing anchors, and then escaping the URL to
+  # ensure it is properly formatted.
   def self.normalize_url(url)
     url = url.to_s
     url = URI.decode_uri_component(url)
@@ -45,6 +76,17 @@ class OllamaChat::Utils::Fetcher
     URI::Parser.new.escape(url).to_s
   end
 
+  # The read method opens a file and extends it with header extension metadata.
+  # It then yields the file to the provided block for processing.
+  # If the file does not exist, it outputs an error message to standard error.
+  #
+  # @param filename [ String ] the path to the file to be read
+  #
+  # @yield [ file ] yields the opened file with header extension
+  #
+  # @return [ nil ] returns nil if the file does not exist
+  # @return [ Object ] returns the result of the block execution if the file
+  # exists
   def self.read(filename, &block)
     if File.exist?(filename)
       File.open(filename) do |file|
@@ -57,6 +99,16 @@ class OllamaChat::Utils::Fetcher
     end
   end
 
+  # The execute method runs a shell command and processes its output.
+  #
+  # It captures the command's standard output and error streams,
+  # writes them to a temporary file, and yields the file to the caller.
+  # If an exception occurs during execution, it reports the error
+  # and yields a failed temporary file instead.
+  #
+  # @param command [ String ] the shell command to execute
+  #
+  # @yield [ tmpfile ]
   def self.execute(command, &block)
     Tempfile.open do |tmp|
       unless command =~ /2>&1/
@@ -80,6 +132,11 @@ class OllamaChat::Utils::Fetcher
     yield HeaderExtension.failed
   end
 
+  # The initialize method sets up the fetcher instance with debugging and HTTP
+  # configuration options.
+  #
+  # @param debug [ TrueClass, FalseClass ] enables or disables debug output
+  # @param http_options [ Hash ] additional options to pass to the HTTP client
   def initialize(debug: false, http_options: {})
     @debug        = debug
     @started      = false
@@ -89,11 +146,34 @@ class OllamaChat::Utils::Fetcher
 
   private
 
+  # The excon method creates a new Excon client instance configured with the
+  # specified URL and options.
+  #
+  # @param url [ String ] the URL to be used for the Excon client
+  # @param options [ Hash ] additional options to be merged with http_options
+  #
+  # @return [ Excon ] a new Excon client instance
+  #
+  # @see #normalize_url
+  # @see #http_options
   def excon(url, **options)
     url = self.class.normalize_url(url)
     Excon.new(url, options.merge(@http_options))
   end
 
+  # Makes an HTTP GET request to the specified URL with optional headers and
+  # processing block.
+  #
+  # This method handles both streaming and non-streaming HTTP requests, using
+  # Excon for the actual HTTP communication. The response body is written to a
+  # temporary file which is then decorated with additional behavior before
+  # being passed to the provided block.
+  #
+  # @param url [String] The URL to make the GET request to
+  # @param headers [Hash] Optional headers to include in the request (keys will
+  #                       be converted to strings)
+  # @yield [Tempfile] The temporary file containing the response body, after
+  #                   decoration
   def get(url, headers: {}, &block)
     headers |= self.headers
     headers = headers.transform_keys(&:to_s)
@@ -130,18 +210,41 @@ class OllamaChat::Utils::Fetcher
     yield HeaderExtension.failed
   end
 
+  # The headers method returns a hash containing the default HTTP headers
+  # that should be used for requests, including a User-Agent header
+  # configured with the application's user agent string.
+  #
+  # @return [ Hash ] a hash mapping header names to their values
+  # @note The returned hash includes the 'User-Agent' header
+  #       set to OllamaChat::Chat.user_agent.
   def headers
     {
       'User-Agent' => OllamaChat::Chat.user_agent,
     }
   end
 
+  # The middlewares method returns the combined array of default Excon
+  # middlewares and the RedirectFollower middleware, ensuring there are no
+  # duplicates.
+  #
+  # @return [ Array ] an array of middleware classes including RedirectFollower
+  #                   deduplicated from the default Excon middlewares.
   def middlewares
     (Excon.defaults[:middlewares] + [ Excon::Middleware::RedirectFollower ]).uniq
   end
 
   private
 
+  # Decorates a temporary IO object with header information from an HTTP
+  # response.
+  #
+  # This method extends the given temporary IO object with HeaderExtension
+  # module and populates it with content type and cache expiration information
+  # extracted from the provided response headers.
+  #
+  # @param tmp [IO] The temporary IO object to decorate (typically a file handle)
+  # @param response [Object] HTTP response object containing headers
+  # @option response [Hash] :headers HTTP headers hash
   def decorate_io(tmp, response)
     tmp.rewind
     tmp.extend(HeaderExtension)
@@ -156,6 +259,13 @@ class OllamaChat::Utils::Fetcher
     end
   end
 
+  # The callback method creates a proc that handles chunked data processing by
+  # updating progress information and writing chunks to a temporary file.
+  #
+  # @param tmp [ Tempfile ] the temporary file to which data chunks are written
+  #
+  # @return [ Proc ] a proc that accepts chunk, remaining_bytes, and total_bytes
+  #                  parameters for processing streamed data
   def callback(tmp)
     -> chunk, remaining_bytes, total_bytes do
       total   = total_bytes or next
@@ -171,6 +281,13 @@ class OllamaChat::Utils::Fetcher
     end
   end
 
+  # The message method formats progress information by combining current and
+  # total values with unit formatting, along with timing details.
+  #
+  # @param current [ Integer ] the current progress value
+  # @param total [ Integer ] the total progress value
+  #
+  # @return [ String ] a formatted progress string including units and timing information
   def message(current, total)
     progress = '%s/%s' % [ current, total ].map {
       Tins::Unit.format(_1, format: '%.2f %U')

data/lib/ollama_chat/version.rb

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

data/lib/ollama_chat/vim.rb

@@ -0,0 +1,53 @@
+require 'tempfile'
+require 'pathname'
+
+class OllamaChat::Vim
+  # Initializes a new Vim server connection
+  #
+  # Creates a new OllamaChat::Vim instance for interacting with a specific Vim
+  # server. If no server name is provided, it defaults to using the current
+  # working directory as the server identifier.
+  #
+  # @param server_name [String, nil] The name of the Vim server to connect to.
+  #  If nil or empty, defaults to the current working directory path in
+  #  uppercase
+  def initialize(server_name)
+    server_name.full? or server_name = default_server_name
+    @server_name = server_name
+  end
+
+  # The default server name is derived from the current working directory It
+  # converts the absolute path to uppercase for consistent identification This
+  # approach ensures each working directory gets a unique server identifier The
+  # server name format makes it easy to distinguish different Vim sessions
+  def default_server_name
+    Pathname.pwd.to_s.upcase
+  end
+
+  # Inserts text at the current cursor position in Vim
+  #
+  # This method writes the provided text to a temporary file and uses Vim's
+  # remote-send functionality to insert it at the current cursor position.
+  # The text is automatically indented to match the current column position.
+  #
+  # @param text [String] The text to be inserted into the Vim buffer
+  def insert(text)
+    spaces = (col - 1).clamp(0..)
+    text   = text.gsub(/^/, ' ' * spaces)
+    Tempfile.open do |tmp|
+      tmp.write(text)
+      tmp.flush
+      system %{vim --servername "#@server_name" --remote-send "<ESC>:r #{tmp.path}<CR>"}
+    end
+  end
+
+  # Returns the current column position of the cursor in the Vim server
+  #
+  # This method queries the specified Vim server for the current cursor position
+  # using Vim's remote expression feature. It executes a Vim command that returns
+  # the result of `col('.')`, which represents the current column number (1-indexed)
+  # of the cursor position.
+  def col
+    `vim --servername "#@server_name" --remote-expr "col('.')"`.chomp.to_i
+  end
+end