Visualization

Overview

Kura provides multiple visualization functions for displaying hierarchical cluster structures in the terminal. These functions offer different levels of detail and formatting, from basic tree views to rich, colorful displays.

Core Functions

visualise_pipeline_results()

Convenience function for visualizing clusters directly from pipeline results.

from kura.visualization import visualise_pipeline_results

visualise_pipeline_results(
    clusters,
    style="enhanced",
    console=None
)

clusters

List[Cluster]

required

List of clusters from pipeline execution

style

Literal['basic', 'enhanced', 'rich']

default:"enhanced"

Visualization style to use:

"basic": Simple tree structure with conversation counts
"enhanced": Includes statistics, percentages, and progress bars
"rich": Full-color Rich library formatting (requires rich package)

console

Optional[Console]

default:"None"

Rich Console instance for "rich" style. Created automatically if not provided.

Example Usage

from kura.visualization import visualise_pipeline_results
from kura.v1 import run_pipeline

# Run analysis pipeline
results = await run_pipeline(
    conversations=conversations,
    summary_model=summary_model,
    cluster_model=cluster_model,
    meta_cluster_model=meta_cluster_model
)

# Visualize with different styles
visualise_pipeline_results(results.meta_clusters, style="basic")
visualise_pipeline_results(results.meta_clusters, style="enhanced")
visualise_pipeline_results(results.meta_clusters, style="rich")

visualise_clusters()

Print a hierarchical visualization of clusters to the terminal with basic formatting.

from kura.visualization import visualise_clusters

visualise_clusters(
    clusters=None,
    checkpoint_path="./checkpoints/meta_clusters.jsonl"
)

clusters

Optional[List[Cluster]]

default:"None"

List of clusters to visualize. If None, loads from checkpoint_path.

checkpoint_path

Optional[Union[str, Path]]

default:"None"

Path to checkpoint file to load clusters from. Required if clusters is None.

Output Example

Clusters (1,234 conversations)
╠══ Compare and improve Flutter and React state management (45 conversations)
║   ╚══ Improve and compare Flutter and React state management (32 conversations)
║       ╠══ Improve React TypeScript application (15 conversations)
║       ╚══ Compare and select Flutter state management solutions (17 conversations)
╠══ Optimize blog posts for SEO and improved user engagement (28 conversations)
╚══ Debug Python application errors (156 conversations)

visualise_clusters_enhanced()

Print an enhanced hierarchical visualization with colors, statistics, and progress bars.

from kura.visualization import visualise_clusters_enhanced

visualise_clusters_enhanced(
    clusters=None,
    checkpoint_path="./checkpoints/meta_clusters.jsonl"
)

clusters

Optional[List[Cluster]]

default:"None"

List of clusters to visualize. If None, loads from checkpoint_path.

checkpoint_path

Optional[Union[str, Path]]

default:"None"

Path to checkpoint file to load clusters from. Required if clusters is None.

Output Example

================================================================================
🎯 ENHANCED CLUSTER VISUALIZATION
================================================================================
🔸 📚 All Clusters (1,234 total conversations)
    📊 1,234 conversations (100.0%) [████████████████████]

╠══ 🔸 Compare and improve state management
║   📊 450 conversations (36.5%) [███████░░░░░░░░░░░░░]
║   💭 Developers comparing Flutter and React patterns
║
╚══ 🔸 Debug application errors
    📊 784 conversations (63.5%) [████████████░░░░░░░░]
    💭 Various debugging and troubleshooting requests

================================================================================
📈 CLUSTER STATISTICS
================================================================================
📊 Total Clusters: 42
🌳 Root Clusters: 8
💬 Total Conversations: 1,234
📏 Average Conversations per Root Cluster: 154.2
================================================================================

visualise_clusters_rich()

Print a rich-formatted hierarchical visualization using the Rich library with full color and interactive-style formatting.

from kura.visualization import visualise_clusters_rich
from rich.console import Console

console = Console()
visualise_clusters_rich(
    clusters=None,
    checkpoint_path="./checkpoints/meta_clusters.jsonl",
    console=console
)

clusters

Optional[List[Cluster]]

default:"None"

List of clusters to visualize. If None, loads from checkpoint_path.

