phronomy 0.26.0 → 0.28.0

data/lib/phronomy/persistence.rb

@@ -1,276 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  class Persistence
-    class ConflictError < Phronomy::Error; end
-    class NotFoundError < Phronomy::Error; end
-    class UnsupportedBackendError < Phronomy::Error; end
-    class SerializationError < Phronomy::Error; end
-
-    REQUIRED_CAPABILITIES = {
-      atomic_all: true,
-      atomic_admission: true,
-      optimistic_revision: true
-    }.freeze
-
-    # Content-addressed immutable content repository. ContentStore has its own
-    # codec/canonicalization boundary and is not wrapped in DurableRecord.
-    #
-    # @return [Object]
-    # @api public
-    attr_reader :contents
-
-    # Runtime/domain-facing AgentRoot repository. The backend repository supplied
-    # to #initialize is record-oriented; this facade owns encode/decode.
-    #
-    # @return [Object]
-    # @api public
-    attr_reader :agents
-
-    # Runtime/domain-facing append-only Agent Journal repository.
-    #
-    # @return [Object]
-    # @api public
-    attr_reader :journals
-
-    # Runtime/domain-facing AgentExecution repository.
-    #
-    # @return [Object]
-    # @api public
-    attr_reader :executions
-
-    # Runtime/domain-facing durable Workflow snapshot repository.
-    #
-    # @return [Object]
-    # @api public
-    attr_reader :workflow_states
-
-    # Purpose-specific durable Handoff and Team repositories in atomic_all.
-    # @api public
-    attr_reader :handoff_states, :teams, :team_executions
-
-    # Read-only exact Agent execution result; never creates a live Agent owner.
-    # Result is nil until a result_ref exists; errors remain canonical data.
-    # @api public
-    def execution_result(execution_id)
-      assert_observation_thread!
-      execution = executions.load(execution_id)
-      {
-        execution_id: execution.execution_id, agent_id: execution.agent_id,
-        status: execution.status, phase: execution.phase,
-        result_ref: execution.result_ref, error_ref: execution.error_ref,
-        result: execution.result_ref && contents.fetch_text(execution.result_ref),
-        error: execution.error_ref && contents.fetch_json(execution.error_ref)
-      }.then { |value| Phronomy::Agent::Immutable.copy(value) }
-    end
-
-    # Follows one exact Handoff turn without loading any Agent or graph.
-    # A committed absent Target reservation remains active; failed reads raise.
-    # @api public
-    def handoff_result(execution_id, main_agent_id: nil)
-      assert_observation_thread!
-      anchor = main_agent_id&.to_s
-      seen = {}
-      current = execution_id.to_s
-      reserved_agent_id = nil
-      loop do
-        raise Phronomy::Persistence::SerializationError, "Cyclic durable Handoff chain" if seen[current]
-        seen[current] = true
-        begin
-          execution = executions.load(current)
-        rescue Phronomy::Persistence::NotFoundError
-          routing = handoff_states.load(anchor)
-          if routing && Array(routing.metadata["cancelled_execution_ids"]).include?(current)
-            return {execution_id: current, agent_id: reserved_agent_id, status: :cancelled, result: nil, error: nil}.freeze
-          end
-          if reserved_agent_id && routing && routing.phase != "stable" && routing.pending_target_execution_id == current
-            return {execution_id: current, agent_id: reserved_agent_id, status: :active,
-                    phase: :target_pending, reserved: true, result: nil, error: nil}.freeze
-          end
-          raise
-        end
-        anchor ||= execution.metadata.dig("coordination", "main_agent_id")
-        unless anchor && execution.metadata.dig("coordination", "main_agent_id") == anchor
-          raise Phronomy::Persistence::ConflictError, "Execution does not belong to this Handoff anchor"
-        end
-        return execution_result(current) unless execution.status == :handed_off
-        reserved_agent_id = execution.metadata.fetch("handoff_target_agent_id")
-        current = execution.metadata.fetch("handoff_target_execution_id")
-      end
-    end
-
-    # Lists retained active and terminal executions in lexical ID order.
-    # after is an exclusive ID cursor; discovery does not imply request dedup.
-    # @api public
-    def list_executions(agent_id, after: nil, limit: 100)
-      assert_observation_thread!
-      executions.list(agent_id, after: after, limit: limit)
-    end
-
-    # Read-only exact Team result, independent of current Team class/Proc wiring.
-    # @api public
-    def team_execution_result(team_execution_id)
-      assert_observation_thread!
-      execution = team_executions.load(team_execution_id)
-      {
-        team_execution_id: execution.team_execution_id, team_id: execution.team_id,
-        status: execution.status, phase: execution.phase,
-        result_ref: execution.result_ref, error_ref: execution.error_ref,
-        result: execution.result_ref && contents.fetch_json(execution.result_ref),
-        error: execution.error_ref && contents.fetch_json(execution.error_ref)
-      }.then { |value| Phronomy::Agent::Immutable.copy(value) }
-    end
-
-    # Lists retained Team runs; no continuation or callback delivery occurs.
-    # @api public
-    def list_team_executions(team_id, after: nil, limit: 100)
-      assert_observation_thread!
-      team_executions.list(team_id, after: after, limit: limit)
-    end
-
-    # Initializes a Persistence backend from record-oriented storage
-    # repositories.
-    #
-    # Except for +contents+, backend repositories exchange
-    # {Phronomy::Persistence::DurableRecord} values. Phronomy's repository
-    # facades own current-format validation and domain-object encode/decode.
-    #
-    # Identity, revision, admission, and index metadata needed by a Backend is
-    # passed explicitly as repository arguments. A Backend must not inspect
-    # DurableRecord#payload to rediscover Phronomy domain semantics.
-    #
-    # Required raw repository shapes:
-    # - agents:
-    #   create(agent_id:, agent_revision:, record:), load(id),
-    #   save(id, expected_revision:, next_revision:, record:), delete(id)
-    # - journals:
-    #   append(id, expected_position:, records:, record_ids:), read/head/delete
-    # - executions:
-    #   create_active(execution_id:, agent_id:, execution_revision:, record:),
-    #   load(id), save(id, expected_revision:, next_revision:, agent_id:,
-    #   active:, record:), list_active/delete/delete_for_agent/assert_idle!
-    # - workflow_states:
-    #   load(id), save(id, expected_revision:, next_revision:, record:), delete
-    #
-    # Subclasses normally construct backend-specific raw repository objects and
-    # call +super+. Construction fails fast when required capabilities are not
-    # advertised.
-    #
-    # @api public
-    def initialize(contents:, agents:, journals:, executions:, workflow_states:, handoff_states:, teams:, team_executions:)
-      @contents = contents
-      @agents = RepositoryFacades::Agents.new(agents)
-      @journals = RepositoryFacades::Journals.new(journals)
-      @executions = RepositoryFacades::Executions.new(executions)
-      @workflow_states = RepositoryFacades::WorkflowStates.new(workflow_states)
-      @handoff_states = RepositoryFacades::HandoffStates.new(handoff_states)
-      @teams = RepositoryFacades::Teams.new(teams)
-      @team_executions = RepositoryFacades::TeamExecutions.new(team_executions)
-      validate_capabilities!
-    end
-
-    # Declares storage semantics provided by this backend.
-    #
-    # Required meanings:
-    # - +atomic_all+: all durable repositories can participate in one atomic
-    #   transaction domain.
-    # - +atomic_admission+: Agent execution admission is atomic; at most one
-    #   active/suspended execution may be admitted for one Agent. This does not
-    #   mean cross-process Workflow admission or distributed locking.
-    # - +optimistic_revision+: Agent, Execution, Workflow revision checks and
-    #   Journal position checks provide compare-and-swap conflict detection.
-    #
-    # @return [Hash{Symbol => Boolean}]
-    # @api public
-    def capabilities
-      {
-        atomic_all: false,
-        atomic_admission: false,
-        optimistic_revision: false
-      }.freeze
-    end
-
-    # Executes one atomic durable transaction.
-    #
-    # The yielded object is a transaction-scoped Persistence view exposing the
-    # same domain-facing repository facades. Its underlying backend repositories
-    # remain DurableRecord-oriented.
-    #
-    # If the block raises, mutations made through the transaction view must not
-    # be committed. Storage failures whose commit outcome is fundamentally
-    # unknown remain backend/database failures; Phronomy does not claim
-    # exactly-once semantics for such failures.
-    #
-    # @yieldparam transaction_view [Object]
-    # @return [Object] the block result
-    # @raise [UnsupportedBackendError] when atomic transactions are unavailable
-    # @api public
-    def transaction
-      raise UnsupportedBackendError, "#{self.class} does not provide atomic_all"
-    end
-
-    # Backend SPI helper for transaction implementations whose transaction-scoped
-    # raw repositories differ from the root repository objects.
-    #
-    # +watermark+ is a transaction-scoped object responding to
-    # +assert_agent_watermark!+. The returned view owns the same Phronomy codec
-    # facades as the root Persistence instance, so backend authors never need to
-    # instantiate RepositoryFacades directly.
-    #
-    # Backends whose repository objects are already transaction-scoped may yield
-    # +self+ and need not call this helper.
-    #
-    # @api public
-    def build_transaction_view(
-      contents:,
-      agents:,
-      journals:,
-      executions:,
-      workflow_states:,
-      handoff_states:, teams:, team_executions:,
-      watermark:
-    )
-      RepositoryFacades::View.new(
-        contents: contents,
-        agents: agents,
-        journals: journals,
-        executions: executions,
-        workflow_states: workflow_states,
-        handoff_states: handoff_states, teams: teams, team_executions: team_executions,
-        watermark: watermark
-      )
-    end
-
-    # Verifies that a live Agent still owns the durable base it hydrated.
-    #
-    # This is a Backend SPI operation invoked by Phronomy at durable barriers.
-    # Ordinary application code should not call it directly. The backend must
-    # compare the stored Agent revision and current Journal position against the
-    # supplied watermark in the same storage consistency view used by subsequent
-    # writes in the surrounding transaction.
-    #
-    # @api public
-    def assert_agent_watermark!(agent_id:, agent_revision:, journal_position:)
-      raise UnsupportedBackendError,
-        "#{self.class} does not provide Agent durable-watermark checks"
-    end
-
-    private
-
-    def assert_observation_thread!
-      if Phronomy::Runtime.in_event_loop_context?
-        raise Phronomy::EventLoopReentrancyError, "Persistence observation cannot block EventLoop"
-      end
-    end
-
-    def validate_capabilities!
-      missing = REQUIRED_CAPABILITIES.reject do |key, value|
-        capabilities[key] == value
-      end
-      return if missing.empty?
-
-      raise UnsupportedBackendError,
-        "Persistence backend lacks required capabilities: #{missing.keys.join(", ")}"
-    end
-  end
-end

