phronomy 0.7.0 → 0.8.0

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: phronomy
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Raizo T.C.S
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-23 00:00:00.000000000 Z
+date: 2026-05-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby_llm
@@ -98,6 +98,7 @@ files:
 - docs/decisions/007-mcp-is-beta-stability.md
 - docs/decisions/008-orchestrator-uses-os-threads.md
 - docs/decisions/009-state-store-abstraction.md
+- docs/decisions/010-cooperative-first-concurrency.md
 - lib/phronomy.rb
 - lib/phronomy/agent.rb
 - lib/phronomy/agent/base.rb
@@ -108,28 +109,49 @@ files:
 - lib/phronomy/agent/concerns/guardrailable.rb
 - lib/phronomy/agent/concerns/retryable.rb
 - lib/phronomy/agent/concerns/suspendable.rb
+- lib/phronomy/agent/context/conversation/compaction_context.rb
+- lib/phronomy/agent/context/conversation/trigger_context.rb
+- lib/phronomy/agent/context/conversation/trim_context.rb
+- lib/phronomy/agent/context/instruction/prompt_template.rb
+- lib/phronomy/agent/context/knowledge/embeddings/base.rb
+- lib/phronomy/agent/context/knowledge/embeddings/ruby_llm_embeddings.rb
+- lib/phronomy/agent/context/knowledge/loader/base.rb
+- lib/phronomy/agent/context/knowledge/loader/csv_loader.rb
+- lib/phronomy/agent/context/knowledge/loader/markdown_loader.rb
+- lib/phronomy/agent/context/knowledge/loader/plain_text_loader.rb
+- lib/phronomy/agent/context/knowledge/source/base.rb
+- lib/phronomy/agent/context/knowledge/source/entity_knowledge.rb
+- lib/phronomy/agent/context/knowledge/source/rag_knowledge.rb
+- lib/phronomy/agent/context/knowledge/source/static_knowledge.rb
+- lib/phronomy/agent/context/knowledge/splitter/base.rb
+- lib/phronomy/agent/context/knowledge/splitter/fixed_size_splitter.rb
+- lib/phronomy/agent/context/knowledge/splitter/recursive_splitter.rb
+- lib/phronomy/agent/context/knowledge/vector_store/async_backend.rb
+- lib/phronomy/agent/context/knowledge/vector_store/base.rb
+- lib/phronomy/agent/context/knowledge/vector_store/in_memory.rb
+- lib/phronomy/agent/context/knowledge/vector_store/pgvector.rb
+- lib/phronomy/agent/context/knowledge/vector_store/redis_search.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/invocation_pipeline.rb
+- lib/phronomy/agent/lifecycle/fsm_session.rb
+- lib/phronomy/agent/lifecycle/phase_machine_builder.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/agent/tool_executor.rb
+- lib/phronomy/concurrency/async_queue.rb
+- lib/phronomy/concurrency/blocking_adapter_pool.rb
+- lib/phronomy/concurrency/cancellation_scope.rb
+- lib/phronomy/concurrency/cancellation_token.rb
+- lib/phronomy/concurrency/concurrency_gate.rb
+- lib/phronomy/concurrency/deadline.rb
+- lib/phronomy/concurrency/gate_registry.rb
+- lib/phronomy/concurrency/pool_registry.rb
 - lib/phronomy/configuration.rb
 - lib/phronomy/context.rb
-- lib/phronomy/context/assembler.rb
-- lib/phronomy/context/compaction_context.rb
-- lib/phronomy/context/context_version_cache.rb
-- lib/phronomy/context/token_budget.rb
-- lib/phronomy/context/token_estimator.rb
-- lib/phronomy/context/trigger_context.rb
-- lib/phronomy/context/trim_context.rb
+- lib/phronomy/diagnostics.rb
 - lib/phronomy/embeddings.rb
-- lib/phronomy/embeddings/base.rb
-- lib/phronomy/embeddings/ruby_llm_embeddings.rb
 - lib/phronomy/eval.rb
 - lib/phronomy/eval/comparison.rb
 - lib/phronomy/eval/dataset.rb
@@ -144,50 +166,68 @@ files:
 - 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/input_guardrail.rb
 - lib/phronomy/guardrail/output_guardrail.rb
+- lib/phronomy/guardrail/prompt_injection_guardrail.rb
+- lib/phronomy/invocation_context.rb
 - lib/phronomy/knowledge_source.rb
