phronomy 0.7.1 → 0.9.0

data/lib/phronomy/tools/vector_search.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Tools
+    # A Capability::Base subclass that wraps a {Phronomy::VectorStore::Base} and
+    # a {Phronomy::VectorStore::Embeddings::Base} adapter so that an agent can
+    # perform semantic search as a tool call.
+    #
+    # Do not instantiate this class directly.  Use the factory method
+    # {.from_store} to produce a configured subclass, then pass it to your agent.
+    #
+    # @example
+    #   store = Phronomy::VectorStore::InMemory.new
+    #   emb   = Phronomy::VectorStore::Embeddings::RubyLLMEmbeddings.new(model: "...")
+    #   tool  = Phronomy::Tools::VectorSearch.from_store(store, embeddings: emb,
+    #             k: 3, tool_name: "search_docs",
+    #             description: "Search the company knowledge base.")
+    #   agent = MyAgent.new
+    #   agent.tools tool
+    #
+    # @api public
+    class VectorSearch < Phronomy::Agent::Context::Capability::Base
+      description "Search for relevant documents using semantic similarity."
+      param :query, type: :string, desc: "The natural-language search query"
+
+      class << self
+        # Build a VectorSearch tool backed by the given store and embeddings adapter.
+        #
+        # @param store       [Phronomy::VectorStore::Base]
+        # @param embeddings  [Phronomy::VectorStore::Embeddings::Base]
+        # @param k           [Integer]       number of results to return (default 5)
+        # @param tool_name   [String]        name exposed to the LLM
+        # @param description [String, nil]   optional description override
+        # @return [Class] anonymous subclass of VectorSearch configured with the given store
+        # @api public
+        def from_store(store, embeddings:, k: 5, tool_name: "vector_search", description: nil)
+          klass = Class.new(self)
+          klass.tool_name(tool_name)
+          klass.description(description || "Search the vector store for documents similar to the query.")
+
+          klass.define_method(:initialize) do
+            @store = store
+            @embeddings = embeddings
+            @k = k
+          end
+
+          klass.define_method(:execute) do |query:|
+            embedding = @embeddings.embed(query)
+            results = @store.search(query_embedding: embedding, k: @k)
+            return "No results found." if results.empty?
+
+            results.map.with_index(1) do |r, i|
+              content = r.dig(:metadata, :content) ||
+                r.dig(:metadata, :text) ||
+                r[:metadata].to_s
+              "[#{i}] (score: #{r[:score].round(3)}) #{content}"
+            end.join("\n")
+          end
+
+          klass
+        end
+      end
+
+      # @api public
+      def execute(query:)
+        raise NotImplementedError, "Use VectorSearch.from_store to create a configured instance"
+      end
+    end
+  end
+end

data/lib/phronomy/tracing/null_tracer.rb

@@ -16,7 +16,9 @@ module Phronomy
       # Returns a minimal span object with the given name.
       def start_span(name, **) = SpanStruct.new(name)
 
-      # Does nothing.
+      # Does nothing. Explicit nil is equivalent to an empty method body; the
+      # mutation "remove nil" is accepted as it does not change observable behaviour.
+      # mutant:disable
       def finish_span(span, **) = nil
     end
   end

data/lib/phronomy/vector_store/async_backend.rb

@@ -36,7 +36,7 @@ module Phronomy
       # @param id                 [String]
       # @param embedding          [Array<Float>]
       # @param metadata           [Hash]
-      # @param cancellation_token [Phronomy::CancellationToken, nil]
+      # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
       # @param timeout            [Numeric, nil]
       # @return [BlockingAdapterPool::PendingOperation]
       # @api public
@@ -56,7 +56,7 @@ module Phronomy
       #
       # @param query_embedding    [Array<Float>]
       # @param k                  [Integer]
-      # @param cancellation_token [Phronomy::CancellationToken, nil]
+      # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
       # @param timeout            [Numeric, nil]
       # @return [BlockingAdapterPool::PendingOperation]
       # @api public
@@ -75,7 +75,7 @@ module Phronomy
       # Override to use a native async driver.
       #
       # @param id                 [String]
-      # @param cancellation_token [Phronomy::CancellationToken, nil]
+      # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
       # @param timeout            [Numeric, nil]
       # @return [BlockingAdapterPool::PendingOperation]
       # @api public
