phronomy 0.16.0 → 0.18.0

data/lib/phronomy.rb

@@ -5,36 +5,18 @@ require "ruby_llm"
 require_relative "phronomy/ruby_llm_patches"
 
 loader = Zeitwerk::Loader.for_gem
-# Teach Zeitwerk that "llm" maps to "LLM" so that file names such as
-# ruby_llm_embeddings.rb resolve to RubyLLMEmbeddings (not RubyLlmEmbeddings).
 loader.inflector.inflect("ruby_llm_embeddings" => "RubyLLMEmbeddings")
-# RAG: Zeitwerk would infer "Rag" — override to "RAG".
 loader.inflector.inflect("rag" => "RAG")
-# FSMSession: Zeitwerk would infer "FsmSession" — override to "FSMSession".
-# Phronomy::FSMSession is the top-level cooperative execution engine shared by
-# WorkflowRunner, AgentInvocationSessionBuilder, and ToolInvocationSessionBuilder.
 loader.inflector.inflect("fsm_session" => "FSMSession")
-# LLMAdapter: Zeitwerk would infer "LlmAdapter" — override to "LLMAdapter".
 loader.inflector.inflect("llm_adapter" => "LLMAdapter")
-# LLMOperationResult: preserve the LLM acronym for the Agent result carrier.
 loader.inflector.inflect("llm_operation_result" => "LLMOperationResult")
-# LLMAdapter::RubyLLM: "ruby_llm" maps to "RubyLLM" (not "RubyLlm").
 loader.inflector.inflect("ruby_llm" => "RubyLLM")
-# CanonicalJSON: preserve uppercase JSON acronym.
 loader.inflector.inflect("canonical_json" => "CanonicalJSON")
-# RubyLLMMaterializer: preserve the double-uppercase LLM acronym.
 loader.inflector.inflect("ruby_llm_materializer" => "RubyLLMMaterializer")
-# LLMCallRecord: preserve uppercase LLM acronym.
 loader.inflector.inflect("llm_call_record" => "LLMCallRecord")
-# LLMInputManifest: preserve uppercase LLM acronym.
 loader.inflector.inflect("llm_input_manifest" => "LLMInputManifest")
-# LLMInputBuildContext / LLMInputPatch: preserve uppercase LLM acronym.
 loader.inflector.inflect("llm_input_build_context" => "LLMInputBuildContext")
 loader.inflector.inflect("llm_input_patch" => "LLMInputPatch")
-# Collapse engine/ so that its contents autoload directly under Phronomy::
-# (no Engine:: prefix).  e.g. engine/event_loop.rb => Phronomy::EventLoop.
-# This allows the execution engine to be organised in its own subdirectory
-# without changing any class names or callers.
 loader.collapse("#{__dir__}/phronomy/engine")
 loader.setup
 
@@ -42,70 +24,31 @@ require_relative "phronomy/version"
 require_relative "phronomy/token_usage"
 
 module Phronomy
-  # Exception hierarchy
   class Error < StandardError; end
   class ParseError < Error; end
   class RecursionLimitError < Error; end
   class ToolError < Error; end
-  # Base error for Phronomy-owned timed boundaries and generic timeout primitives.
   class TimeoutError < Error; end
-
   class ConfigurationError < Error; end
-
   class HandoffError < Error; end
 
-  # Raised when a network or transport layer call fails (e.g. LLM API unreachable,
-  # MCP server connection refused). Distinguishable from application-level errors
-  # so callers can apply network-specific retry logic.
   class TransportError < Error; end
-
-  # Raised when the LLM API returns a rate-limit response (HTTP 429 or equivalent).
-  # Callers should back off and retry after the indicated delay.
   class RateLimitError < TransportError; end
-
-  # Raised when the LLM API rejects the request due to an invalid or revoked API key.
-  # Callers should not retry without fixing the credentials.
   class AuthenticationError < TransportError; end
-
-  # Raised when the prompt exceeds the model's context window limit.
   class ContextLengthError < Error; end
