phronomy 0.26.0 → 0.28.0

data/lib/phronomy/context/default_policy.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Context
+    class DefaultPolicy < ContextPolicy
+      CONVERSATION_SHARE = 0.60
+
+      def self.instance
+        @instance ||= new.freeze
+      end
+
+      def call(input)
+        unless input.is_a?(ContextPolicyInput)
+          raise ArgumentError, "Default ContextPolicy expected ContextPolicyInput"
+        end
+
+        return all_context(input) unless input.token_budget
+
+        limit = input.token_budget.effective_input_limit
+        required_knowledge = input.knowledge.select(&:required?)
+        optional_knowledge = input.knowledge.reject(&:required?)
+        required_conversation = input.conversation.select { |group| group.any?(&:required?) }
+        optional_conversation = input.conversation.reject { |group| group.any?(&:required?) }
+
+        fixed_cost = item_cost(input.instruction) + item_cost(input.tools) +
+          item_cost(required_knowledge) + group_cost(required_conversation)
+        if fixed_cost > limit
+          raise Phronomy::Context::BudgetExceededError,
+            "Required Context (estimated #{fixed_cost} tokens) exceeds " \
+            "available input budget (#{limit} tokens)"
+        end
+
+        remaining = limit - fixed_cost
+        conversation_budget = (remaining * CONVERSATION_SHARE).floor
+        knowledge_budget = remaining - conversation_budget
+
+        selected_conversation, older_conversation, conversation_used =
+          select_recent_suffix(optional_conversation, conversation_budget)
+        selected_knowledge, remaining_knowledge, knowledge_used =
+          select_stable_fit(optional_knowledge, knowledge_budget)
+
+        reusable = remaining - conversation_used - knowledge_used
+        if reusable.positive? && !older_conversation.empty?
+          more_conversation, _, used =
+            select_recent_suffix(older_conversation, reusable)
+          selected_conversation = more_conversation + selected_conversation
+          reusable -= used
+        end
+        if reusable.positive? && !remaining_knowledge.empty?
+          more_knowledge, _remaining_knowledge, used =
+            select_stable_fit(remaining_knowledge, reusable)
+          selected_knowledge += more_knowledge
+          reusable -= used
+        end
+
+        conversation = (required_conversation + selected_conversation)
+          .uniq
+          .sort_by { |group| group_sequence(group) }
+        knowledge_ids = (required_knowledge + selected_knowledge).to_h { |item| [item.id, true] }
+        knowledge = input.knowledge.select { |item| knowledge_ids[item.id] }
+
+        plan(
+          instruction: input.instruction,
+          knowledge: knowledge,
+          tools: input.tools,
+          conversation: conversation,
+          metadata: {
+            "default_policy" => true,
+            "estimated_fixed_tokens" => fixed_cost,
+            "estimated_unused_tokens" => reusable
+          }
+        )
+      end
+
+      private
+
+      def all_context(input)
+        plan(
+          instruction: input.instruction,
+          knowledge: input.knowledge,
+          tools: input.tools,
+          conversation: input.conversation,
+          metadata: {"default_policy" => true}
+        )
+      end
+
+      def item_cost(items)
+        Array(items).sum { |item| Integer(item.estimated_tokens || 0) }
+      end
+
+      def group_cost(groups)
+        Array(groups).sum { |group| item_cost(group) }
+      end
+
+      def group_sequence(group)
+        group.filter_map(&:sequence).min || 0
+      end
+
+      def select_recent_suffix(groups, budget)
+        ordered = Array(groups).sort_by { |group| group_sequence(group) }
+        selected = []
+        remaining = Integer(budget)
+        stop_index = -1
+
+        (ordered.length - 1).downto(0) do |index|
+          cost = item_cost(ordered[index])
+          if cost > remaining
+            stop_index = index
+            break
+          end
+          selected.unshift(ordered[index])
+          remaining -= cost
+        end
+
+        older = if stop_index >= 0
+          ordered[0..stop_index]
+        else
+          []
+        end
+        [selected.freeze, older.freeze, Integer(budget) - remaining]
+      end
+
+      def select_stable_fit(items, budget)
+        remaining = Integer(budget)
+        selected = []
+        unselected = []
+        Array(items).each do |item|
+          cost = Integer(item.estimated_tokens || 0)
+          if cost <= remaining
+            selected << item
+            remaining -= cost
+          else
+            unselected << item
+          end
+        end
+        [selected.freeze, unselected.freeze, Integer(budget) - remaining]
+      end
+    end
+  end
+end