-- lib/phronomy/knowledge_source/base.rb
-- lib/phronomy/knowledge_source/entity_knowledge.rb
-- lib/phronomy/knowledge_source/rag_knowledge.rb
-- lib/phronomy/knowledge_source/static_knowledge.rb
+- lib/phronomy/llm_adapter.rb
+- lib/phronomy/llm_adapter/base.rb
+- lib/phronomy/llm_adapter/ruby_llm.rb
+- lib/phronomy/llm_context_window/assembler.rb
+- lib/phronomy/llm_context_window/context_version_cache.rb
+- lib/phronomy/llm_context_window/token_budget.rb
+- lib/phronomy/llm_context_window/token_estimator.rb
 - lib/phronomy/loader.rb
-- lib/phronomy/loader/base.rb
-- lib/phronomy/loader/csv_loader.rb
-- lib/phronomy/loader/markdown_loader.rb
-- lib/phronomy/loader/plain_text_loader.rb
+- lib/phronomy/metrics.rb
+- lib/phronomy/multi_agent/handoff.rb
+- lib/phronomy/multi_agent/orchestrator.rb
+- lib/phronomy/multi_agent/parallel_tool_chat.rb
+- lib/phronomy/multi_agent/team_coordinator.rb
 - lib/phronomy/output_parser.rb
 - lib/phronomy/output_parser/base.rb
 - lib/phronomy/output_parser/json_parser.rb
 - lib/phronomy/output_parser/structured_parser.rb
-- lib/phronomy/prompt_template.rb
 - lib/phronomy/ruby_llm_patches.rb
 - lib/phronomy/runnable.rb
+- lib/phronomy/runtime.rb
+- lib/phronomy/runtime/deterministic_scheduler.rb
+- lib/phronomy/runtime/fake_scheduler.rb
+- lib/phronomy/runtime/runtime_metrics.rb
+- lib/phronomy/runtime/scheduler.rb
+- lib/phronomy/runtime/scheduler_timer_adapter.rb
+- lib/phronomy/runtime/task_registry.rb
+- lib/phronomy/runtime/thread_scheduler.rb
+- lib/phronomy/runtime/timer_queue.rb
+- lib/phronomy/runtime/timer_service.rb
 - lib/phronomy/splitter.rb
-- 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/task.rb
+- lib/phronomy/task/backend.rb
+- lib/phronomy/task/fiber_backend.rb
+- lib/phronomy/task/immediate_backend.rb
+- lib/phronomy/task/thread_backend.rb
+- lib/phronomy/task_group.rb
+- lib/phronomy/testing.rb
+- lib/phronomy/testing/fake_clock.rb
+- lib/phronomy/testing/fake_scheduler.rb
+- lib/phronomy/testing/scheduler_helpers.rb
 - lib/phronomy/token_usage.rb
 - lib/phronomy/tool.rb
 - lib/phronomy/tool/agent_tool.rb
 - lib/phronomy/tool/base.rb
 - lib/phronomy/tool/mcp_tool.rb
+- lib/phronomy/tool/scope_policy.rb
 - lib/phronomy/tracing.rb
 - lib/phronomy/tracing/base.rb
 - lib/phronomy/tracing/langfuse_tracer.rb
 - lib/phronomy/tracing/null_tracer.rb
 - lib/phronomy/tracing/open_telemetry_tracer.rb
 - lib/phronomy/vector_store.rb
-- lib/phronomy/vector_store/base.rb
-- lib/phronomy/vector_store/in_memory.rb
-- lib/phronomy/vector_store/pgvector.rb
-- lib/phronomy/vector_store/redis_search.rb
 - lib/phronomy/version.rb
 - lib/phronomy/workflow.rb
 - lib/phronomy/workflow_context.rb

data/lib/phronomy/agent/parallel_tool_chat.rb

