phronomy 0.7.1 → 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/tool_executor.rb

@@ -1,106 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  # Centralises tool execution routing based on {Tool::Base.execution_mode}.
-  #
-  # This is the single place in the framework that decides *how* a tool call is
-  # dispatched:
-  #
-  # - +:cooperative+       — dispatched via +Runtime#spawn+ through the configured
-  #                          scheduler. Under the +:fiber+ backend this avoids an
-  #                          extra OS thread; under the +:thread+ backend it is
-  #                          backed by +ThreadScheduler+ (one thread per task).
-  # - +:blocking_io+       — submitted to +BlockingAdapterPool+ when the runtime
-  #                          provides a pool; falls back to +Runtime#spawn+ otherwise.
-  # - +:cpu_bound+         — emits a deprecation-style warning then falls back to
-  #                          +:blocking_io+ routing (no process pool available yet).
-  # - +:external_process+  — falls back to +:blocking_io+ routing (no process
-  #                          manager available yet).
-  #
-  # All paths return an object that responds to +#await+ (+Phronomy::Task+ or
-  # +BlockingAdapterPool::PendingOperation+), so callers can collect results
-  # uniformly.
-  #
-  # @note Non-goals
-  #   ToolExecutor deliberately does NOT provide:
-  #   - A CPU-bound process pool. CPU-intensive tool work must be handled at the
-  #     application layer (e.g., fork, Sidekiq, separate OS processes). The
-  #     framework will not add a +ProcessPoolExecutor+ equivalent.
-  #   - An external process manager. Spawning or supervising subprocesses is
-  #     out of scope for this module.
-  #   - Additional core execution routes beyond scheduler-backed cooperative
-  #     execution and BlockingAdapterPool-backed blocking I/O isolation.
-  #     The +:cpu_bound+ and +:external_process+ modes are accepted for
-  #     compatibility but both fall back to +:blocking_io+ routing with a
-  #     one-time warning. If a genuinely new core execution route is needed,
-  #     a new ADR is required.
-  #   These non-goals follow from the cooperative-first, non-preemptive
-  #   concurrency model (ADR-010): framework components must not assume the
-  #   caller's concurrency model, and CPU/process management belongs to the
-  #   application layer.
-  #
-  # @api private
-  module ToolExecutor
-    # Tracks tool classes that have already emitted an execution_mode warning so
-    # that the same warning is only logged once per process lifetime.
-    WARNED_MODES = Set.new
-    WARNED_MODES_MUTEX = Mutex.new
-    private_constant :WARNED_MODES, :WARNED_MODES_MUTEX
-
-    # Dispatches a single tool call asynchronously according to its
-    # +execution_mode+ and returns an awaitable.
-    #
-    # @param tool               [Phronomy::Tool::Base] the tool instance to invoke
-    # @param args               [Hash]                 argument hash to pass to {Tool::Base#call}
-    # @param cancellation_token [Phronomy::CancellationToken, nil]
-    # @param runtime            [Phronomy::Runtime]    runtime to use for spawning
-    #                           (defaults to {Runtime.instance}; injectable for tests)
-    # @return [#await] a {Phronomy::Task} or {BlockingAdapterPool::PendingOperation}
-    # @api private
-    def self.call_async(tool:, args:, cancellation_token: nil, runtime: Phronomy::Runtime.instance)
-      ct = cancellation_token
-      mode = tool.class.execution_mode
-
-      # Warn and normalise unsupported modes to :blocking_io.
-      # Each (tool class, mode) pair emits the warning at most once per process
-      # lifetime to avoid log flooding in high-throughput scenarios.
-      if mode == :cpu_bound || mode == :external_process
-        warn_key = [tool.class.name, mode]
-        newly_warned = WARNED_MODES_MUTEX.synchronize { WARNED_MODES.add?(warn_key) }
-        if newly_warned
-          msg = if mode == :cpu_bound
-            "[Phronomy] Tool #{tool.class.name} declares execution_mode :cpu_bound, " \
-            "which has no dedicated executor. " \
-            "Falling back to blocking_io (BlockingAdapterPool). " \
-            "Use :blocking_io explicitly to suppress this warning."
-          else
-            "[Phronomy] Tool #{tool.class.name} declares execution_mode :external_process, " \
-            "which has no dedicated process manager. " \
-            "Falling back to blocking_io (BlockingAdapterPool)."
-          end
-          if Phronomy.configuration.logger
-            Phronomy.configuration.logger.warn(msg)
-          else
-            warn msg
-          end
-        end
-        mode = :blocking_io
-      end
-
-      pool = begin
-        runtime&.blocking_io
-      rescue
-        nil
-      end
-
-      if mode == :cooperative || pool.nil?
-        runtime.spawn(name: "tool-#{tool.class.name.to_s.split("::").last}") do
-          tool.call(args, cancellation_token: ct)
-        end
-      else
-        # Submit directly to pool — no wrapping Task thread required.
-        pool.submit(cancellation_token: ct) { tool.call(args, cancellation_token: ct) }
-      end
-    end
-  end
-end

