autorag.viz

Topic embedding visualization: Chroma-backed embeddings + UMAP + FastAPI endpoints.

class autorag.viz.TopicPoint(**data)

Bases: BaseModel

One topic node placed in 3-D space by the UMAP projection.

Parameters:

• data (Any)

• topic_title (str)

• clip_id (str)

• clip_title (str)

• level (int)

• start_s (float)

• duration_s (float)

• number (str)

• summary (str)

• x (float)

• y (float)

• z (float)

• cluster_id (int)

topic_title: str

clip_id: str

clip_title: str

level: int

start_s: float

duration_s: float

number: str

summary: str

x: float

y: float

z: float

cluster_id: int

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class autorag.viz.Edge(**data)

Bases: BaseModel

A similarity edge between two TopicPoint indices.

Parameters:

• data (Any)

• a (int)

• b (int)

• similarity (float)

a: int

b: int

similarity: float

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class autorag.viz.VizData(**data)

Bases: BaseModel

Payload returned by GET /viz/data — points, edges, clip metadata.

Parameters:

• data (Any)

• points (list[TopicPoint])

• clip_ids (list[str])

• clip_titles (dict[str, str])

• total_topics (int)

• total_clips (int)

• edges (list[Edge])

• total_clusters (int)

points: list[TopicPoint]

clip_ids: list[str]

clip_titles: dict[str, str]

total_topics: int

total_clips: int

edges: list[Edge]

total_clusters: int

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class autorag.viz.SearchResult(**data)

Bases: BaseModel

One hit returned by GET /viz/search.

Parameters:

• data (Any)

• point_index (int)

• topic_title (str)

• clip_title (str)

• clip_id (str)

• similarity (float)

• summary (str)

point_index: int

topic_title: str

clip_title: str

clip_id: str

similarity: float

summary: str

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

autorag.viz.umap_3d(embeddings)

Project N-D embeddings down to 3 columns with cosine UMAP.

Handles the small-N degenerate cases (n == 1 → all zeros; n < 4 → pad to three columns) so the page can render the very first clip.

Parameters:

embeddings (list[list[float]])

Return type:

float64

autorag.viz.Row

(clip_id, clip_title, topic, topic_index).

Type:

A single point in the viz

alias of tuple[str, str, dict[str, Any], int]

autorag.viz.viz_page()

Serve the React/r3f single-page app at GET /viz.

Return type:

HTMLResponse

autorag.viz.viz_data(distance_threshold=fastapi.Query)

Return the full VizData payload for the /viz page.

Pulls every clip + topic from SQLite, fills missing embeddings via Ollama (and caches them in Chroma), runs the 3-D UMAP projection, and assembles cluster labels and similarity edges using distance_threshold as the cluster cut.

Parameters:

distance_threshold (float)

Return type:

VizData

autorag.viz.viz_search(q=fastapi.Query, top_k=fastapi.Query)

Return the top_k topics whose embedding is closest to q.

Embeds the query with the same Ollama model used at ingest time and runs the search inside Chroma. Hits that don’t have a corresponding point in the current viz dataset are skipped silently.

Parameters:

• q (str)

• top_k (int)

Return type:

list[SearchResult]