@@ -1,92 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    # RubyLLM::Chat subclass that executes multiple tool calls concurrently.
-    #
-    # When the LLM returns more than one tool call in a single response, each
-    # tool is dispatched in a dedicated IO thread and all results are collected
-    # before being appended to the message history. This preserves a
-    # deterministic message order while reducing wall-clock latency when tools
-    # are IO-bound (HTTP calls, DB queries, etc.).
-    #
-    # Single-tool responses fall through to the standard sequential path via
-    # +super+, preserving all existing edge-case behaviour (Tool::Halt,
-    # forced_tool_choice, streaming, SuspendSignal, etc.).
-    #
-    # This class is used automatically when the agent is running inside an
-    # {AgentFSM} IO thread (i.e. when the +:phronomy_agent_parallel_tools+
-    # thread-local flag is +true+).  It is not used for direct synchronous
-    # +invoke+ calls so that the streaming callback state remains single-threaded.
-    # @api private
-    class ParallelToolChat < RubyLLM::Chat
-      private
-
-      # Overrides RubyLLM::Chat#handle_tool_calls to parallelise execution
-      # when multiple tool calls are present in a single LLM response.
-      #
-      # The method preserves the three-phase protocol of the original:
-      #   1. Pre-execution callbacks (+on_new_message+, +on_tool_call+) —
-      #      sequential so that the Suspendable concern's approval hook can
-      #      raise +SuspendSignal+ before any tool is executed.
-      #   2. Parallel tool execution — one IO thread per tool call.
-      #   3. Post-execution callbacks and message recording — sequential,
-      #      in the original tool-call order.
-      #
-      # @param response [RubyLLM::Message] the LLM response containing tool calls
-      # @yield streaming block forwarded to +complete+
-      # @api private
-      def handle_tool_calls(response, &block)
-        tool_calls = response.tool_calls.values
-
-        # Single tool: delegate to the parent implementation to preserve every
-        # edge case (forced_tool_choice, streaming, Halt, SuspendSignal…).
-        return super if tool_calls.size <= 1
-
-        # Phase 1 — pre-execution callbacks (sequential, original order).
-        # The SuspendSignal approval hook is registered via on_tool_call, so it
-        # MUST fire before execution begins.
-        tool_calls.each do |tool_call|
-          @on[:new_message]&.call
-          @on[:tool_call]&.call(tool_call)
-        end
-
-        # Phase 2 — parallel tool execution.
-        # Honour the per-agent concurrency cap (max_parallel_tools DSL).
-        # Tool calls are processed in batches of at most `max` threads;
-        # batches run sequentially so the total in-flight thread count never
-        # exceeds the limit.
-        #
-        # Check for cancellation before dispatching each batch so that
-        # already-cancelled tokens do not start new LLM/tool-round-trips.
-        ct = Thread.current[:phronomy_cancellation_token]
-        max = Thread.current[:phronomy_max_parallel_tools] || 10
-        thread_results = tool_calls.each_slice(max).flat_map do |batch|
-          if ct&.cancelled?
-            raise Phronomy::CancellationError, "invocation cancelled before tool execution"
-          end
-
-          threads = batch.map do |tool_call|
-            Thread.new { {tool_call: tool_call, result: execute_tool(tool_call)} }
-          end
-          threads.map(&:value)
-        end
-
-        # Phase 3 — post-execution callbacks and message recording (sequential).
-        halt_result = nil
-        thread_results.each do |item|
-          result = item[:result]
-          @on[:tool_result]&.call(result)
-          tool_payload = result.is_a?(RubyLLM::Tool::Halt) ? result.content : result
-          content = content_like?(tool_payload) ? tool_payload : tool_payload.to_s
-          message = add_message(role: :tool, content: content, tool_call_id: item[:tool_call].id)
-          @on[:end_message]&.call(message)
-          halt_result = result if result.is_a?(RubyLLM::Tool::Halt)
-        end
-
-        reset_tool_choice if forced_tool_choice?
-        halt_result || complete(&block)
-      end
-    end
-  end
-end

data/lib/phronomy/cancellation_token.rb

@@ -1,92 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  # Provides cooperative cancellation for agent invocations.
-  #
-  # Pass a token to an agent via +config: { cancellation_token: token }+.
-  # The agent checks the token before each LLM call and raises
-  # {Phronomy::CancellationError} when the token is cancelled or the
-  # optional deadline has passed.
-  #
-  # A token may be shared across multiple agent invocations and across threads;
-  # all access to internal state is protected by a Mutex.
-  #
-  # @example Explicit cancel from another thread
-  #   token = Phronomy::CancellationToken.new
-  #   Thread.new { sleep 5; token.cancel! }
-  #   result = agent.invoke("...", config: { cancellation_token: token })
-  #
-  # @example Hard deadline via monotonic clock (recommended)
-  #   token = Phronomy::CancellationToken.timeout_after(30)
-  #   result = agent.invoke("...", config: { cancellation_token: token })
-  #
-  # @example Hard deadline via wall-clock (legacy)
-  #   token = Phronomy::CancellationToken.new(deadline: Time.now + 30)
-  #   result = agent.invoke("...", config: { cancellation_token: token })
-  #
-  # @example Propagate to parallel workers
-  #   token = Phronomy::CancellationToken.new
-  #   orchestrator.dispatch_parallel(task1, task2, cancellation_token: token)
-  class CancellationToken
-    # Returns a new token that will expire after +seconds+ seconds, measured
-    # with the monotonic clock (+Process::CLOCK_MONOTONIC+). Unlike constructing
-    # a token with +deadline: Time.now + seconds+, this factory is immune to NTP
-    # adjustments and DST transitions.
-    #
-    # @param seconds [Numeric] duration in seconds until the token expires.
-    # @return [CancellationToken]
-    # @api public
-    def self.timeout_after(seconds)
-      monotonic_deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + seconds
-      new(monotonic_deadline: monotonic_deadline)
-    end
-
-    # @param deadline [Time, nil] optional wall-clock deadline; the token reports
-    #   +cancelled?+ as +true+ once +Time.now >= deadline+.  Prefer
-    #   {.timeout_after} for duration-based cancellation.
-    # @param monotonic_deadline [Float, nil] internal monotonic timestamp set by
-    #   {.timeout_after}; prefer that factory method over passing this directly.
-    # @api public
-    def initialize(deadline: nil, monotonic_deadline: nil)
-      @cancelled = false
-      @deadline = deadline
-      @monotonic_deadline = monotonic_deadline
-      @mutex = Mutex.new
-    end
-
-    # @return [Time, nil] the wall-clock deadline passed to {#initialize}, or +nil+.
-    attr_reader :deadline
-
-    # Mark the token as cancelled. Thread-safe; may be called from any thread.
-    # @return [self]
-    # @api public
-    def cancel!
-      @mutex.synchronize { @cancelled = true }
-      self
-    end
-
-    # Returns +true+ when the token has been explicitly cancelled via {#cancel!},
-    # when the wall-clock deadline has passed, or when the monotonic deadline
-    # (set by {.timeout_after}) has elapsed. Thread-safe.
-    # @return [Boolean]
-    # @api public
-    def cancelled?
-      return true if @mutex.synchronize { @cancelled }
-      return true if !@deadline.nil? && Time.now >= @deadline
-      !@monotonic_deadline.nil? &&
-        Process.clock_gettime(Process::CLOCK_MONOTONIC) >= @monotonic_deadline
-    end
-
-    # Raises {Phronomy::CancellationError} if the token is cancelled.
-    # A convenience method for cooperative cancellation checks inside tools,
-    # RAG loaders, and hooks, replacing the +if cancelled? then raise+ pattern.
-    #
-    # @param message [String] optional error message
-    # @return [nil] when the token is not cancelled
-    # @raise [Phronomy::CancellationError] when the token is cancelled
-    # @api public
-    def raise_if_cancelled!(message = "invocation cancelled")
-      raise Phronomy::CancellationError, message if cancelled?
-    end
-  end
-end

data/lib/phronomy/context/compaction_context.rb

