phronomy 0.27.0 → 0.29.0

data/lib/phronomy/{agent/context_contract → context}/llm_input_manifest.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Phronomy
-  module Agent
+  module Context
     # ContentStore-backed durable codec boundary for one Provider input manifest.
     # It is intentionally separate from Storage::DurableRecord.
     class LLMInputManifest
@@ -62,7 +62,7 @@ module Phronomy
             label: label
           )
           unless SEGMENT_DELIVERIES.include?(delivery)
-            raise Phronomy::Storage::SerializationError,
+            raise Phronomy::Context::ManifestError,
               "LLMInputManifest segment delivery must be one of #{SEGMENT_DELIVERIES.inspect}, got #{delivery.inspect}"
           end
           tool_call_id = LLMInputManifest.send(
@@ -87,10 +87,10 @@ module Phronomy
             tool_call_id: tool_call_id,
             metadata: metadata
           )
-        rescue Phronomy::Storage::SerializationError
+        rescue Phronomy::Context::ManifestError
           raise
         rescue => error
-          raise Phronomy::Storage::SerializationError,
+          raise Phronomy::Context::ManifestError,
             "invalid LLMInputManifest segment: #{error.class}: #{error.message}"
         end
 
@@ -162,7 +162,7 @@ module Phronomy
         label = "LLMInputManifest"
         version = source.fetch("version")
         unless version.is_a?(String) && version == VERSION
-          raise Phronomy::Storage::SerializationError,
+          raise Phronomy::Context::ManifestError,
             "unsupported LLMInputManifest version: #{version.inspect}; " \
             "current version is #{VERSION.inspect}"
         end
@@ -229,10 +229,10 @@ module Phronomy
           adapter_name: adapter_name,
           adapter_version: adapter_version
         )
-      rescue Phronomy::Storage::SerializationError
+      rescue Phronomy::Context::ManifestError
         raise
       rescue => error
-        raise Phronomy::Storage::SerializationError,
+        raise Phronomy::Context::ManifestError,
           "invalid LLMInputManifest: #{error.class}: #{error.message}"
       end
 
@@ -262,11 +262,11 @@ module Phronomy
 
         def strict_source!(hash, required:, optional:, label:)
           unless hash.is_a?(Hash)
-            raise Phronomy::Storage::SerializationError,
+            raise Phronomy::Context::ManifestError,
               "#{label} must be a Hash"
           end
           unless hash.keys.all? { |key| key.is_a?(String) }
-            raise Phronomy::Storage::SerializationError,
+            raise Phronomy::Context::ManifestError,
               "#{label} keys must all be String"
           end
 
@@ -277,13 +277,13 @@ module Phronomy
             details = []
             details << "missing=#{missing.inspect}" unless missing.empty?
             details << "unknown=#{unknown.inspect}" unless unknown.empty?
-            raise Phronomy::Storage::SerializationError,
+            raise Phronomy::Context::ManifestError,
               "#{label} schema mismatch (#{details.join(", ")})"
           end
           Phronomy::CanonicalJSON.dump(hash)
           hash
         rescue ArgumentError => error
-          raise Phronomy::Storage::SerializationError,
+          raise Phronomy::Context::ManifestError,
             "#{label} is not canonical JSON compatible: #{error.message}"
         end
 
@@ -291,7 +291,7 @@ module Phronomy
           value = hash.fetch(key)
           return value if value.is_a?(Integer)
 
-          raise Phronomy::Storage::SerializationError,
+          raise Phronomy::Context::ManifestError,
             "#{label} #{key} must be an Integer"
         end
 
@@ -299,7 +299,7 @@ module Phronomy
           value = hash.fetch(key)
           return value if value.is_a?(Integer) && value.positive?
 
-          raise Phronomy::Storage::SerializationError,
+          raise Phronomy::Context::ManifestError,
             "#{label} #{key} must be a positive Integer"
         end
 
@@ -307,7 +307,7 @@ module Phronomy
           value = hash.fetch(key)
           return value if value.is_a?(Integer) && value >= 0
 
-          raise Phronomy::Storage::SerializationError,
+          raise Phronomy::Context::ManifestError,
             "#{label} #{key} must be a non-negative Integer"
         end
 
@@ -315,7 +315,7 @@ module Phronomy
           value = hash.fetch(key)
           return value if value.is_a?(String) && !value.empty?
 
-          raise Phronomy::Storage::SerializationError,
+          raise Phronomy::Context::ManifestError,
             "#{label} #{key} must be a non-empty String"
         end
 
@@ -323,7 +323,7 @@ module Phronomy
           value = hash[key]
           return value if value.nil? || value.is_a?(String)
 
-          raise Phronomy::Storage::SerializationError,
+          raise Phronomy::Context::ManifestError,
             "#{label} #{key} must be a String or nil"
         end
 
@@ -331,7 +331,7 @@ module Phronomy
           value = hash.fetch(key)
           return value if value.is_a?(String) && allowed.include?(value)
 
