phronomy 0.2.2 → 0.4.0

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

@@ -1,76 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Memory
-    module Retrieval
-      # Retrieval strategy that merges results from multiple child retrieval strategies.
-      #
-      # Each child is given a weight that controls what fraction of a token budget
-      # it should consume. Results are deduplicated (by role + content) and
-      # system messages are sorted to the front.
-      #
-      # @example
-      #   composite = Phronomy::Memory::Retrieval::Composite.new(
-      #     sources: [
-      #       { retrieval: Phronomy::Memory::Retrieval::Recent.new(k: 5),    weight: 0.4 },
-      #       { retrieval: Phronomy::Memory::Retrieval::Semantic.new(...),   weight: 0.6 }
-      #     ]
-      #   )
-      #   manager = Phronomy::Memory::ConversationManager.new(
-      #     storage:   Phronomy::Memory::Storage::InMemory.new,
-      #     retrieval: composite
-      #   )
-      class Composite < Base
-        # @param sources [Array<Hash>] each entry: { retrieval:, weight: } (weight default 1.0)
-        def initialize(sources:)
-          @sources = sources.map { |s| {retrieval: s[:retrieval], weight: (s[:weight] || 1.0).to_f} }
-        end
-
-        # Merge results from all child retrievals, deduplicating by role+content.
-        # System messages are sorted to the front; others preserve insertion order.
-        #
-        # @param messages  [Array]        full chronological history
-        # @param query     [String, nil]  forwarded to each child retrieval
-        # @param thread_id [String, nil]  forwarded to each child retrieval
-        # @return [Array]
-        def select(messages, query: nil, thread_id: nil)
-          all_messages = []
-          seen = {}
-
-          @sources.each do |source|
-            source[:retrieval].select(messages, query: query, thread_id: thread_id).each do |msg|
-              key = "#{msg.role}:#{msg.content}"
-              next if seen[key]
-
-              seen[key] = true
-              all_messages << msg
-            end
-          end
-
-          systems = all_messages.select { |m| m.role.to_sym == :system }
-          others = all_messages.reject { |m| m.role.to_sym == :system }
-          systems + others
-        end
-
-        # Forward index calls to all child retrievals that support it.
-        #
-        # @param thread_id [String]
-        # @param messages  [Array]
-        def index(thread_id:, messages:)
-          @sources.each do |source|
-            source[:retrieval].index(thread_id: thread_id, messages: messages) if source[:retrieval].respond_to?(:index)
-          end
-        end
-
-        # Forward clear_index to all child retrievals that support it.
-        #
-        # @param thread_id [String]
-        def clear_index(thread_id:)
-          @sources.each do |source|
-            source[:retrieval].clear_index(thread_id: thread_id) if source[:retrieval].respond_to?(:clear_index)
-          end
-        end
-      end
-    end
-  end
-end

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

@@ -1,35 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Memory
-    module Retrieval
-      # Retrieval strategy that returns the most recent k turns (k*2 messages).
-      #
-      # This is the simplest and most predictable strategy: older messages are
-      # discarded without compression.
-      #
-      # @example
-      #   retrieval = Phronomy::Memory::Retrieval::Recent.new(k: 10)
-      #   manager = Phronomy::Memory::ConversationManager.new(
-      #     storage: storage,
-      #     retrieval: retrieval
-      #   )
-      class Recent < Base
-        # @param k [Integer] number of turns to retain (each turn = 1 user + 1 assistant message)
-        def initialize(k: 10)
-          @k = k
-        end
-
-        # Returns the last k*2 messages from the history.
-        #
-        # @param messages  [Array]        full chronological history
-        # @param query     [String, nil]  unused for recency-based retrieval
-        # @param thread_id [String, nil]  unused for recency-based retrieval
-        # @return [Array]
-        def select(messages, query: nil, thread_id: nil)
-          messages.last(@k * 2)
-        end
-      end
-    end
-  end
-end

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

