> ## Documentation Index
> Fetch the complete documentation index at: https://docs.transluce.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Clustering

> Access clustering results for rubric evaluations

After running a rubric evaluation, Docent can cluster judge results to identify
common patterns. See [Search and Clustering](/analysis/search-and-clustering) for a walkthrough.

## Get Clustering State

```python theme={null}
from docent import Docent

client = Docent()

state = client.get_clustering_state("my-collection-id", "rubric-123")
print(f"Job ID: {state.get('job_id')}")
print(f"Centroids: {len(state.get('centroids', []))}")
```

### Parameters

<ParamField body="collection_id" type="str" required>
  ID of the collection.
</ParamField>

<ParamField body="rubric_id" type="str" required>
  ID of the rubric.
</ParamField>

### Returns

<ResponseField name="state" type="dict">
  Clustering state.

  <Expandable title="Fields">
    <ResponseField name="job_id" type="str | None">Clustering job ID.</ResponseField>
    <ResponseField name="centroids" type="list[dict]">List of cluster centroids.</ResponseField>
    <ResponseField name="assignments" type="dict">Mapping of centroid IDs to judge result IDs.</ResponseField>
  </Expandable>
</ResponseField>

***

## Get Cluster Centroids

```python theme={null}
centroids = client.get_cluster_centroids("my-collection-id", "rubric-123")
for centroid in centroids:
    print(centroid)
```

### Parameters

<ParamField body="collection_id" type="str" required>
  ID of the collection.
</ParamField>

<ParamField body="rubric_id" type="str" required>
  ID of the rubric.
</ParamField>

### Returns

<ResponseField name="centroids" type="list[dict]">
  List of centroid information dictionaries.
</ResponseField>

***

## Get Cluster Assignments

```python theme={null}
assignments = client.get_cluster_assignments("my-collection-id", "rubric-123")
for centroid_id, result_ids in assignments.items():
    print(f"Cluster {centroid_id}: {len(result_ids)} results")
```

### Parameters

<ParamField body="collection_id" type="str" required>
  ID of the collection.
</ParamField>

<ParamField body="rubric_id" type="str" required>
  ID of the rubric.
</ParamField>

### Returns

<ResponseField name="assignments" type="dict[str, list[str]]">
  Mapping of centroid IDs to lists of judge result IDs belonging to that cluster.
</ResponseField>