-          raise Phronomy::Storage::SerializationError,
+          raise Phronomy::Context::ManifestError,
             "#{label} #{key} must be one of #{allowed.inspect}"
         end
 
@@ -339,7 +339,7 @@ module Phronomy
           value = hash.fetch(key)
           return value if value.is_a?(Array)
 
-          raise Phronomy::Storage::SerializationError,
+          raise Phronomy::Context::ManifestError,
             "#{label} #{key} must be an Array"
         end
 
@@ -347,7 +347,7 @@ module Phronomy
           value = hash.fetch(key)
           return value if value.is_a?(Hash)
 
-          raise Phronomy::Storage::SerializationError,
+          raise Phronomy::Context::ManifestError,
             "#{label} #{key} must be a Hash"
         end
       end

data/lib/phronomy/{agent/context_contract → context}/llm_input_patch.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Phronomy
-  module Agent
+  module Context
     # Typed, canonicalizable input customization returned by before_llm_input.
     # v1 deliberately exposes only fields that are fully applied to every call.
     LLMInputPatch = Data.define(:model_config_patch, :segment_candidates) do

data/lib/phronomy/context/manifest_error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "../common/error"
+
+module Phronomy
+  module Context
+    # Invalid canonical context input; independent of its persistence backend.
+    class ManifestError < Phronomy::Error; end
+  end
+end

data/lib/phronomy/context/prompt_template.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Context
+    # A prompt template that substitutes {{variable}} placeholders in a string.
+    #
+    # @example Simple human template
+    #   t = Phronomy::Context::PromptTemplate.new(template: "Translate to {{lang}}: {{text}}")
+    #   t.format(lang: "French", text: "Hello")
+    #   # => "Translate to French: Hello"
+    #
+    # @example With a system template
+    #   t = Phronomy::Context::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
+end

data/lib/phronomy/{vector_store → documents}/loader/base.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Phronomy
-  module VectorStore
+  module Documents
     module Loader
       # Abstract base class for document loaders.
       #

data/lib/phronomy/{vector_store → documents}/loader/csv_loader.rb

@@ -3,7 +3,7 @@
 require "csv"
 
 module Phronomy
-  module VectorStore
+  module Documents
     module Loader
       # Loads a CSV file, converting each row into a separate document.
       #
@@ -12,7 +12,7 @@ module Phronomy
       # a human-readable "key: value" string for embedding.
       #
       # @example
-      #   loader = Phronomy::VectorStore::Loader::CsvLoader.new
+      #   loader = Phronomy::Documents::Loader::CsvLoader.new
       #   docs   = loader.load("products.csv")
       #   # => [
       #   #   { text: "name: Widget\nprice: 9.99", metadata: { source: "...", row: 1, name: "Widget", price: "9.99" } },

data/lib/phronomy/{vector_store → documents}/loader/markdown_loader.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Phronomy
-  module VectorStore
+  module Documents
     module Loader
       # Loads a Markdown file, optionally splitting on top-level headings.
       #
@@ -10,12 +10,12 @@ module Phronomy
       # rather than the full file at once.
       #
       # @example Single document (heading split disabled)
-      #   loader = Phronomy::VectorStore::Loader::MarkdownLoader.new(split_on_headings: false)
+      #   loader = Phronomy::Documents::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
+      #   loader = Phronomy::Documents::Loader::MarkdownLoader.new
       #   docs   = loader.load("guide.md")
       #   # => [
       #   #   { text: "# Section 1\n...", metadata: { source: "guide.md", section: "Section 1" } },

data/lib/phronomy/{vector_store → documents}/loader/plain_text_loader.rb

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
 module Phronomy
-  module VectorStore
+  module Documents
     module Loader
       # Loads a plain-text file as a single document.
       #
       # @example
-      #   loader = Phronomy::VectorStore::Loader::PlainTextLoader.new
+      #   loader = Phronomy::Documents::Loader::PlainTextLoader.new
       #   docs   = loader.load("/path/to/file.txt")
       #   # => [{ text: "...", metadata: { source: "/path/to/file.txt" } }]
       class PlainTextLoader < Base

data/lib/phronomy/{vector_store → documents}/splitter/base.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Phronomy
-  module VectorStore
+  module Documents
     module Splitter
       # Abstract base class for text splitters.
       #

data/lib/phronomy/{vector_store → documents}/splitter/fixed_size_splitter.rb

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
 module Phronomy
-  module VectorStore
+  module Documents
     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)
+      #   splitter = Phronomy::Documents::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 } },

data/lib/phronomy/{vector_store → documents}/splitter/recursive_splitter.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Phronomy
-  module VectorStore
+  module Documents
     module Splitter
       # Splits text recursively using a prioritised list of separator strings.
       #
@@ -18,7 +18,7 @@ module Phronomy
       #   5. ""      — character-level fallback
       #
       # @example
-      #   splitter = Phronomy::VectorStore::Splitter::RecursiveSplitter.new(chunk_size: 300, chunk_overlap: 30)
+      #   splitter = Phronomy::Documents::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