data/lib/phronomy/context/final_budget_validator.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Context
+    class FinalBudgetValidator
+      def initialize(content_loader:)
+        @content_loader = content_loader
+      end
+
+      def validate!(token_budget:, segments:, extra_values: [])
+        return 0 unless token_budget
+
+        estimated = Array(segments).sum do |segment|
+          Phronomy::LlmContextWindow::TokenEstimator.estimate(
+            @content_loader.call(segment.fetch(:content_ref))
+          )
+        end
+        estimated += Array(extra_values).sum do |value|
+          bytes = value.is_a?(String) ? value : Phronomy::CanonicalJSON.dump(value)
+          Phronomy::LlmContextWindow::TokenEstimator.estimate(bytes)
+        end
+
+        limit = token_budget.effective_input_limit
+        if estimated > limit
+          raise Phronomy::Context::BudgetExceededError,
+            "Canonical LLM input (estimated #{estimated} tokens) exceeds " \
+            "available input budget (#{limit} tokens)"
+        end
+        estimated
+      end
+    end
+  end
+end

data/lib/phronomy/{agent → context}/llm_input_build_context.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Phronomy
-  module Agent
+  module Context
     # Immutable metadata passed to before_llm_input hooks. Runtime objects such
     # as RubyLLM::Chat, messages and the mutable Agent instance are not exposed.
     LLMInputBuildContext = Data.define(
@@ -9,7 +9,7 @@ module Phronomy
       :config, :call_sequence
     ) do
       def initialize(**values)
-        super(**values.merge(config: Immutable.copy(values.fetch(:config, {}))))
+        super(**values.merge(config: Phronomy::Values::Immutable.copy(values.fetch(:config, {}))))
         freeze
       end
     end

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

@@ -1,9 +1,9 @@
 # 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 Persistence::DurableRecord.
+    # It is intentionally separate from Storage::DurableRecord.
     class LLMInputManifest
       VERSION = "0.1"
       CALL_MODES = %i[ask complete].freeze
@@ -18,7 +18,7 @@ module Phronomy
           if delivery.nil? || !SEGMENT_DELIVERIES.include?(delivery.to_s)
             raise ArgumentError, "unknown Segment delivery: #{delivery.inspect}"
           end
-          super(**values.merge(metadata: Immutable.copy(values[:metadata] || {})))
+          super(**values.merge(metadata: Phronomy::Values::Immutable.copy(values[:metadata] || {})))
           freeze
         end
 
@@ -62,7 +62,7 @@ module Phronomy
             label: label
           )
           unless SEGMENT_DELIVERIES.include?(delivery)
-            raise Phronomy::Persistence::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::Persistence::SerializationError
+        rescue Phronomy::Context::ManifestError
           raise
         rescue => error
-          raise Phronomy::Persistence::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::Persistence::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::Persistence::SerializationError
+      rescue Phronomy::Context::ManifestError
         raise
       rescue => error
-        raise Phronomy::Persistence::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::Persistence::SerializationError,
+            raise Phronomy::Context::ManifestError,
               "#{label} must be a Hash"
           end
           unless hash.keys.all? { |key| key.is_a?(String) }
-            raise Phronomy::Persistence::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::Persistence::SerializationError,
+            raise Phronomy::Context::ManifestError,
               "#{label} schema mismatch (#{details.join(", ")})"
           end
           Phronomy::CanonicalJSON.dump(hash)
           hash
         rescue ArgumentError => error
-          raise Phronomy::Persistence::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::Persistence::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::Persistence::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::Persistence::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::Persistence::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::Persistence::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::Persistence::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::Persistence::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::Persistence::SerializationError,
+          raise Phronomy::Context::ManifestError,
             "#{label} #{key} must be a Hash"
         end
       end

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

@@ -1,14 +1,14 @@
 # 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
       def initialize(model_config_patch: nil, segment_candidates: nil)
         super(
-          model_config_patch: model_config_patch && Immutable.copy(model_config_patch),
-          segment_candidates: segment_candidates && Immutable.copy(Array(segment_candidates))
+          model_config_patch: model_config_patch && Phronomy::Values::Immutable.copy(model_config_patch),
+          segment_candidates: segment_candidates && Phronomy::Values::Immutable.copy(Array(segment_candidates))
         )
         freeze
       end

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