@@ -1,111 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Context
-    # Context object passed to the +on_compact+ callback registered on an agent.
-    #
-    # The callback calls #compact one or more times to specify which ranges of
-    # messages to replace with a summary. Each call:
-    #   1. Yields the selected message elements to the block.
-    #   2. Receives the block's return value as the summary text.
-    #   3. Persists a compaction record to the memory store (if available).
-    #   4. Updates #result_messages so that the compacted range is replaced
-    #      by a single +:system+ summary message.
-    #
-    # The agent reads #result_messages after the callback returns and uses it
-    # as the new message list for this invocation.
-    #
-    # @example Summarise the oldest half of the conversation
-    #   on_compact do |ctx|
-    #     half = ctx.message_elements.length / 2
-    #     ctx.compact(0...half) do |elements|
-    #       texts = elements.map { |e| "#{e[:role]}: #{e[:message].content}" }.join("\n")
-    #       "Summary of earlier conversation:\n#{texts}"
-    #     end
-    #   end
-    class CompactionContext
-      # @return [Array<Hash>] message elements at compaction time
-      attr_reader :message_elements
-
-      # @return [Phronomy::Context::TokenBudget, nil]
-      attr_reader :budget
-
-      # @return [Integer] total estimated token count before compaction
-      attr_reader :total_tokens
-
-      # The current message list to be used after all compact calls have been made.
-      # Updated by each call to #compact.
-      #
-      # @return [Array]
-      attr_reader :result_messages
-
-      # @param message_elements [Array<Hash>]
-      #   each element: { seq: Integer, message: Object, tokens: Integer, role: Symbol }
-      # @param budget [Phronomy::Context::TokenBudget, nil]
-      # @param thread_id [String, nil] used when saving compaction records
-      # @param memory [Object, nil] memory object; must respond to #save_compaction
-      #   for compaction records to be persisted
-      # @api private
-      def initialize(message_elements:, budget:, thread_id: nil, memory: nil)
-        @message_elements = message_elements.dup
-        @budget = budget
-        @total_tokens = message_elements.sum { |e| e[:tokens] }
-        @thread_id = thread_id
-        @memory = memory
-        @result_messages = @message_elements.map { |e| e[:message] }
-      end
-
-      # Replace a range of messages with a summary produced by the block.
-      #
-      # The block receives the selected Array<Hash> elements and must return a
-      # String that serves as the summary text. After the call, #result_messages
-      # reflects the replacement.
-      #
-      # If the memory object responds to #save_compaction, a compaction record
-      # { start_seq:, end_seq:, summary_text: } is persisted for auditability.
-      #
-      # @param range [Range, Integer] index range into message_elements (0-based)
-      # @yieldparam elements [Array<Hash>] the selected message elements
-      # @yieldreturn [String] summary text to replace the selected messages
-      # @return [Array] the updated result_messages array
-      # @api private
-      def compact(range)
-        # Normalise: Integer index → single-element Array; Range → Array slice.
-        raw = @message_elements[range]
-        elements = if raw.is_a?(Array)
-          raw
-        elsif raw.nil?
-          []
-        else
-          [raw]
-        end
-        return @result_messages if elements.empty?
-
-        summary_text = yield(elements).to_s
-
-        start_seq = elements.first[:seq]
-        end_seq = elements.last[:seq]
-
-        if @memory && @thread_id && @memory.respond_to?(:save_compaction)
-          @memory.save_compaction(
-            thread_id: @thread_id,
-            start_seq: start_seq,
-            end_seq: end_seq,
-            summary_text: summary_text
-          )
-        end
-
-        # Compute the last included index in the original @message_elements array.
-        last_idx = if range.is_a?(Range)
-          range.exclude_end? ? range.last - 1 : range.last
-        else
-          range.to_i
-        end
-
-        remaining = (@message_elements[(last_idx + 1)..] || []).map { |e| e[:message] }
-        summary_msg = RubyLLM::Message.new(role: :system, content: summary_text)
-        @result_messages = [summary_msg] + remaining
-      end
-    end
-  end
-end

data/lib/phronomy/context/trigger_context.rb

@@ -1,39 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Context
-    # Read-only context passed to the +on_compaction_trigger+ callback.
-    #
-    # The callback inspects the current message list and budget, then returns
-    # a truthy value to trigger compaction or a falsy value to skip it.
-    #
-    # No mutations are allowed through this object; use CompactionContext
-    # (passed to +on_compact+) for actual modifications.
-    #
-    # @example Trigger compaction when messages exceed 80% of the input budget
-    #   on_compaction_trigger do |ctx|
-    #     limit = ctx.budget&.available(used: 0) || Float::INFINITY
-    #     ctx.total_tokens > limit * 0.8
-    #   end
-    class TriggerContext
-      # @return [Array<Hash>] frozen snapshot of message elements
-      #   each element: { seq: Integer, message: Object, tokens: Integer, role: Symbol }
-      attr_reader :message_elements
-
-      # @return [Phronomy::Context::TokenBudget, nil] token budget for this invocation
-      attr_reader :budget
-
-      # @return [Integer] total estimated token count of all message elements
-      attr_reader :total_tokens
-
-      # @param message_elements [Array<Hash>]
-      # @param budget [Phronomy::Context::TokenBudget, nil]
-      # @api private
-      def initialize(message_elements:, budget:)
-        @message_elements = message_elements.dup.freeze
-        @budget = budget
-        @total_tokens = message_elements.sum { |e| e[:tokens] }
-      end
-    end
-  end
-end

data/lib/phronomy/context/trim_context.rb

