phronomy 0.2.2 → 0.4.0

data/lib/phronomy/generator_verifier.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Implements the Generator-Verifier multi-agent coordination pattern
+  # (Anthropic blog, Pattern 1): a generator agent produces an
+  # answer while a verifier agent evaluates its quality.
+  #
+  # @see https://claude.com/blog/multi-agent-coordination-patterns
+  #
+  # All prompt construction and result parsing are provided by the caller,
+  # giving full control over the LLM dialogue.
+  # The generator and verifier agents are configurable, and the pipeline
+  # retries until confidence passes the threshold or max iterations are reached.
+  #
+  # @example Basic usage with custom prompt builders
+  #   pipeline = Phronomy::GeneratorVerifier.new(
+  #     draft_agent:           MyDraftAgent,
+  #     review_agent:          MyReviewAgent,
+  #     draft_prompt_builder:  ->(input, feedback) { "Question: #{input}" },
+  #     review_prompt_builder: ->(input, draft, citations) { "Review: #{draft}" }
+  #   )
+  #   result = pipeline.invoke("What is the refund policy?")
+  #   puts result.output      # the final answer string
+  #   puts result.trusted?    # true when confidence >= threshold
+  #
+  # @example Custom result parsers
+  #   pipeline = Phronomy::GeneratorVerifier.new(
+  #     ...,
+  #     draft_result_parser:  ->(text) { my_parse_draft(text) },
+  #     review_result_parser: ->(text) { my_parse_review(text) }
+  #   )
+  #
+  # @example Raising on low confidence
+  #   pipeline = Phronomy::GeneratorVerifier.new(
+  #     ...,
+  #     raise_if_untrusted: true
+  #   )
+  #   begin
+  #     result = pipeline.invoke("question")
+  #   rescue Phronomy::LowConfidenceError => e
+  #     puts "Untrusted: #{e.result.confidence}"
+  #   end
+  class GeneratorVerifier
+    # Default confidence threshold for trusting an answer.
+    DEFAULT_CONFIDENCE_THRESHOLD = 0.7
+
+    # Default maximum draft-review cycles before returning best effort.
+    DEFAULT_MAX_ITERATIONS = 3
+
+    # Immutable value object returned by {GeneratorVerifier#invoke}.
+    #
+    # @!attribute [r] output
+    #   @return [String] the final answer text
+    # @!attribute [r] confidence
+    #   @return [Float] combined confidence score (0.0–1.0)
+    # @!attribute [r] citations
+    #   @return [Array<Hash>] [{source:, excerpt:}, ...]
+    #
+    #   **WARNING**: These citations are extracted from the LLM's own response
+    #   and are **not** verified against any external knowledge base or URL.
+    #   Do not treat them as authoritative without independent verification.
+    # @!attribute [r] iterations
+    #   @return [Integer] number of draft-review cycles executed
+    # @!attribute [r] review_notes
+    #   @return [Array<String>] reviewer feedback for each cycle
+    # @!attribute [r] trusted
+    #   @return [Boolean] true when confidence >= threshold
+    Result = Struct.new(
+      :output, :confidence, :citations, :iterations, :review_notes, :trusted,
+      keyword_init: true
+    ) do
+      # @return [Boolean] true when confidence >= threshold
+      alias_method :trusted?, :trusted
+    end
+
+    # Internal graph state — not part of the public API.
+    # @private
+    class PipelineState
+      include Phronomy::WorkflowContext
+
+      field :input, type: :replace, default: -> { "" }
+      field :draft, type: :replace, default: -> {}
+      field :self_score, type: :replace, default: -> { 0.0 }
+      field :review_score, type: :replace, default: -> { 0.0 }
+      field :citations, type: :replace, default: -> { [] }
+      field :review_notes, type: :append, default: -> { [] }
+      field :iteration, type: :replace, default: -> { 0 }
+      field :approved, type: :replace, default: -> { false }
+      field :output, type: :replace, default: -> {}
+    end
+
+    private_constant :PipelineState
+
+    # @param draft_agent           [Class]   subclass of Phronomy::Agent::Base
+    #   used to generate answer drafts
+    # @param review_agent          [Class]   subclass of Phronomy::Agent::Base
+    #   used to evaluate each draft
+    # @param draft_prompt_builder  [#call]   +call(input, feedback)+ → String
+    #   prompt for the generator. +feedback+ is nil on the first iteration and
+    #   contains the reviewer's feedback string on subsequent iterations.
+    # @param review_prompt_builder [#call]   +call(input, draft, citations)+ → String
+    #   prompt for the verifier. +citations+ is an Array of Hashes.
+    # @param draft_result_parser   [#call, nil]  +call(text)+ → Hash with
+    #   +:answer+, +:confidence+, and +:citations+ keys. Defaults to JSON parsing
+    #   with a safe fallback when the response cannot be parsed.
+    # @param review_result_parser  [#call, nil]  +call(text)+ → Hash with
+    #   +:approved+, +:score+, and +:feedback+ keys. Defaults to JSON parsing
+    #   with a safe fallback.
+    # @param confidence_threshold  [Float]   minimum combined confidence to
+    #   trust an answer (default: 0.7)
+    # @param max_iterations        [Integer] maximum draft-review cycles
+    #   before returning the best-effort answer (default: 3)
+    # @param raise_if_untrusted    [Boolean] when +true+, raises
+    #   {Phronomy::LowConfidenceError} if the final result does not meet the
+    #   confidence threshold (default: false)
+    def initialize(
+      draft_agent:,
+      review_agent:,
+      draft_prompt_builder:,
+      review_prompt_builder:,
+      draft_result_parser: nil,
+      review_result_parser: nil,
+      confidence_threshold: DEFAULT_CONFIDENCE_THRESHOLD,
+      max_iterations: DEFAULT_MAX_ITERATIONS,
+      raise_if_untrusted: false
+    )
+      @draft_agent_class = draft_agent
+      @review_agent_class = review_agent
+      @draft_prompt_builder = draft_prompt_builder
+      @review_prompt_builder = review_prompt_builder
+      @draft_result_parser = draft_result_parser || method(:default_parse_draft)
+      @review_result_parser = review_result_parser || method(:default_parse_review)
+      @threshold = confidence_threshold.to_f
+      @max_iterations = max_iterations.to_i
+      @raise_if_untrusted = raise_if_untrusted
+      @compiled_graph = nil
+    end
+
+    # Run the generator-verifier pipeline.
+    #
+    # @param input  [String] the user question or task description
+    # @param config [Hash]   forwarded to the underlying agents (e.g. thread_id)
+    # @return [Result]
+    # @raise [Phronomy::LowConfidenceError] when +raise_if_untrusted:+ is +true+
+    #   and the result does not meet the confidence threshold
+    def invoke(input, config: {})
+      app = compiled_graph
+      state = app.invoke({input: input}, config: config)
+      confidence = combined_confidence(state)
+      trusted = confidence >= @threshold
+      result = Result.new(
+        output: state.output || state.draft.to_s,
+        confidence: confidence,
+        citations: state.citations,
+        iterations: state.iteration,
+        review_notes: state.review_notes,
+        trusted: trusted
+      )
+      raise LowConfidenceError.new(result) if @raise_if_untrusted && !trusted
+      result
+    end
+
+    private
+
+    def combined_confidence(state)
+      [(state.self_score || 0.0).to_f, (state.review_score || 0.0).to_f].min
+    end
+
+    def compiled_graph
+      @compiled_graph ||= build_workflow
+    end
+
+    def build_workflow
+      draft_agent = @draft_agent_class.new
+      review_agent = @review_agent_class.new
+      threshold = @threshold
+      max_iter = @max_iterations
+      dpb = @draft_prompt_builder
+      rpb = @review_prompt_builder
+      drp = @draft_result_parser
+      rrp = @review_result_parser
+      pipeline = self
+
+      Phronomy::Workflow.define(PipelineState) do
+        initial :draft
+
+        state :draft, action: ->(state) {
+          feedback = state.review_notes.last
+          prompt = dpb.call(state.input, feedback)
+          result = draft_agent.invoke(prompt)
+          parsed = drp.call(result[:output])
+          state.merge(
+            draft: parsed[:answer].to_s,
+            self_score: pipeline.__send__(:clamp, parsed[:confidence]),
+            citations: pipeline.__send__(:normalize_citations, parsed[:citations]),
+            iteration: state.iteration + 1
+          )
+        }
+
+        state :review, action: ->(state) {
+          prompt = rpb.call(state.input, state.draft, state.citations)
+          result = review_agent.invoke(prompt)
+          parsed = rrp.call(result[:output])
+          state.merge(
+            review_score: pipeline.__send__(:clamp, parsed[:score]),
+            approved: parsed[:approved] == true,
+            review_notes: parsed[:feedback].to_s
+          )
+        }
+
+        state :finalize, action: ->(state) { state.merge(output: state.draft) }
+
+        after :draft, to: :review
+        after :finalize, to: :__finish__
+
+        event :route_review, from: :review,
+          guard: ->(state) {
+            confidence = [state.self_score || 0.0, state.review_score || 0.0].min
+            (confidence >= threshold && state.approved) || state.iteration >= max_iter
+          },
+          to: :finalize
+        event :route_review, from: :review, to: :draft
+      end
+    end
+
+    def default_parse_draft(text)
+      json_parser.parse(text)
+    rescue Phronomy::ParseError
+      {answer: text.to_s, confidence: 0.0, citations: []}
+    end
+
+    def default_parse_review(text)
+      json_parser.parse(text)
+    rescue Phronomy::ParseError
+      {approved: false, score: 0.0, feedback: "Review output could not be parsed: #{text}"}
+    end
+
+    def json_parser
+      @json_parser ||= Phronomy::OutputParser::JsonParser.new
+    end
+
+    def clamp(val)
+      val.to_f.clamp(0.0, 1.0)
+    end
+
+    def normalize_citations(raw)
+      Array(raw).filter_map { |c| c.is_a?(Hash) ? c.transform_keys(&:to_sym) : nil }
+    end
+  end
+end

