Skip to content

Feature Request: Add onLabelsChange callback to expose generated cluster labels #142

@dataelvisliang

Description

@dataelvisliang

Summary
Currently there's no way to programmatically read the auto-generated cluster labels from the EmbeddingAtlas / EmbeddingView components. The internal clusterLabels state is computed but never exposed to consumers.

Use Case
I'm building an LLM-powered agent that can understand and navigate the topic structure of the embedding visualization. The agent needs to:

  • Know what topics/clusters exist on the map
  • Select a topic and get all documents within that region
  • Compare topics (e.g., "What's different between Cluster A and Cluster B?")
  • Without access to the generated labels and their spatial bounds, the agent can only do basic SQL queries on the data - it cannot leverage the rich topic structure that Atlas visualizes.

Current Behavior
Labels are generated internally via generateLabels() in EmbeddingViewImpl.svelte
The clusterLabels state variable holds the computed labels
No API exposes these labels to external code

Proposed API

interface LabelWithBounds {
  x: number;
  y: number;
  text: string;
  level?: number;
  priority?: number;
  // Include the bounding rectangles so we can query documents in that region
  rects?: Rectangle[];
}

// New callback prop
onLabelsChange?: (labels: LabelWithBounds[]) => void;

Example Usage

<EmbeddingAtlas
  coordinator={coordinator}
  data={data}
  onLabelsChange={(labels) => {
    // Now the agent can use these labels
    setCurrentTopics(labels);
    
    // Agent can query documents in a topic region:
    // SELECT * FROM data WHERE x BETWEEN rect.x1 AND rect.x2 ...
  }}
/>

I think reading elements from SVG is fragile and doesn't provide bounds, but could work for the time being for my use cases.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions