phronomy 0.2.2 → 0.4.0

data/lib/phronomy/active_record/acts_as.rb

@@ -1,48 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module ActiveRecord
-    # DSL mixin that can be included in ApplicationRecord subclasses
-    # to declaratively associate them with Phronomy persistence roles.
-    #
-    # @example
-    #   class PhronomyMessage < ApplicationRecord
-    #     acts_as_phronomy_message
-    #   end
-    module ActsAs
-      def self.included(base)
-        base.extend(ClassMethods)
-      end
-
-      module ClassMethods
-        # Configures this model as a Phronomy checkpoint store.
-        # Applies validations and exposes a convenience checkpointer factory.
-        #
-        # @param encryptor [StateStore::Encryptor::Base, nil] optional encryptor
-        #   for encrypting +state_json+ at rest.
-        def acts_as_phronomy_checkpoint(encryptor: nil)
-          include ::Phronomy::ActiveRecord::Checkpoint
-
-          define_singleton_method(:phronomy_checkpointer) do |enc: encryptor|
-            ::Phronomy::StateStore::ActiveRecord.new(model_class: self, encryptor: enc)
-          end
-        end
-
-        # Configures this model as a Phronomy message store.
-        # Applies validations and exposes a convenience factory method.
-        #
-        # @return [Phronomy::Memory::ConversationManager] a ready-to-use memory object
-        def acts_as_phronomy_message
-          include ::Phronomy::ActiveRecord::Message
-
-          define_singleton_method(:phronomy_memory) do
-            ::Phronomy::Memory::ConversationManager.new(
-              storage: ::Phronomy::Memory::Storage::ActiveRecord.new(model_class: self),
-              retrieval: ::Phronomy::Memory::Retrieval::Recent.new
-            )
-          end
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/active_record/checkpoint.rb

@@ -1,20 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module ActiveRecord
-    # Mixin for models backed by the phronomy_checkpoints table.
-    # Validates the required columns and exposes a convenience factory.
-    #
-    # @example
-    #   class PhronomyCheckpoint < ApplicationRecord
-    #     include Phronomy::ActiveRecord::ActsAs
-    #     acts_as_phronomy_checkpoint
-    #   end
-    module Checkpoint
-      def self.included(base)
-        base.validates :thread_id, presence: true
-        base.validates :state_json, presence: true
-      end
-    end
-  end
-end

data/lib/phronomy/active_record/extensions.rb

@@ -1,14 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module ActiveRecord
-    # Convenience namespace loaded by Railtie when ActiveRecord is available.
-    # Ensures all Phronomy::ActiveRecord mixins are eager-loaded in Rails context.
-    module Extensions
-    end
-  end
-end
-
-require_relative "checkpoint"
-require_relative "message"
-require_relative "acts_as"

data/lib/phronomy/active_record/message.rb

@@ -1,20 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module ActiveRecord
-    # Mixin for models backed by the phronomy_messages table.
-    #
-    # @example
-    #   class PhronomyMessage < ApplicationRecord
-    #     include Phronomy::ActiveRecord::Message
-    #   end
-    module Message
-      def self.included(base)
-        base.validates :thread_id, presence: true
-        base.validates :role, presence: true
-        # content may be blank for assistant messages that carry only tool calls
-        base.validates :content, presence: false, allow_nil: true
-      end
-    end
-  end
-end

data/lib/phronomy/actor.rb

