Skip to main content
A collection is a container for agent runs, rubrics, and evaluation results. See Introduction for more on how collections fit into the Docent workflow.

​
Create a Collection

from docent import Docent

client = Docent()

collection_id = client.create_collection(
    name="GPT-4 Customer Support Runs",
    description="Production runs from the support agent",
    metadata={"team": "support", "model": "gpt-4"},
)
print(collection_id)  # e.g., "a1b2c3d4-..."

​
Parameters

​
collection_id
str | None
Optional ID for the new collection. If not provided, one is generated automatically.
​
name
str | None
Display name for the collection.
​
description
str | None
Description of the collection’s purpose.
​
metadata
dict | None
Arbitrary key-value metadata to attach to the collection.

​
Returns

​
collection_id
str
The ID of the created collection.

​
List Collections

collections = client.list_collections()
for c in collections:
    print(f"{c['id']}: {c['name']}")

​
Returns

​
collections
list[dict]
List of collection objects.

​
Get a Collection

import requests

try:
    collection = client.get_collection("my-collection-id")
    print(collection["name"])
except requests.exceptions.HTTPError as e:
    if e.response.status_code == 404:
        print("Collection not found")
    else:
        raise

​
Parameters

​
collection_id
str
required
ID of the collection to retrieve.

​
Returns

​
collection
dict
The collection object with id, name, description, created_at, and created_by.

​
Errors

  • HTTPError (404) — Collection not found

​
Update a Collection

client.update_collection(
    "my-collection-id",
    name="Renamed Collection",
    description="Updated description",
)

​
Parameters

​
collection_id
str
required
ID of the collection to update.
​
name
str | None
New name. If None, the name is left unchanged.
​
description
str | None
New description. If None, the description is left unchanged.

​
Check if a Collection Exists

if client.collection_exists("my-collection-id"):
    print("Collection found")

​
Parameters

​
collection_id
str
required
ID of the collection to check.

​
Returns

​
exists
bool
True if the collection exists, False otherwise.

​
Delete Agent Runs

Remove specific agent runs from a collection. 
deleted = client.delete_agent_runs("my-collection-id", ["run-1", "run-2"])
print(f"Deleted {deleted} runs")

​
Parameters

​
collection_id
str
required
ID of the collection.
​
agent_run_ids
list[str]
required
List of agent run IDs to delete.

​
Returns

​
deleted_count
int
Number of agent runs deleted.

​
Errors

  • ValueError — agent_run_ids is empty
  • HTTPError (404) — Collection not found