checkpoint_path

Optional[Union[str, Path]]

default:"None"

Path to checkpoint file to load clusters from. Required if clusters is None.

console

Optional[Console]

default:"None"

Rich Console instance. If None, creates a new one or falls back to enhanced visualization.

Requires the rich package to be installed. Falls back to visualise_clusters_enhanced() if Rich is not available.

Features

Full-color output with level-based color schemes
Interactive-style tree rendering
Statistical tables with size distributions
Progress bars for visual representation
Automatic truncation of long descriptions

visualise_from_checkpoint_manager()

Visualize clusters using a CheckpointManager and meta cluster model from the v1 pipeline.

from kura.visualization import visualise_from_checkpoint_manager

visualise_from_checkpoint_manager(
    checkpoint_manager,
    meta_cluster_model,
    style="enhanced",
    console=None
)

checkpoint_manager

BaseCheckpointManager

required

CheckpointManager instance from v1 pipeline

meta_cluster_model

BaseMetaClusterModel

required

Meta cluster model with checkpoint_filename attribute

style

str

default:"basic"

Visualization style: "basic", "enhanced", or "rich"

console

Optional[Console]

default:"None"

Rich Console instance (for rich style)

Example Usage

from kura.visualization import visualise_from_checkpoint_manager
from kura.checkpoints import JSONLCheckpointManager
from kura.meta_cluster import MetaClusterModel

# Setup pipeline components
checkpoint_manager = JSONLCheckpointManager("./checkpoints")
meta_cluster_model = MetaClusterModel(max_clusters=10)

# Run pipeline...
# ...

# Visualize results
visualise_from_checkpoint_manager(
    checkpoint_manager,
    meta_cluster_model,
    style="rich"
)

Visualization Styles Comparison

Style	Colors	Statistics	Progress Bars	Requirements	Best For
basic	No	Minimal	No	None	Quick checks, CI/CD
enhanced	Emoji	Detailed	Yes (ASCII)	None	Regular terminal use
rich	Full color	Comprehensive	Yes (styled)	`rich` package	Development, demos

Advanced Usage

Custom Console Configuration

from rich.console import Console
from kura.visualization import visualise_clusters_rich

# Configure console for file output
console = Console(record=True)
visualise_clusters_rich(clusters, console=console)

# Save to HTML
console.save_html("clusters.html")

# Save to SVG
console.save_svg("clusters.svg", title="Cluster Analysis")

Filtering Clusters Before Visualization

from kura.visualization import visualise_pipeline_results

# Only visualize large clusters
large_clusters = [
    cluster for cluster in clusters
    if len(cluster.chat_ids) > 50
]

visualise_pipeline_results(large_clusters, style="enhanced")

Programmatic Tree Building

from kura.visualization import _build_cluster_tree
from kura.types import Cluster

# Build tree structure from clusters
node_id_to_cluster = _build_cluster_tree(clusters)

# Access tree nodes
for cluster_id, node in node_id_to_cluster.items():
    print(f"{node.name}: {node.count} conversations")
    print(f"Children: {len(node.children)}")

Integration Examples

With Class-Based API

from kura import Kura
from kura.visualization import visualise_pipeline_results

# Run analysis
kura = Kura(...)
await kura.fit(conversations)

# Visualize results
visualise_pipeline_results(
    kura.meta_clusters,
    style="rich"
)

With Procedural API (v1)

from kura.v1 import run_pipeline
from kura.visualization import visualise_pipeline_results

# Run pipeline
results = await run_pipeline(
    conversations=conversations,
    summary_model=summary_model,
    cluster_model=cluster_model,
    meta_cluster_model=meta_cluster_model
)

# Visualize
visualise_pipeline_results(
    results.meta_clusters,
    style="enhanced"
)

Loading from Checkpoint

from kura.visualization import visualise_clusters_enhanced
from pathlib import Path

# Visualize from checkpoint file
checkpoint_path = Path("./checkpoints/meta_clusters.jsonl")

if checkpoint_path.exists():
    visualise_clusters_enhanced(checkpoint_path=checkpoint_path)
else:
    print("Checkpoint not found. Run analysis first.")

Cluster Tree Structure

ClusterTreeNode