@@ -1,114 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Memory
-    module Retrieval
-      # Retrieval strategy that returns the k semantically closest messages to the query.
-      #
-      # Messages are indexed in a VectorStore on save. On retrieval, the query is
-      # embedded and the k nearest messages are returned. Falls back to the k most
-      # recent messages when no query is provided.
-      #
-      # @example
-      #   retrieval = Phronomy::Memory::Retrieval::Semantic.new(
-      #     embeddings: Phronomy::Embeddings::RubyLLMEmbeddings.new(model: "text-embedding-3-small"),
-      #     k: 10
-      #   )
-      class Semantic < Base
-        # @param store      [Phronomy::VectorStore::Base]  vector store (default InMemory)
-        # @param embeddings [Phronomy::Embeddings::Base]   embeddings adapter
-        # @param k          [Integer]                      number of messages to retrieve
-        # @param max_index_size [Integer, nil] maximum number of entries kept in the
-        #   local index. When nil, the index grows unboundedly. When exceeded, the
-        #   oldest entries (by insertion order) are evicted.
-        def initialize(embeddings:, store: nil, k: 10, max_index_size: nil)
-          @store = store || Phronomy::VectorStore::InMemory.new
-          @embeddings = embeddings
-          @k = k
-          @index = {}   # id => message  (insertion-ordered via Ruby Hash)
-          @counter = 0
-          @max_index_size = max_index_size
-          @actor = Phronomy::Actor.new
-          @indexed_object_ids = {}  # thread_id => { object_id => true }
-        end
-
-        # Index a new batch of messages so they are searchable on future #select calls.
-        # Called by ConversationManager#save.
-        #
-        # Messages are deduplicated by object identity: if a message object has already
-        # been indexed for the given thread_id, it is skipped (no duplicate embed call).
-        #
-        # @param thread_id [String]
-        # @param messages  [Array]
-        def index(thread_id:, messages:)
-          messages.each do |msg|
-            # Fast path: skip already-indexed messages without calling embed.
-            already_indexed = @actor.call do
-              (@indexed_object_ids[thread_id] ||= {})[msg.object_id]
-            end
-            next if already_indexed
-
-            embedding = @embeddings.embed(msg.content.to_s)
-            @actor.call do
-              # Re-check inside Actor to handle concurrent callers for the same thread.
-              indexed = (@indexed_object_ids[thread_id] ||= {})
-              next if indexed[msg.object_id]
-
-              id = "#{thread_id}:#{@counter}"
-              @counter += 1
-              @store.add(id: id, embedding: embedding, metadata: {thread_id: thread_id, message: msg})
-              @index[id] = msg
-              indexed[msg.object_id] = true
-              evict_oldest! if @max_index_size && @index.size > @max_index_size
-            end
-          end
-        end
-
-        # Clear indexed messages for a thread.
-        #
-        # @param thread_id [String]
-        def clear_index(thread_id:)
-          @actor.call do
-            ids = @index.keys.select { |id| id.start_with?("#{thread_id}:") }
-            ids.each do |id|
-              @index.delete(id)
-              @store.remove(id: id)
-            end
-            @indexed_object_ids.delete(thread_id)
-          end
-        end
-
-        # Return semantically relevant messages, or recent messages when query is nil.
-        #
-        # @param messages   [Array]        full history (used as fallback when query is nil)
-        # @param query      [String, nil]  current user input for semantic search
-        # @param thread_id  [String, nil]  when provided, results are filtered to this thread
-        # @return [Array]
-        def select(messages, query: nil, thread_id: nil)
-          if query && !query.strip.empty?
-            query_embedding = @embeddings.embed(query)
-            results = @actor.call { @store.search(query_embedding: query_embedding, k: @k * 3) }
-            results
-              .select { |r| thread_id.nil? || r[:metadata][:thread_id] == thread_id }
-              .first(@k)
-              .map { |r| r[:metadata][:message] }
-          else
-            messages.last(@k)
-          end
-        end
-
-        private
-
-        # Evicts the oldest index entry to enforce max_index_size.
-        # Must be called inside the Actor.
-        def evict_oldest!
-          oldest_id = @index.keys.first
-          return unless oldest_id
-
-          @index.delete(oldest_id)
-          @store.remove(id: oldest_id)
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/memory/retrieval.rb

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Memory
-    # Retrieval is the selection axis of conversation management.
-    # Implementations decide which messages from a full history to return
-    # given a query and a maximum message count or token limit.
-    # Token budgeting is NOT their responsibility — that belongs to Context::Assembler.
-    module Retrieval
-    end
-  end
-end

data/lib/phronomy/memory/storage/active_record.rb

