phronomy 0.2.2 → 0.4.0

data/lib/phronomy/state_store/redis.rb

@@ -1,70 +0,0 @@
-# frozen_string_literal: true
-
-require "json"
-
-module Phronomy
-  module StateStore
-    # Redis-backed state store.
-    # Persists graph state as a JSON string under the key
-    # "phronomy:state:<thread_id>" in Redis.
-    #
-    # The Redis client must be compatible with the redis-rb gem interface:
-    #   client.set(key, value)
-    #   client.get(key)
-    #   client.del(key)
-    #
-    # @example
-    #   require "redis"
-    #   redis = Redis.new(url: ENV["REDIS_URL"])
-    #   Phronomy.configure do |c|
-    #     c.default_state_store = Phronomy::StateStore::Redis.new(client: redis)
-    #   end
-    #
-    # @example with TTL
-    #   Phronomy::StateStore::Redis.new(client: redis, ttl: 3600)
-    class Redis < Base
-      KEY_PREFIX = "phronomy:state:"
-      private_constant :KEY_PREFIX
-
-      # @param client [#set, #get, #del] Redis-compatible client
-      # @param ttl    [Integer, nil] optional key expiry in seconds
-      def initialize(client:, ttl: nil)
-        @client = client
-        @ttl = ttl
-      end
-
-      # @param state [Object] includes Phronomy::WorkflowContext
-      # @return [self]
-      def save(state)
-        serialized = serialize_state(state)
-        if @ttl
-          @client.set(key(state.thread_id), serialized, ex: @ttl)
-        else
-          @client.set(key(state.thread_id), serialized)
-        end
-        self
-      end
-
-      # @param thread_id [String]
-      # @return [Object, nil] state instance or nil
-      def load(thread_id)
-        raw = @client.get(key(thread_id))
-        return nil unless raw
-
-        deserialize_state(raw)
-      end
-
-      # @return [self]
-      def clear(thread_id)
-        @client.del(key(thread_id))
-        self
-      end
-
-      private
-
-      def key(thread_id)
-        "#{KEY_PREFIX}#{thread_id}"
-      end
-    end
-  end
-end

data/lib/phronomy/state_store.rb

@@ -1,9 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  # Namespace for state persistence backends.
-  # A StateStore saves and loads graph State objects keyed by thread_id.
-  # The thread_id is embedded in the State itself (state.thread_id).
-  module StateStore
-  end
-end

data/lib/phronomy/thread_actor_registry.rb

@@ -1,85 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  # Global per-thread-id {Actor} registry.
-  #
-  # Maps the +:thread_id+ key from the +config:+ argument passed to
-  # {Phronomy::Agent::Base#invoke} to a {Phronomy::Actor} instance.
-  # Each thread_id gets exactly one Actor so that all operations for the same
-  # conversation are serialised automatically.
-  #
-  # @example
-  #   Phronomy::ThreadActorRegistry.for("user-42").call do
-  #     # runs sequentially on the Actor's thread
-  #   end
-  module ThreadActorRegistry
-    @actors = {}
-    @registry_actor = Actor.new
-
-    class << self
-      # Returns (or lazily creates) the {Actor} for +thread_id+.
-      #
-      # When +Phronomy.configuration.max_actors+ is set, the registry evicts the
-      # least-recently-used Actor (by stopping it) before inserting a new one.
-      # Accessing an existing Actor moves it to the most-recently-used position.
-      #
-      # @param thread_id [String]
-      # @return [Phronomy::Actor]
-      def for(thread_id)
-        @registry_actor.call do
-          if @actors.key?(thread_id)
-            # LRU touch: move to end (most-recently used)
-            actor = @actors.delete(thread_id)
-            @actors[thread_id] = actor
-          else
-            evict_lru_if_needed!
-            @actors[thread_id] = Actor.new
-          end
-          @actors[thread_id]
-        end
-      end
-
-      # Returns the current number of registered Actors.
-      #
-      # @return [Integer]
-      def actor_count
-        @registry_actor.call { @actors.size }
-      end
-
-      # Gracefully stops the Actor for +thread_id+ and removes it from the
-      # registry.  The next call to {.for} with the same id creates a fresh Actor.
-      #
-      # @param thread_id [String]
-      def stop(thread_id)
-        @registry_actor.call { @actors.delete(thread_id) }&.stop
-      end
-
-      # Stops and removes every registered Actor.
-      # Intended for test teardown and process shutdown.
-      def clear_all
-        actors = @registry_actor.call { @actors.values.tap { @actors.clear } }
-        actors.each(&:stop)
-      end
-
-      # Yields each currently registered Actor.
-      # A snapshot is taken so the registry cannot change while callers iterate.
-      #
-      # @yield [Phronomy::Actor]
-      def each_actor(&block)
-        @registry_actor.call { @actors.values.dup }.each(&block)
-      end
-
-      private
-
-      # Evicts the least-recently-used Actor when the registry is at capacity.
-      # Must be called from within @registry_actor.call { } to be thread-safe.
-      def evict_lru_if_needed!
-        max = Phronomy.configuration.max_actors
-        return unless max && @actors.size >= max
-
-        _lru_id, lru_actor = @actors.shift
-        lru_actor.stop
-      end
-    end
-  end
-end