@@ -1,68 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  # Lightweight synchronous actor backed by a dedicated +Thread+ and a +Queue+.
-  #
-  # A caller submits work via {#call}, which blocks until the actor's thread
-  # finishes executing the block and then returns the result (or re-raises any
-  # exception that occurred inside the actor).
-  #
-  # === Reentrant safety
-  #
-  # If {#call} is invoked from within the actor's own thread (i.e. from inside
-  # a block that is already executing on this actor), the block is executed
-  # directly in the current thread instead of being pushed onto the queue.
-  # This prevents deadlocks in deeply nested call paths without requiring
-  # callers to track whether they are already "inside" the actor.
-  #
-  # === Usage
-  #
-  #   actor = Phronomy::Actor.new
-  #   result = actor.call { expensive_operation() }   # blocks caller; runs on actor thread
-  #   actor.stop                                       # graceful shutdown
-  class Actor
-    def initialize
-      @queue = Queue.new
-      @thread = Thread.new do
-        loop do
-          task = @queue.pop
-          break if task == :stop
-          task.call
-        end
-      end
-    end
-
-    # Run +block+ on the actor's thread and return its result.
-    #
-    # If the current thread is already the actor's thread (reentrant call),
-    # the block is executed inline to prevent deadlocks.
-    #
-    # Any exception raised inside the block is captured and re-raised in the
-    # calling thread.
-    #
-    # @yield block to execute on the actor's thread
-    # @return the return value of the block
-    def call(&block)
-      return block.call if Thread.current == @thread
-
-      done = Queue.new
-      @queue.push(-> {
-        begin
-          done.push([true, block.call])
-        rescue => e
-          done.push([false, e])
-        end
-      })
-      success, value = done.pop
-      raise value unless success
-      value
-    end
-
-    # Send a +:stop+ sentinel to gracefully terminate the actor's thread.
-    # Pending tasks already in the queue will still be processed before
-    # the thread exits.
-    def stop
-      @queue.push(:stop)
-    end
-  end
-end

data/lib/phronomy/memory/compression/base.rb

@@ -1,37 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Memory
-    module Compression
-      # Abstract base class for compression strategies.
-      #
-      # Two kinds of compression exist:
-      #
-      # * Content pruning (e.g. ToolOutputPruner) — modifies individual message
-      #   content in-place (e.g. truncates oversized tool outputs). The original
-      #   data loss is limited and intentional (tool outputs are auxiliary).
-      #   These subclasses return { messages: Array, compaction: nil }.
-      #
-      # * Compaction (e.g. Summary) — replaces multiple messages with an LLM
-      #   summary. Originals are preserved in Storage via a compaction record.
-      #   These subclasses return { messages: Array, compaction: Hash } where
-      #   compaction is { start_seq:, end_seq:, summary_text: }.
-      #
-      # ConversationManager inspects the :compaction key and persists the record
-      # in Storage when present.
-      #
-      # @abstract Subclass and implement #compress.
-      class Base
-        # Compress a message array and return a result hash.
-        #
-        # @param thread_id  [String]  thread identifier (used by stateful compressors)
-        # @param messages   [Array]   message history to compress
-        # @param seq_offset [Integer] seq number of messages[0] in the raw history
-        # @return [Hash] { messages: Array, compaction: Hash|nil }
-        def compress(thread_id:, messages:, seq_offset: 0)
-          raise NotImplementedError, "#{self.class}#compress is not implemented"
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/memory/compression/summary.rb

@@ -1,107 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Memory
-    module Compression
-      # Compaction strategy that summarizes old messages with an LLM.
-      #
-      # When the total estimated token count of the uncompacted message history
-      # exceeds +max_tokens+, all messages except the most recent +keep+ are
-      # summarized by an LLM. The original messages are preserved in Storage
-      # (via ConversationManager); this class only decides whether compaction is
-      # needed and produces the summary text.
-      #
-      # The #compress method now returns a Hash instead of a plain Array:
-      #   {
-      #     messages:   Array,            # context-ready message list
-      #     compaction: Hash | nil        # { start_seq:, end_seq:, summary_text: }
-      #                                   # nil when no compaction was performed
-      #   }
-      #
-      # ConversationManager uses the :compaction entry to persist the compaction
-      # record in Storage, ensuring originals are never discarded.
-      #
-      # @example
-      #   compressor = Phronomy::Memory::Compression::Summary.new(
-      #     max_tokens: 4000,
-      #     summarizer_model: "gpt-4o-mini"
-      #   )
-      #   manager = Phronomy::Memory::ConversationManager.new(
-      #     storage: storage,
-      #     retrieval: retrieval,
-      #     compression: compressor
-      #   )
-      class Summary < Base
-        # @param max_tokens          [Integer]     token threshold above which old messages are compacted
-        # @param keep                [Integer]     number of recent messages to preserve verbatim
-        # @param summarizer_model    [String, nil] LLM model for summarization; nil uses global default
-        # @param summarizer_provider [Symbol, nil] LLM provider; required for unregistered models
-        def initialize(max_tokens: 4000, keep: 5, summarizer_model: nil, summarizer_provider: nil)
-          @max_tokens = max_tokens
-          @keep = keep
-          @summarizer_model = summarizer_model
-          @summarizer_provider = summarizer_provider
-        end
-
-        # Evaluate whether compaction is needed and produce a summary if so.
-        #
-        # +seq_offset+ is the seq number of messages[0] in the raw history.
-        # ConversationManager passes this so the compaction record can reference
-        # the correct seq range in Storage.
-        #
-        # @param thread_id  [String]
-        # @param messages   [Array]   uncompacted messages to consider
-        # @param seq_offset [Integer] seq number assigned to messages[0]
-        # @return [Hash] { messages: Array, compaction: Hash|nil }
-        #   compaction is { start_seq:, end_seq:, summary_text: } or nil
-        def compress(thread_id:, messages:, seq_offset: 0)
-          estimated = messages.sum { |m| Phronomy::Context::TokenEstimator.estimate(m.content.to_s) }
-
-          if estimated > @max_tokens && messages.length > @keep
-            compact(messages, seq_offset: seq_offset)
-          else
-            {messages: messages, compaction: nil}
-          end
-        rescue => e
-          warn "[Phronomy] Compression failed (#{e.class}: #{e.message}); saving without compaction."
-          {messages: messages, compaction: nil}
-        end
-
-        private
-
-        def compact(messages, seq_offset:)
-          old_count = messages.length - @keep
-          old_messages = messages[0, old_count]
-          recent_messages = messages[old_count..]
-
-          opts = {}
-          opts[:model] = @summarizer_model if @summarizer_model
-          opts[:provider] = @summarizer_provider if @summarizer_provider
-          opts[:assume_model_exists] = true if @summarizer_provider
-          chat = RubyLLM.chat(**opts)
-          summary_text = chat.ask(
-            "Please summarize the following conversation concisely:\n" +
-              old_messages.map { |m| "#{m.role}: #{m.content}" }.join("\n")
-          ).content
-
-          compaction_record = {
-            start_seq: seq_offset,
-            end_seq: seq_offset + old_count - 1,
-            summary_text: summary_text
-          }
-
-          {messages: [summary_message(summary_text)] + recent_messages, compaction: compaction_record}
-        end
-
-        def summary_message(text)
-          content = <<~CONTEXT.chomp
-            <context type="summary" source="memory" trusted="false">
-            #{text}
-            </context>
-          CONTEXT
-          RubyLLM::Message.new(role: :system, content: content)
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/memory/compression/tool_output_pruner.rb

