Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/jxnl/kura/llms.txt

Use this file to discover all available pages before exploring further.

​
MetaClusterModel

Model for reducing clusters into a hierarchical structure by iteratively combining similar clusters.

​
Constructor

MetaClusterModel(
    max_concurrent_requests: int = 50,
    model: str = "openai/gpt-4o-mini",
    embedding_model: Optional[BaseEmbeddingModel] = None,
    clustering_model: Union[BaseClusteringMethod, None] = None,
    max_clusters: int = 10,
    console: Optional["Console"] = None,
    **kwargs,
)
​
max_concurrent_requests
int
default:"50"
Maximum concurrent API requests
​
model
str
default:"openai/gpt-4o-mini"
Model identifier for LLM calls
​
embedding_model
Optional[BaseEmbeddingModel]
default:"None"
Embedding model to use (defaults to OpenAIEmbeddingModel)
​
clustering_model
Union[BaseClusteringMethod, None]
default:"None"
Clustering method to use (defaults to KmeansClusteringModel with 12 items per cluster)
​
max_clusters
int
default:"10"
Target number of root clusters in final hierarchy
​
console
Optional[Console]
default:"None"
Rich console for progress tracking

​
Methods

​
reduce_clusters()

Takes a list of existing clusters and generates higher-order clusters that are more general. This represents a single iteration of the meta clustering process. 
async def reduce_clusters(clusters: list[Cluster]) -> list[Cluster]
​
clusters
list[Cluster]
required
List of clusters to reduce into higher-level groupings
​
return
list[Cluster]
List of clusters including both new meta-clusters (parent_id=None) and updated original clusters (with parent_id set)
Note: In the event of a single cluster, returns a new higher level cluster with the same name as the original cluster.

​
generate_meta_clusters()

Generates meta-clusters from a group of clusters by creating candidate labels and organizing them hierarchically. 
async def generate_meta_clusters(
    clusters: list[Cluster],
    show_preview: bool = True
) -> list[Cluster]
​
clusters
list[Cluster]
required
List of clusters to organize into meta-clusters
​
show_preview
bool
default:"True"
Whether to show live preview of generated meta-clusters
​
return
list[Cluster]
List of clusters including meta-clusters and their children

​
generate_candidate_clusters()

Generate higher-level cluster names based on a given list of clusters. 
async def generate_candidate_clusters(
    clusters: list[Cluster],
    sem: Semaphore
) -> list[str]
​
clusters
list[Cluster]
required
List of clusters to analyze for creating candidate labels
​
sem
Semaphore
required
Asyncio semaphore for rate limiting
​
return
list[str]
List of candidate cluster names that could encompass multiple sub-clusters

​
label_cluster()

Categorize a specific cluster into one of the provided higher-level clusters. 
async def label_cluster(
    cluster: Cluster,
    candidate_clusters: list[str]
)
​
cluster
Cluster
required
Cluster to categorize
​
candidate_clusters
list[str]
required
List of valid higher-level cluster names to choose from
​
return
dict
Dictionary with keys “cluster” (original Cluster object) and “label” (selected higher-level cluster name)

​
rename_cluster_group()

Summarize a group of related clusters into a new meta-cluster with a unified name and description. 
async def rename_cluster_group(clusters: list[Cluster]) -> list[Cluster]
​
clusters
list[Cluster]
required
List of related clusters to summarize
​
return
list[Cluster]
List containing the new meta-cluster (first item, parent_id=None) followed by updated original clusters (with parent_id set to the new meta-cluster’s ID)

​
reduce_clusters_from_base_clusters()

Reduce clusters into a hierarchical structure. Iteratively combines similar clusters until the number of root clusters is less than or equal to the model’s max_clusters setting. 
async def reduce_clusters_from_base_clusters(
    clusters: list[Cluster],
    *,
    model: BaseMetaClusterModel,
    checkpoint_manager: Optional[BaseCheckpointManager] = None,
) -> list[Cluster]
​
clusters
list[Cluster]
required
List of initial clusters to reduce
​
model
BaseMetaClusterModel
required
Meta-clustering model to use for reduction
​
checkpoint_manager
Optional[BaseCheckpointManager]
default:"None"
Optional checkpoint manager for caching
​
return
list[Cluster]
List of clusters with hierarchical structure (includes both root and child clusters)
Example: 
from kura.meta_cluster import (
    MetaClusterModel,
    reduce_clusters_from_base_clusters
)

# Create meta-clustering model with target of 5 root clusters
meta_model = MetaClusterModel(max_clusters=5)

# Reduce base clusters into hierarchy
reduced = await reduce_clusters_from_base_clusters(
    clusters=base_clusters,
    model=meta_model,
    checkpoint_manager=checkpoint_mgr
)

# Get only root clusters
root_clusters = [c for c in reduced if c.parent_id is None]
print(f"Reduced to {len(root_clusters)} root clusters")

Build docs developers (and LLMs) love

Get started for freeTalk to us