@@ -93,7 +93,7 @@ module Phronomy
       # Submits the clear call to {BlockingAdapterPool} by default.
       # Override to use a native async driver.
       #
-      # @param cancellation_token [Phronomy::CancellationToken, nil]
+      # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
       # @param timeout            [Numeric, nil]
       # @return [BlockingAdapterPool::PendingOperation]
       # @api public

data/lib/phronomy/vector_store/base.rb

@@ -19,7 +19,7 @@ module Phronomy
       # @param id                 [String]                         unique document identifier
       # @param embedding          [Array<Float>]                   vector embedding
       # @param metadata           [Hash]                           arbitrary metadata (e.g. the original message object)
-      # @param cancellation_token [Phronomy::CancellationToken, nil] optional; raises CancellationError when cancelled
+      # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil] optional; raises CancellationError when cancelled
       # @api public
       def add(id:, embedding:, metadata: {}, cancellation_token: nil)
         cancellation_token&.raise_if_cancelled!
@@ -30,7 +30,7 @@ module Phronomy
       #
       # @param query_embedding    [Array<Float>]
       # @param k                  [Integer]                        number of results
-      # @param cancellation_token [Phronomy::CancellationToken, nil] optional; raises CancellationError when cancelled
+      # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil] optional; raises CancellationError when cancelled
       # @return [Array<Hash>] each element: { id:, score:, metadata: }
       # @api public
       def search(query_embedding:, k: 5, cancellation_token: nil)

data/lib/phronomy/vector_store/embeddings/base.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module VectorStore
+    module Embeddings
+      # Abstract interface for embedding adapters.
+      #
+      # Concrete implementations must override {#embed} and return a vector
+      # as an +Array<Float>+.
+      class Base
+        # Embed the given text and return a vector representation.
+        #
+        # @param text               [String]                         the text to embed
+        # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil] optional; raises CancellationError when cancelled
+        # @return [Array<Float>] the embedding vector
+        # @api public
+        def embed(text, cancellation_token = nil)
+          cancellation_token&.raise_if_cancelled!
+          raise NotImplementedError, "#{self.class}#embed is not implemented"
+        end
+
+        # Submits an {#embed} call to {BlockingAdapterPool} and returns a
+        # {BlockingAdapterPool::PendingOperation}.
+        #
+        # @param text               [String]
+        # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
+        # @param timeout            [Numeric, nil] seconds before the operation is abandoned
+        # @return [BlockingAdapterPool::PendingOperation]
+        # @api public
+        def embed_async(text, cancellation_token = nil, timeout: nil)
+          Phronomy::Runtime.instance.blocking_io.submit(
+            timeout: timeout,
+            cancellation_token: cancellation_token
+          ) do
+            embed(text, cancellation_token)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/vector_store/embeddings/ruby_llm_embeddings.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module VectorStore
+    module Embeddings
+      # Embeddings adapter backed by RubyLLM.
+      #
+      # Delegates to +RubyLLM.embed+ and returns the resulting vector as an
+      # +Array<Float>+.
+      #
+      # @example Default model
+      #   embeddings = Phronomy::VectorStore::Embeddings::RubyLLMEmbeddings.new
+      #   vector = embeddings.embed("Hello, world!")
+      #
+      # @example Explicit model
+      #   embeddings = Phronomy::VectorStore::Embeddings::RubyLLMEmbeddings.new(model: "text-embedding-3-small")
+      #   vector = embeddings.embed("Hello, world!")
+      class RubyLLMEmbeddings < Base
+        # @param model               [String, nil] embedding model identifier; nil uses the RubyLLM default
+        # @param provider            [Symbol, nil] provider override (e.g. :openai); nil uses the RubyLLM default
+        # @param assume_model_exists [Boolean]     when true, skips RubyLLM model-registry validation
+        #                                          (useful for locally hosted models not in the registry)
+        # @api public
+        def initialize(model: nil, provider: nil, assume_model_exists: false)
+          @model = model
+          @provider = provider
+          @assume_model_exists = assume_model_exists
+        end
+
+        # Embed text via RubyLLM.
+        #
+        # @param text               [String]
+        # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil] optional; raises CancellationError when cancelled
+        # @return [Array<Float>]
+        # @api public
+        def embed(text, cancellation_token = nil)
+          cancellation_token&.raise_if_cancelled!
+          opts = {}
+          opts[:model] = @model if @model
+          opts[:provider] = @provider if @provider
+          opts[:assume_model_exists] = true if @assume_model_exists
+          RubyLLM.embed(text, **opts).vectors
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/vector_store/in_memory.rb