data/lib/phronomy/recovery.rb

@@ -1,186 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  # Small private Recovery semantic/primitives layer shared by Agent and
-  # Workflow recovery. Entity-specific orchestration remains outside this module.
-  # @api private
-  module Recovery
-    RESUMABLE = :resumable
-    RECONCILABLE = :reconcilable
-    RESOLUTION_REQUIRED = :resolution_required
-    DISPOSITIONS = [RESUMABLE, RECONCILABLE, RESOLUTION_REQUIRED].freeze
-
-    ALLOWED_OUTCOMES = %i[succeeded failed not_performed].freeze
-    # Internal shorthand used by the Agent Recovery implementation. This is not
-    # a public API constant; both names refer to the same frozen value.
-    OUTCOMES = ALLOWED_OUTCOMES
-
-    MISSING = Object.new.freeze
-
-    Classification = Data.define(
-      :disposition, :reason, :subject, :allowed_outcomes, :facts
-    ) do
-      def initialize(
-        disposition:,
-        reason:,
-        subject: nil,
-        allowed_outcomes: [],
-        facts: {}
-      )
-        normalized = disposition.to_sym
-        unless Phronomy::Recovery::DISPOSITIONS.include?(normalized)
-          raise ArgumentError, "unknown Recovery disposition: #{disposition.inspect}"
-        end
-        super(
-          disposition: normalized,
-          reason: reason.to_sym,
-          subject: subject && Phronomy::Recovery.normalize_subject(subject),
-          allowed_outcomes: Array(allowed_outcomes).map(&:to_sym).freeze,
-          facts: Phronomy::Agent::Immutable.copy(facts || {})
-        )
-      end
-    end
-
-    module_function
-
-    def normalize_outcome(outcome)
-      normalized = outcome.to_sym
-      unless OUTCOMES.include?(normalized)
-        raise ArgumentError, "unsupported Recovery outcome: #{outcome.inspect}"
-      end
-      normalized
-    end
-
-    def validate_resolution_material!(outcome:, result_present:, error_present:)
-      normalized = normalize_outcome(outcome)
-      case normalized
-      when :succeeded
-        raise ArgumentError, "Recovery :succeeded requires result:" unless result_present
-        raise ArgumentError, "Recovery :succeeded forbids error:" if error_present
-      when :failed
-        raise ArgumentError, "Recovery :failed requires error:" unless error_present
-        raise ArgumentError, "Recovery :failed forbids result:" if result_present
-      when :not_performed
-        if result_present || error_present
-          raise ArgumentError, "Recovery :not_performed accepts neither result: nor error:"
-        end
-      end
-      true
-    end
-
-    def normalize_subject(subject)
-      hash = subject.to_h.transform_keys(&:to_sym)
-      type = hash.fetch(:type).to_sym
-      normalized = {type: type}
-      case type
-      when :llm_call
-        normalized[:llm_call_id] = required_id(hash, :llm_call_id)
-      when :tool_invocation
-        normalized[:tool_invocation_id] = required_id(hash, :tool_invocation_id)
-      when :persistence_operation
-        # Persistence operation references are structural only. Do not introduce
-        # a generic durable operation/recovery identity here.
-        normalized[:entity] = hash.fetch(:entity).to_sym
-      else
-        raise ArgumentError, "unsupported Recovery subject type: #{type.inspect}"
-      end
-      normalized.freeze
-    end
-
-    def subject_key(subject)
-      normalized = normalize_subject(subject)
-      case normalized.fetch(:type)
-      when :llm_call
-        "llm_call:#{normalized.fetch(:llm_call_id)}"
-      when :tool_invocation
-        "tool_invocation:#{normalized.fetch(:tool_invocation_id)}"
-      when :persistence_operation
-        "persistence_operation:#{normalized.fetch(:entity)}"
-      end
-    end
-
-    def subject_equal?(left, right)
-      normalize_subject(left) == normalize_subject(right)
-    rescue ArgumentError, KeyError
-      false
-    end
-
-    # Compare authoritative current state with a known pre/post revision pair.
-    # This is deliberately small: callers still validate entity-specific content.
-    def compare_revisions(current_revision:, expected_pre_revision:, intended_post_revision:)
-      current = current_revision
-      return :post_state if current == intended_post_revision
-      return :pre_state if current == expected_pre_revision
-
-      :conflict
-    end
-
-    # Generic F1 helper for revisioned snapshot repositories such as Workflow.
-    # Some repositories return a newly allocated revision only after save, so
-    # callers may not know the intended post revision in advance. In that case
-    # the intended snapshot plus a revision different from the expected pre
-    # revision identifies the post-state.
-    def compare_revisioned_snapshot(
-      record:,
-      expected_pre_revision:,
-      intended_snapshot:,
-      intended_post_revision: nil
-    )
-      return :pre_state if record.nil? && expected_pre_revision.nil?
-      return :conflict if record.nil?
-
-      revision = fetch_value(record, :revision)
-      snapshot = fetch_value(record, :snapshot)
-      normalized_snapshot = normalize_value(snapshot)
-      normalized_intended = normalize_value(intended_snapshot)
-
-      if intended_post_revision
-        if revision == intended_post_revision &&
-            normalized_snapshot == normalized_intended
-          return :post_state
-        end
-      elsif normalized_snapshot == normalized_intended &&
-          revision != expected_pre_revision
-        return :post_state
-      end
-
-      return :pre_state if revision == expected_pre_revision
-
-      :conflict
-    end
-
-    def normalize_value(value)
-      case value
-      when Hash
-        value.each_with_object({}) do |(key, child), result|
-          result[key.to_s] = normalize_value(child)
-        end
-      when Array
-        value.map { |child| normalize_value(child) }
-      when Symbol
-        value.to_s
-      else
-        value
-      end
-    end
-
-    def fetch_value(record, key)
-      return nil unless record
-      return record.public_send(key) if record.respond_to?(key)
-      return record[key] if record.respond_to?(:key?) && record.key?(key)
-      string_key = key.to_s
-      return record[string_key] if record.respond_to?(:key?) && record.key?(string_key)
-
-      nil
-    end
-
-    def required_id(hash, key)
-      value = hash.fetch(key)
-      text = value.to_s
-      raise ArgumentError, "#{key} must not be empty" if text.empty?
-
-      text.freeze
-    end
-    private_class_method :required_id
-  end
-end