data/lib/phronomy/guardrail/builtin/pii_pattern_detector.rb

@@ -7,10 +7,10 @@ module Phronomy
       #
       # Four categories are supported and each can be individually toggled:
       #
-      # - +:my_number+   — Japanese My Number (12-digit national ID)
+      # - +:ssn+         — US Social Security Numbers (###-##-####)
       # - +:credit_card+ — Credit / debit card numbers
       # - +:email+       — E-mail addresses
-      # - +:phone+       — Japanese domestic phone numbers
+      # - +:phone+       — Phone numbers
       #
       # All four categories are active by default.
       #
@@ -24,13 +24,10 @@ module Phronomy
       class PIIPatternDetector < InputGuardrail
         # Recognised PII categories and their detection patterns.
         PATTERNS = {
-          # Japanese My Number: 12 consecutive or grouped digits (4-4-4).
-          # Matched candidates are additionally validated with the official check-digit
-          # algorithm (JIS X 0076) to eliminate false positives from arbitrary 12-digit strings.
-          my_number: {
-            pattern: /(?<!\d)(?<!\d[- ])\d{4}[- ]?\d{4}[- ]?\d{4}(?![- ]?\d)/,
-            label: "My Number",
-            validate_my_number: true
+          # US Social Security Number: ###-##-#### (hyphens required).
+          ssn: {
+            pattern: /\b\d{3}-\d{2}-\d{4}\b/,
+            label: "SSN"
           },
           # Credit / debit card: 16 digits, optionally separated by spaces or hyphens.
           # Matched candidates are additionally validated with the Luhn algorithm
@@ -45,9 +42,10 @@ module Phronomy
             pattern: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/,
             label: "email address"
           },
-          # Japanese phone number: starts with 0, groups of 2-5 / 1-4 / 4 digits.
+          # Phone number: 3-digit area code, 3-4-digit exchange, 4-digit subscriber;
+          # optional E.164 country-code prefix (e.g. +1, +44).
           phone: {
-            pattern: /\b0\d{1,4}[- ]?\d{1,4}[- ]?\d{4}\b/,
+            pattern: /(?:\+\d{1,3}[.\- ]?)?\(?\d{3}\)?[.\- ]?\d{3,4}[.\- ]?\d{4}\b/,
             label: "phone number"
           }
         }.freeze