-
-  # Raised when a workflow or agent execution is explicitly cancelled.
-  # Separate from TimeoutError (deadline exceeded) — this is an intentional stop.
   class CancellationError < Error; end
 
-  # Raised when {Agent#invoke} (a synchronous, blocking call) is attempted from
-  # inside an active scheduler task and +strict_runtime_guards+ is enabled.
-  #
-  # Calling a blocking invocation from within a scheduler task stalls the
-  # scheduler until the inner invocation completes, preventing other tasks from
-  # making progress (hidden deadlock risk).  Use {Agent#invoke_async} followed by
-  # +#await+ inside scheduler tasks instead.
-  #
-  # This error is only raised when:
-  #   Phronomy.configure { |c| c.strict_runtime_guards = true }
-  #
-  # By default a warning is logged and execution continues.
-  #
-  # @see Phronomy::Runtime.in_scheduler_context?
-  class SchedulerReentrancyError < Error; end
-
-  # Raised when work is submitted to a Runtime whose shutdown has begun, or
-  # when a Runtime cannot be reset because owned resources are still alive.
-  class RuntimeShutdownError < Error; end
+  # Raised when a synchronous API would block the EventLoop control thread.
+  class EventLoopReentrancyError < Error; end
+
+  # Backward-compatible error class name for callers that still rescue the old
+  # scheduler-oriented exception. New code should use EventLoopReentrancyError.
+  class SchedulerReentrancyError < EventLoopReentrancyError; end
 
-  # Raised when Runtime#shutdown is invoked from inside a Phronomy::Task.
+  class RuntimeShutdownError < Error; end
   class RuntimeShutdownReentrancyError < RuntimeShutdownError; end
 
-  # Raised by {Phronomy::GeneratorVerifier#invoke} when +raise_if_untrusted: true+
-  # and the pipeline's combined confidence score falls below the configured threshold.
-  #
-  # @example
-  #   rescue Phronomy::LowConfidenceError => e
-  #     puts e.result.confidence   # => e.g. 0.45
-  #     puts e.result.output       # best-effort answer despite low confidence
   class LowConfidenceError < Error
-    # @return [Phronomy::GeneratorVerifier::Result] the untrusted result
     attr_reader :result
 
     def initialize(result)
@@ -114,9 +57,6 @@ module Phronomy
     end
   end
 
-  # Raised by a {Phronomy::Filter::Base} subclass when the filter rejects a
-  # value without transforming it (blocking the pipeline).
-  # @api public
   class FilterBlockError < Error
     attr_reader :filter
 
@@ -126,27 +66,9 @@ module Phronomy
     end
   end
 
-  # Raised when an operation is submitted to a {BlockingAdapterPool} that has
-  # already been shut down via {BlockingAdapterPool#shutdown}.
   class PoolShutdownError < Error; end
-
-  # Raised when a concurrency limit is exceeded and the configured backpressure
-  # strategy is +:raise+. The caller should back off and retry.
   class BackpressureError < Error; end
 
-  # Raised by {CancellationScope#pop_queue} when the deadline expires before a
-  # result is available. Extends {TimeoutError} for backwards compatibility.
-  class ScopeTimeoutError < TimeoutError; end
-
-  # Deprecated compatibility constant. Workflow entry/exit actions are
-  # synchronous and the Workflow DSL no longer accepts +action_timeout:+.
-  class ActionTimeoutError < TimeoutError; end
-
-  # Raised when a {Phronomy::WorkflowContext} field is mutated from a thread
-  # that does not own the context (i.e. not the EventLoop dispatch thread).
-  # Only raised in EventLoop mode.  Use +context.merge(...)+ to produce a new
-  # context, or deliver updates as +:action_completed+ event payloads
-  # via {Agent::Base#invoke_async} + {Task#map}.
   class WorkflowContextOwnershipError < Error; end
 
   class << self
@@ -158,36 +80,10 @@ module Phronomy
       yield configuration
     end
 
