swarm_sdk 2.7.14 → 3.0.0.alpha1

data/lib/swarm_sdk/v3/memory/compressor.rb

@@ -0,0 +1,496 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module V3
+    module Memory
+      # Compression ladder for memory cards
+      #
+      # Demotes low-exposure cards through compression levels:
+      # - L0: Raw (original text)
+      # - L1: Faithful summary
+      # - L2: Sparse bullets
+      # - L3: Schema-only (entities + type)
+      # - L4: Embedding + title only
+      #
+      # Also supports **promotion**: when a compressed card (L1-L4) is
+      # accessed frequently, it gets promoted one level up by rebuilding
+      # a richer summary from its graph neighbors and cluster context.
+      #
+      # Uses LLM for L0→L1 and L1→L2 transitions. L3 and L4 are
+      # mechanical transformations that don't require LLM calls.
+      #
+      # @example Compress
+      #   compressor = Compressor.new(adapter: adapter, chat: llm_chat)
+      #   compressor.compress_card(card)  # Advances one level
+      #
+      # @example Promote
+      #   compressor.promote_card(card)   # Moves one level up if eligible
+      class Compressor
+        # Maximum cards per LLM call to stay within token limits
+        BATCH_SIZE = 20
+
+        # @param adapter [Adapters::Base] Storage adapter
+        # @param chat [RubyLLM::Chat, nil] LLM chat for summarization (nil = skip LLM steps)
+        def initialize(adapter:, chat: nil)
+          @adapter = adapter
+          @chat = chat
+        end
+
+        # Compress a card one level down the ladder
+        #
+        # @param card [Card] Card to compress
+        # @return [Card] Updated card (also persisted to adapter)
+        def compress_card(card)
+          case card.compression_level
+          when 0 then compress_l0_to_l1(card)
+          when 1 then compress_l1_to_l2(card)
+          when 2 then compress_l2_to_l3(card)
+          when 3 then compress_l3_to_l4(card)
+          else card # Already at max compression
+          end
+        end
+
+        # Compress all low-exposure cards using batched LLM calls
+        #
+        # Groups cards by compression level transition and batches LLM calls
+        # for L0→L1 and L1→L2. L2→L3 and L3→L4 are mechanical (no LLM).
+        #
+        # @param exposure_tracker [ExposureTracker] For scoring cards
+        # @param threshold [Float] Exposure score threshold
+        # @return [Integer] Number of cards compressed
+        def compress_low_exposure(exposure_tracker:, threshold: 1.0)
+          candidates = exposure_tracker.low_exposure_cards(threshold: threshold)
+          eligible = candidates.reject { |c| c.compression_level >= 4 }
+          DebugLog.log("compressor", "compress_low_exposure: #{eligible.size}/#{candidates.size} eligible cards")
+          return 0 if eligible.empty?
+
+          # Group by current compression level
+          l0_cards = eligible.select { |c| c.compression_level == 0 }
+          l1_cards = eligible.select { |c| c.compression_level == 1 }
+          l2_cards = eligible.select { |c| c.compression_level == 2 }
+          l3_cards = eligible.select { |c| c.compression_level == 3 }
+
+          count = 0
+
+          # Batch LLM transitions (L0→L1, L1→L2)
+          count += batch_compress_l0_to_l1(l0_cards) if l0_cards.any?
+          count += batch_compress_l1_to_l2(l1_cards) if l1_cards.any?
+
+          # Mechanical transitions (no LLM needed)
+          l2_cards.each { |c| compress_l2_to_l3(c) }
+          count += l2_cards.size
+
+          l3_cards.each { |c| compress_l3_to_l4(c) }
+          count += l3_cards.size
+
+          DebugLog.log("compressor", "compressed #{count} cards")
+          count
+        end
+
+        # Promote a compressed card one level up
+        #
+        # When a compressed card is accessed frequently, it should be promoted
+        # to recover detail. L4→L3 and L3→L2 are mechanical (rebuild from
+        # entities/type). L2→L1 and L1→L0 use LLM to rebuild richer text
+        # from graph neighbors and cluster context.
+        #
+        # @param card [Card] Compressed card (compression_level > 0)
+        # @return [Card] Updated card at one level higher, or unchanged if L0
+        def promote_card(card)
+          case card.compression_level
+          when 4 then promote_l4_to_l3(card)
+          when 3 then promote_l3_to_l2(card)
+          when 2 then promote_l2_to_l1(card)
+          when 1 then promote_l1_to_l0(card)
+          else card # Already at L0
+          end
+        end
+
+        # Promote all eligible compressed cards that have high access
+        #
+        # Cards at L1+ with access_count above the threshold are promoted
+        # one level toward L0. Uses batched LLM calls for L2→L1 and L1→L0
+        # promotions.
+        #
+        # @param access_threshold [Integer] Minimum access count for promotion
+        # @return [Integer] Number of cards promoted
+        def promote_eligible(access_threshold: 5)
+          eligible = @adapter.list_cards.select do |card|
+            card.compression_level >= 1 && card.access_count >= access_threshold
+          end
+          return 0 if eligible.empty?
+
+          # Group by current compression level
+          l4_cards = eligible.select { |c| c.compression_level == 4 }
+          l3_cards = eligible.select { |c| c.compression_level == 3 }
+          l2_cards = eligible.select { |c| c.compression_level == 2 }
+          l1_cards = eligible.select { |c| c.compression_level == 1 }
+
+          count = 0
+
+          # Mechanical promotions (L4→L3, L3→L2)
+          l4_cards.each { |c| promote_l4_to_l3(c) }
+          count += l4_cards.size
+
+          l3_cards.each { |c| promote_l3_to_l2(c) }
+          count += l3_cards.size
+
+          # Batch LLM promotions (L2→L1, L1→L0)
+          count += batch_promote_l2_to_l1(l2_cards) if l2_cards.any?
+          count += batch_promote_l1_to_l0(l1_cards) if l1_cards.any?
+
+          count
+        end
+
+        private
+
+        # Batch compress L0 cards to L1 using a single LLM call per batch
+        #
+        # @param cards [Array<Card>] L0 cards to compress
+        # @return [Integer] Number of cards compressed
+        def batch_compress_l0_to_l1(cards)
+          batch_llm_compress(cards, 1, "Summarize each card faithfully in 1-2 sentences.")
+        end
+
+        # Batch compress L1 cards to L2 using a single LLM call per batch
+        #
+        # @param cards [Array<Card>] L1 cards to compress
+        # @return [Integer] Number of cards compressed
+        def batch_compress_l1_to_l2(cards)
+          batch_llm_compress(cards, 2, "Convert each card to 2-3 bullet points.")
+        end
+
+        # Batch compress cards using XML-tagged LLM calls
+        #
+        # Groups cards into batches of BATCH_SIZE and makes one LLM call per
+        # batch. Falls back to individual compression for any cards missing
+        # from the batch response.
+        #
+        # @param cards [Array<Card>] Cards to compress
+        # @param target_level [Integer] Target compression level
+        # @param task_description [String] LLM instruction
+        # @return [Integer] Number of cards compressed
+        def batch_llm_compress(cards, target_level, task_description)
+          return cards.each { |c| compress_card(c) }.size unless @chat
+
+          count = 0
+          cards.each_slice(BATCH_SIZE) do |batch|
+            results = llm_batch_summarize(batch, task_description)
+
+            batch.each_with_index do |card, i|
+              summary = results[i + 1] # 1-indexed IDs
+              if summary
+                card.text = summary
+                card.compression_level = target_level
+                card.updated_at = Time.now
+                @adapter.write_card(card)
+              else
+                # Missing from batch response — fall back to individual
+                compress_card(card)
+              end
+              count += 1
+            end
+          end
+          count
+        end
+
+        # Make a batched LLM call with XML-tagged cards
+        #
+        # @param cards [Array<Card>] Cards to summarize
+        # @param task_description [String] LLM instruction
+        # @return [Hash<Integer, String>] Mapping of card ID (1-indexed) to content
+        def llm_batch_summarize(cards, task_description)
+          @chat.reset_messages!
+
+          input_cards = cards.each_with_index.map do |card, i|
+            "<card id=\"#{i + 1}\">\n#{card.text}\n</card>"
+          end.join("\n\n")
+
+          prompt = <<~PROMPT
+            #{task_description}
+
+            #{input_cards}
+
+            Return each result inside <card id="N">RESULT</card> tags matching the input IDs.
+          PROMPT
+
+          response = @chat.ask(prompt)
+          parse_card_responses(response.content)
+        rescue StandardError => e
+          EventStream.emit(type: "memory_compression_batch_error", error: "#{e.class}: #{e.message}")
+          {} # Return empty hash to trigger individual fallback
+        end
+
+        # Parse <card id="N">content</card> tags from LLM response
+        #
+        # @param text [String] LLM response text
+        # @return [Hash<Integer, String>] Mapping of card ID to content
+        def parse_card_responses(text)
+          results = {}
+          text.scan(%r{<card\s+id="(\d+)">(.*?)</card>}mi) do |id, content|
+            results[id.to_i] = content.strip
+          end
+          results
+        end
+
+        # Batch promote L2 cards to L1 using LLM
+        #
+        # @param cards [Array<Card>] L2 cards to promote
+        # @return [Integer] Number of cards promoted
+        def batch_promote_l2_to_l1(cards)
+          batch_llm_promote(cards, 1, "Write a faithful 1-2 sentence summary for each card:")
+        end
+
+        # Batch promote L1 cards to L0 using LLM
+        #
+        # @param cards [Array<Card>] L1 cards to promote
+        # @return [Integer] Number of cards promoted
+        def batch_promote_l1_to_l0(cards)
+          batch_llm_promote(cards, 0, "Expand each card into a detailed paragraph (max 250 words):")
+        end
+
+        # Batch promote cards using XML-tagged LLM calls with neighbor context
+        #
+        # @param cards [Array<Card>] Cards to promote
+        # @param target_level [Integer] Target compression level
+        # @param task_description [String] LLM instruction
+        # @return [Integer] Number of cards promoted
+        def batch_llm_promote(cards, target_level, task_description)
+          return cards.each { |c| promote_card(c) }.size unless @chat
+
+          count = 0
+          cards.each_slice(BATCH_SIZE) do |batch|
+            results = llm_batch_promote(batch, task_description)
+
+            batch.each_with_index do |card, i|
+              rebuilt = results[i + 1] # 1-indexed IDs
+              if rebuilt
+                card.text = rebuilt
+                card.compression_level = target_level
+                card.updated_at = Time.now
+                @adapter.write_card(card)
+              else
+                # Missing from batch response — fall back to individual
+                promote_card(card)
+              end
+              count += 1
+            end
+          end
+          count
+        end
+
+        # Make a batched LLM promotion call with XML-tagged cards and neighbor context
+        #
+        # @param cards [Array<Card>] Cards to promote
+        # @param task_description [String] LLM instruction
+        # @return [Hash<Integer, String>] Mapping of card ID (1-indexed) to content
+        def llm_batch_promote(cards, task_description)
+          @chat.reset_messages!
+
+          input_cards = cards.each_with_index.map do |card, i|
+            neighbor_context = gather_neighbor_context(card)
+            context_section = neighbor_context.empty? ? "" : "\nRelated context:\n#{neighbor_context}"
+            "<card id=\"#{i + 1}\">\n#{card.text}\nType: #{card.type}\nEntities: #{card.entities.join(", ")}#{context_section}\n</card>"
+          end.join("\n\n")
+
+          prompt = <<~PROMPT
+            #{task_description}
+
+            #{input_cards}
+
+            Return each result inside <card id="N">RESULT</card> tags matching the input IDs.
+          PROMPT
+
+          response = @chat.ask(prompt)
+          parse_card_responses(response.content)
+        rescue StandardError => e
+          EventStream.emit(type: "memory_promotion_batch_error", error: "#{e.class}: #{e.message}")
+          {} # Return empty hash to trigger individual fallback
+        end
+
+        # L0 → L1: Raw text → faithful summary
+        #
+        # @param card [Card] L0 card
+        # @return [Card] Updated card at L1
+        def compress_l0_to_l1(card)
+          if @chat
+            summary = llm_summarize(card.text, "Summarize this faithfully in 1-2 sentences:")
+            card.text = summary
+          else
+            EventStream.emit(
+              type: "memory_compression_no_llm",
+              card_id: card.id,
+              from_level: 0,
+              to_level: 1,
+            )
+          end
+          card.compression_level = 1
+          card.updated_at = Time.now
+          @adapter.write_card(card)
+          card
+        end
+
+        # L1 → L2: Summary → sparse bullets
+        #
+        # @param card [Card] L1 card
+        # @return [Card] Updated card at L2
+        def compress_l1_to_l2(card)
+          if @chat
+            bullets = llm_summarize(card.text, "Convert to 2-3 bullet points:")
+            card.text = bullets
+          else
+            EventStream.emit(
+              type: "memory_compression_no_llm",
+              card_id: card.id,
+              from_level: 1,
+              to_level: 2,
+            )
+          end
+          card.compression_level = 2
+          card.updated_at = Time.now
+          @adapter.write_card(card)
+          card
+        end
+
+        # L2 → L3: Bullets → schema only (no LLM needed)
+        #
+        # @param card [Card] L2 card
+        # @return [Card] Updated card at L3
+        def compress_l2_to_l3(card)
+          schema = "Type: #{card.type} | Entities: #{card.entities.join(", ")}"
+          card.text = schema
+          card.compression_level = 3
+          card.updated_at = Time.now
+          @adapter.write_card(card)
+          card
+        end
+
+        # L3 → L4: Schema → embedding + title only
+        #
+        # @param card [Card] L3 card
+        # @return [Card] Updated card at L4
+        def compress_l3_to_l4(card)
+          card.text = "[Compressed] #{card.type}: #{card.entities.first || "unknown"}"
+          card.compression_level = 4
+          card.updated_at = Time.now
+          @adapter.write_card(card)
+          card
+        end
+
+        # L4 → L3: Rebuild schema from card metadata
+        #
+        # @param card [Card] L4 card
+        # @return [Card] Updated card at L3
+        def promote_l4_to_l3(card)
+          card.text = "Type: #{card.type} | Entities: #{card.entities.join(", ")}"
+          card.compression_level = 3
+          card.updated_at = Time.now
+          @adapter.write_card(card)
+          card
+        end
+
+        # L3 → L2: Rebuild bullets from neighbor context
+        #
+        # @param card [Card] L3 card
+        # @return [Card] Updated card at L2
+        def promote_l3_to_l2(card)
+          neighbor_context = gather_neighbor_context(card)
+          if @chat && !neighbor_context.empty?
+            rebuilt = llm_rebuild(card, neighbor_context, "Convert to 2-3 bullet points capturing key details:")
+            card.text = rebuilt
+          end
+          card.compression_level = 2
+          card.updated_at = Time.now
+          @adapter.write_card(card)
+          card
+        end
+
+        # L2 → L1: Rebuild faithful summary from neighbor context
+        #
+        # @param card [Card] L2 card
+        # @return [Card] Updated card at L1
+        def promote_l2_to_l1(card)
+          neighbor_context = gather_neighbor_context(card)
+          if @chat && !neighbor_context.empty?
+            rebuilt = llm_rebuild(card, neighbor_context, "Write a faithful 1-2 sentence summary:")
+            card.text = rebuilt
+          end
+          card.compression_level = 1
+          card.updated_at = Time.now
+          @adapter.write_card(card)
+          card
+        end
+
+        # L1 → L0: Rebuild richer text from neighbor context
+        #
+        # @param card [Card] L1 card
+        # @return [Card] Updated card at L0
+        def promote_l1_to_l0(card)
+          neighbor_context = gather_neighbor_context(card)
+          if @chat && !neighbor_context.empty?
+            rebuilt = llm_rebuild(card, neighbor_context, "Expand into a detailed paragraph (max 250 words):")
+            card.text = rebuilt
+          end
+          card.compression_level = 0
+          card.updated_at = Time.now
+          @adapter.write_card(card)
+          card
+        end
+
+        # Gather text from 1-hop graph neighbors for rehydration
+        #
+        # @param card [Card] Card to find neighbors for
+        # @return [String] Concatenated neighbor context
+        def gather_neighbor_context(card)
+          edges = @adapter.edges_for(card.id)
+          neighbor_ids = edges.map { |e| e.from_id == card.id ? e.to_id : e.from_id }.uniq
+          neighbors = neighbor_ids.take(4).filter_map { |nid| @adapter.read_card(nid) }
+          neighbors.map(&:text).join("\n")
+        end
+
+        # Use LLM to rebuild richer text from card + neighbor context
+        #
+        # @param card [Card] Card being promoted
+        # @param neighbor_context [String] Context from neighbors
+        # @param instruction [String] Rebuild instruction
+        # @return [String] Rebuilt text
+        def llm_rebuild(card, neighbor_context, instruction)
+          @chat.reset_messages!
+          response = @chat.ask(<<~PROMPT)
+            #{instruction}
+
+            Current card (#{card.type}): #{card.text}
+            Entities: #{card.entities.join(", ")}
+
+            Related context from neighboring cards:
+            #{neighbor_context}
+          PROMPT
+          response.content.strip
+        rescue StandardError => e
+          EventStream.emit(type: "memory_promotion_llm_error", error: "#{e.class}: #{e.message}")
+          card.text # Fall back to current text
+        end
+
+        # Use LLM to summarize text
+        #
+        # Resets the background chat before each call to prevent message
+        # accumulation across multiple compression operations.
+        #
+        # @param text [String] Text to summarize
+        # @param instruction [String] Summarization instruction
+        # @return [String] Summary
+        def llm_summarize(text, instruction)
+          @chat.reset_messages!
+          response = @chat.ask("#{instruction}\n\n#{text}")
+          response.content.strip
+        rescue StandardError => e
+          EventStream.emit(
+            type: "memory_compression_llm_error",
+            error: "#{e.class}: #{e.message}",
+          )
+          text # Fall back to original text on LLM error
+        end
+      end
+    end
+  end
+end