@@ -55,7 +53,7 @@ module Phronomy
         ALL_CATEGORIES = PATTERNS.keys.freeze
 
         # @param detect [Array<Symbol>] categories to detect.
-        #   Defaults to all four: +:my_number+, +:credit_card+, +:email+, +:phone+.
+        #   Defaults to all four: +:ssn+, +:credit_card+, +:email+, +:phone+.
         # @raise [ArgumentError] when an unknown category symbol is provided.
         def initialize(detect: ALL_CATEGORIES)
           unknown = Array(detect) - ALL_CATEGORIES
@@ -74,10 +72,6 @@ module Phronomy
               # Scan for all candidates then filter by Luhn check-digit validation.
               # This avoids false positives on arbitrary 16-digit strings (e.g. internal IDs).
               text.scan(entry[:pattern]).any? { |m| luhn_valid?(m.gsub(/[- ]/, "")) }
-            elsif entry[:validate_my_number]
-              # Scan for all candidates then apply the JIS X 0076 check-digit algorithm.
-              # This avoids false positives on arbitrary 12-digit strings.
-              text.scan(entry[:pattern]).any? { |m| my_number_valid?(m.gsub(/[- ]/, "")) }
             else
               text.match?(entry[:pattern])
             end
@@ -87,17 +81,6 @@ module Phronomy
 
         private
 