-    # Resets the global Phronomy configuration to defaults.
-    #
-    # **Intended for test suites only.** Calling this in a production process
-    # will drop all runtime configuration (tracer, model, tokenizer, etc.)
-    # globally and immediately affect all subsequent agent and workflow calls.
-    #
-    # **Parallel test suites warning:** When tests run in parallel (e.g.
-    # `parallel_tests` or `parallel_rspec`), +reset_configuration!+ in one
-    # worker will clear configuration shared with other workers in the same
-    # process. Prefer process-isolation strategies (forked workers) over
-    # thread-based parallelism when using this method.
-    #
-    # Typical usage in a sequential test suite:
-    #   after { Phronomy.reset_configuration! }
     def reset_configuration!
       @configuration = Configuration.new
     end
 
-    # Yields the current {Configuration} object, then restores the original
-    # configuration on exit (even if the block raises).
-    #
-    # Intended for test helpers that need to temporarily override settings
-    # without permanently mutating the global configuration.
-    #
-    # @yield [config] the current {Configuration} instance (mutable)
-    # @example
-    #   Phronomy.with_configuration do |c|
-    #     c.logger = Logger.new($stdout)
-    #   end
-    # @api public
     def with_configuration
       original = @configuration&.dup
       yield configuration
@@ -195,16 +91,6 @@ module Phronomy
       @configuration = original
     end
 
-    # Shuts down and clears the process-wide default Runtime, then resets
-    # global configuration. Intended for test suites only.
-    #
-    # Runtime execution failure and resource cleanup are separate. The
-    # singleton is cleared when cleanup completed, even if execution failed.
-    #
-    # @param timeout [Numeric] maximum graceful wait for Runtime tasks and
-    #   EventLoop shutdown
-    # @return [Phronomy::Runtime::ShutdownResult]
-    # @api public
     def reset_runtime!(timeout: configuration.event_loop_stop_grace_seconds)
       previous_grace = @configuration&.event_loop_stop_grace_seconds
       result = Runtime.reset_default!(timeout: timeout)

data/scripts/api_snapshot.rb

@@ -3,24 +3,19 @@
 
 # scripts/api_snapshot.rb
 #
-# Dumps the public instance methods of all Stable/Beta public API classes to
-# JSON.  The snapshot is stored in spec/fixtures/api_snapshot.json and is used
-# by spec/phronomy/api_compatibility_spec.rb to detect unintended API removals.
+# Dumps the public instance methods of all Stable/Beta product API classes to
+# JSON. Testing helpers are intentionally excluded from this compatibility gate.
+# The snapshot is stored in spec/fixtures/api_snapshot.json and is used by
+# spec/phronomy/api_compatibility_spec.rb to detect unintended API removals.
 #
 # Usage:
-#   # Regenerate spec/fixtures/api_snapshot.json (run when intentionally adding
-#   # or removing public API methods after updating the stability table):
 #   ruby scripts/api_snapshot.rb --write
-#
-#   # Print snapshot to stdout (useful for manual inspection):
 #   ruby scripts/api_snapshot.rb
 
 require "json"
 require "fileutils"
 require_relative "../lib/phronomy"
 
