phronomy 0.7.0 → 0.8.0

data/lib/phronomy/prompt_template.rb

@@ -1,96 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  # A prompt template that substitutes {{variable}} placeholders in a string.
-  #
-  # @example Simple human template
-  #   t = Phronomy::PromptTemplate.new(template: "Translate to {{lang}}: {{text}}")
-  #   t.format(lang: "French", text: "Hello")
-  #   # => "Translate to French: Hello"
-  #
-  # @example With a system template
-  #   t = Phronomy::PromptTemplate.new(
-  #     template: "{{question}}",
-  #     system_template: "You are a {{role}} assistant."
-  #   )
-  #   t.format_system(role: "helpful")
-  #   # => "You are a helpful assistant."
-  #
-  # As a Runnable, #invoke accepts a Hash of variables and returns a Hash
-  # with :prompt (and optionally :system) keys.
-  class PromptTemplate
-    include Phronomy::Runnable
-
-    PLACEHOLDER = /\{\{(\w+)\}\}/
-
-    attr_reader :template, :system_template
-
-    # @param template        [String] human message template with {{var}} placeholders
-    # @param system_template [String, nil] optional system message template
-    # @api public
-    def initialize(template:, system_template: nil)
-      @template = template
-      @system_template = system_template
-    end
-
-    # Substitute all {{var}} placeholders in the human template.
-    #
-    # @param variables [Hash{Symbol => String}]
-    # @return [String]
-    # @api public
-    def format(**variables)
-      substitute(@template, variables)
-    end
-
-    # Substitute all {{var}} placeholders in the system template.
-    # Returns nil when no system template was set.
-    #
-    # @param variables [Hash{Symbol => String}]
-    # @return [String, nil]
-    # @api public
-    def format_system(**variables)
-      @system_template && substitute(@system_template, variables)
-    end
-
-    # Runnable interface: accepts a Hash of variable values.
-    # Returns { prompt: String, system: String|nil }.
-    #
-    # @param input  [Hash{Symbol => String}]
-    # @return [Hash]
-    # @api public
-    def invoke(input, config: {})
-      vars = normalize_input(input)
-      result = {prompt: format(**vars)}
-      sys = format_system(**vars)
-      result[:system] = sys if sys
-      result
-    end
-
-    # Returns the list of placeholder names found in both templates.
-    #
-    # @return [Array<Symbol>]
-    # @api public
-    def variables
-      names = @template.scan(PLACEHOLDER).flatten
-      names += @system_template.scan(PLACEHOLDER).flatten if @system_template
-      names.map(&:to_sym).uniq
-    end
-
-    private
-
-    def substitute(text, variables)
-      text.gsub(PLACEHOLDER) do |match|
-        key = Regexp.last_match(1).to_sym
-        variables.fetch(key) { raise KeyError, "Missing variable: {{#{key}}}" }
-      end
-    end
-
-    def normalize_input(input)
-      case input
-      when Hash then input
-      when String then {input: input}
-      else raise ArgumentError, "PromptTemplate#invoke expects a Hash of variables, got #{input.class}"
-      end
-    end
-  end
-end

data/lib/phronomy/splitter/base.rb

@@ -1,47 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  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

data/lib/phronomy/splitter/fixed_size_splitter.rb

@@ -1,51 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Splitter
-    # Splits text into fixed-size character chunks with optional overlap.
-    #
-    # @example
-    #   splitter = Phronomy::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

data/lib/phronomy/splitter/recursive_splitter.rb