@@ -1,75 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Context
-    # Context object passed to the +on_trim+ callback registered on an agent class.
-    #
-    # The callback receives a TrimContext and may call #remove to drop specific
-    # messages from the conversation before the LLM is called. Changes affect
-    # only the current invocation; the underlying memory store is not modified.
-    #
-    # Message elements are identified by a +:seq+ integer that is assigned
-    # sequentially (0-based) when messages are loaded from memory each turn.
-    #
-    # @example Remove the oldest two messages when the budget is tight
-    #   on_trim do |ctx|
-    #     if ctx.total_tokens > ctx.budget.available(used: 0) * 0.9
-    #       seqs_to_drop = ctx.message_elements.first(2).map { |e| e[:seq] }
-    #       ctx.remove(seqs_to_drop)
-    #     end
-    #   end
-    class TrimContext
-      # @return [Phronomy::Context::TokenBudget, nil] token budget for this invocation
-      attr_reader :budget
-
-      # @return [Integer] total estimated token count of all current message elements
-      attr_reader :total_tokens
-
-      # @param message_elements [Array<Hash>]
-      #   each element: { seq: Integer, message: Object, tokens: Integer, role: Symbol }
-      # @param budget [Phronomy::Context::TokenBudget, nil]
-      # @api private
-      def initialize(message_elements:, budget:)
-        @message_elements = message_elements.dup
-        @budget = budget
-        recalculate!
-      end
-
-      # Returns a snapshot of the current message elements (defensive copy).
-      # Each element is a Hash with +:seq+, +:message+, +:tokens+, and +:role+.
-      #
-      # @return [Array<Hash>]
-      # @api private
-      def message_elements
-        @message_elements.dup
-      end
-
-      # Remove messages identified by seq numbers.
-      # Calling this multiple times accumulates removals.
-      #
-      # @param seqs [Integer, Array<Integer>] seq number(s) to remove
-      # @return [self]
-      # @api private
-      def remove(seqs)
-        seqs_set = Array(seqs).to_set
-        @message_elements.reject! { |e| seqs_set.include?(e[:seq]) }
-        recalculate!
-        self
-      end
-
-      # Convenience: returns the plain message objects (without element metadata).
-      #
-      # @return [Array]
-      # @api private
-      def messages
-        @message_elements.map { |e| e[:message] }
-      end
-
-      private
-
-      def recalculate!
-        @total_tokens = @message_elements.sum { |e| e[:tokens] }
-      end
-    end
-  end
-end

data/lib/phronomy/embeddings/base.rb

@@ -1,22 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Embeddings
-    # Abstract interface for embedding adapters.
-    #
-    # Concrete implementations must override {#embed} and return a vector
-    # as an +Array<Float>+.
-    class Base
-      # Embed the given text and return a vector representation.
-      #
-      # @param text               [String]                         the text to embed
-      # @param cancellation_token [Phronomy::CancellationToken, nil] optional; raises CancellationError when cancelled
-      # @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
-    end
-  end
-end

data/lib/phronomy/embeddings/ruby_llm_embeddings.rb

@@ -1,45 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Embeddings
-    # Embeddings adapter backed by RubyLLM.
-    #
-    # Delegates to +RubyLLM.embed+ and returns the resulting vector as an
-    # +Array<Float>+.
-    #
-    # @example Default model
-    #   embeddings = Phronomy::Embeddings::RubyLLMEmbeddings.new
-    #   vector = embeddings.embed("Hello, world!")
-    #
-    # @example Explicit model
-    #   embeddings = Phronomy::Embeddings::RubyLLMEmbeddings.new(model: "text-embedding-3-small")
-    #   vector = embeddings.embed("Hello, world!")
-    class RubyLLMEmbeddings < Base
-      # @param model               [String, nil] embedding model identifier; nil uses the RubyLLM default
-      # @param provider            [Symbol, nil] provider override (e.g. :openai); nil uses the RubyLLM default
-      # @param assume_model_exists [Boolean]     when true, skips RubyLLM model-registry validation
-      #                                          (useful for locally hosted models not in the registry)
-      # @api public
-      def initialize(model: nil, provider: nil, assume_model_exists: false)
-        @model = model
-        @provider = provider
-        @assume_model_exists = assume_model_exists
-      end
-
-      # Embed text via RubyLLM.
-      #
-      # @param text               [String]
-      # @param cancellation_token [Phronomy::CancellationToken, nil] optional; raises CancellationError when cancelled
-      # @return [Array<Float>]
-      # @api public
-      def embed(text, cancellation_token = nil)
-        cancellation_token&.raise_if_cancelled!
-        opts = {}
-        opts[:model] = @model if @model
-        opts[:provider] = @provider if @provider
-        opts[:assume_model_exists] = true if @assume_model_exists
-        RubyLLM.embed(text, **opts).vectors
-      end
-    end
-  end
-end