ClusterModel.swift

ClusterModel Documentation

Overview

ClusterModel.swift defines the Cluster struct, which represents a grouping of related entries based on their similarity threshold. Clusters help organize and categorize entries using their vector embeddings and optional category labels.

Structure Definition

struct Cluster: Codable, Identifiable {
    let id: UUID
    let entries: [Entry]
    let threshold: Float
    let category: String?
}

Properties

Property	Type	Description
id	UUID	Unique identifier for the cluster. Automatically generated if not provided.
entries	[Entry]	Array of Entry objects that belong to this cluster.
threshold	Float	Similarity threshold value used to determine cluster membership.
category	String?	Optional label or category name for the cluster.

Protocol Conformance

Codable

• Enables JSON encoding and decoding

• Used for persistence and API communication

• Automatic synthesis as all properties are Codable-conforming types

Identifiable

• Provides unique identification for SwiftUI integration

• Uses the id property as the unique identifier

• Enables direct use in SwiftUI Lists and ForEach

Hashable

• Custom implementation focusing on id property

• Enables use in Sets and as Dictionary keys

• Implementation:

  func hash(into hasher: inout Hasher) {
      hasher.combine(id)
  }
  
  static func == (lhs: Cluster, rhs: Cluster) -> Bool {
      lhs.id == rhs.id
  }

Initialization

init(id: UUID = UUID(), 
     entries: [Entry] = [], 
     threshold: Float, 
     category: String? = nil)

Parameters

• id: Optional. Defaults to new UUID if not provided

• entries: Optional. Defaults to empty array

• threshold: Required. Similarity threshold for cluster membership

• category: Optional. Defaults to nil

Usage Examples

Creating an Empty Cluster

let cluster = Cluster(threshold: 0.85)

Creating a Cluster with Entries

let entries = [entry1, entry2, entry3]
let cluster = Cluster(
    entries: entries,
    threshold: 0.85,
    category: "Technology"
)

Using in Collections

var clusterSet = Set<Cluster>()
clusterSet.insert(cluster)

var clusterDictionary = [Cluster: String]()
clusterDictionary[cluster] = "metadata"

Best Practices

1. Choose appropriate threshold values based on your similarity requirements

2. Consider grouping related entries before creating a cluster

3. Use meaningful category names when applicable

4. Maintain consistency in threshold values across related clusters

5. Consider memory implications when storing large numbers of entries in a cluster

Common Operations

Adding Entries

// Since properties are immutable, create a new cluster with updated entries
let updatedCluster = Cluster(
    id: cluster.id,
    entries: cluster.entries + [newEntry],
    threshold: cluster.threshold,
    category: cluster.category
)

Checking Entry Similarity

// Example similarity check (implementation depends on your similarity metric)
func canAddEntry(_ entry: Entry) -> Bool {
    return entries.allSatisfy { existingEntry in
        calculateSimilarity(entry.embeddings, existingEntry.embeddings) >= threshold
    }
}

Related Components

• EntryModel.swift: Provides the Entry type used in clusters

• Storage Provider: Handles persistence of Cluster objects

• Clustering Algorithm: Uses threshold to determine cluster membership

• SwiftUI Views: Displays clusters and their entries