data/lib/phronomy/ruby_llm_patches.rb

@@ -1,24 +0,0 @@
-# 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.
-
-# Guard: apply monkey-patches only to affected ruby_llm versions so that
-# upgrading the gem does not silently keep dead overrides in place.
-if Gem::Version.new(RubyLLM::VERSION) <= Gem::Version.new("1.15.0")
-  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
-end

data/lib/phronomy/runnable.rb

@@ -1,54 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  # Base interface for executable graph components.
-  # Provides invoke / stream / batch.
-  module Runnable
-    # Synchronous execution. Must be overridden in subclasses.
-    def invoke(input, config: {})
-      raise NotImplementedError, "#{self.class}#invoke is not implemented"
-    end
-
-    # Streaming execution. Default yields the invoke result as a single chunk.
-    def stream(input, config: {}, &block)
-      result = invoke(input, config: config)
-      yield result if block
-      result
-    end
-
-    # Batch execution. Default calls invoke sequentially.
-    def batch(inputs, config: {})
-      inputs.map { |input| invoke(input, config: config) }
-    end
-
-    # Convenience wrapper that delegates to the global tracer.
-    # Yields a span; the block must return [result, usage] where usage is a
-    # Phronomy::TokenUsage or nil. Returns only the result value.
-    #
-    # When +trace_pii+ is disabled, both the input and the output (LLM response,
-    # tool result) are replaced with the literal string "[REDACTED]" before being
-    # forwarded to the tracing backend. The actual result is still returned to
-    # the caller — only the copy sent to the tracer is redacted.
-    #
-    # @example
-    #   trace("my_chain", input: input) { [invoke(input), nil] }
-    # @api public
-    def trace(name, input: nil, **meta, &block)
-      traced_input = Phronomy.configuration.trace_pii ? input : "[REDACTED]"
-
-      if Phronomy.configuration.trace_pii
-        # PII recording is allowed: pass through unchanged.
-        Phronomy.configuration.tracer.trace(name, input: traced_input, **meta, &block)
-      else
-        # Redact both input (above) and output before forwarding to the tracer.
-        # Capture the real result so callers receive the unredacted value.
-        real_result = nil
-        Phronomy.configuration.tracer.trace(name, input: traced_input, **meta) do |span|
-          real_result, usage = block.call(span)
-          ["[REDACTED]", usage]
-        end
-        real_result
-      end
-    end
-  end
-end