data/lib/phronomy/embeddings/async/async_client.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Embeddings
+    # Framework-owned asynchronous execution of a synchronous embedding adapter.
+    #
+    # Construction starts no Runtime. Each operation uses the current default
+    # pool unless a caller-owned pool was injected. Timeout includes queue wait
+    # and settles the result without forcibly interrupting an executing adapter.
+    #
+    # @api public
+    class AsyncClient
+      # @param adapter [Embeddings::Base] synchronous embedding adapter
+      # @param pool [Concurrency::OffloadPool, nil] optional execution pool
+      # @api public
+      def initialize(adapter:, pool: nil)
+        @adapter = adapter
+        @pool = pool
+      end
+
+      # Submits a synchronous embed call without waiting for queue capacity.
+      #
+      # @param text [String]
+      # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
+      # @param timeout [Numeric, nil] operation-wide submit timeout
+      # @return [Phronomy::TaskResult] the pool's original completion handle
+      # @api public
+      def embed_async(text, cancellation_token = nil, timeout: nil)
+        Phronomy::Execution.submit(pool: default_pool,
+          timeout: timeout,
+          cancellation_token: cancellation_token,
+          on_full: :raise) do
+          @adapter.embed(text, cancellation_token)
+        end
+      end
+
+      private
+
+      def default_pool
+        @pool
+      end
+    end
+  end
+end

data/lib/phronomy/embeddings/authentication_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "transport_error"
+
+module Phronomy
+  module Embeddings
+    # Provider refusal; this classification alone does not authorize retries.
+    # @api public
+    class AuthenticationError < TransportError; end
+  end
+end

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

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Phronomy
+  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::Embeddings::RubyLLMEmbeddings.new
+    #   vector = embeddings.embed("Hello, world!")
+    #
+    # @example Explicit model
+    #   embeddings = Phronomy::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
+
+      protected
+
+      # 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 perform_embed(text, cancellation_token = nil)
+        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
+      rescue ::RubyLLM::UnauthorizedError, ::RubyLLM::ForbiddenError => error
+        raise AuthenticationError.new(error.message, code: "embeddings.authentication_failed"), cause: error
+      rescue ::RubyLLM::RateLimitError => error
+        raise RateLimitError.new(error.message, code: "embeddings.rate_limited"), cause: error
+      rescue ::RubyLLM::Error => error
+        raise TransportError.new(error.message), cause: error
+      end
+    end
+  end
+end

data/lib/phronomy/embeddings/base.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "invalid_result_error"
+
+module Phronomy
+  module Embeddings
+    # Owns input validation, the cancellation checkpoint and result validation.
+    # Providers implement perform_embed; execution belongs to AsyncClient.
+    # This contract selects no provider or vector store.
+    # @api public
+    class Base
+      # @param text [String] empty text is allowed; model restrictions are provider-owned
+      # @param cancellation_token [#raise_if_cancelled!, nil]
+      # @return [Array<Float>] non-empty finite vector
+      # @raise [ArgumentError] when input is not text
+      # @raise [InvalidResultError] when the provider returns a malformed vector
+      # @api public
+      def embed(text, cancellation_token = nil)
+        cancellation_token&.raise_if_cancelled!
+        raise ArgumentError, "text must be a String" unless text.is_a?(String)
+        vector = perform_embed(text, cancellation_token)
+        unless vector.is_a?(Array) && !vector.empty? && vector.all? { |value|
+          value.is_a?(Numeric) && value.real? && value.finite? && value.to_f.finite?
+        }
+          raise InvalidResultError, "embed must return a non-empty Array of finite real numbers"
+        end
+        vector.map(&:to_f)
+      end
+
+      protected
+
+      # Provider extension point. Preserve cancellation and application errors;
+      # SDK adapters translate their own provider errors to TransportError.
+      # @param text [String]
+      # @param cancellation_token [#raise_if_cancelled!, nil]
+      # @return [Array<Numeric>]
+      # @api public
+      def perform_embed(text, cancellation_token = nil)
+        raise NotImplementedError, "#{self.class}#perform_embed is not implemented"
+      end
+    end
+  end
+end

data/lib/phronomy/embeddings/invalid_result_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "../common/error"
+
+module Phronomy
+  module Embeddings
+    # A provider returned data that violates the embedding result contract.
+    # @api public
+    class InvalidResultError < Phronomy::Error; end
+  end
+end

data/lib/phronomy/embeddings/rate_limit_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "transport_error"
+
+module Phronomy
+  module Embeddings
+    # Provider refusal; this classification alone does not authorize retries.
+    # @api public
+    class RateLimitError < TransportError; end
+  end
+end

data/lib/phronomy/embeddings/transport_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "../common/error"
+
+module Phronomy
+  module Embeddings
+    # An embedding provider failed; the original SDK exception remains #cause.
+    # @api public
+    class TransportError < Phronomy::Error; end
+  end
+end