@@ -1,105 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Splitter
-    # Splits text recursively using a prioritised list of separator strings.
-    #
-    # The splitter tries each separator in order.  When a separator produces
-    # chunks that are still larger than +chunk_size+, it recurses with the
-    # next separator in the list.  This mirrors LangChain's
-    # RecursiveCharacterTextSplitter behaviour.
-    #
-    # Default separators (in priority order):
-    #   1. "\n\n"  — paragraph breaks
-    #   2. "\n"    — line breaks
-    #   3. ". "    — sentence boundaries
-    #   4. " "     — word boundaries
-    #   5. ""      — character-level fallback
-    #
-    # @example
-    #   splitter = Phronomy::Splitter::RecursiveSplitter.new(chunk_size: 300, chunk_overlap: 30)
-    #   chunks   = splitter.split({ text: long_markdown, metadata: { source: "guide.md" } })
-    class RecursiveSplitter < Base
-      DEFAULT_SEPARATORS = ["\n\n", "\n", ". ", " ", ""].freeze
-
-      # @param chunk_size    [Integer] maximum characters per chunk (default: 1000)
-      # @param chunk_overlap [Integer] overlap characters (default: 200)
-      # @param separators    [Array<String>] separator list in priority order
-      # @api public
-      def initialize(chunk_size: 1000, chunk_overlap: 200, separators: DEFAULT_SEPARATORS)
-        raise ArgumentError, "chunk_overlap must be less than chunk_size" if chunk_overlap >= chunk_size
-
-        @chunk_size = chunk_size
-        @chunk_overlap = chunk_overlap
-        @separators = separators
-      end
-
-      # @param document [Hash, String]
-      # @return [Array<Hash>]
-      # @api public
-      def split(document)
-        doc = normalise(document)
-        texts = recursive_split(doc[:text], @separators)
-        merge_with_overlap(texts).each_with_index.map do |text, idx|
-          {text: text, metadata: doc[:metadata].merge(chunk: idx)}
-        end
-      end
-
-      private
-
-      # Split +text+ using the first separator that yields non-trivial pieces,
-      # then recurse on any piece that is still too large.
-      def recursive_split(text, separators)
-        return [text] if text.length <= @chunk_size || separators.empty?
-
-        sep, *rest_seps = separators
-
-        # Character-level fallback: just slice
-        if sep == ""
-          return FixedSizeSplitter
-              .new(chunk_size: @chunk_size, chunk_overlap: @chunk_overlap)
-              .split(text)
-              .map { |c| c[:text] }
-        end
-
-        parts = text.split(sep)
-
-        # If this separator doesn't split, try the next
-        return recursive_split(text, rest_seps) if parts.length <= 1
-
-        # Re-attach the separator to each part except the last so context is preserved
-        parts_with_sep = parts.each_with_index.map do |part, i|
-          (i < parts.length - 1) ? part + sep : part
-        end
-
-        parts_with_sep.flat_map do |part|
-          if part.length > @chunk_size
-            recursive_split(part, rest_seps)
-          else
-            [part]
-          end
-        end.reject { |t| t.strip.empty? }
-      end
-
-      # Merge small adjacent pieces and apply overlap between chunks.
-      def merge_with_overlap(texts)
-        merged = []
-        current = +""
-
-        texts.each do |text|
-          if current.length + text.length <= @chunk_size
-            current << text
-          else
-            merged << current.strip unless current.strip.empty?
-            # Start next chunk with overlap from the end of current
-            overlap_text = (current.length > @chunk_overlap) ? current[-@chunk_overlap..] : current
-            current = overlap_text + text
-          end
-        end
-
-        merged << current.strip unless current.strip.empty?
-        merged
-      end
-    end
-  end
-end

data/lib/phronomy/vector_store/base.rb

@@ -1,82 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module VectorStore
-    # Abstract interface for vector stores.
-    #
-    # Implementations manage a collection of (embedding, metadata) pairs and
-    # support similarity search.
-    class Base
-      # Add a document with its vector embedding.
-      #
-      # @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
-      # @api public
-      def add(id:, embedding:, metadata: {}, cancellation_token: nil)
-        cancellation_token&.raise_if_cancelled!
-        raise NotImplementedError, "#{self.class}#add is not implemented"
-      end
-
-      # Return the k most similar documents to the query embedding.
-      #
-      # @param query_embedding    [Array<Float>]
-      # @param k                  [Integer]                        number of results
-      # @param cancellation_token [Phronomy::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)
-        cancellation_token&.raise_if_cancelled!
-        raise NotImplementedError, "#{self.class}#search is not implemented"
-      end
-
-      # Remove a single document by id.
-      #
-      # @param id [String] document identifier
-      # @api public
-      def remove(id:)
-        raise NotImplementedError, "#{self.class}#remove is not implemented"
-      end
-
-      # Remove all documents.
-      def clear
-        raise NotImplementedError, "#{self.class}#clear is not implemented"
-      end
-
-      # Return the number of documents stored.
-      #
-      # @return [Integer]
-      # @api public
-      def size
-        raise NotImplementedError, "#{self.class}#size is not implemented"
-      end
-
-      private
-
-      # Validates that embedding has the expected dimension.
-      # Raises ArgumentError if sizes differ.
-      # A nil expected_dimension is a no-op (dimension not yet established).
-      def validate_embedding_dimension!(embedding, expected_dimension)
-        return unless expected_dimension
-
-        actual = embedding.size
-        return if actual == expected_dimension
-
-        raise ArgumentError,
-          "Embedding dimension mismatch: expected #{expected_dimension}, got #{actual}"
-      end
-
-      # Validates that k is a positive integer.
-      # Accepts any value accepted by Integer() (e.g. "5"), but raises
-      # ArgumentError for non-integer strings, zero, and negative values.
-      def validate_k!(k)
-        int_k = Integer(k)
-        raise ArgumentError, "k must be a positive integer, got #{int_k}" unless int_k >= 1
-        int_k
-      rescue ArgumentError => e
-        raise ArgumentError, "k must be a positive integer: #{e.message}"
-      end
-    end
-  end
-end