Internal data structure for tree representation:

from kura.types import ClusterTreeNode

node = ClusterTreeNode(
    id="cluster_1",
    name="Debug Python errors",
    description="Troubleshooting Python applications",
    slug="debug-python-errors",
    count=156,
    children=["cluster_2", "cluster_3"]
)

str

Unique identifier for the cluster

name

str

Human-readable cluster name

description

str

Detailed description of the cluster

slug

str

URL-safe slug for the cluster

count

int

Number of conversations in this cluster

children

List[str]

List of child cluster IDs

Best Practices

Use visualise_pipeline_results() for the simplest integration with pipeline results.

Start with "enhanced" style for a good balance of detail and compatibility.

Use "rich" style when presenting results or during development for the best visual experience.

Use "basic" style in CI/CD pipelines or when redirecting output to files.

Load from checkpoints when you want to visualize previously computed results without re-running the pipeline.

Troubleshooting

Rich Not Available

from kura.visualization import visualise_pipeline_results

# This will automatically fall back to enhanced style
visualise_pipeline_results(clusters, style="rich")
# Output: "Rich library not available. Using enhanced visualization..."

Solution: Install the rich package:

pip install rich
# or
uv pip install rich

Checkpoint Not Found

from kura.visualization import visualise_clusters

try:
    visualise_clusters(checkpoint_path="./missing.jsonl")
except FileNotFoundError as e:
    print(f"Error: {e}")
    print("Run the analysis pipeline first to generate checkpoints.")

Empty Visualization

# Ensure clusters have parent-child relationships
for cluster in clusters:
    if not cluster.parent_id:
        print(f"Root cluster: {cluster.name}")
    else:
        print(f"Child cluster: {cluster.name} -> parent: {cluster.parent_id}")

Character Encoding Issues

# Set encoding for Windows terminals
import sys
import io

sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')

from kura.visualization import visualise_clusters_enhanced
visualise_clusters_enhanced(clusters)

Core Components

Data Types

Utilities

Visualization

Overview

Core Functions

visualise_pipeline_results()

Example Usage

visualise_clusters()

Output Example

visualise_clusters_enhanced()

Output Example

visualise_clusters_rich()

Features

visualise_from_checkpoint_manager()

Example Usage

Visualization Styles Comparison

Advanced Usage

Custom Console Configuration

Filtering Clusters Before Visualization

Programmatic Tree Building

Integration Examples

With Class-Based API

With Procedural API (v1)

Loading from Checkpoint

Cluster Tree Structure

ClusterTreeNode

Best Practices

Troubleshooting

Rich Not Available

Checkpoint Not Found

Empty Visualization

Character Encoding Issues

Build docs developers (and LLMs) love

Core Components

Data Types

Utilities

Documentation Index

​Overview

​Core Functions

​visualise_pipeline_results()

​Example Usage

​visualise_clusters()

​Output Example

​visualise_clusters_enhanced()

​Output Example

​visualise_clusters_rich()

​Features

​visualise_from_checkpoint_manager()

​Example Usage

​Visualization Styles Comparison

​Advanced Usage

​Custom Console Configuration

​Filtering Clusters Before Visualization

​Programmatic Tree Building

​Integration Examples

​With Class-Based API

​With Procedural API (v1)

​Loading from Checkpoint

​Cluster Tree Structure

​ClusterTreeNode

​Best Practices

​Troubleshooting

​Rich Not Available

​Checkpoint Not Found

​Empty Visualization

​Character Encoding Issues

Build docs developers (and LLMs) love

Overview

Core Functions

visualise_pipeline_results()

Example Usage

visualise_clusters()

Output Example

visualise_clusters_enhanced()

Output Example

visualise_clusters_rich()

Features

visualise_from_checkpoint_manager()

Example Usage

Visualization Styles Comparison

Advanced Usage

Custom Console Configuration

Filtering Clusters Before Visualization

Programmatic Tree Building

Integration Examples

With Class-Based API

With Procedural API (v1)

Loading from Checkpoint

Cluster Tree Structure

ClusterTreeNode

Best Practices

Troubleshooting

Rich Not Available

Checkpoint Not Found

Empty Visualization

Character Encoding Issues