phronomy 0.15.1 → 0.17.0

data/lib/phronomy/vector_store/in_memory.rb

@@ -4,8 +4,8 @@ module Phronomy
   module VectorStore
     # Pure-Ruby in-memory vector store using cosine similarity.
     #
-    # Intended for tests, short-lived agents, and Retrieval::Semantic scenarios where
-    # the message count is small enough that a linear scan is fast enough.
+    # Intended for tests, short-lived agents, and small retrieval workloads where
+    # the document count is small enough that a linear scan is fast enough.
     #
     # @example
     #   store = Phronomy::VectorStore::InMemory.new

data/lib/phronomy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Phronomy
-  VERSION = "0.15.1"
+  VERSION = "0.17.0"
 end

data/lib/phronomy.rb

@@ -5,25 +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")
-# 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.inflector.inflect("canonical_json" => "CanonicalJSON")
+loader.inflector.inflect("ruby_llm_materializer" => "RubyLLMMaterializer")
+loader.inflector.inflect("llm_call_record" => "LLMCallRecord")
+loader.inflector.inflect("llm_input_manifest" => "LLMInputManifest")
+loader.inflector.inflect("llm_input_build_context" => "LLMInputBuildContext")
+loader.inflector.inflect("llm_input_patch" => "LLMInputPatch")
 loader.collapse("#{__dir__}/phronomy/engine")
 loader.setup
 
@@ -31,70 +24,25 @@ 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 Runtime#shutdown is invoked from inside a Phronomy::Task.
   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)
@@ -103,9 +51,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
 
@@ -115,27 +60,12 @@ 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}.
+  # Raised when a WorkflowContext field is mutated from a thread that does not
+  # own the context. Deliver asynchronous updates back to the Workflow as later
+  # events via Workflow#signal instead of mutating context from worker callbacks.
   class WorkflowContextOwnershipError < Error; end
 
   class << self
@@ -147,36 +77,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
@@ -184,16 +88,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/add_to_h_to_token_doubles.rb