data/lib/phronomy/vector_store/in_memory.rb

@@ -1,93 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module VectorStore
-    # Pure-Ruby in-memory vector store using cosine similarity.
-    #
-    # Intended for tests, short-lived agents, and Retrieval::Semantic scenarios where
-    # the message count is small enough that a linear scan is fast enough.
-    #
-    # @example
-    #   store = Phronomy::VectorStore::InMemory.new
-    #   store.add(id: "1", embedding: [0.1, 0.9], metadata: { message: msg })
-    #   results = store.search(query_embedding: [0.1, 0.8], k: 3)
-    class InMemory < Base
-      # @param dimension [Integer, nil] expected embedding dimension.
-      #   When nil, the dimension is inferred from the first call to #add.
-      #   For multi-threaded use, pass dimension: explicitly; concurrent first
-      #   adds are not guaranteed to be race-free.
-      # @api public
-      def initialize(dimension: nil)
-        @documents = {}
-        @expected_dimension = dimension
-      end
-
-      # @param id                 [String]
-      # @param embedding          [Array<Float>]
-      # @param metadata           [Hash]
-      # @param cancellation_token [Phronomy::CancellationToken, nil]
-      # @api public
-      def add(id:, embedding:, metadata: {}, cancellation_token: nil)
-        cancellation_token&.raise_if_cancelled!
-        # Establish expected dimension on first add, then validate.
-        @expected_dimension ||= embedding.size
-        validate_embedding_dimension!(embedding, @expected_dimension)
-        @documents[id] = {embedding: embedding, metadata: metadata}
-        self
-      end
-
-      # @param query_embedding    [Array<Float>]
-      # @param k                  [Integer]
-      # @param cancellation_token [Phronomy::CancellationToken, nil]
-      # @return [Array<Hash>] sorted by descending score
-      # @api public
-      def search(query_embedding:, k: 5, cancellation_token: nil)
-        cancellation_token&.raise_if_cancelled!
-        k = validate_k!(k)
-        # search never establishes dimension; validate only when dimension is known.
-        validate_embedding_dimension!(query_embedding, @expected_dimension)
-        # Take an atomic snapshot before iterating.  Hash#dup is a C-level
-        # call that completes without releasing the GVL, so it is atomic with
-        # respect to any other Ruby thread.  Iterating the copy instead of
-        # @documents directly prevents "can't add a new key into hash during
-        # iteration" when a concurrent thread calls #add.
-        snapshot = @documents.dup
-        results = snapshot.map do |id, doc|
-          score = cosine_similarity(query_embedding, doc[:embedding])
-          {id: id, score: score, metadata: doc[:metadata]}
-        end
-        results.sort_by { |r| -r[:score] }.first(k)
-      end
-
-      def remove(id:)
-        @documents.delete(id)
-        self
-      end
-
-      def clear
-        @documents.clear
-        self
-      end
-
-      # @return [Integer] number of documents stored
-      # @api public
-      def size
-        @documents.size
-      end
-
-      private
-
-      def cosine_similarity(a, b)
-        return 0.0 if a.empty? || b.empty?
-
-        dot = a.zip(b).sum { |x, y| x * y }
-        norm_a = Math.sqrt(a.sum { |x| x**2 })
-        norm_b = Math.sqrt(b.sum { |x| x**2 })
-
-        return 0.0 if norm_a.zero? || norm_b.zero?
-
-        dot / (norm_a * norm_b)
-      end
-    end
-  end
-end

data/lib/phronomy/vector_store/pgvector.rb

