ProjectedCluster

Extends Cluster with 2D projection coordinates for visualization on a scatter plot or map.

x_coord

float

required

X-axis coordinate in the 2D projection space

y_coord

float

required

Y-axis coordinate in the 2D projection space

level

int

required

Hierarchy level of the cluster (0 for root, increasing for deeper levels)

str

required

Show Inherited from Cluster

Unique identifier for the cluster. Auto-generated using uuid.uuid4().hex if not provided

name

str

required

Show Inherited from Cluster

Short, imperative sentence describing the cluster (at most ten words)

description

str

required

Show Inherited from Cluster

Detailed description of what conversations in this cluster are about

slug

str

required

Show Inherited from Cluster

Three-word snake_case summary of the cluster topic

chat_ids

list[str]

required

Show Inherited from Cluster

List of conversation IDs belonging to this cluster

parent_id

Union[str, None]

required

Show Inherited from Cluster

ID of the parent cluster in the hierarchy, or None for top-level clusters

count

int

Show Inherited from Cluster

Number of conversations in this cluster. Computed from len(chat_ids)

Example

from kura.types import ProjectedCluster

projected = ProjectedCluster(
    id="cluster-123",
    name="Debug Python asyncio issues",
    description="Users troubleshooting asyncio event loops and coroutine errors in Python.",
    slug="python_asyncio_debugging",
    chat_ids=["chat-1", "chat-2", "chat-3", "chat-4"],
    parent_id="parent-cluster-456",
    x_coord=12.5,
    y_coord=-8.3,
    level=2
)

print(f"Cluster at ({projected.x_coord}, {projected.y_coord})")
print(f"Contains {projected.count} conversations at level {projected.level}")
# Cluster at (12.5, -8.3)
# Contains 4 conversations at level 2

Use Case

Projected clusters are used for visualization in the Kura UI. The coordinates represent the cluster’s position after dimensionality reduction (typically UMAP), allowing related clusters to be positioned near each other on a 2D map. The level field indicates the cluster’s position in the meta-clustering hierarchy:

level=0: Root-level clusters (highest abstraction)
level=1: First-level sub-clusters
level=2+: Deeper nested clusters

# Typical usage in visualization pipeline
from kura.dimensionality import HDBUMAP

reducer = HDBUMAP()
projected_clusters = reducer.reduce(clusters, embeddings)

# Each projected_cluster now has x_coord, y_coord, and level
for cluster in projected_clusters:
    plot_point(cluster.x_coord, cluster.y_coord, label=cluster.name)

Core Components

Data Types

Utilities

ProjectedCluster