-        # Returns true when +digits+ (a 12-character string of decimal digits) satisfies
-        # the Japanese My Number check-digit algorithm defined in JIS X 0076.
-        # The check digit is the 12th digit.
-        def my_number_valid?(digits)
-          weights = [6, 5, 4, 3, 2, 7, 6, 5, 4, 3, 2]
-          total = weights.each_with_index.sum { |w, i| w * digits[i].to_i }
-          remainder = total % 11
-          check = (remainder <= 1) ? 0 : 11 - remainder
-          check == digits[11].to_i
-        end
-
         # Returns true when +digits+ (a string of decimal digits) satisfies the
         # Luhn check-digit algorithm used by payment card networks.
         def luhn_valid?(digits)

data/lib/phronomy/railtie.rb

@@ -30,16 +30,10 @@ module Phronomy
 
     # Loads Phronomy::Rails::AgentJob when both ActionCable and ActiveJob are present.
     initializer "phronomy.agent_job" do
-      if defined?(::ActionCable) && defined?(::ActiveJob)
-        require "phronomy/rails/agent_job"
-      end
     end
 
     # Loads Phronomy ActiveRecord extensions when ActiveRecord is available.
     initializer "phronomy.active_record", after: "active_record.initialize_database" do
-      ActiveSupport.on_load(:active_record) do
-        require "phronomy/active_record/extensions" if defined?(::ActiveRecord)
-      end
     end
   end
 end

data/lib/phronomy/ruby_llm_patches.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Patches for upstream ruby_llm bugs that have not yet been released.
+# Remove each patch once the fix is available in a published gem version.
+
+module RubyLLM
+  module Streaming
+    private
+
+    # Upstream ruby_llm <= 1.15.0 assumes the SSE error chunk always has two
+    # lines ("event: error\ndata: {...}") and uses a fixed index [1], which
+    # raises NoMethodError when some providers (e.g. Qwen) return a single-line
+    # chunk ("data: {...}").  This patch finds the data line by content instead.
+    def handle_error_chunk(chunk, env)
+      data_line = chunk.split("\n").find { |l| l.start_with?("data: ") } || chunk.split("\n")[0]
+      error_data = data_line.delete_prefix("data: ")
+      parse_error_from_json(error_data, env, "Failed to parse error chunk")
+    end
+  end
+end

data/lib/phronomy/tool/mcp_tool.rb

@@ -11,10 +11,11 @@ module Phronomy
     # A Phronomy::Tool::Base subclass that wraps a tool exposed by an external
     # MCP (Model Context Protocol) server.
     #
-    # Currently supports the **stdio** transport only: the MCP server is launched
-    # as a child process and communicates via newline-delimited JSON-RPC on stdin/stdout.
-    #
-    # HTTP/SSE transport support can be added later by subclassing Transport.
+    # Supports two transport schemes:
+    # - <b>"stdio://\<command\>"</b> — spawns a child process that communicates via
+    #   newline-delimited JSON-RPC on stdin/stdout.
+    # - <b>"http://\<url\>"</b> / <b>"https://\<url\>"</b> — connects to a running
+    #   HTTP/SSE MCP server using +net/http+.
     #
     # @example
     #   web_search = Phronomy::Tool::McpTool.from_server(
@@ -31,6 +32,7 @@ module Phronomy
         # @param server_uri [String] URI of the MCP server.
         #   Supported schemes:
         #   - "stdio://<command>"  — spawn a child process
+        #   - "http://<url>" / "https://<url>" — connect to an HTTP/SSE server
         # @param tool_name [String] the tool name as registered in the MCP server
         # @return [McpTool] a configured subclass instance ready for use with an Agent
         def from_server(server_uri, tool_name:)
@@ -87,7 +89,6 @@ module Phronomy
           # Split the command string into an argv array so that Open3 executes
           # it directly without going through the shell, preventing injection.
           @command = Shellwords.split(command)
-          @actor = Phronomy::Actor.new
           @stdin = nil
           @stdout = nil
           @stderr = nil
@@ -97,19 +98,17 @@ module Phronomy
 
         # Shut down the child process and close its IO streams.
         def close
-          stderr_thread, wait_thr = @actor.call do
-            @stdin&.close
-            @stdout&.close
-            @stderr&.close
-            @stdin = nil
-            @stdout = nil
-            @stderr = nil
-            t = [@stderr_thread, @wait_thr]
-            @stderr_thread = nil
-            @wait_thr = nil
-            t
-          end
-          # Join outside the Actor to avoid blocking the Actor thread on slow joins.
+          @stdin&.close
+          @stdout&.close
+          @stderr&.close
+          @stdin = nil
+          @stdout = nil
+          @stderr = nil
+          stderr_thread = @stderr_thread
+          wait_thr = @wait_thr
+          @stderr_thread = nil
+          @wait_thr = nil
+          # Join outside the lock to avoid blocking on slow joins.
           stderr_thread&.join(1)
           wait_thr&.join(5)
         end
@@ -168,14 +167,12 @@ module Phronomy
         end
 
         def rpc_call(method, params)
-          @actor.call do
-            ensure_started!
-            payload = JSON.generate(jsonrpc: "2.0", id: SecureRandom.uuid, method: method, params: params)
-            @stdin.puts(payload)
-            raw = @stdout.gets
-            raise Phronomy::ToolError, "MCP server closed the connection unexpectedly" if raw.nil?
-            JSON.parse(raw)
-          end
+          ensure_started!
+          payload = JSON.generate(jsonrpc: "2.0", id: SecureRandom.uuid, method: method, params: params)
+          @stdin.puts(payload)
+          raw = @stdout.gets
+          raise Phronomy::ToolError, "MCP server closed the connection unexpectedly" if raw.nil?
+          JSON.parse(raw)
         end
 
         def parse_schema_params(properties)

data/lib/phronomy/tracing/langfuse_tracer.rb

@@ -36,7 +36,6 @@ module Phronomy
         @secret_key = secret_key
         @host = host.chomp("/")
         @http = nil
-        @actor = Phronomy::Actor.new
       end
 
       # Returns a plain Hash that records the span start state.
@@ -90,13 +89,11 @@ module Phronomy
         req["Authorization"] = "Basic #{Base64.strict_encode64("#{@public_key}:#{@secret_key}")}"
         req.body = JSON.generate({batch: events})
 
-        @actor.call do
-          @http ||= build_http(uri)
-          @http.request(req)
-        end
+        @http ||= build_http(uri)
+        @http.request(req)
       rescue IOError, Errno::ECONNRESET, Errno::EPIPE => e
         # Connection was reset; drop the cached connection and warn.
-        @actor.call { @http = nil }
+        @http = nil
         warn "[Phronomy::LangfuseTracer] Ingestion failed: #{e.class}: #{e.message}"
         nil
       rescue => e

data/lib/phronomy/vector_store/redis_search.rb

@@ -38,7 +38,7 @@ module Phronomy
         @index_name = index_name
         @dimension = dimension
         @index_created = false
-        @actor = Phronomy::Actor.new
+        @mutex = Mutex.new
       end
 
       # @param id        [String]
@@ -80,7 +80,7 @@ module Phronomy
       end
 
       def clear
-        @actor.call do
+        @mutex.synchronize do
           begin
             @redis.call("FT.DROPINDEX", @index_name, "DD")
           rescue => e
@@ -94,8 +94,8 @@ module Phronomy
       private
 
       def ensure_index!(dim)
-        @actor.call do
-          next if @index_created
+        @mutex.synchronize do
+          return if @index_created
 
           @dimension ||= dim
           begin

data/lib/phronomy/version.rb

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

data/lib/phronomy/workflow.rb

@@ -53,11 +53,10 @@ module Phronomy
 
     # Defines a new Workflow.
     # @param context_class [Class] class that includes Phronomy::WorkflowContext
-    # @param state_store [Object, nil] optional state store override (passed to WorkflowRunner)
     # @yield block evaluated in DSL context
     # @return [Phronomy::Workflow] compiled and ready-to-run workflow instance
-    def self.define(context_class, state_store: nil, &block)
-      builder = Builder.new(context_class, state_store: state_store)
+    def self.define(context_class, &block)
+      builder = Builder.new(context_class)
       builder.instance_eval(&block)
       builder.build
     end
@@ -110,9 +109,8 @@ module Phronomy
     class Builder
       FINISH = Phronomy::WorkflowRunner::FINISH
 
-      def initialize(context_class, state_store: nil)
+      def initialize(context_class)
         @context_class = context_class
-        @state_store = state_store
         @initial = nil
         # { node_name => callable }
         @states = {}
@@ -210,8 +208,7 @@ module Phronomy
           route_transitions: route_transitions,
           external_events: external_events,
           entry_point: @initial || nodes.keys.first,
-          wait_state_names: @wait_state_names,
-          state_store: @state_store
+          wait_state_names: @wait_state_names
         )
 
         Workflow.new(runner)