@@ -1,127 +0,0 @@
-# frozen_string_literal: true
-
-require "json"
-
-module Phronomy
-  module VectorStore
-    # PostgreSQL-backed vector store using the pgvector extension.
-    #
-    # Requires:
-    #   - The +pgvector+ gem (add to your Gemfile)
-    #   - An ActiveRecord model class with the following columns:
-    #       id        (string / uuid)
-    #       embedding (vector — from the pgvector column type)
-    #       metadata  (text or jsonb — stores arbitrary metadata as JSON)
-    #
-    # @example Usage
-    #   store = Phronomy::VectorStore::Pgvector.new(model_class: VectorDocument)
-    #   store.add(id: "doc1", embedding: [0.1, 0.9], metadata: {text: "hello"})
-    #   results = store.search(query_embedding: [0.1, 0.8], k: 5)
-    class Pgvector < Base
-      # @param model_class [Class]        ActiveRecord model with id/embedding/metadata columns
-      # @param dimension   [Integer, nil] expected embedding dimension for Phronomy-side
-      #   pre-validation.  When nil, dimension enforcement is delegated to the
-      #   database schema; no pre-validation is performed by Phronomy.
-      # @api public
-      def initialize(model_class:, dimension: nil)
-        begin
-          require "pgvector"
-        rescue LoadError
-          raise LoadError,
-            "pgvector gem is required for Phronomy::VectorStore::Pgvector. " \
-            "Add `gem 'pgvector'` to your Gemfile."
-        end
-        @model_class = model_class
-        @dimension = dimension
-      end
-
-      # @param id                 [String]
-      # @param embedding          [Array<Float>]
-      # @param metadata           [Hash]
-      # @param cancellation_token [Phronomy::CancellationToken, nil]
-      # @api public
-      def add(id:, embedding:, metadata: {}, cancellation_token: nil)
-        cancellation_token&.raise_if_cancelled!
-        validate_embedding_dimension!(embedding, @dimension)
-        @model_class.upsert(
-          {id: id, embedding: safe_vector(embedding), metadata: metadata.to_json},
-          unique_by: :id
-        )
-        self
-      end
-
-      # @param query_embedding    [Array<Float>]
-      # @param k                  [Integer]
-      # @param cancellation_token [Phronomy::CancellationToken, nil]
-      # @return [Array<Hash>] sorted by descending similarity score
-      # @api public
-      def search(query_embedding:, k: 5, cancellation_token: nil)
-        cancellation_token&.raise_if_cancelled!
-        k_safe = validate_k!(k)
-        validate_embedding_dimension!(query_embedding, @dimension)
-        vec = safe_vector_literal(query_embedding)
-        conn = @model_class.connection
-        quoted_vec = "#{conn.quote(vec)}::vector"
-
-        @model_class
-          .select("id, metadata, 1 - (embedding <=> #{quoted_vec}) AS score")
-          .order("embedding <=> #{quoted_vec}")
-          .limit(k_safe)
-          .map do |r|
-            {
-              id: r.id.to_s,
-              score: r.score.to_f,
-              metadata: parse_metadata(r.metadata)
-            }
-          end
-      end
-
-      def remove(id:)
-        @model_class.where(id: id).delete_all
-        self
-      end
-
-      def clear
-        @model_class.delete_all
-        self
-      end
-
-      # Returns the number of documents in the backing table.
-      def size
-        @model_class.count
-      end
-
-      private
-
-      # Parses a metadata value returned by the pg driver.
-      # Handles NULL (nil), already-parsed Hash, and JSON string forms.
-      def parse_metadata(raw)
-        return {} if raw.nil?
-        return symbolize_hash_keys(raw) if raw.is_a?(Hash)
-
-        parsed = JSON.parse(raw.to_s, symbolize_names: true)
-        parsed.is_a?(Hash) ? parsed : {}
-      rescue JSON::ParserError
-        {}
-      end
-
-      # Recursively symbolizes keys for an already-parsed Hash.
-      def symbolize_hash_keys(hash)
-        hash.each_with_object({}) do |(k, v), h|
-          h[k.to_sym] = v.is_a?(Hash) ? symbolize_hash_keys(v) : v
-        end
-      end
-
-      # Validates that all elements are numeric and converts to a pgvector-
-      # compatible literal string (e.g. "[1.0,0.5,-0.3]").
-      def safe_vector_literal(embedding)
-        "[#{embedding.map { |v| Float(v) }.join(",")}]"
-      end
-
-      # Returns a validated vector for the upsert call.
-      def safe_vector(embedding)
-        safe_vector_literal(embedding)
-      end
-    end
-  end
-end