@@ -0,0 +1,33 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Adds to_h to all Tokens-like doubles so ExecutionCoordinator can serialize usage.
+
+files = Dir.glob("spec/**/*.rb").sort
+
+total = 0
+files.each do |f|
+  content = File.read(f)
+  modified = content.gsub(
+    /double\(("[^"]+"),\s*(input: \d+, output: \d+, cached: \d+, cache_creation: \d+)\)/
+  ) do
+    name = $1
+    attrs = $2
+    next $& if $&.include?("to_h")
+
+    h_entries = attrs.split(",").map(&:strip).map do |pair|
+      k, v = pair.split(":").map(&:strip)
+      "\"#{k}\" => #{v}"
+    end.join(", ")
+
+    total += 1
+    "double(#{name}, #{attrs}, to_h: {#{h_entries}})"
+  end
+
+  if modified != content
+    File.write(f, modified)
+    puts "  patched: #{f}"
+  end
+end
+
+puts "\nAdded to_h to #{total} Tokens doubles."

data/scripts/add_to_h_unnamed_doubles.rb

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Adds to_h to unnamed (no-string-name) Tokens doubles like double(input: 5, ...)
+
+files = Dir.glob("spec/**/*.rb").sort
+
+total = 0
+files.each do |f|
+  content = File.read(f)
+  modified = content.gsub(
+    /double\((input: (\d+), output: (\d+), cached: (\d+), cache_creation: (\d+))\)/
+  ) do
+    attrs, a, b, c, d = $1, $2, $3, $4, $5
+    next $& if $&.include?("to_h")
+
+    total += 1
+    "double(#{attrs}, to_h: {\"input\" => #{a}, \"output\" => #{b}, \"cached\" => #{c}, \"cache_creation\" => #{d}})"
+  end
+
+  if modified != content
+    File.write(f, modified)
+    puts "  patched: #{f}"
+  end
+end
+
+puts "\nAdded to_h to #{total} unnamed Tokens doubles."

data/scripts/api_snapshot.rb

@@ -4,23 +4,17 @@
 # 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
+# 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.
 #
 # 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,8 +31,6 @@ 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,
@@ -47,7 +39,6 @@ PUBLIC_API_ENTRIES = [
   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
     {

data/scripts/migrate_spec_agent_definition.rb

@@ -0,0 +1,108 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Migrates spec files to add agent_definition to Agent::Base subclasses.
+# - Named classes: inserts after the class declaration line
+# - Anonymous blocks (do...end): inserts after the opening `do`
+# - Inline anonymous ({ ... }): expands to multi-line with agent_definition
+# Safe: skips classes that already have agent_definition
+
+require "fileutils"
+
+SPEC_DIR = File.expand_path("../spec", __dir__)
+AGENT_BASE_PATTERN = /Phronomy::Agent::Base/
+
+def snake_case(class_name)
+  # Remove trailing Agent/Tool suffixes, snake_case the name
+  name = class_name.split("::").last
+  name.gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+    .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+    .downcase
+end
+
+counter = 0
+files_modified = 0
+
+Dir.glob("#{SPEC_DIR}/**/*.rb").sort.each do |file|
+  lines = File.readlines(file, chomp: false)
+  new_lines = []
+  modified = false
+  i = 0
+
+  while i < lines.length
+    line = lines[i]
+
+    # ── Named class: class FooAgent < Phronomy::Agent::Base ──────────────────
+    if line =~ /^(\s*)class\s+(\w+)\s*<\s*(?:::)?Phronomy::Agent::Base\s*$/
+      indent = $1
+      class_name = $2
+      id = snake_case(class_name).sub(/_agent$/, "-agent").tr("_", "-")
+      id = "#{id}-agent" unless id.end_with?("-agent")
+      new_lines << line
+      i += 1
+      # Check if agent_definition already present in the class body
+      look_ahead = lines[i..]&.take(10) || []
+      unless look_ahead.any? { |l| l =~ /agent_definition/ }
+        new_lines << "#{indent}  agent_definition id: #{id.inspect}, version: 1\n"
+        counter += 1
+        modified = true
+      end
+      next
+    end
+
+    # ── Anonymous block (do...end): Class.new(Phronomy::Agent::Base) do ─────
+    if line =~ /^(\s*)([\w.]*\s*=\s*)?Class\.new\((?:::)?Phronomy::Agent::Base\)\s+do\s*(\|\w+\|)?\s*$/
+      indent = $1
+      # Check if agent_definition already present
+      look_ahead = lines[i + 1..]&.take(10) || []
+      new_lines << line
+      i += 1
+      unless look_ahead.any? { |l| l =~ /agent_definition/ }
+        # Derive indentation from the `do` block body (first non-blank line)
+        inner = lines[i..]&.take(5)&.find { |l| l.strip.length > 0 } || ""
+        inner_indent = inner.match(/^(\s*)/)[1]
+        inner_indent = "#{indent}  " if inner_indent.strip.length > 0 && inner_indent.length < indent.length + 2
+        new_lines << "#{inner_indent}agent_definition id: \"test-agent-#{counter += 1}\", version: 1\n"
+        modified = true
+      end
+      next
+    end
+
+    # ── Inline anonymous: Class.new(Phronomy::Agent::Base) { ... } ───────────
+    if line =~ /^(\s*)((?:[\w.]*\s*=\s*)?)Class\.new\((?:::)?Phronomy::Agent::Base\)\s*\{(.+)\}\s*$/
+      indent = $1
+      assignment = $2
+      body = $3
+      # Skip if agent_definition already present
+      if /agent_definition/.match?(body)
+        new_lines << line
+      else
+        id = counter += 1
+        definition_line = "agent_definition id: \"test-agent-#{id}\", version: 1;"
+        new_lines << "#{indent}#{assignment}Class.new(Phronomy::Agent::Base) do\n"
+        new_lines << "#{indent}  #{definition_line}\n"
+        # Rewrite the original body lines, stripping leading spaces
+        body.strip.split(";").each do |stmt|
+          stmt = stmt.strip
+          next if stmt.empty?
+          new_lines << "#{indent}  #{stmt}\n"
+        end
+        new_lines << "#{indent}end\n"
+        modified = true
+      end
+      i += 1
+      next
+    end
+
+    new_lines << line
+    i += 1
+  end
+
+  if modified
+    File.write(file, new_lines.join)
+    files_modified += 1
+    puts "  patched: #{file.sub("#{SPEC_DIR}/", "spec/")}"
+  end
+end
+
+puts "\nDone: #{counter} agent_definition insertions in #{files_modified} files."

data/scripts/migrate_spec_agent_definition_pass2.rb

@@ -0,0 +1,53 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Second pass: handles patterns missed by the first script
+#   - Class.new(Phronomy::Agent::Base) { ... }.new  (inline + .new suffix)
+#   - Class.new(Phronomy::Agent::Base).new           (no block + .new)
+#   - { Class.new(Phronomy::Agent::Base) }           (no block, inside outer { })
+
+require "fileutils"
+
+SPEC_DIR = File.expand_path("../spec", __dir__)
+counter = 200
+
+files_modified = 0
+
+Dir.glob("#{SPEC_DIR}/**/*.rb").sort.each do |file|
+  content = File.read(file)
+  new_content = content.dup
+
+  # Pattern A: Class.new(Phronomy::Agent::Base) { body }.new
+  new_content = new_content.gsub(
+    /Class\.new\(Phronomy::Agent::Base\) \{([^}]*)\}\.new/
+  ) do
+    body = $1
+    next $& if body.include?("agent_definition")
+    counter += 1
+    "Class.new(Phronomy::Agent::Base) { agent_definition id: \"test-agent-#{counter}\", version: 1;#{body}}.new"
+  end
+
+  # Pattern B: Class.new(Phronomy::Agent::Base).new  (no block, chained .new)
+  new_content = new_content.gsub(
+    /Class\.new\(Phronomy::Agent::Base\)\.new\b/
+  ) do
+    counter += 1
+    "Class.new(Phronomy::Agent::Base) { agent_definition id: \"test-agent-#{counter}\", version: 1 }.new"
+  end
+
+  # Pattern C: { Class.new(Phronomy::Agent::Base) }  (no block, inside outer block)
+  new_content = new_content.gsub(
+    "{ Class.new(Phronomy::Agent::Base) }"
+  ) do
+    counter += 1
+    "{ Class.new(Phronomy::Agent::Base) { agent_definition id: \"test-agent-#{counter}\", version: 1 } }"
+  end
+
+  if new_content != content
+    File.write(file, new_content)
+    files_modified += 1
+    puts "  patched: #{file.sub("#{SPEC_DIR}/", "spec/")}"
+  end
+end
+
+puts "\nSecond pass done: #{files_modified} files modified."

data/scripts/migrate_spec_inline_pass3.rb

@@ -0,0 +1,24 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Adds agent_definition to single-line inline anonymous blocks like:
+# Class.new(Phronomy::Agent::Base) { model "test-model" }
+
+counter = 300
+files = Dir.glob("spec/**/*.rb").sort
+
+files.each do |f|
+  content = File.read(f)
+  modified = content.gsub(
+    /Class\.new\(Phronomy::Agent::Base\) \{ ([^{}]+) \}/
+  ) do
+    body = $1
+    next $& if body.include?("agent_definition")
+    counter += 1
+    "Class.new(Phronomy::Agent::Base) { agent_definition id: \"test-agent-#{counter}\", version: 1; #{body} }"
+  end
+  if modified != content
+    File.write(f, modified)
+    puts "  patched: #{f}"
+  end
+end