phronomy 0.5.4 → 0.7.0

data/lib/phronomy.rb

@@ -8,6 +8,10 @@ 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")
+# FSMSession: Zeitwerk would infer "FsmSession" — override to "FSMSession".
+loader.inflector.inflect("fsm_session" => "FSMSession")
+# AgentFSM: Zeitwerk would infer "Fsm" — override to "FSM".
+loader.inflector.inflect("fsm" => "FSM")
 loader.setup
 
 require_relative "phronomy/version"
@@ -19,11 +23,33 @@ module Phronomy
   class ParseError < Error; end
   class RecursionLimitError < Error; end
   class ToolError < Error; end
+  # Raised when an agent invocation exceeds the timeout set via +invoke_timeout+.
+  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 by {Phronomy::GeneratorVerifier#invoke} when +raise_if_untrusted: true+
   # and the pipeline's combined confidence score falls below the configured threshold.
   #
@@ -59,9 +85,56 @@ module Phronomy
       yield configuration
     end
 
-    # Resets configuration; primarily used in tests.
+    # 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
+    ensure
+      @configuration = original
+    end
+
+    # Resets all Phronomy runtime state: configuration and the EventLoop
+    # singleton (if running).
+    #
+    # **Intended for test suites only.**  Stops any running EventLoop thread,
+    # clears the EventLoop singleton, and resets configuration to defaults.
+    # Call once before/after each example to ensure test isolation.
+    #
+    # @example
+    #   config.around { |ex| Phronomy.reset_runtime! ; ex.run ; Phronomy.reset_runtime! }
+    # @api public
+    def reset_runtime!
+      Phronomy::EventLoop.reset!
+      @configuration = Configuration.new
+    end
   end
 end

data/scripts/api_snapshot.rb

@@ -0,0 +1,91 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# 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.
+#
+# 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,
+  Phronomy::Tool::Base,
+  Phronomy::Workflow,
+  Phronomy::WorkflowContext,
+  Phronomy::Runnable,
+  Phronomy::PromptTemplate,
+  # Beta
+  Phronomy::Agent::ReactAgent,
+  Phronomy::Agent::Orchestrator,
+  Phronomy::Agent::TeamCoordinator,
+  Phronomy::Guardrail::InputGuardrail,
+  Phronomy::Guardrail::OutputGuardrail,
+  Phronomy::VectorStore::Base,
+  Phronomy::VectorStore::InMemory,
+  Phronomy::Embeddings::Base,
+  Phronomy::KnowledgeSource::Base,
+  Phronomy::KnowledgeSource::StaticKnowledge,
+  Phronomy::KnowledgeSource::RAGKnowledge,
+  Phronomy::Tracing::Base,
+  Phronomy::Tracing::NullTracer,
+  Phronomy::Eval::Runner
+].freeze
+
+# Baseline methods common to all Ruby objects — excluded from the snapshot.
+BASELINE_INSTANCE_METHODS = (
+  Object.public_instance_methods |
+  Kernel.public_instance_methods
+).uniq.freeze
+
+BASELINE_CLASS_METHODS = (
+  Class.public_methods |
+  Module.public_methods
+).uniq.freeze
+
+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,
+      "type" => "module",
+      "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
+    {
+      "name" => klass.name,
+      "type" => "class",
+      "public_instance_methods" => instance_methods,
+      "public_class_methods" => class_methods
+    }
+  end
+end
+
+snapshot = PUBLIC_API_ENTRIES.map { |entry| snapshot_entry(entry) }
+
+if ARGV.include?("--write")
+  path = File.expand_path("../spec/fixtures/api_snapshot.json", __dir__)
+  FileUtils.mkdir_p(File.dirname(path))
+  File.write(path, JSON.pretty_generate(snapshot) + "\n")
+  puts "Wrote #{path}"
+else
+  puts JSON.pretty_generate(snapshot)
+end

data/scripts/check_api_annotations.rb