@@ -25,7 +25,7 @@ module Phronomy
       # @param id                 [String]
       # @param embedding          [Array<Float>]
       # @param metadata           [Hash]
-      # @param cancellation_token [Phronomy::CancellationToken, nil]
+      # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
       # @api public
       def add(id:, embedding:, metadata: {}, cancellation_token: nil)
         cancellation_token&.raise_if_cancelled!
@@ -38,9 +38,14 @@ module Phronomy
 
       # @param query_embedding    [Array<Float>]
       # @param k                  [Integer]
-      # @param cancellation_token [Phronomy::CancellationToken, nil]
+      # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
       # @return [Array<Hash>] sorted by descending score
       # @api public
+      # mutant:disable - genuine equivalent mutations: doc.fetch(:embedding) vs doc[:embedding] (key
+      #   always present); {id:, score:, metadata: doc.fetch(:metadata)} shorthand+fetch vs []
+      #   (key always present); -r.fetch(:score) vs -r[:score] (key always present); snapshot = @documents
+      #   vs .dup is equivalent in single-threaded tests (GVL makes Hash#dup atomic, no behaviour
+      #   difference under test isolation)
       def search(query_embedding:, k: 5, cancellation_token: nil)
         cancellation_token&.raise_if_cancelled!
         k = validate_k!(k)
@@ -77,6 +82,11 @@ module Phronomy
 
       private
 
+      # mutant:disable - empty-vector early-return condition variants (if false, if nil, if a.empty?,
+      #   if b.empty?, if a.empty? && b.empty?, if a.empty? || false, if false || b.empty?,
+      #   if nil || b.empty?, if nil && b.empty?) are genuine equivalents: dimension validation in
+      #   #add and #search enforces same-size embeddings, so a.empty? iff b.empty?; when both are
+      #   empty norm_a = sqrt(0) = 0 so the norm_a.zero? guard returns 0.0 anyway
       def cosine_similarity(a, b)
         return 0.0 if a.empty? || b.empty?
 