@@ -1,67 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Memory
-    module Compression
-      # Compression strategy that truncates oversized tool-call result messages.
-      #
-      # Large tool outputs — such as a full web-page dump or a massive JSON
-      # response — can consume a significant fraction of the context window.
-      # This compressor truncates the content of any :tool message whose character
-      # count exceeds max_chars, appending a note that the output was truncated.
-      #
-      # Unlike Summary, this is a stateless compressor: it does not accumulate
-      # state across calls and requires no thread_id bookkeeping.
-      #
-      # @example
-      #   compressor = Phronomy::Memory::Compression::ToolOutputPruner.new(max_chars: 4000)
-      #   manager = Phronomy::Memory::ConversationManager.new(
-      #     storage: storage,
-      #     retrieval: retrieval,
-      #     compression: compressor
-      #   )
-      class ToolOutputPruner < Base
-        TRUNCATION_NOTE = "\n[... output truncated ...]"
-
-        # Internal value object for cloned messages.
-        # Uses Struct (not OpenStruct) so that unknown attribute access raises NoMethodError.
-        ClonedMessage = Struct.new(:role, :content, :tool_calls, :model_id, keyword_init: true)
-        private_constant :ClonedMessage
-
-        # @param max_chars [Integer] maximum character length for tool-result content
-        def initialize(max_chars: 4000)
-          @max_chars = max_chars
-        end
-
-        # Truncate oversized :tool messages in-place (non-destructive — returns new array).
-        # Content pruning does not produce a compaction record; :compaction is always nil.
-        #
-        # @param thread_id  [String]  unused (stateless pruner)
-        # @param messages   [Array]
-        # @param seq_offset [Integer] unused
-        # @return [Hash] { messages: Array, compaction: nil }
-        def compress(thread_id:, messages:, seq_offset: 0)
-          pruned = messages.map do |msg|
-            next msg unless msg.role.to_sym == :tool
-            next msg if msg.content.to_s.length <= @max_chars
-
-            truncated = msg.content.to_s[0, @max_chars] + TRUNCATION_NOTE
-            clone_message(msg, truncated)
-          end
-          {messages: pruned, compaction: nil}
-        end
-
-        private
-
-        def clone_message(original, new_content)
-          ClonedMessage.new(
-            role: original.role,
-            content: new_content,
-            tool_calls: (original.tool_calls if original.respond_to?(:tool_calls)),
-            model_id: (original.model_id if original.respond_to?(:model_id))
-          )
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/memory/compression.rb

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Memory
-    # Compression is the reduction axis of conversation management.
-    # Implementations transform a message array into a smaller representation
-    # (e.g. LLM summary, tool-output truncation) before storage or retrieval.
-    module Compression
-    end
-  end
-end

data/lib/phronomy/memory/conversation_manager.rb

