phronomy 0.2.2 → 0.3.0

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

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

@@ -1,152 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Memory
-    module Storage
-      # In-process storage for conversation messages backed by per-thread-id
-      # {Phronomy::Actor} instances from {Phronomy::ThreadActorRegistry}.
-      # Messages are lost when the process exits.
-      #
-      # @example
-      #   storage = Phronomy::Memory::Storage::InMemory.new
-      #   manager = Phronomy::Memory::ConversationManager.new(storage: storage, ...)
-      class InMemory < Base
-        # Thread-local key for per-thread-id storage data (namespaced by store
-        # instance object_id to support multiple independent InMemory stores).
-        THREAD_DATA_KEY = :phronomy_storage_in_memory_data
-
-        def initialize
-        end
-
-        # -----------------------------------------------------------------------
-        # Legacy interface
-        # -----------------------------------------------------------------------
-
-        # @param thread_id [String]
-        # @return [Array]
-        def load(thread_id:)
-          Phronomy::ThreadActorRegistry.for(thread_id).call { (thread_data.store || []).dup }
-        end
-
-        # @param thread_id [String]
-        # @param messages  [Array]
-        def save(thread_id:, messages:)
-          Phronomy::ThreadActorRegistry.for(thread_id).call { thread_data.store = messages.dup }
-        end
-
-        # @param thread_id [String]
-        def clear(thread_id:)
-          store_id = object_id
-          Phronomy::ThreadActorRegistry.for(thread_id).call do
-            (Thread.current[THREAD_DATA_KEY] ||= {}).delete(store_id)
-          end
-        end
-
-        # -----------------------------------------------------------------------
-        # Raw message interface
-        # -----------------------------------------------------------------------
-
-        # @param thread_id    [String]
-        # @param messages     [Array]
-        # @param starting_seq [Integer]
-        # @param recorded_at  [Time, nil] timestamp for test overrides; defaults to +Time.now+
-        def append_raw(thread_id:, messages:, starting_seq:, recorded_at: nil)
-          now = recorded_at || Time.now
-          Phronomy::ThreadActorRegistry.for(thread_id).call do
-            data = thread_data
-            messages.each_with_index do |msg, i|
-              seq = starting_seq + i
-              data.raw_messages << {seq: seq, message: msg, recorded_at: now}
-              data.hwm = [data.hwm, seq].max
-            end
-          end
-        end
-
-        # @param thread_id [String]
-        # @return [Integer]
-        def next_seq(thread_id:)
-          Phronomy::ThreadActorRegistry.for(thread_id).call { thread_data.hwm + 1 }
-        end
-
-        # Routes +block+ through the per-thread-id {Phronomy::Actor}, serialising
-        # all operations for the same thread.  Reentrant calls (the block itself
-        # calling storage methods that also route through the Actor) are safe
-        # because {Phronomy::Actor#call} detects the same-thread case and executes
-        # inline.
-        #
-        # @param thread_id [String]
-        def with_thread_lock(thread_id:, &block)
-          Phronomy::ThreadActorRegistry.for(thread_id).call(&block)
-        end
-
-        # @param thread_id [String]
-        # @return [Array<Hash>]
-        def load_raw(thread_id:)
-          Phronomy::ThreadActorRegistry.for(thread_id).call { thread_data.raw_messages.dup }
-        end
-
-        # @param thread_id [String]
-        def clear_raw(thread_id:)
-          Phronomy::ThreadActorRegistry.for(thread_id).call { thread_data.raw_messages.clear }
-        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:)
-          Phronomy::ThreadActorRegistry.for(thread_id).call do
-            thread_data.compactions << {start_seq: start_seq, end_seq: end_seq, summary_text: summary_text}
-          end
-        end
-
-        # @param thread_id [String]
-        # @return [Array<Hash>]
-        def load_compactions(thread_id:)
-          Phronomy::ThreadActorRegistry.for(thread_id).call { thread_data.compactions.dup }
-        end
-
-        # @param thread_id [String]
-        def clear_compactions(thread_id:)
-          Phronomy::ThreadActorRegistry.for(thread_id).call { thread_data.compactions.clear }
-        end
-
-        # Remove raw messages recorded before +older_than+ for this thread.
-        #
-        # @param thread_id  [String]
-        # @param older_than [Time]
-        def purge_older_than(thread_id:, older_than:)
-          Phronomy::ThreadActorRegistry.for(thread_id).call do
-            thread_data.raw_messages.reject! { |entry| entry[:recorded_at] && entry[:recorded_at] < older_than }
-          end
-        end
-
-        private
-
-        # Returns (or lazily initialises) the {ThreadData} for the current Actor
-        # thread and this storage instance.  Must only be called from within a
-        # {Phronomy::ThreadActorRegistry.for} block so that +Thread.current+ is
-        # the correct Actor thread.
-        def thread_data
-          (Thread.current[THREAD_DATA_KEY] ||= {})[object_id] ||= ThreadData.new
-        end
-
-        # Value object holding all per-thread-id storage state.
-        class ThreadData
-          attr_accessor :store, :raw_messages, :compactions, :hwm
-
-          def initialize
-            @store = nil
-            @raw_messages = []
-            @compactions = []
-            @hwm = -1
-          end
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/memory/storage.rb

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Memory
-    # Storage is the persistence axis of conversation management.
-    # Implementations are responsible only for saving and loading raw message arrays.
-    # Token budgeting, retrieval selection, and compression are handled by other axes.
-    module Storage
-    end
-  end
-end

data/lib/phronomy/memory.rb

@@ -1,21 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Memory
-  end
-end
-
-require_relative "memory/storage"
-require_relative "memory/storage/base"
-require_relative "memory/storage/in_memory"
-require_relative "memory/storage/active_record"
-require_relative "memory/retrieval"
-require_relative "memory/retrieval/base"
-require_relative "memory/retrieval/recent"
-require_relative "memory/retrieval/semantic"
-require_relative "memory/retrieval/composite"
-require_relative "memory/compression"
-require_relative "memory/compression/base"
-require_relative "memory/compression/summary"
-require_relative "memory/compression/tool_output_pruner"
-require_relative "memory/conversation_manager"

data/lib/phronomy/rails/agent_job.rb

@@ -1,75 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Rails
-    # ActiveJob-based job that runs a Phronomy agent in streaming mode and
-    # broadcasts each event to an ActionCable stream.
-    #
-    # Enqueue with +perform_later+ to run the agent asynchronously in a background
-    # worker. Every streaming event is forwarded to ActionCable subscribers in
-    # real time.
-    #
-    # @example Enqueueing a streaming agent job
-    #   Phronomy::Rails::AgentJob.perform_later(
-    #     "MyAgent",
-    #     "What is the weather today?",
-    #     channel: "AgentChannel",
-    #     stream: "agent_#{current_user.id}"
-    #   )
-    #
-    # Events broadcast to the ActionCable stream:
-    #   { type: "token",   content: "..." }  — each content delta from the LLM
-    #   { type: "done",    output:  "..." }  — final complete output
-    #   { type: "error",   message: "..." }  — when the agent or job raises
-    #
-    class AgentJob < ::ActiveJob::Base
-      # @param agent_class_name [String]
-      #   The constantize-able class name of the agent to run (e.g. "MyAgent").
-      #   **Security**: only classes that are subclasses of +Phronomy::Agent::Base+
-      #   are accepted. Never pass a value derived from user-controlled input.
-      # @param input [String, Hash]
-      #   User input forwarded unchanged to the agent's +#stream+ method.
-      # @param channel [String]
-      #   ActionCable channel name. Retained for documentation / future routing.
-      # @param stream [String]
-      #   ActionCable stream identifier passed to +ActionCable.server.broadcast+.
-      # @param config [Hash]
-      #   Configuration forwarded to the agent's +#stream+ call. Both symbol and
-      #   string keys are accepted; all keys are converted to symbols before use.
-      def perform(agent_class_name, input, channel:, stream:, config: {})
-        klass = resolve_agent_class!(agent_class_name)
-        agent = klass.new
-        agent.stream(input, config: config.transform_keys(&:to_sym)) do |event|
-          ActionCable.server.broadcast(stream, build_payload(event))
-        end
-      rescue => e
-        ::Rails.logger.error("[Phronomy::Rails::AgentJob] agent error (#{e.class}): #{e.message}")
-        ActionCable.server.broadcast(stream, {type: "error", message: "An error occurred while processing your request."})
-      end
-
-      private
-
-      # Resolves and validates the agent class name.
-      # Raises ArgumentError when the name does not resolve to a subclass of
-      # Phronomy::Agent::Base, preventing arbitrary class instantiation.
-      def resolve_agent_class!(class_name)
-        klass = Object.const_get(class_name.to_s)
-        unless klass.is_a?(Class) && klass < Phronomy::Agent::Base
-          raise ArgumentError, "#{class_name.inspect} is not a Phronomy::Agent::Base subclass"
-        end
-        klass
-      rescue NameError
-        raise ArgumentError, "Unknown agent class: #{class_name.inspect}"
-      end
-
-      def build_payload(event)
-        case event.type
-        when :token then {type: "token", content: event.payload[:content]}
-        when :done then {type: "done", output: event.payload[:output]}
-        when :error then {type: "error", message: "An error occurred while processing your request."}
-        else {type: event.type.to_s}
-        end
-      end
-    end
-  end
-end