data/lib/phronomy/vector_store/loader/base.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module VectorStore
+    module Loader
+      # Abstract base class for document loaders.
+      #
+      # A loader converts an external source (file path, URL, etc.) into an
+      # Array of document hashes understood by the rest of the pipeline:
+      #
+      #   [{ text: String, metadata: Hash }, ...]
+      #
+      # Subclasses must implement {#load}.
+      class Base
+        # Load documents from +source+ and return an array of document hashes.
+        #
+        # @param source [String] file path, URL, or other source identifier
+        # @return [Array<Hash>] array of <tt>{ text: String, metadata: Hash }</tt>
+        # @raise [NotImplementedError] when not overridden by a subclass
+        # @api public
+        def load(source)
+          raise NotImplementedError, "#{self.class}#load is not implemented"
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/vector_store/loader/csv_loader.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "csv"
+
+module Phronomy
+  module VectorStore
+    module Loader
+      # Loads a CSV file, converting each row into a separate document.
+      #
+      # By default the first row is treated as a header and column names are
+      # available in the document metadata.  The full row is serialised to
+      # a human-readable "key: value" string for embedding.
+      #
+      # @example
+      #   loader = Phronomy::VectorStore::Loader::CsvLoader.new
+      #   docs   = loader.load("products.csv")
+      #   # => [
+      #   #   { text: "name: Widget\nprice: 9.99", metadata: { source: "...", row: 1, name: "Widget", price: "9.99" } },
+      #   #   ...
+      #   # ]
+      class CsvLoader < Base
+        # @param headers     [Boolean] treat the first row as headers (default: true)
+        # @param text_column [String, nil] if set, use only this column as the document text
+        # @api public
+        def initialize(headers: true, text_column: nil)
+          @headers = headers
+          @text_column = text_column
+        end
+
+        # @param source [String] path to a CSV file
+        # @return [Array<Hash>]
+        # @raise [Errno::ENOENT] if the file does not exist
+        # @api public
+        def load(source)
+          rows = CSV.read(source, headers: @headers, encoding: "UTF-8")
+
+          if @headers
+            rows.each_with_index.map do |row, idx|
+              row_hash = row.to_h
+              text = if @text_column
+                row_hash[@text_column].to_s
+              else
+                row_hash.map { |k, v| "#{k}: #{v}" }.join("\n")
+              end
+              metadata = row_hash.transform_keys(&:to_sym).merge(source: source, row: idx + 1)
+              {text: text, metadata: metadata}
+            end
+          else
+            rows.each_with_index.map do |row, idx|
+              text = row.join(", ")
+              {text: text, metadata: {source: source, row: idx + 1}}
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/vector_store/loader/markdown_loader.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module VectorStore
+    module Loader
+      # Loads a Markdown file, optionally splitting on top-level headings.
+      #
+      # When +split_on_headings:+ is true (the default), each H1/H2 section
+      # becomes a separate document so that embeddings capture section semantics
+      # rather than the full file at once.
+      #
+      # @example Single document (heading split disabled)
+      #   loader = Phronomy::VectorStore::Loader::MarkdownLoader.new(split_on_headings: false)
+      #   docs   = loader.load("README.md")
+      #   # => [{ text: "# Title\n...", metadata: { source: "README.md" } }]
+      #
+      # @example Split per heading (default)
+      #   loader = Phronomy::VectorStore::Loader::MarkdownLoader.new
+      #   docs   = loader.load("guide.md")
+      #   # => [
+      #   #   { text: "# Section 1\n...", metadata: { source: "guide.md", section: "Section 1" } },
+      #   #   { text: "## Sub-section\n...", metadata: { source: "guide.md", section: "Sub-section" } },
+      #   # ]
+      class MarkdownLoader < Base
+        HEADING_RE = /^(\#{1,6})\s+(.+)$/
+
+        # @param split_on_headings [Boolean] split on H1–H6 boundaries (default: true)
+        # @api public
+        def initialize(split_on_headings: true)
+          @split_on_headings = split_on_headings
+        end
+
+        # @param source [String] path to a Markdown file
+        # @return [Array<Hash>]
+        # @raise [Errno::ENOENT] if the file does not exist
+        # @api public
+        def load(source)
+          content = File.read(source, encoding: "UTF-8")
+          return [{text: content, metadata: {source: source}}] unless @split_on_headings
+
+          split_by_headings(content, source)
+        end
+
+        private
+
+        def split_by_headings(content, source)
+          sections = []
+          current_lines = []
+          current_heading = nil
+
+          content.each_line do |line|
+            if (m = HEADING_RE.match(line.chomp))
+              flush_section(sections, current_lines, current_heading, source) if current_lines.any?
+              current_heading = m[2].strip
+              current_lines = [line]
+            else
+              current_lines << line
+            end
+          end
+
+          flush_section(sections, current_lines, current_heading, source) if current_lines.any?
+
+          # Fall back to single document if no headings were found
+          sections.empty? ? [{text: content, metadata: {source: source}}] : sections
+        end
+
+        def flush_section(sections, lines, heading, source)
+          text = lines.join
+          return if text.strip.empty?
+
+          metadata = {source: source}
+          metadata[:section] = heading if heading
+          sections << {text: text, metadata: metadata}
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/vector_store/loader/plain_text_loader.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module VectorStore
+    module Loader
+      # Loads a plain-text file as a single document.
+      #
+      # @example
+      #   loader = Phronomy::VectorStore::Loader::PlainTextLoader.new
+      #   docs   = loader.load("/path/to/file.txt")
+      #   # => [{ text: "...", metadata: { source: "/path/to/file.txt" } }]
+      class PlainTextLoader < Base
+        # @param source [String] absolute or relative path to a text file
+        # @return [Array<Hash>] single-element array with the file contents
+        # @raise [Errno::ENOENT] if the file does not exist
+        # @api public
+        def load(source)
+          text = File.read(source, encoding: "UTF-8")
+          [{text: text, metadata: {source: source}}]
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/vector_store/pgvector.rb

@@ -38,7 +38,7 @@ module Phronomy
       # @param id                 [String]
       # @param embedding          [Array<Float>]
       # @param metadata           [Hash]
-      # @param cancellation_token [Phronomy::CancellationToken, nil]
+      # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
       # @api public
       def add(id:, embedding:, metadata: {}, cancellation_token: nil)
         cancellation_token&.raise_if_cancelled!
@@ -52,7 +52,7 @@ module Phronomy
 
       # @param query_embedding    [Array<Float>]
       # @param k                  [Integer]
-      # @param cancellation_token [Phronomy::CancellationToken, nil]
+      # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
       # @return [Array<Hash>] sorted by descending similarity score
       # @api public
       def search(query_embedding:, k: 5, cancellation_token: nil)

data/lib/phronomy/vector_store/redis_search.rb

@@ -49,7 +49,7 @@ module Phronomy
       # @param id                 [String]
       # @param embedding          [Array<Float>]
       # @param metadata           [Hash]
-      # @param cancellation_token [Phronomy::CancellationToken, nil]
+      # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
       # @api public
       def add(id:, embedding:, metadata: {}, cancellation_token: nil)
         cancellation_token&.raise_if_cancelled!
@@ -68,7 +68,7 @@ module Phronomy
 
       # @param query_embedding    [Array<Float>]
       # @param k                  [Integer]
-      # @param cancellation_token [Phronomy::CancellationToken, nil]
+      # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
       # @return [Array<Hash>] sorted by descending similarity score
       # @api public
       def search(query_embedding:, k: 5, cancellation_token: nil)

data/lib/phronomy/vector_store/splitter/base.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module VectorStore
+    module Splitter
+      # Abstract base class for text splitters.
+      #
+      # A splitter takes a single document hash (or plain text) and returns an
+      # array of smaller chunk documents:
+      #
+      #   [{ text: String, metadata: Hash }, ...]
+      #
+      # Subclasses must implement {#split}.
+      class Base
+        # Split +document+ into an array of chunk documents.
+        #
+        # @param document [Hash, String]
+        #   Either a document hash (<tt>{ text: String, metadata: Hash }</tt>)
+        #   returned by a Loader, or a plain String.
+        # @return [Array<Hash>] array of <tt>{ text: String, metadata: Hash }</tt>
+        # @raise [NotImplementedError] when not overridden by a subclass
+        # @api public
+        def split(document)
+          raise NotImplementedError, "#{self.class}#split is not implemented"
+        end
+
+        # Convenience method: split an array of documents.
+        #
+        # @param documents [Array<Hash, String>]
+        # @return [Array<Hash>]
+        # @api public
+        def split_all(documents)
+          documents.flat_map { |doc| split(doc) }
+        end
+
+        private
+
+        # Normalise a document-or-string argument into {text:, metadata:}.
+        def normalise(document)
+          case document
+          when Hash then {text: document[:text].to_s, metadata: document.fetch(:metadata, {})}
+          when String then {text: document, metadata: {}}
+          else raise ArgumentError, "document must be a Hash or String, got #{document.class}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/vector_store/splitter/fixed_size_splitter.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module VectorStore
+    module Splitter
+      # Splits text into fixed-size character chunks with optional overlap.
+      #
+      # @example
+      #   splitter = Phronomy::VectorStore::Splitter::FixedSizeSplitter.new(chunk_size: 200, chunk_overlap: 20)
+      #   chunks   = splitter.split({ text: long_text, metadata: { source: "doc.txt" } })
+      #   # => [
+      #   #   { text: "...(200 chars)...", metadata: { source: "doc.txt", chunk: 0 } },
+      #   #   { text: "...(200 chars, 20-char overlap)...", metadata: { source: "doc.txt", chunk: 1 } },
+      #   # ]
+      class FixedSizeSplitter < Base
+        # @param chunk_size    [Integer] maximum characters per chunk (default: 1000)
+        # @param chunk_overlap [Integer] characters to repeat at the start of each
+        #   subsequent chunk (default: 200); must be less than chunk_size
+        # @api public
+        def initialize(chunk_size: 1000, chunk_overlap: 200)
+          raise ArgumentError, "chunk_overlap must be less than chunk_size" if chunk_overlap >= chunk_size
+
+          @chunk_size = chunk_size
+          @chunk_overlap = chunk_overlap
+        end
+
+        # @param document [Hash, String]
+        # @return [Array<Hash>]
+        # @api public
+        def split(document)
+          doc = normalise(document)
+          text = doc[:text]
+          base_metadata = doc[:metadata]
+
+          chunks = []
+          start = 0
+          index = 0
+
+          while start < text.length
+            chunk_text = text[start, @chunk_size]
+            chunks << {text: chunk_text, metadata: base_metadata.merge(chunk: index)}
+            break if start + @chunk_size >= text.length
+
+            start += @chunk_size - @chunk_overlap
+            index += 1
+          end
+
+          chunks
+        end
+      end
+    end
+  end
+end