@@ -1,213 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Memory
-    # ConversationManager combines the three independent axes of conversation handling:
-    #   - Storage:     where messages are persisted (InMemory, ActiveRecord, ...)
-    #   - Retrieval:   which messages to select (Recent, Semantic, ...)
-    #   - Compression: how to reduce message size before storage (Summary, ToolOutputPruner, ...)
-    #
-    # This is the primary entry point for context region 4 (Conversation) in Agent::Base.
-    #
-    # === Original preservation policy
-    #
-    # All original messages are appended to Storage's raw history with a
-    # monotonically increasing seq number (0-based, per thread). Raw messages
-    # are never modified or deleted.
-    #
-    # When Compression::Summary performs a compaction, a compaction record
-    # { start_seq:, end_seq:, summary_text: } is saved in Storage alongside the
-    # raw messages. This allows callers to reconstruct the full history or audit
-    # which messages were summarised.
-    #
-    # On #load, the message list is reconstructed from raw history + compaction
-    # records: each compacted range is replaced by a single summary system message,
-    # and uncompacted messages are returned verbatim.
-    #
-    # @example Simple recency-based in-memory manager
-    #   manager = Phronomy::Memory::ConversationManager.new(
-    #     storage:   Phronomy::Memory::Storage::InMemory.new,
-    #     retrieval: Phronomy::Memory::Retrieval::Recent.new(k: 10)
-    #   )
-    #
-    # @example With LLM summary compaction
-    #   manager = Phronomy::Memory::ConversationManager.new(
-    #     storage:     Phronomy::Memory::Storage::InMemory.new,
-    #     retrieval:   Phronomy::Memory::Retrieval::Recent.new(k: 5),
-    #     compression: Phronomy::Memory::Compression::Summary.new(max_tokens: 4000)
-    #   )
-    class ConversationManager
-      # @param storage     [Memory::Storage::Base]     persistence backend (required)
-      # @param retrieval   [Memory::Retrieval::Base]   selection strategy (required)
-      # @param compression [Memory::Compression::Base, nil] optional compression strategy
-      # @param ttl         [Integer, nil] message time-to-live in seconds; messages older
-      #                    than this value are removed from storage on each {#load} call.
-      #                    +nil+ disables TTL (default).
-      def initialize(storage:, retrieval:, compression: nil, ttl: nil)
-        @storage = storage
-        @retrieval = retrieval
-        @compression = compression
-        @ttl = ttl
-      end
-
-      # Load conversation messages for a thread, applying retrieval selection.
-      #
-      # When a TTL is configured, raw messages older than the TTL are permanently
-      # removed from storage before reconstruction.
-      #
-      # Reconstructs the message list from raw history + compaction records:
-      #   - Each compacted range [start_seq..end_seq] is replaced by a summary
-      #     system message.
-      #   - Uncompacted messages are returned in original order.
-      #
-      # @param thread_id [String]
-      # @param query     [String, nil] current user input for query-aware retrieval
-      # @return [Array]
-      def load(thread_id:, query: nil)
-        @storage.purge_older_than(thread_id: thread_id, older_than: Time.now - @ttl) if @ttl
-        messages = reconstruct(thread_id)
-        @retrieval.select(messages, query: query, thread_id: thread_id)
-      end
-
-      # Persist new messages for a thread and optionally apply compression.
-      #
-      # New messages are determined by comparing the incoming array length with
-      # the existing raw history length (messages are always append-only).
-      # Only truly new messages (beyond raw.length) are appended to raw storage.
-      #
-      # When a compression strategy is configured, it is evaluated against the
-      # full set of uncompacted raw messages. If compaction fires, the resulting
-      # compaction record is saved in storage (originals are preserved).
-      #
-      # @param thread_id [String]
-      # @param messages  [Array] full conversation history up to this point
-      def save(thread_id:, messages:)
-        @storage.with_thread_lock(thread_id: thread_id) do
-          append_new_messages(thread_id: thread_id, messages: messages)
-          compress_and_save(thread_id: thread_id, messages: messages)
-        end
-        @retrieval.index(thread_id: thread_id, messages: messages) if @retrieval.respond_to?(:index)
-      end
-
-      # Delete all messages (raw, compaction records, and legacy store) for a thread.
-      #
-      # @param thread_id [String]
-      def clear(thread_id:)
-        @storage.clear(thread_id: thread_id)
-        @retrieval.clear_index(thread_id: thread_id) if @retrieval.respond_to?(:clear_index)
-      end
-
-      # Permanently erase all stored data for a thread (right-to-erasure / purge).
-      # Delegates to the storage backend's {Storage::Base#purge} and also clears
-      # any retrieval index for the thread.
-      #
-      # @param thread_id [String]
-      def purge(thread_id:)
-        @storage.purge(thread_id: thread_id)
-        @retrieval.clear_index(thread_id: thread_id) if @retrieval.respond_to?(:clear_index)
-      end
-
-      # Record an application-driven compaction for a thread.
-      # Called by CompactionContext when the on_compact callback invokes ctx.compact.
-      #
-      # @param thread_id   [String]
-      # @param start_seq   [Integer] first seq number in the compacted range
-      # @param end_seq     [Integer] last seq number in the compacted range
-      # @param summary_text [String] replacement text for the compacted messages
-      def save_compaction(thread_id:, start_seq:, end_seq:, summary_text:)
-        @storage.save_compaction(
-          thread_id: thread_id,
-          start_seq: start_seq,
-          end_seq: end_seq,
-          summary_text: summary_text
-        )
-      end
-
-      private
-
-      # Append messages that are new since the last save to the raw history.
-      # Must be called while holding the per-thread lock (via Storage#with_thread_lock).
-      # Messages are append-only; existing raw entries are never modified.
-      #
-      # The next seq number is derived from Storage#next_seq, which owns the
-      # high-water-mark counter. This survives TTL purges because Storage tracks
-      # the HWM independently of the stored raw entries.
-      def append_new_messages(thread_id:, messages:)
-        next_seq = @storage.next_seq(thread_id: thread_id)
-        new_messages = messages[next_seq..]
-        @storage.append_raw(thread_id: thread_id, messages: new_messages, starting_seq: next_seq) if new_messages&.any?
-      end
-
-      # Apply the configured compression strategy and persist the result.
-      # When no strategy is configured, saves messages directly to the legacy store.
-      # When compression fires, also persists the compaction record.
-      # If the compression strategy raises (e.g. LLM timeout), we fall back to
-      # saving the messages without compaction so the conversation is never lost
-      # due to a transient summarization failure (Issue #58).
-      def compress_and_save(thread_id:, messages:)
-        unless @compression
-          @storage.save(thread_id: thread_id, messages: messages)
-          return
-        end
-
-        compactions = @storage.load_compactions(thread_id: thread_id)
-        uncompacted_start_seq = compactions.any? ? compactions.last[:end_seq] + 1 : 0
-        all_raw = @storage.load_raw(thread_id: thread_id)
-        uncompacted = all_raw.select { |r| r[:seq] >= uncompacted_start_seq }.map { |r| r[:message] }
-
-        result = begin
-          @compression.compress(
-            thread_id: thread_id,
-            messages: uncompacted,
-            seq_offset: uncompacted_start_seq
-          )
-        rescue => e
-          warn "[Phronomy] Compression failed (#{e.class}: #{e.message}); saving without compaction."
-          {messages: messages, compaction: nil}
-        end
-
-        if result[:compaction]
-          @storage.save_compaction(
-            thread_id: thread_id,
-            start_seq: result[:compaction][:start_seq],
-            end_seq: result[:compaction][:end_seq],
-            summary_text: result[:compaction][:summary_text]
-          )
-        end
-
-        # For non-Summary compressors (ToolOutputPruner), store the pruned
-        # version in the legacy store so legacy #load still works.
-        @storage.save(thread_id: thread_id, messages: result[:messages])
-      end
-
-      # Reconstruct context-ready messages from raw history + compaction records.
-      # When no compaction records exist (no Summary compaction has fired), we
-      # return the legacy store directly — this preserves the effect of content
-      # pruners like ToolOutputPruner, whose pruned messages are saved there.
-      # When compaction records exist, we rebuild the context from raw history:
-      # each compacted seq range is replaced by a single summary system message.
-      def reconstruct(thread_id)
-        compactions = @storage.load_compactions(thread_id: thread_id)
-        return @storage.load(thread_id: thread_id) if compactions.empty?
-
-        raw = @storage.load_raw(thread_id: thread_id)
-        last_compacted_seq = compactions.last[:end_seq]
-        summary_msgs = compactions.map { |c| summary_message(c[:summary_text]) }
-        uncompacted = raw.select { |r| r[:seq] > last_compacted_seq }.map { |r| r[:message] }
-        summary_msgs + uncompacted
-      end
-
-      # Immutable value object used as a summary placeholder in reconstructed context.
-      SummaryMessage = Data.define(:role, :content)
-
-      def summary_message(text)
-        content = <<~CONTEXT.chomp
-          <context type="summary" source="memory" trusted="false">
-          #{text}
-          </context>
-        CONTEXT
-        SummaryMessage.new(role: :system, content: content)
-      end
-    end
-  end
-end

data/lib/phronomy/memory/retrieval/base.rb

@@ -1,22 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Memory
-    module Retrieval
-      # Abstract base class for conversation retrieval strategies.
-      #
-      # @abstract Subclass and implement #select.
-      class Base
-        # Select messages to inject into the context from a full chronological history.
-        #
-        # @param messages  [Array]        full history in chronological order
-        # @param query     [String, nil]  current user input for query-aware retrieval
-        # @param thread_id [String, nil]  active thread identifier for scoped retrieval
-        # @return [Array] subset of messages in chronological order
-        def select(messages, query: nil, thread_id: nil)
-          raise NotImplementedError, "#{self.class}#select is not implemented"
-        end
-      end
-    end
-  end
-end