data/lib/phronomy/vector_store/async_backend.rb

@@ -1,110 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module VectorStore
-    # Mixin that defines the async interface for VectorStore backends.
-    #
-    # Mixing this module into a VectorStore class provides three choices:
-    #
-    # 1. **Do nothing** — inherits default implementations from {VectorStore::Base}
-    #    that route through {BlockingAdapterPool} (the previous behaviour).
-    #
-    # 2. **Override selectively** — override only the async methods where the
-    #    backend has a native async driver, while the remaining methods fall back
-    #    to the pool.
-    #
-    # 3. **Implement all natively** — override all async methods to avoid pool
-    #    allocation entirely.
-    #
-    # @example Native async search (no pool worker thread allocated)
-    #   class MyFastStore < Phronomy::VectorStore::Base
-    #     include Phronomy::VectorStore::AsyncBackend
-    #
-    #     def search_async(query_embedding:, k: 5, cancellation_token: nil, timeout: nil)
-    #       # Returns a PendingOperation backed by a native async driver.
-    #       native_async_search(query_embedding, k)
-    #     end
-    #   end
-    #
-    # @api public
-    module AsyncBackend
-      # Async variant of {VectorStore::Base#add}.
-      #
-      # Submits the add call to {BlockingAdapterPool} by default.
-      # Override to use a native async driver.
-      #
-      # @param id                 [String]
-      # @param embedding          [Array<Float>]
-      # @param metadata           [Hash]
-      # @param cancellation_token [Phronomy::CancellationToken, nil]
-      # @param timeout            [Numeric, nil]
-      # @return [BlockingAdapterPool::PendingOperation]
-      # @api public
-      def add_async(id:, embedding:, metadata: {}, cancellation_token: nil, timeout: nil)
-        Phronomy::Runtime.instance.blocking_io.submit(
-          timeout: timeout,
-          cancellation_token: cancellation_token
-        ) do
-          add(id: id, embedding: embedding, metadata: metadata, cancellation_token: cancellation_token)
-        end
-      end
-
-      # Async variant of {VectorStore::Base#search}.
-      #
-      # Submits the search call to {BlockingAdapterPool} by default.
-      # Override to use a native async driver.
-      #
-      # @param query_embedding    [Array<Float>]
-      # @param k                  [Integer]
-      # @param cancellation_token [Phronomy::CancellationToken, nil]
-      # @param timeout            [Numeric, nil]
-      # @return [BlockingAdapterPool::PendingOperation]
-      # @api public
-      def search_async(query_embedding:, k: 5, cancellation_token: nil, timeout: nil)
-        Phronomy::Runtime.instance.blocking_io.submit(
-          timeout: timeout,
-          cancellation_token: cancellation_token
-        ) do
-          search(query_embedding: query_embedding, k: k, cancellation_token: cancellation_token)
-        end
-      end
-
-      # Async variant of {VectorStore::Base#remove}.
-      #
-      # Submits the remove call to {BlockingAdapterPool} by default.
-      # Override to use a native async driver.
-      #
-      # @param id                 [String]
-      # @param cancellation_token [Phronomy::CancellationToken, nil]
-      # @param timeout            [Numeric, nil]
-      # @return [BlockingAdapterPool::PendingOperation]
-      # @api public
-      def remove_async(id:, cancellation_token: nil, timeout: nil)
-        Phronomy::Runtime.instance.blocking_io.submit(
-          timeout: timeout,
-          cancellation_token: cancellation_token
-        ) do
-          remove(id: id)
-        end
-      end
-
-      # Async variant of {VectorStore::Base#clear}.
-      #
-      # Submits the clear call to {BlockingAdapterPool} by default.
-      # Override to use a native async driver.
-      #
-      # @param cancellation_token [Phronomy::CancellationToken, nil]
-      # @param timeout            [Numeric, nil]
-      # @return [BlockingAdapterPool::PendingOperation]
-      # @api public
-      def clear_async(cancellation_token: nil, timeout: nil)
-        Phronomy::Runtime.instance.blocking_io.submit(
-          timeout: timeout,
-          cancellation_token: cancellation_token
-        ) do
-          clear
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/vector_store/base.rb

@@ -1,89 +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.
-    #
-    # Async methods (`search_async`, `add_async`, `remove_async`, `clear_async`)
-    # are provided by the {AsyncBackend} mixin which defaults to routing calls
-    # through {BlockingAdapterPool}.  Backends with native async drivers may
-    # override individual async methods without touching the pool at all.
-    class Base
-      include AsyncBackend
-
-      # 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