@@ -1,248 +0,0 @@
-# frozen_string_literal: true
-
-require "json"
-
-module Phronomy
-  module Memory
-    module Storage
-      # ActiveRecord-backed storage for conversation messages.
-      # Persists messages to a relational database via user-supplied AR model classes.
-      #
-      # The message model_class must respond to:
-      #   .where(thread_id:).order(:created_at) — returns a collection of records
-      #   .where(thread_id:).delete_all
-      #   .create!(thread_id:, role:, content:, tool_calls_json:, model_id:)
-      # Each record must expose: #role, #content, #tool_calls_json, #model_id
-      #
-      # The raw_model_class (optional) must respond to:
-      #   .where(thread_id:).order(:seq) — returns records in seq order
-      #   .where(thread_id:).delete_all
-      #   .create!(thread_id:, seq:, role:, content:, tool_calls_json:, model_id:)
-      # Each record must expose: #seq, #role, #content, #tool_calls_json, #model_id
-      #
-      # The compaction_model_class (optional) must respond to:
-      #   .where(thread_id:).order(:start_seq)
-      #   .where(thread_id:).delete_all
-      #   .create!(thread_id:, start_seq:, end_seq:, summary_text:)
-      # Each record must expose: #start_seq, #end_seq, #summary_text
-      #
-      # When raw_model_class or compaction_model_class are nil, the corresponding
-      # operations raise NotImplementedError — use InMemory storage if you do not
-      # need full raw/compaction persistence.
-      #
-      # @example
-      #   storage = Phronomy::Memory::Storage::ActiveRecord.new(
-      #     model_class:            PhronomyMessage,
-      #     raw_model_class:        PhronomyRawMessage,
-      #     compaction_model_class: PhronomyCompaction
-      #   )
-      #   manager = Phronomy::Memory::ConversationManager.new(storage: storage, ...)
-      # Internal value object representing a loaded message record.
-      MessageStruct = Data.define(:role, :content, :tool_calls, :model_id)
-      private_constant :MessageStruct
-
-      class ActiveRecord < Base
-        # @param model_class            [Class]      AR model for the legacy load/save interface
-        # @param raw_model_class        [Class, nil] AR model for raw message storage
-        # @param compaction_model_class [Class, nil] AR model for compaction records
-        def initialize(model_class:, raw_model_class: nil, compaction_model_class: nil)
-          @model_class = model_class
-          @raw_model_class = raw_model_class
-          @compaction_model_class = compaction_model_class
-        end
-
-        # -----------------------------------------------------------------------
-        # Legacy interface
-        # -----------------------------------------------------------------------
-
-        # Load all messages for a thread, ordered by creation time.
-        #
-        # @param thread_id [String]
-        # @return [Array<MessageStruct>]
-        def load(thread_id:)
-          records = @model_class.where(thread_id: thread_id).order(:created_at).to_a
-          records.map { |r| to_message_struct(r) }
-        end
-
-        # Replace all stored messages for a thread.
-        #
-        # @param thread_id [String]
-        # @param messages  [Array]
-        def save(thread_id:, messages:)
-          @model_class.transaction do
-            @model_class.where(thread_id: thread_id).delete_all
-            messages.each do |msg|
-              @model_class.create!(
-                thread_id: thread_id,
-                role: msg.role.to_s,
-                content: msg.content,
-                tool_calls_json: serialize_tool_calls(msg),
-                model_id: (msg.model_id if msg.respond_to?(:model_id))
-              )
-            end
-          end
-        end
-
-        # @param thread_id [String]
-        def clear(thread_id:)
-          @model_class.where(thread_id: thread_id).delete_all
-          clear_raw(thread_id: thread_id)
-          clear_compactions(thread_id: thread_id)
-        end
-
-        # -----------------------------------------------------------------------
-        # Raw message interface
-        # -----------------------------------------------------------------------
-
-        # @param thread_id    [String]
-        # @param messages     [Array]
-        # @param starting_seq [Integer]
-        def append_raw(thread_id:, messages:, starting_seq:)
-          return unless @raw_model_class
-
-          @raw_model_class.transaction do
-            messages.each_with_index do |msg, i|
-              @raw_model_class.create!(
-                thread_id: thread_id,
-                seq: starting_seq + i,
-                role: msg.role.to_s,
-                content: msg.content,
-                tool_calls_json: serialize_tool_calls(msg),
-                model_id: (msg.model_id if msg.respond_to?(:model_id))
-              )
-            end
-          end
-        end
-
-        # @param thread_id [String]
-        # @return [Array<Hash>]
-        def load_raw(thread_id:)
-          return [] unless @raw_model_class
-
-          records = @raw_model_class.where(thread_id: thread_id).order(:seq).to_a
-          records.map { |r| {seq: r.seq, message: to_message_struct(r)} }
-        end
-
-        # @param thread_id [String]
-        def clear_raw(thread_id:)
-          @raw_model_class&.where(thread_id: thread_id)&.delete_all
-        end
-
-        # -----------------------------------------------------------------------
-        # Compaction record interface
-        # -----------------------------------------------------------------------
-
-        # @param thread_id    [String]
-        # @param start_seq    [Integer]
-        # @param end_seq      [Integer]
-        # @param summary_text [String]
-        def save_compaction(thread_id:, start_seq:, end_seq:, summary_text:)
-          ensure_compaction_model!
-          @compaction_model_class.create!(
-            thread_id: thread_id,
-            start_seq: start_seq,
-            end_seq: end_seq,
-            summary_text: summary_text
-          )
-        end
-
-        # @param thread_id [String]
-        # @return [Array<Hash>]
-        def load_compactions(thread_id:)
-          return [] unless @compaction_model_class
-
-          records = @compaction_model_class.where(thread_id: thread_id).order(:start_seq).to_a
-          records.map { |r| {start_seq: r.start_seq, end_seq: r.end_seq, summary_text: r.summary_text} }
-        end
-
-        # @param thread_id [String]
-        def clear_compactions(thread_id:)
-          @compaction_model_class&.where(thread_id: thread_id)&.delete_all
-        end
-
-        # Remove messages for a thread that were created before +older_than+.
-        # Only the legacy message store is filtered; raw and compaction records
-        # are left untouched because they use seq-based addressing.
-        #
-        # @param thread_id  [String]
-        # @param older_than [Time]
-        def purge_older_than(thread_id:, older_than:)
-          @model_class.where(thread_id: thread_id).where("created_at < ?", older_than).delete_all
-        end
-
-        # Returns the next seq number to use for new raw messages for +thread_id+.
-        # Derived from MAX(seq) in the database; since purge_older_than does not
-        # touch raw records, this value is always correct.
-        #
-        # @param thread_id [String]
-        # @return [Integer]
-        def next_seq(thread_id:)
-          return 0 unless @raw_model_class
-
-          ((@raw_model_class.where(thread_id: thread_id).maximum(:seq) || -1) + 1)
-        end
-
-        # Delegates to the block directly; serialisation of concurrent saves
-        # for the same thread_id is the caller's responsibility (e.g. DB-level
-        # transaction isolation or application-layer queuing).
-        # @param thread_id [String]
-        def with_thread_lock(thread_id:)
-          yield
-        end
-
-        private
-
-        def ensure_raw_model!
-          raise NotImplementedError, "raw_model_class is required for raw message storage" unless @raw_model_class
-        end
-
-        def ensure_compaction_model!
-          raise NotImplementedError, "compaction_model_class is required for compaction record storage" unless @compaction_model_class
-        end
-
-        def serialize_tool_calls(msg)
-          return unless msg.respond_to?(:tool_calls) && msg.tool_calls
-
-          serializable = case msg.tool_calls
-          when Hash
-            msg.tool_calls.transform_values { |tc| tc.respond_to?(:to_h) ? tc.to_h : tc }
-          when Array
-            msg.tool_calls.map { |tc| tc.respond_to?(:to_h) ? tc.to_h : tc }
-          else
-            msg.tool_calls
-          end
-          JSON.generate(serializable)
-        end
-
-        def to_message_struct(record)
-          tool_calls = if record.tool_calls_json
-            parsed = JSON.parse(record.tool_calls_json)
-            case parsed
-            when Hash
-              parsed.transform_values { |tc| restore_tool_call(tc) }
-            when Array
-              parsed.map { |tc| restore_tool_call(tc) }
-            else
-              parsed
-            end
-          end
-          MessageStruct.new(
-            role: record.role.to_sym,
-            content: record.content,
-            tool_calls: tool_calls,
-            model_id: record.respond_to?(:model_id) ? record.model_id : nil
-          )
-        end
-
-        def restore_tool_call(tc)
-          return tc unless tc.is_a?(Hash) && tc["id"] && tc["name"]
-          RubyLLM::ToolCall.new(
-            id: tc["id"],
-            name: tc["name"],
-            arguments: tc["arguments"] || {}
-          )
-        end
-      end
-    end
-  end
-end

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