data/lib/phronomy/trust_pipeline.rb

@@ -1,264 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  # Orchestrates three trust mechanisms in a single pipeline:
-  #
-  # 1. **Citation Tracking** — the DraftAgent is prompted to list the knowledge
-  #    sources it relied on. Citations are extracted and attached to the result.
-  #
-  # 2. **Self-Review Loop** — a dedicated ReviewAgent evaluates each draft,
-  #    assigns a quality score, and provides actionable feedback. Rejected drafts
-  #    are retried with the reviewer's feedback embedded in the next prompt.
-  #
-  # 3. **Confidence Gate** — a combined confidence score (the minimum of the
-  #    DraftAgent's self-reported confidence and the ReviewAgent's score) is
-  #    compared against a threshold. The pipeline finishes early when the gate
-  #    passes; after +max_iterations+ cycles it finishes regardless and marks
-  #    the result as untrusted when the threshold was not reached.
-  #
-  # @example
-  #   pipeline = Phronomy::TrustPipeline.new(
-  #     draft_agent:          PolicyDraftAgent,
-  #     review_agent:         PolicyReviewAgent,
-  #     confidence_threshold: 0.7,
-  #     max_iterations:       3
-  #   )
-  #   result = pipeline.invoke("What is the refund policy?")
-  #   puts result.output      # the final answer string
-  #   puts result.trusted?    # true when confidence >= threshold
-  #   result.citations.each { |c| puts "#{c[:source]}: #{c[:excerpt]}" }
-  class TrustPipeline
-    # 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 {TrustPipeline#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 via
-    #   the ReviewAgent and are **not** verified against any external knowledge base,
-    #   document store, 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
-    # @param review_agent         [Class]   subclass of Phronomy::Agent::Base
-    # @param confidence_threshold [Float]   answers below this are retried (default: 0.7)
-    # @param max_iterations       [Integer] maximum draft-review cycles (default: 3)
-    # @param input_delimiter      [Array<String>, nil] optional two-element array
-    #   [start_tag, end_tag] used to wrap user input in prompts, e.g.
-    #   ["<user_input>", "</user_input>"] or
-    #   ["=== user input start ===", "=== user input end ==="].
-    #   When nil (default), input is embedded as-is for backward compatibility.
-    def initialize(draft_agent:, review_agent:,
-      confidence_threshold: DEFAULT_CONFIDENCE_THRESHOLD,
-      max_iterations: DEFAULT_MAX_ITERATIONS,
-      input_delimiter: nil)
-      @draft_agent_class = draft_agent
-      @review_agent_class = review_agent
-      @threshold = confidence_threshold.to_f
-      @max_iterations = max_iterations.to_i
-      @input_delimiter = input_delimiter
-      @actor = Phronomy::Actor.new
-      @compiled_graph = nil
-    end
-
-    # Run the pipeline.
-    #
-    # @param input  [String] the user question or task description
-    # @param config [Hash]   forwarded to the underlying agents (e.g. thread_id)
-    # @return [Result]
-    def invoke(input, config: {})
-      app = compiled_graph
-      state = app.invoke({input: input}, config: config)
-      confidence = combined_confidence(state)
-      Result.new(
-        output: state.output || state.draft.to_s,
-        confidence: confidence,
-        citations: state.citations,
-        iterations: state.iteration,
-        review_notes: state.review_notes,
-        trusted: confidence >= @threshold
-      )
-    end
-
-    private
-
-    def combined_confidence(state)
-      [(state.self_score || 0.0).to_f, (state.review_score || 0.0).to_f].min
-    end
-
-    # Returns the compiled workflow, building and caching it on first call.
-    def compiled_graph
-      @actor.call { @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
-      pipeline = self
-
-      Phronomy::Workflow.define(PipelineState) do
-        initial :draft
-
-        state :draft, action: ->(state) {
-          feedback = state.review_notes.last
-          prompt = pipeline.__send__(:draft_prompt, state.input, feedback)
-          result = draft_agent.invoke(prompt)
-          parsed = pipeline.__send__(:safe_parse_draft, 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 = pipeline.__send__(:review_prompt, state.input, state.draft, state.citations)
-          result = review_agent.invoke(prompt)
-          parsed = pipeline.__send__(:safe_parse_review, 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
-
-    # Wraps +input+ with the configured delimiter pair when +input_delimiter+ is set.
-    # When no delimiter is configured the input is returned unchanged.
-    def wrap_input(input)
-      return input unless @input_delimiter
-
-      start_tag, end_tag = @input_delimiter
-      "#{start_tag}\n#{input}\n#{end_tag}"
-    end
-
-    # Builds the prompt sent to the DraftAgent for each iteration.
-    def draft_prompt(input, feedback)
-      lines = [
-        "Answer the following question as accurately as possible.",
-        "Use any knowledge provided in <context> tags and cite your sources."
-      ]
-      if feedback && !feedback.strip.empty?
-        lines << ""
-        lines << "Your previous draft was reviewed and rejected. Address ALL of this feedback:"
-        lines << feedback.strip
-      end
-      lines += [
-        "",
-        "Question: #{wrap_input(input)}",
-        "",
-        "RESPOND ONLY WITH VALID JSON (no text outside the JSON block):",
-        '{"answer":"<full answer>","confidence":<0.0-1.0>,' \
-          '"citations":[{"source":"<doc name>","excerpt":"<exact quote>"}]}'
-      ]
-      lines.join("\n")
-    end
-
-    # Builds the prompt sent to the ReviewAgent.
-    def review_prompt(input, draft, citations)
-      citation_text = if citations.empty?
-        "  (none)"
-      else
-        citations.map { |c| "  - #{c[:source]}: \"#{c[:excerpt]}\"" }.join("\n")
-      end
-      [
-        "You are a rigorous quality reviewer. Evaluate the draft answer below.",
-        "",
-        "Question: #{wrap_input(input)}",
-        "",
-        "Draft answer:",
-        draft.to_s,
-        "",
-        "Citations provided:",
-        citation_text,
-        "",
-        "Evaluation criteria:",
-        "  1. Is the answer factually accurate and complete?",
-        "  2. Is every significant claim backed by a citation?",
-        "  3. Is the self-reported confidence realistic?",
-        "",
-        "RESPOND ONLY WITH VALID JSON (no text outside the JSON block):",
-        '{"approved":<true|false>,"score":<0.0-1.0>,' \
-          '"feedback":"<specific actionable feedback, or empty string if approved>"}'
-      ].join("\n")
-    end
-
-    def safe_parse_draft(text)
-      json_parser.parse(text)
-    rescue Phronomy::ParseError
-      {answer: text.to_s, confidence: 0.0, citations: []}
-    end
-
-    def safe_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