-# Classes and modules whose public API is tracked.
-# Add an entry whenever a new class/module is promoted to Stable or Beta in README.md.
 PUBLIC_API_ENTRIES = [
   # Stable
   Phronomy::Agent::Base,
@@ -37,17 +32,13 @@ PUBLIC_API_ENTRIES = [
   Phronomy::VectorStore::Base,
   Phronomy::VectorStore::InMemory,
   Phronomy::VectorStore::Embeddings::Base,
-  Phronomy::Agent::Context::Knowledge::Base,
-  Phronomy::Agent::Context::Knowledge::StaticKnowledge,
   Phronomy::Tracing::Base,
   Phronomy::Tracing::NullTracer,
-  Phronomy::Eval::Runner,
   Phronomy::Tools::Mcp,
   Phronomy::Tools::Agent,
   Phronomy::Tools::VectorSearch
 ].freeze
 
-# Baseline methods common to all Ruby objects — excluded from the snapshot.
 BASELINE_INSTANCE_METHODS = (
   Object.public_instance_methods |
   Kernel.public_instance_methods
@@ -60,7 +51,6 @@ BASELINE_CLASS_METHODS = (
 
 def snapshot_entry(klass)
   if klass.instance_of?(Module)
-    # Module — capture instance methods defined in this module only
     own_methods = klass.public_instance_methods(false).sort
     {
       "name" => klass.name,
@@ -68,7 +58,6 @@ def snapshot_entry(klass)
       "public_instance_methods" => own_methods
     }
   else
-    # Class — capture public instance methods minus universal baseline
     instance_methods = (klass.public_instance_methods - BASELINE_INSTANCE_METHODS).sort
     class_methods = (klass.public_methods(false) - BASELINE_CLASS_METHODS).sort
     {

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: phronomy
 version: !ruby/object:Gem::Version
-  version: 0.16.0
+  version: 0.18.0
 platform: ruby
 authors:
 - Raizo T.C.S
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-08 00:00:00.000000000 Z
+date: 2026-08-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby_llm
@@ -104,6 +104,7 @@ files:
 - benchmark/bench_vector_store.rb
 - benchmark/bench_workflow.rb
 - benchmark/run_all.rb
+- docs/changelog/0.14-and-earlier.md
 - docs/decisions/001-rubyllm-as-provider-layer.md
 - docs/decisions/002-workflow-context-immutability.md
 - docs/decisions/003-event-loop-singleton.md
@@ -117,7 +118,13 @@ files:
 - docs/decisions/011-build-context-as-single-llm-input-authority.md
 - docs/decisions/011-delegate-transport-policy-to-adapters.md
 - docs/decisions/012-canonical-execution-log-and-context-policy.md
+- docs/decisions/013-journal-backed-knowledge-as-context-candidates.md
+- docs/features.md
+- docs/getting-started.md
 - docs/mcp-client.md
+- docs/migrations/0.15.md
+- docs/migrations/0.16.md
+- docs/runtime-and-concurrency.md
 - examples/workflows/agent_event_mapping.rb
 - examples/workflows/generic_task_event_mapping.rb
 - gemfiles/mcp_1_0.gemfile
@@ -137,9 +144,6 @@ files:
 - lib/phronomy/agent/concerns/filterable.rb
 - lib/phronomy/agent/context/capability/base.rb
 - lib/phronomy/agent/context/instruction/prompt_template.rb
-- lib/phronomy/agent/context/knowledge/base.rb
-- lib/phronomy/agent/context/knowledge/entity_knowledge.rb
-- lib/phronomy/agent/context/knowledge/static_knowledge.rb
 - lib/phronomy/agent/context_assembler.rb
 - lib/phronomy/agent/context_candidate.rb
 - lib/phronomy/agent/context_candidate_resolver.rb
@@ -159,7 +163,6 @@ files:
 - lib/phronomy/agent/context_selection_unit.rb
 - lib/phronomy/agent/derived_content_spec.rb
 - lib/phronomy/agent/execution_coordinator.rb
-- lib/phronomy/agent/fsm_runtime_adapter.rb
 - lib/phronomy/agent/immutable.rb
 - lib/phronomy/agent/journal_projection.rb
 - lib/phronomy/agent/journal_record.rb
@@ -187,44 +190,18 @@ files:
 - lib/phronomy/context_budget_exceeded_error.rb
 - lib/phronomy/diagnostics.rb
 - lib/phronomy/engine/concurrency/async_queue.rb
-- lib/phronomy/engine/concurrency/blocking_adapter_pool.rb
 - lib/phronomy/engine/concurrency/cancellation_scope.rb
 - lib/phronomy/engine/concurrency/cancellation_token.rb
 - lib/phronomy/engine/concurrency/deadline.rb
+- lib/phronomy/engine/concurrency/offload_pool.rb
 - lib/phronomy/engine/concurrency/pool_registry.rb
 - lib/phronomy/engine/event_loop.rb
 - lib/phronomy/engine/fsm_session.rb
 - lib/phronomy/engine/runtime.rb
-- lib/phronomy/engine/runtime/deterministic_scheduler.rb
-- lib/phronomy/engine/runtime/fake_scheduler.rb
-- lib/phronomy/engine/runtime/runtime_metrics.rb
-- lib/phronomy/engine/runtime/scheduler.rb
-- lib/phronomy/engine/runtime/scheduler_timer_adapter.rb
 - lib/phronomy/engine/runtime/shutdown_result.rb
-- lib/phronomy/engine/runtime/task_registry.rb
-- lib/phronomy/engine/runtime/thread_scheduler.rb
 - lib/phronomy/engine/runtime/timer_queue.rb
 - lib/phronomy/engine/runtime/timer_service.rb
 - lib/phronomy/engine/task.rb
-- lib/phronomy/engine/task/backend.rb
-- lib/phronomy/engine/task/deferred_backend.rb
-- lib/phronomy/engine/task/fiber_backend.rb
-- lib/phronomy/engine/task/immediate_backend.rb
-- lib/phronomy/engine/task/mapped_backend.rb
-- lib/phronomy/engine/task/thread_backend.rb
-- lib/phronomy/engine/task_group.rb
-- lib/phronomy/eval.rb
-- lib/phronomy/eval/comparison.rb
-- lib/phronomy/eval/dataset.rb
-- lib/phronomy/eval/eval_case.rb
-- lib/phronomy/eval/eval_result.rb
-- lib/phronomy/eval/metrics.rb
-- lib/phronomy/eval/runner.rb
-- lib/phronomy/eval/scorer.rb
-- lib/phronomy/eval/scorer/base.rb
-- lib/phronomy/eval/scorer/exact_match.rb
-- lib/phronomy/eval/scorer/includes_scorer.rb
-- lib/phronomy/eval/scorer/llm_judge.rb
 - lib/phronomy/event.rb
 - lib/phronomy/execution_rehydration_required_error.rb
 - lib/phronomy/filter.rb
@@ -236,15 +213,14 @@ files:
 - lib/phronomy/invalid_async_workflow_action_error.rb
 - lib/phronomy/invalid_context_budget_configuration_error.rb
 - lib/phronomy/invocation_context.rb
-- lib/phronomy/knowledge_source.rb
 - lib/phronomy/llm_adapter.rb
 - lib/phronomy/llm_adapter/base.rb
 - lib/phronomy/llm_adapter/ruby_llm.rb
-- lib/phronomy/llm_context_window/assembler.rb
-- lib/phronomy/llm_context_window/context_version_cache.rb
 - lib/phronomy/llm_context_window/token_budget.rb
 - lib/phronomy/llm_context_window/token_estimator.rb
 - lib/phronomy/metrics.rb
+- lib/phronomy/multi_agent/fan_out_invocation.rb
+- lib/phronomy/multi_agent/fan_out_session_builder.rb
 - lib/phronomy/multi_agent/handoff.rb
 - lib/phronomy/multi_agent/orchestrator.rb
 - lib/phronomy/multi_agent/parallel_tool_chat.rb
@@ -261,9 +237,19 @@ files:
 - lib/phronomy/state_store/in_memory.rb
 - lib/phronomy/stream_callback_error.rb
 - lib/phronomy/testing.rb
+- lib/phronomy/testing/eval.rb
+- lib/phronomy/testing/eval/comparison.rb
+- lib/phronomy/testing/eval/dataset.rb
+- lib/phronomy/testing/eval/eval_case.rb
+- lib/phronomy/testing/eval/eval_result.rb
+- lib/phronomy/testing/eval/metrics.rb
+- lib/phronomy/testing/eval/runner.rb
+- lib/phronomy/testing/eval/scorer.rb
+- lib/phronomy/testing/eval/scorer/base.rb
+- lib/phronomy/testing/eval/scorer/exact_match.rb
+- lib/phronomy/testing/eval/scorer/includes_scorer.rb
+- lib/phronomy/testing/eval/scorer/llm_judge.rb
 - lib/phronomy/testing/fake_clock.rb
-- lib/phronomy/testing/fake_scheduler.rb
-- lib/phronomy/testing/scheduler_helpers.rb
 - lib/phronomy/token_usage.rb
 - lib/phronomy/tools/agent.rb
 - lib/phronomy/tools/mcp.rb

data/lib/phronomy/agent/context/knowledge/base.rb

@@ -1,58 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    module Context
-      module Knowledge
-        # Abstract base class for all KnowledgeSource implementations.
-        #
-        # Subclasses must implement #fetch(query:) and return an Array of chunk Hashes.
-        # Each chunk Hash must contain:
-        #   :content [String]  the text to inject into the context
-        #   :type    [Symbol]  semantic tag (e.g. :static, :rag, :entity)
-        class Base
-          # Retrieve knowledge chunks relevant to the given query.
-          #
-          # @param query              [String, nil]                    the current user input used to select relevant chunks
-          # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil] optional token; raises CancellationError when cancelled
-          # @return [Array<Hash>] array of { content: String, type: Symbol }
-          # @api public
-          def fetch(query: nil, cancellation_token: nil)
-            cancellation_token&.raise_if_cancelled!
-            raise NotImplementedError, "#{self.class}#fetch is not implemented"
-          end
-
-          # Submits a {#fetch} call to {BlockingAdapterPool} and returns a
-          # {BlockingAdapterPool::PendingOperation}.
-          # Callers can fan out multiple fetches in parallel and await them all.
-          #
-          # @param query              [String, nil]
-          # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
-          # @param timeout            [Numeric, nil] seconds before the operation is abandoned
-          # @return [BlockingAdapterPool::PendingOperation]
-          # @api public
-          def fetch_async(query: nil, cancellation_token: nil, timeout: nil)
-            Phronomy::Runtime.instance.blocking_io.submit(
-              timeout: timeout,
-              cancellation_token: cancellation_token
-            ) do
-              fetch(query: query, cancellation_token: cancellation_token)
-            end
-          end
-
-          # Returns true when this source's content is considered static (i.e. does
-          # not change between agent invocations). Static sources are eligible for
-          # fingerprint-based caching in ContextVersionCache.
-          #
-          # Override in subclasses that return fixed content.
-          #
-          # @return [Boolean]
-          # @api public
-          def static?
-            false
-          end
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/agent/context/knowledge/entity_knowledge.rb

@@ -1,102 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    module Context
-      module Knowledge
-        # A KnowledgeSource that extracts named-entity facts from conversation history.
-        #
-        # This is the knowledge-injection counterpart of the old EntityMemory.
-        # It scans saved user messages with a regex heuristic (no LLM call) and
-        # returns the discovered facts as a single knowledge chunk tagged :entity.
-        #
-        # EntityKnowledge is stateful: it accumulates extracted facts via #update(messages:)
-        # which should be called each time new messages are saved.
-        #
-        # Supported extraction patterns (case-insensitive):
-        #   "my name is Alice"          → { name: "Alice" }
-        #   "I am Alice"                → { identity: "Alice" }
-        #   "I'm a software engineer"   → { occupation: "software engineer" }
-        #   "I work at / for Acme"      → { workplace: "Acme" }
-        #   "I live in Tokyo"           → { location: "Tokyo" }
-        #   "I'm from Tokyo"            → { location: "Tokyo" }
-        #   "I like / love Ruby"        → { preference: "Ruby" }
-        #
-        # @example
-        #   ks = Phronomy::Agent::Context::Knowledge::EntityKnowledge.new
-        #   ks.update(messages: chat_messages)
-        #   agent = MyAgent.new
-        #   agent.add_knowledge_source(ks)
-        #   agent.invoke("What is my name?")
-        class EntityKnowledge < Base
-          PATTERNS = [
-            [:name, /\bmy name is\s+([A-Za-z][A-Za-z0-9 \-']*)/i],
-            [:identity, /\bI\s+am\s+([A-Z][A-Za-z0-9 \-']+)/],
-            [:occupation, /\bI(?:'m| am) a(?:n)?\s+([A-Za-z][A-Za-z0-9 \-']*)/i],
-            [:workplace, /\bI (?:work|worked) (?:at|for|in)\s+([A-Za-z0-9][A-Za-z0-9 \-'.&,]*)/i],
-            [:location, /\bI live in\s+([A-Za-z][A-Za-z0-9 \-']*)/i],
-            [:location, /\bI(?:'m| am) from\s+([A-Za-z][A-Za-z0-9 \-']*)/i],
-            [:preference, /\bI (?:like|love|enjoy)\s+([A-Za-z][A-Za-z0-9 \-']*)/i]
-          ].freeze
-
-          def initialize
-            @entities = {}
-          end
-
-          # Scan messages and accumulate entity facts.
-          # Call this after saving a new set of messages (e.g. from a ConversationManager save hook).
-          #
-          # @param messages [Array] message objects responding to #role and #content
-          # @api public
-          def update(messages:)
-            messages.each do |msg|
-              next unless msg.role.to_sym == :user
-
-              extract(msg.content.to_s).each { |key, value| @entities[key] = value }
-            end
-          end
-
-          # Returns a single chunk containing all known entity facts in XML context format.
-          # Returns an empty array when no entities have been discovered.
-          #
-          # @param query              [String, nil]                    unused — entity knowledge is always fully injected
-          # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil] optional; raises CancellationError when cancelled
-          # @return [Array<Hash>]
-          # @api public
-          def fetch(query: nil, cancellation_token: nil)
-            cancellation_token&.raise_if_cancelled!
-            return [] if @entities.empty?
-
-            lines = @entities.map { |key, value| "- #{key}: #{value}" }.join("\n")
-            content = <<~CONTENT.chomp
-              Known facts about the user:
-              #{lines}
-            CONTENT
-            [{content: content, type: :entity}]
-          end
-
-          # Returns the current entity store (primarily for testing).
-          #
-          # @return [Hash]
-          # @api public
-          def entities
-            @entities.dup
-          end
-
-          private
-
-          def extract(text)
-            found = {}
-            PATTERNS.each do |key, pattern|
-              if (match = text.match(pattern))
-                value = match[1].strip.sub(/[.!?]\s+.*$/, "").gsub(/[.,;!?]+$/, "")
-                found[key] = value unless value.empty?
-              end
-            end
-            found
-          end
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/agent/context/knowledge/static_knowledge.rb

@@ -1,58 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    module Context
-      module Knowledge
-        # A KnowledgeSource backed by fixed text provided at construction time.
-        #
-        # Useful for injecting static documents, policy files, or configuration
-        # knowledge that does not change per request.
-        #
-        # @example
-        #   ks = Phronomy::Agent::Context::Knowledge::StaticKnowledge.new(
-        #     "Our refund policy: ...",
-        #     type: :policy
-        #   )
-        #   agent = MyAgent.new
-        #   agent.add_knowledge_source(ks)
-        #   agent.invoke("What is the refund policy?")
-        class StaticKnowledge < Base
-          # @param text   [String] the static knowledge text to inject
-          # @param type   [Symbol] semantic tag for the chunk (default :static)
-          # @param source [String, nil] label identifying where this knowledge came from
-          #   (e.g. a filename). Included in the context XML tag and exposed to the LLM
-          #   so that agents can produce grounded citations.
-          # @api public
-          def initialize(text, type: :static, source: nil)
-            @text = text.to_s
-            @type = type
-            @source = source
-          end
-
-          # Returns the fixed text as a single chunk, regardless of query.
-          #
-          # @param query              [String, nil]                    ignored for static knowledge
-          # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil] optional; raises CancellationError when cancelled
-          # @return [Array<Hash>]
-          # @api public
-          def fetch(query: nil, cancellation_token: nil)
-            cancellation_token&.raise_if_cancelled!
-            return [] if @text.empty?
-
-            chunk = {content: @text, type: @type}
-            chunk[:source] = @source if @source
-            [chunk]
-          end
-
-          # Static knowledge content never changes between invocations.
-          # @return [true]
-          # @api public
-          def static?
-            true
-          end
-        end
-      end
-    end
-  end
-end