Class: SwarmSDK::V3::Memory::Cluster

Inherits:
Object
  • Object
show all
Defined in:
lib/swarm_sdk/v3/memory/cluster.rb

Overview

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.

Examples:

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"],
)

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(title:, id: nil, embedding: nil, rolling_summary: "", decision_log: [], key_entities: [], card_ids: [], created_at: nil, updated_at: nil) ⇒ Cluster

Create a new cluster

Parameters:

  • title (String) —

    Cluster title

  • id (String, nil) (defaults to: nil) —

    Cluster ID (auto-generated if nil)

  • embedding (Array<Float>, nil) (defaults to: nil) —

    Centroid embedding

  • rolling_summary (String) (defaults to: "") —

    Summary of contents

  • decision_log (Array<String>) (defaults to: []) —

    Decision entries

  • key_entities (Array<String>) (defaults to: []) —

    Key entities

  • card_ids (Array<String>) (defaults to: []) —

    Member card IDs

  • created_at (Time, nil) (defaults to: nil) —

    Creation time

  • updated_at (Time, nil) (defaults to: nil) —

    Update time



57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
 
# File 'lib/swarm_sdk/v3/memory/cluster.rb', line 57

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

Instance Attribute Details

#card_ids ⇒ Array<String>

Returns Member card IDs.

Returns:

  • (Array<String>) —

    Member card IDs



38
39
40
 
# File 'lib/swarm_sdk/v3/memory/cluster.rb', line 38

def card_ids
  @card_ids
end

#created_at ⇒ Time (readonly)

Returns Creation timestamp.

Returns:

  • (Time) —

    Creation timestamp



41
42
43
 
# File 'lib/swarm_sdk/v3/memory/cluster.rb', line 41

def created_at
  @created_at
end

#decision_log ⇒ Array<String>

Returns Decision log entries.

Returns:

  • (Array<String>) —

    Decision log entries



32
33
34
 
# File 'lib/swarm_sdk/v3/memory/cluster.rb', line 32

def decision_log
  @decision_log
end

#embedding ⇒ Array<Float>?

Returns Cluster centroid embedding.

Returns:

  • (Array<Float>, nil) —

    Cluster centroid embedding



26
27
28
 
# File 'lib/swarm_sdk/v3/memory/cluster.rb', line 26

def embedding
  @embedding
end

#id ⇒ String (readonly)

Returns Unique cluster identifier.

Returns:

  • (String) —

    Unique cluster identifier



20
21
22
 
# File 'lib/swarm_sdk/v3/memory/cluster.rb', line 20

def id
  @id
end

#key_entities ⇒ Array<String>

Returns Key entities in this cluster.

Returns:

  • (Array<String>) —

    Key entities in this cluster



35
36
37
 
# File 'lib/swarm_sdk/v3/memory/cluster.rb', line 35

def key_entities
  @key_entities
end

#rolling_summary ⇒ String

Returns Rolling summary of cluster contents.

Returns:

  • (String) —

    Rolling summary of cluster contents



29
30
31
 
# File 'lib/swarm_sdk/v3/memory/cluster.rb', line 29

def rolling_summary
  @rolling_summary
end

#title ⇒ String

Returns Cluster title/topic.

Returns:

  • (String) —

    Cluster title/topic



23
24
25
 
# File 'lib/swarm_sdk/v3/memory/cluster.rb', line 23

def title
  @title
end

#updated_at ⇒ Time

Returns Last update timestamp.

Returns:

  • (Time) —

    Last update timestamp



44
45
46
 
# File 'lib/swarm_sdk/v3/memory/cluster.rb', line 44

def updated_at
  @updated_at
end

Class Method Details

.from_h(hash) ⇒ Cluster

Deserialize from a hash

Parameters:

  • hash (Hash) —

    Serialized cluster data

Returns:



128
129
130
131
132
133
134
135
136
137
138
139
140
141
 
# File 'lib/swarm_sdk/v3/memory/cluster.rb', line 128

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

Instance Method Details

#add_card(card_id) ⇒ void

This method returns an undefined value.

Add a card to this cluster

Parameters:

  • card_id (String) —

    Card ID to add



83
84
85
86
87
88
 
# File 'lib/swarm_sdk/v3/memory/cluster.rb', line 83

def add_card(card_id)
  return if @card_ids.include?(card_id)

  @card_ids << card_id
  @updated_at = Time.now
end

#remove_card(card_id) ⇒ void

This method returns an undefined value.

Remove a card from this cluster

Parameters:

  • card_id (String) —

    Card ID to remove



94
95
96
97
 
# File 'lib/swarm_sdk/v3/memory/cluster.rb', line 94

def remove_card(card_id)
  @card_ids.delete(card_id)
  @updated_at = Time.now
end

#size ⇒ Integer

Number of cards in this cluster

Returns:

  • (Integer) 


102
103
104
 
# File 'lib/swarm_sdk/v3/memory/cluster.rb', line 102

def size
  @card_ids.size
end

#to_h ⇒ Hash

Serialize to a hash

Returns:

  • (Hash) 


109
110
111
112
113
114
115
116
117
118
119
120
121
 
# File 'lib/swarm_sdk/v3/memory/cluster.rb', line 109

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