@@ -1,155 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Memory
-    module Storage
-      # Abstract base class for conversation storage backends.
-      #
-      # Each backend manages two independent datasets per thread:
-      #
-      #   1. Raw messages  — the original, unmodified conversation history.
-      #      Every message is stored with a monotonically increasing seq number
-      #      (0-based, scoped to thread_id). Raw messages are never modified or
-      #      deleted; they are the authoritative record.
-      #
-      #   2. Compaction records — the output of LLM-based compaction (summarization).
-      #      Each record covers a contiguous range [start_seq..end_seq] of raw
-      #      messages and stores the summary text produced for that range.
-      #      Multiple non-overlapping compaction records may exist per thread.
-      #
-      # The conventional load/save/clear interface is kept for use by
-      # ConversationManager (compression path) and direct storage access.
-      #
-      # @abstract Subclass and implement all abstract methods.
-      class Base
-        # -----------------------------------------------------------------------
-        # Conventional load/save/clear interface
-        # -----------------------------------------------------------------------
-
-        # Load all messages for a thread in chronological order.
-        #
-        # @param thread_id [String]
-        # @return [Array]
-        def load(thread_id:)
-          raise NotImplementedError, "#{self.class}#load is not implemented"
-        end
-
-        # Persist messages for a thread (replaces existing messages).
-        #
-        # @param thread_id [String]
-        # @param messages  [Array]
-        def save(thread_id:, messages:)
-          raise NotImplementedError, "#{self.class}#save is not implemented"
-        end
-
-        # Delete all messages for a thread.
-        #
-        # @param thread_id [String]
-        def clear(thread_id:)
-          raise NotImplementedError, "#{self.class}#clear is not implemented"
-        end
-
-        # -----------------------------------------------------------------------
-        # Raw message interface
-        # -----------------------------------------------------------------------
-
-        # Append new messages to the raw history for a thread.
-        # Each message is stored together with its seq number.
-        #
-        # @param thread_id    [String]
-        # @param messages     [Array]  message objects to append
-        # @param starting_seq [Integer] seq number to assign to messages[0]
-        def append_raw(thread_id:, messages:, starting_seq:)
-          raise NotImplementedError, "#{self.class}#append_raw is not implemented"
-        end
-
-        # Return all raw messages for a thread as an array of hashes.
-        #
-        # @param thread_id [String]
-        # @return [Array<Hash>] each entry: { seq: Integer, message: Object }
-        def load_raw(thread_id:)
-          raise NotImplementedError, "#{self.class}#load_raw is not implemented"
-        end
-
-        # Delete raw messages for a thread (used in #clear).
-        #
-        # @param thread_id [String]
-        def clear_raw(thread_id:)
-          raise NotImplementedError, "#{self.class}#clear_raw is not implemented"
-        end
-
-        # -----------------------------------------------------------------------
-        # Compaction record interface
-        # -----------------------------------------------------------------------
-
-        # Persist a compaction record for a thread.
-        # A compaction record stores the LLM-generated summary that covers raw
-        # messages from start_seq to end_seq (inclusive).
-        #
-        # @param thread_id    [String]
-        # @param start_seq    [Integer]
-        # @param end_seq      [Integer]
-        # @param summary_text [String]
-        def save_compaction(thread_id:, start_seq:, end_seq:, summary_text:)
-          raise NotImplementedError, "#{self.class}#save_compaction is not implemented"
-        end
-
-        # Return all compaction records for a thread in ascending start_seq order.
-        #
-        # @param thread_id [String]
-        # @return [Array<Hash>] each entry: { start_seq:, end_seq:, summary_text: }
-        def load_compactions(thread_id:)
-          raise NotImplementedError, "#{self.class}#load_compactions is not implemented"
-        end
-
-        # Delete all compaction records for a thread.
-        #
-        # @param thread_id [String]
-        def clear_compactions(thread_id:)
-          raise NotImplementedError, "#{self.class}#clear_compactions is not implemented"
-        end
-
-        # Remove all stored data (raw messages, compaction records, legacy store)
-        # for a thread. Equivalent to {#clear}, provided as a named alias to make
-        # the "right to erasure" intent explicit.
-        #
-        # @param thread_id [String]
-        def purge(thread_id:)
-          clear(thread_id: thread_id)
-        end
-
-        # Remove raw messages recorded before +older_than+ for a thread.
-        # The default implementation is a no-op; backends that support
-        # timestamp-based deletion should override this method.
-        #
-        # @param thread_id  [String]
-        # @param older_than [Time]
-        def purge_older_than(thread_id:, older_than:)
-          # no-op by default
-        end
-
-        # Returns the next seq number to assign when appending new raw messages
-        # for +thread_id+. Must be monotonically increasing and must survive
-        # purge_older_than (i.e. the counter must not reset when old raw records
-        # are deleted by a TTL purge).
-        #
-        # @param thread_id [String]
-        # @return [Integer]
-        def next_seq(thread_id:)
-          raise NotImplementedError, "#{self.class}#next_seq is not implemented"
-        end
-
-        # Executes the block while holding a per-thread-id lock for +thread_id+.
-        # Used by ConversationManager to prevent concurrent compaction for the
-        # same thread. The default implementation yields without locking; backends
-        # that require serialisation should override this method.
-        #
-        # @param thread_id [String]
-        # @yield
-        def with_thread_lock(thread_id:)
-          yield
-        end
-      end
-    end
-  end
-end