@@ -0,0 +1,68 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# check_api_annotations.rb
+#
+# Verifies that every YARD-documented public method in lib/ carries either
+# "@api public" or "@api private".
+#
+# A method is considered "YARD-documented" when its preceding comment block
+# contains at least one @param, @return, @raise, @yield, @example, or
+# @overload tag.  Methods with only a plain prose description (no @ tags)
+# are exempt.
+#
+# Usage (run from the phronomy/ repository root):
+#   ruby scripts/check_api_annotations.rb
+#
+# Exit codes:
+#   0 — all documented methods carry @api annotations
+#   1 — one or more documented methods are missing @api annotations
+
+lib_dir = File.expand_path("../lib", __dir__)
+
+unless File.directory?(lib_dir)
+  warn "ERROR: lib directory not found at #{lib_dir}"
+  exit 1
+end
+
+errors = []
+
+Dir.glob(File.join(lib_dir, "**", "*.rb")).sort.each do |file|
+  lines = File.readlines(file)
+
+  lines.each_with_index do |line, i|
+    next unless line.match?(/^\s*def\s+\w/)
+
+    # Collect the contiguous comment block immediately above this def.
+    comment_lines = []
+    j = i - 1
+    while j >= 0 && lines[j].match?(/^\s*#/)
+      comment_lines.unshift(lines[j])
+      j -= 1
+    end
+
+    next if comment_lines.empty?
+
+    comment = comment_lines.join
+
+    # Only lint methods that carry at least one YARD type tag.
+    next unless comment.match?(/#[ \t]+@(param|return|raise|yield|example|overload)/)
+
+    # Pass if an @api tag is already present.
+    next if comment.match?(/#[ \t]+@api[ \t]+(public|private)/)
+
+    rel_path = file.sub("#{lib_dir}/../", "")
+    m = line.match(/def\s+(\w+[!?=]?)/)
+    method_name = m ? m[1] : "unknown"
+    errors << "#{rel_path}:#{i + 1}  def #{method_name}  (missing @api public or @api private)"
+  end
+end
+
+if errors.empty?
+  puts "OK: all YARD-documented methods carry @api annotations"
+  exit 0
+else
+  puts "FAIL: #{errors.size} method(s) missing @api annotation:"
+  errors.each { |e| puts "  #{e}" }
+  exit 1
+end

data/scripts/check_private_enforcement.rb

@@ -0,0 +1,93 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# check_private_enforcement.rb
+#
+# Verifies that every instance method annotated @api private in lib/ is
+# actually non-public at the Ruby level (i.e., NOT in Module#public_instance_methods).
+#
+# Class methods (def self.xxx) are excluded from this check because their
+# visibility is managed separately on the singleton class and rarely causes
+# accidental public exposure to consumers.
+#
+# Usage (run from the phronomy/ repository root):
+#   bundle exec ruby scripts/check_private_enforcement.rb
+#
+# Exit codes:
+#   0 — all @api private instance methods are non-public (or have no Ruby def)
+#   1 — one or more @api private instance methods are exposed as public
+
+require "bundler/setup"
+require_relative "../lib/phronomy"
+
+lib_dir = File.expand_path("../lib", __dir__)
+
+unless File.directory?(lib_dir)
+  warn "ERROR: lib directory not found at #{lib_dir}"
+  exit 1
+end
+
+# Step 1: Collect instance methods annotated @api private via static analysis.
+api_private_entries = []
+
+Dir.glob(File.join(lib_dir, "**", "*.rb")).sort.each do |file|
+  lines = File.readlines(file)
+
+  lines.each_with_index do |line, i|
+    next unless line.match?(/^\s*#\s*@api\s+private\s*$/)
+
+    # Advance past any further comment or blank lines to reach the def.
+    j = i + 1
+    j += 1 while j < lines.size && lines[j].match?(/^\s*(#|$)/)
+    next unless j < lines.size
+
+    # Skip class-level methods — they live on the singleton class, not as
+    # public instance methods accessible to consumers.
+    next if lines[j].match?(/def\s+self\./)
+
+    # Match both plain def and "private def".
+    m = lines[j].match(/^\s*(?:private\s+)?def\s+(\w+[!?=]?)/)
+    next unless m
+
+    rel_path = file.sub("#{lib_dir}/../", "")
+    api_private_entries << {name: m[1].to_sym, file: rel_path, line: j + 1}
+  end
+end
+
+if api_private_entries.empty?
+  puts "No @api private instance methods found."
+  exit 0
+end
+
+# Step 2: Build a map of publicly exposed instance methods across all
+# Phronomy-namespaced modules/classes (own methods only, no inheritance).
+all_phronomy_modules = ObjectSpace.each_object(Module).select do |mod|
+  mod.name&.start_with?("Phronomy")
+end
+
+public_exposure_map = {}
+all_phronomy_modules.each do |mod|
+  mod.public_instance_methods(false).each do |meth|
+    (public_exposure_map[meth] ||= []) << mod.name
+  end
+end
+
+# Step 3: Report violations — @api private methods that are still public.
+errors = []
+
+api_private_entries.each do |entry|
+  exposing_modules = public_exposure_map[entry[:name]]
+  next unless exposing_modules
+
+  errors << "#{entry[:file]}:#{entry[:line]}  def #{entry[:name]}" \
+            "  (annotated @api private but public in: #{exposing_modules.join(", ")})"
+end
+
+if errors.empty?
+  puts "OK: all #{api_private_entries.size} @api private instance methods are non-public."
+  exit 0
+else
+  warn "ERROR: #{errors.size} @api private instance method(s) are exposed as public:"
+  errors.each { |e| warn "  #{e}" }
+  exit 1
+end

data/scripts/check_readme_runnable.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+# scripts/check_readme_runnable.rb
+#
+# Extracts ```ruby runnable blocks from README.md and executes each in an
+# isolated subprocess with a fake LLM stub to catch API drift.
+#
+# Any block that raises NoMethodError / ArgumentError / NameError causes a
+# non-zero exit, failing the CI step.
+#
+# Usage (from the phronomy/ root):
+#   bundle exec ruby scripts/check_readme_runnable.rb
+
+require "tempfile"
+require "open3"
+
+REPO_ROOT = File.expand_path("..", __dir__)
+README_PATH = File.join(REPO_ROOT, "README.md")
+
+# Injected before every runnable block.
+# Uses the Gemfile of this project so subprocesses can load phronomy.
+PREAMBLE = <<~RUBY
+  # frozen_string_literal: true
+  # --- CI preamble: stub LLM calls so no real network requests are made ---
+  ENV["BUNDLE_GEMFILE"] ||= "#{File.join(REPO_ROOT, "Gemfile")}"
+  require "bundler/setup"
+  require "phronomy"
+
+  # Patch invoke methods to return canned responses instead of calling the LLM.
+  module Phronomy
+    module Agent
+      class Base
+        def invoke(input = nil, **)
+          {output: "ci-stub-output", messages: []}
+        end
+      end
+
+      class Runner
+        def invoke(input = nil, **)
+          {output: "ci-stub-output", agent: nil, messages: []}
+        end
+      end
+    end
+
+    module Chain
+      class LLMChain
+        def invoke(vars = {})
+          "ci-stub-chain"
+        end
+      end
+    end
+  end
+  # --- end CI preamble ---
+
+RUBY
+
+readme = File.read(README_PATH)
+
+# Match opening fence with 'runnable' annotation: ```ruby runnable
+blocks = readme.scan(/^```ruby runnable\n(.*?)^```/m).map.with_index(1) { |(code), i| [i, code] }
+
+if blocks.empty?
+  puts "No 'ruby runnable' blocks found in README.md."
+  exit 0
+end
+
+puts "Checking #{blocks.size} runnable Ruby block(s) in README.md..."
+
+failures = []
+
+blocks.each do |index, code|
+  Tempfile.create(["readme_runnable_#{index}", ".rb"]) do |f|
+    f.write(PREAMBLE)
+    f.write(code)
+    f.flush
+
+    out, err, status = Open3.capture3(RbConfig.ruby, f.path)
+    combined = (out + err).gsub(f.path, "block ##{index}")
+
+    if status.success?
+      puts "  OK   block ##{index}"
+    else
+      failures << index
+      puts "  FAIL block ##{index}"
+      # Print at most 15 lines of output to keep CI logs readable.
+      puts combined.lines.first(15).join
+    end
+  end
+end
+
+puts
+if failures.empty?
+  puts "All #{blocks.size} runnable block(s) passed."
+  exit 0
+else
+  puts "#{failures.size} block(s) failed: #{failures.join(", ")}"
+  exit 1
+end

data/scripts/run_mutation.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# scripts/run_mutation.sh — Run mutation tests on core Phronomy domain classes.
+#
+# Usage:
+#   bash scripts/run_mutation.sh [SUBJECT_PATTERN]
+#
+# SUBJECT_PATTERN (optional): restrict to a specific subject, e.g. "Phronomy::WorkflowContext"
+# When omitted, all subjects listed in .mutant.yml are tested.
+#
+# Requires mutant-rspec (in Gemfile development group):
+#   gem "mutant-rspec", "~> 0.15.1"
+#
+# Target: mutation score >= 80% for each listed subject.
+# Baseline scores (as of initial run):
+#   Phronomy::WorkflowContext  84.85%
+#   Phronomy::Tool::Base       55.74%
+#
+# Note: mutation testing is slow (~1-5 min per subject). Run locally or via
+# the nightly-mutation GitHub Actions workflow.
+
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+if ! bundle exec mutant --version &>/dev/null; then
+  echo "ERROR: mutant is not available. Run: bundle install"
+  exit 1
+fi
+
+SUBJECT="${1:-}"
+
+echo "=== Phronomy Mutation Test ==="
+echo "Date: $(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+echo "Ruby: $(ruby --version)"
+echo "Mutant: $(bundle exec mutant --version 2>&1 | grep -v warning | head -1)"
+echo ""
+
+if [[ -n "$SUBJECT" ]]; then
+  echo "Subject: $SUBJECT"
+  echo ""
+  bundle exec mutant run -- "$SUBJECT"
+else
+  echo "Subjects: all (see .mutant.yml)"
+  echo ""
+  bundle exec mutant run
+fi

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: phronomy
 version: !ruby/object:Gem::Version
-  version: 0.5.4
+  version: 0.7.0
 platform: ruby
 authors:
 - Raizo T.C.S
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-20 00:00:00.000000000 Z
+date: 2026-05-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby_llm
@@ -17,6 +17,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -24,6 +27,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
@@ -31,6 +37,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '2.6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -38,6 +47,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '2.6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
 - !ruby/object:Gem::Dependency
   name: state_machines
   requirement: !ruby/object:Gem::Requirement
@@ -60,30 +72,55 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".mutant.yml"
 - ".yardopts"
 - CHANGELOG.md
+- CONTRIBUTING.md
 - README.md
+- RELEASE_CHECKLIST.md
 - Rakefile
+- SECURITY.md
+- benchmark/baseline.json
+- benchmark/bench_agent_invoke.rb
+- benchmark/bench_context_assembler.rb
+- benchmark/bench_regression.rb
+- benchmark/bench_token_estimator.rb
+- benchmark/bench_tool_schema.rb
+- benchmark/bench_vector_store.rb
+- benchmark/bench_workflow.rb
+- benchmark/run_all.rb
+- docs/decisions/001-rubyllm-as-provider-layer.md
+- docs/decisions/002-workflow-context-immutability.md
+- docs/decisions/003-event-loop-singleton.md
+- docs/decisions/004-invoke-timeout-is-not-cancellation.md
+- docs/decisions/005-static-knowledge-class-level-cache.md
+- docs/decisions/006-no-built-in-guardrails.md
+- docs/decisions/007-mcp-is-beta-stability.md
+- docs/decisions/008-orchestrator-uses-os-threads.md
+- docs/decisions/009-state-store-abstraction.md
 - lib/phronomy.rb
 - lib/phronomy/agent.rb
 - lib/phronomy/agent/base.rb
 - lib/phronomy/agent/before_completion_context.rb
 - lib/phronomy/agent/checkpoint.rb
 - lib/phronomy/agent/concerns/before_completion.rb
+- lib/phronomy/agent/concerns/error_translation.rb
 - lib/phronomy/agent/concerns/guardrailable.rb
 - lib/phronomy/agent/concerns/retryable.rb
 - lib/phronomy/agent/concerns/suspendable.rb
+- lib/phronomy/agent/fsm.rb
 - lib/phronomy/agent/handoff.rb
 - lib/phronomy/agent/orchestrator.rb
+- lib/phronomy/agent/parallel_tool_chat.rb
 - lib/phronomy/agent/react_agent.rb
 - lib/phronomy/agent/runner.rb
 - lib/phronomy/agent/shared_state.rb
 - lib/phronomy/agent/suspend_signal.rb
 - lib/phronomy/agent/team_coordinator.rb
+- lib/phronomy/cancellation_token.rb
 - lib/phronomy/configuration.rb
 - lib/phronomy/context.rb
 - lib/phronomy/context/assembler.rb
-- lib/phronomy/context/builder.rb
 - lib/phronomy/context/compaction_context.rb
 - lib/phronomy/context/context_version_cache.rb
 - lib/phronomy/context/token_budget.rb
@@ -105,12 +142,12 @@ files:
 - 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/event_loop.rb
+- lib/phronomy/fsm_session.rb
 - lib/phronomy/generator_verifier.rb
 - lib/phronomy/guardrail.rb
 - lib/phronomy/guardrail/base.rb
-- lib/phronomy/guardrail/builtin.rb
-- lib/phronomy/guardrail/builtin/pii_pattern_detector.rb
-- lib/phronomy/guardrail/builtin/prompt_injection_detector.rb
 - lib/phronomy/guardrail/input_guardrail.rb
 - lib/phronomy/guardrail/output_guardrail.rb
 - lib/phronomy/knowledge_source.rb
@@ -134,6 +171,8 @@ files:
 - lib/phronomy/splitter/base.rb
 - lib/phronomy/splitter/fixed_size_splitter.rb
 - lib/phronomy/splitter/recursive_splitter.rb
+- lib/phronomy/state_store/base.rb
+- lib/phronomy/state_store/in_memory.rb
 - lib/phronomy/token_usage.rb
 - lib/phronomy/tool.rb
 - lib/phronomy/tool/agent_tool.rb
@@ -153,7 +192,12 @@ files:
 - lib/phronomy/workflow.rb
 - lib/phronomy/workflow_context.rb
 - lib/phronomy/workflow_runner.rb
+- scripts/api_snapshot.rb
+- scripts/check_api_annotations.rb
+- scripts/check_private_enforcement.rb
 - scripts/check_readme_ruby.rb
+- scripts/check_readme_runnable.rb
+- scripts/run_mutation.sh
 - sig/phronomy.rbs
 homepage: https://github.com/Raizo-TCS/phronomy
 licenses: