apple / apple/embedding-atlas

Feature Request: Add onLabelsChange callback to expose generated cluster labels

Open
#142 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
4.9k
Forks
325
Avg merge
14h 48m
Merged PRs (30d)
7

Description

**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**
```
{
// 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.

Contributor guide

Open the contributing guide

Research direction

Start in EmbeddingViewImpl.svelte by reading generateLabels() and the clusterLabels state, then trace how EmbeddingAtlas and EmbeddingView receive component props. Define how the callback should expose the generated labels and their bounds, and verify that consumers can receive updates through onLabelsChange.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
frontend
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.