data/lib/phronomy/token_usage.rb

@@ -1,85 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  # Immutable value object that holds token usage counts for a single LLM call
-  # or an accumulated total across multiple calls.
-  #
-  # Fields mirror the values reported by RubyLLM::Tokens:
-  #
-  #   input          - tokens consumed by the input (prompt)
-  #   output         - tokens produced by the model (completion)
-  #   cached         - input tokens served from the provider's prompt cache
-  #   cache_creation - input tokens written into the prompt cache (Anthropic)
-  #
-  # All fields are Integer or nil (nil means the provider did not report that
-  # value for this call).
-  #
-  # @example Accumulate usage across a ReAct loop
-  #   total = Phronomy::TokenUsage.zero
-  #   chat.messages.each do |msg|
-  #     total += Phronomy::TokenUsage.from_tokens(msg.tokens)
-  #   end
-  class TokenUsage
-    attr_reader :input, :output, :cached, :cache_creation
-
-    def initialize(input: nil, output: nil, cached: nil, cache_creation: nil)
-      @input = input
-      @output = output
-      @cached = cached
-      @cache_creation = cache_creation
-    end
-
-    # Returns a zero-valued TokenUsage suitable as an accumulator seed.
-    def self.zero
-      new(input: 0, output: 0, cached: 0, cache_creation: 0)
-    end
-
-    # Builds a TokenUsage from a RubyLLM::Tokens object. Returns zero
-    # when tokens is nil (provider did not report usage).
-    # nil fields within the tokens object are coerced to 0.
-    def self.from_tokens(tokens)
-      return zero if tokens.nil?
-
-      new(
-        input: tokens.input || 0,
-        output: tokens.output || 0,
-        cached: tokens.cached || 0,
-        cache_creation: tokens.cache_creation || 0
-      )
-    end
-
-    # Adds two TokenUsage instances. nil fields are treated as 0 so that
-    # partially-reported usage accumulates correctly.
-    # When other is nil, returns self unchanged.
-    def +(other)
-      return self if other.nil?
-
-      self.class.new(
-        input: _add(input, other.input),
-        output: _add(output, other.output),
-        cached: _add(cached, other.cached),
-        cache_creation: _add(cache_creation, other.cache_creation)
-      )
-    end
-
-    def ==(other)
-      other.is_a?(TokenUsage) &&
-        input == other.input &&
-        output == other.output &&
-        cached == other.cached &&
-        cache_creation == other.cache_creation
-    end
-
-    def to_h
-      {input: input, output: output, cached: cached, cache_creation: cache_creation}
-    end
-
-    private
-
-    def _add(a, b)
-      return nil if a.nil? && b.nil?
-
-      (a || 0) + (b || 0)
-    end
-  end
-end

data/lib/phronomy/vector_store/embeddings/base.rb

@@ -1,44 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module VectorStore
-    module Embeddings
-      # Public extension SPI for embedding adapters.
-      #
-      # Concrete implementations override {#embed}. Phronomy owns the async
-      # bridge: {#embed_async} routes the synchronous implementation through the
-      # bounded OffloadPool and returns a {Phronomy::TaskResult}.
-      #
-      # @api public
-      class Base
-        # Embed the given text and return a vector representation.
-        #
-        # @param text               [String] the text to embed
-        # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
-        # @return [Array<Float>] the embedding vector
-        # @api public
-        def embed(text, cancellation_token = nil)
-          cancellation_token&.raise_if_cancelled!
-          raise NotImplementedError, "#{self.class}#embed is not implemented"
-        end
-
-        # Submits an {#embed} call to {OffloadPool}.
-        #
-        # @param text               [String]
-        # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
-        # @param timeout            [Numeric, nil] operation-wide submit timeout
-        # @return [Phronomy::TaskResult]
-        # @api public
-        def embed_async(text, cancellation_token = nil, timeout: nil)
-          Phronomy::Runtime.instance.offload.submit(
-            timeout: timeout,
-            cancellation_token: cancellation_token,
-            on_full: :raise
-          ) do
-            embed(text, cancellation_token)
-          end
-        end
-      end
-    end
-  end
-end