swarm_sdk 2.7.14 → 3.0.0.alpha2

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

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module V3
+    module Memory
+      # A self-contained memory unit (<=250 words)
+      #
+      # Cards are the atomic unit of the memory system. Each card captures
+      # a single idea, fact, decision, or concept with enough context to
+      # be understood in isolation.
+      #
+      # @example Create a fact card
+      #   card = Card.new(
+      #     text: "The API uses JWT tokens for authentication with RS256 signing.",
+      #     type: :fact,
+      #     entities: ["API", "JWT", "RS256"],
+      #     source_turn_ids: ["turn_001"],
+      #   )
+      class Card
+        TYPES = [:fact, :concept, :decision, :constraint, :preference, :incident].freeze
+
+        # @return [String] Unique card identifier (card_<hex>)
+        attr_reader :id
+
+        # @return [String] Card content (<=250 words, self-contained)
+        attr_accessor :text
+
+        # @return [Symbol] Card type (fact, concept, decision, constraint, preference, incident)
+        attr_reader :type
+
+        # @return [Array<String>] Named entities mentioned in the card
+        attr_accessor :entities
+
+        # @return [Array<String>] Turn IDs that contributed to this card
+        attr_accessor :source_turn_ids
+
+        # @return [Array<Float>, nil] Embedding vector (384 dimensions for MiniLM)
+        attr_accessor :embedding
+
+        # @return [Float] Importance score (0.0-1.0)
+        attr_accessor :importance
+
+        # @return [Float] Confidence score (0.0-1.0, default 1.0)
+        attr_accessor :confidence
+
+        # @return [Integer] Number of times this card was retrieved
+        attr_accessor :access_count
+
+        # @return [Time, nil] Last time this card was accessed
+        attr_accessor :last_accessed
+
+        # @return [Float] Dwell time weight (how long card was in context)
+        attr_accessor :dwell
+
+        # @return [Integer] Compression level (0=raw, 1=summary, 2=bullets, 3=schema, 4=embedding-only)
+        attr_accessor :compression_level
+
+        # @return [String, nil] ID of canonical card if this was merged
+        attr_accessor :canonical_id
+
+        # @return [Time] Creation timestamp
+        attr_reader :created_at
+
+        # @return [Time] Last update timestamp
+        attr_accessor :updated_at
+
+        # Create a new memory card
+        #
+        # @param text [String] Card content
+        # @param type [Symbol] Card type
+        # @param entities [Array<String>] Named entities
+        # @param source_turn_ids [Array<String>] Contributing turn IDs
+        # @param id [String, nil] Card ID (auto-generated if nil)
+        # @param embedding [Array<Float>, nil] Embedding vector
+        # @param importance [Float] Importance score
+        # @param confidence [Float] Confidence score (0.0-1.0)
+        # @param access_count [Integer] Access count
+        # @param last_accessed [Time, nil] Last access time
+        # @param dwell [Float] Dwell time weight
+        # @param compression_level [Integer] Compression level (0-4)
+        # @param canonical_id [String, nil] Canonical card ID
+        # @param created_at [Time, nil] Creation time
+        # @param updated_at [Time, nil] Update time
+        #
+        # @raise [ArgumentError] If type is invalid
+        def initialize(
+          text:,
+          type: :fact,
+          entities: [],
+          source_turn_ids: [],
+          id: nil,
+          embedding: nil,
+          importance: 0.5,
+          confidence: 1.0,
+          access_count: 0,
+          last_accessed: nil,
+          dwell: 0.0,
+          compression_level: 0,
+          canonical_id: nil,
+          created_at: nil,
+          updated_at: nil
+        )
+          @id = id || "card_#{SecureRandom.hex(6)}"
+          @text = text
+          @type = type.to_sym
+          @entities = Array(entities)
+          @source_turn_ids = Array(source_turn_ids)
+          @embedding = embedding
+          @importance = importance.to_f
+          @confidence = confidence.to_f
+          @access_count = access_count.to_i
+          @last_accessed = last_accessed
+          @dwell = dwell.to_f
+          @compression_level = compression_level.to_i
+          @canonical_id = canonical_id
+          @created_at = created_at || Time.now
+          @updated_at = updated_at || Time.now
+
+          validate!
+        end
+
+        # Record an access to this card (included in working context)
+        #
+        # Increments access count, updates last accessed time, and
+        # increases dwell weight to track how often this card has
+        # been included in the working context.
+        #
+        # @param dwell_increment [Float] Amount to add to dwell (default: 1.0)
+        # @return [void]
+        def record_access!(dwell_increment: 1.0)
+          @access_count += 1
+          @last_accessed = Time.now
+          @dwell += dwell_increment
+          @updated_at = Time.now
+        end
+
+        # Whether this card has been merged into a canonical card
+        #
+        # @return [Boolean]
+        def merged?
+          !@canonical_id.nil?
+        end
+
+        # Serialize to a hash for JSON storage
+        #
+        # @return [Hash] Serializable representation
+        def to_h
+          {
+            id: @id,
+            text: @text,
+            type: @type.to_s,
+            entities: @entities,
+            source_turn_ids: @source_turn_ids,
+            embedding: @embedding,
+            importance: @importance,
+            confidence: @confidence,
+            access_count: @access_count,
+            last_accessed: @last_accessed&.iso8601,
+            dwell: @dwell,
+            compression_level: @compression_level,
+            canonical_id: @canonical_id,
+            created_at: @created_at.iso8601,
+            updated_at: @updated_at.iso8601,
+          }
+        end
+
+        class << self
+          # Deserialize from a hash
+          #
+          # @param hash [Hash] Serialized card data
+          # @return [Card]
+          def from_h(hash)
+            hash = hash.transform_keys(&:to_sym)
+            new(
+              id: hash[:id],
+              text: hash[:text],
+              type: hash[:type]&.to_sym || :fact,
+              entities: hash[:entities] || [],
+              source_turn_ids: hash[:source_turn_ids] || [],
+              embedding: hash[:embedding],
+              importance: hash[:importance] || 0.5,
+              confidence: hash[:confidence] || 1.0,
+              access_count: hash[:access_count] || 0,
+              last_accessed: hash[:last_accessed] ? Time.parse(hash[:last_accessed]) : nil,
+              dwell: hash[:dwell] || 0.0,
+              compression_level: hash[:compression_level] || 0,
+              canonical_id: hash[:canonical_id],
+              created_at: hash[:created_at] ? Time.parse(hash[:created_at]) : nil,
+              updated_at: hash[:updated_at] ? Time.parse(hash[:updated_at]) : nil,
+            )
+          end
+        end
+
+        private
+
+        # @raise [ArgumentError] If type is invalid
+        def validate!
+          raise ArgumentError, "Invalid card type: #{@type}. Must be one of: #{TYPES.join(", ")}" unless TYPES.include?(@type)
+          raise ArgumentError, "Card text is required" if @text.nil? || @text.strip.empty?
+          raise ArgumentError, "Confidence must be 0.0-1.0" unless (0.0..1.0).cover?(@confidence)
+          raise ArgumentError, "Compression level must be 0-4" unless (0..4).cover?(@compression_level)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module V3
+    module Memory
+      # A topic cluster grouping related memory cards
+      #
+      # Clusters provide a higher-level organization of memory cards
+      # by topic. Each cluster maintains a rolling summary and tracks
+      # its member cards.
+      #
+      # @example Create a cluster
+      #   cluster = Cluster.new(
+      #     title: "Authentication System",
+      #     rolling_summary: "The project uses JWT-based auth with RS256 signing...",
+      #     card_ids: ["card_a1b2c3", "card_d4e5f6"],
+      #   )
+      class Cluster
+        # @return [String] Unique cluster identifier
+        attr_reader :id
+
+        # @return [String] Cluster title/topic
+        attr_accessor :title
+
+        # @return [Array<Float>, nil] Cluster centroid embedding
+        attr_accessor :embedding
+
+        # @return [String] Rolling summary of cluster contents
+        attr_accessor :rolling_summary
+
+        # @return [Array<String>] Decision log entries
+        attr_accessor :decision_log
+
+        # @return [Array<String>] Key entities in this cluster
+        attr_accessor :key_entities
+
+        # @return [Array<String>] Member card IDs
+        attr_accessor :card_ids
+
+        # @return [Time] Creation timestamp
+        attr_reader :created_at
+
+        # @return [Time] Last update timestamp
+        attr_accessor :updated_at
+
+        # Create a new cluster
+        #
+        # @param title [String] Cluster title
+        # @param id [String, nil] Cluster ID (auto-generated if nil)
+        # @param embedding [Array<Float>, nil] Centroid embedding
+        # @param rolling_summary [String] Summary of contents
+        # @param decision_log [Array<String>] Decision entries
+        # @param key_entities [Array<String>] Key entities
+        # @param card_ids [Array<String>] Member card IDs
+        # @param created_at [Time, nil] Creation time
+        # @param updated_at [Time, nil] Update time
+        def initialize(
+          title:,
+          id: nil,
+          embedding: nil,
+          rolling_summary: "",
+          decision_log: [],
+          key_entities: [],
+          card_ids: [],
+          created_at: nil,
+          updated_at: nil
+        )
+          @id = id || "cluster_#{SecureRandom.hex(6)}"
+          @title = title
+          @embedding = embedding
+          @rolling_summary = rolling_summary
+          @decision_log = Array(decision_log)
+          @key_entities = Array(key_entities)
+          @card_ids = Array(card_ids)
+          @created_at = created_at || Time.now
+          @updated_at = updated_at || Time.now
+        end
+
+        # Add a card to this cluster
+        #
+        # @param card_id [String] Card ID to add
+        # @return [void]
+        def add_card(card_id)
+          return if @card_ids.include?(card_id)
+
+          @card_ids << card_id
+          @updated_at = Time.now
+        end
+
+        # Remove a card from this cluster
+        #
+        # @param card_id [String] Card ID to remove
+        # @return [void]
+        def remove_card(card_id)
+          @card_ids.delete(card_id)
+          @updated_at = Time.now
+        end
+
+        # Number of cards in this cluster
+        #
+        # @return [Integer]
+        def size
+          @card_ids.size
+        end
+
+        # Serialize to a hash
+        #
+        # @return [Hash]
+        def to_h
+          {
+            id: @id,
+            title: @title,
+            embedding: @embedding,
+            rolling_summary: @rolling_summary,
+            decision_log: @decision_log,
+            key_entities: @key_entities,
+            card_ids: @card_ids,
+            created_at: @created_at.iso8601,
+            updated_at: @updated_at.iso8601,
+          }
+        end
+
+        class << self
+          # Deserialize from a hash
+          #
+          # @param hash [Hash] Serialized cluster data
+          # @return [Cluster]
+          def from_h(hash)
+            hash = hash.transform_keys(&:to_sym)
+            new(
+              id: hash[:id],
+              title: hash[:title],
+              embedding: hash[:embedding],
+              rolling_summary: hash[:rolling_summary] || "",
+              decision_log: hash[:decision_log] || [],
+              key_entities: hash[:key_entities] || [],
+              card_ids: hash[:card_ids] || [],
+              created_at: hash[:created_at] ? Time.parse(hash[:created_at]) : nil,
+              updated_at: hash[:updated_at] ? Time.parse(hash[:updated_at]) : nil,
+            )
+          end
+        end
+      end
+    end
+  end
+end