> ## 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.

# Labels, Tags & Comments

> Annotate agent runs with structured labels, tags, and comments

Docent provides three annotation mechanisms for agent runs:

* **Label sets** — structured annotations validated against a JSON schema
* **Tags** — lightweight string annotations
* **Comments** — free-text notes

See [Labeling Agent Runs](/analysis/labeling) for a tutorial.

## Label Sets

### Create a Label Set

Define a new label set with a JSON schema that all labels must conform to.

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

client = Docent()

label_set_id = client.create_label_set(
    "my-collection-id",
    name="Quality Assessment",
    description="Human quality ratings for agent responses",
    label_schema={
        "type": "object",
        "properties": {
            "quality": {"type": "string", "enum": ["good", "acceptable", "poor"]},
            "notes": {"type": "string"},
        },
        "required": ["quality"],
    },
)
```

#### Parameters

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

<ParamField body="name" type="str" required>
  Display name for the label set.
</ParamField>

<ParamField body="label_schema" type="dict" required>
  JSON schema for validating labels. Must be a valid JSON Schema object.
</ParamField>

<ParamField body="description" type="str | None">
  Optional description.
</ParamField>

#### Returns

<ResponseField name="label_set_id" type="str">
  ID of the created label set.
</ResponseField>

### List Label Sets

```python theme={null}
label_sets = client.get_label_sets("my-collection-id")
for ls in label_sets:
    print(f"{ls['id']}: {ls['name']}")
```

### Add a Label

```python theme={null}
from docent.data_models.judge import Label

label = Label(
    label_set_id=label_set_id,
    agent_run_id="run-id-123",
    label_value={"quality": "good", "notes": "Clear and helpful response"},
)
result = client.add_label("my-collection-id", label)
```

### Add Multiple Labels

```python theme={null}
labels = [
    Label(
        label_set_id=label_set_id,
        agent_run_id=run_id,
        label_value={"quality": "good"},
    )
    for run_id in run_ids
]
result = client.add_labels("my-collection-id", labels)
```

### Get Labels

```python theme={null}
labels = client.get_labels("my-collection-id", label_set_id)

# Only get labels that pass schema validation (including required fields)
valid_labels = client.get_labels(
    "my-collection-id",
    label_set_id,
    filter_valid_labels=True,
)
```

#### Parameters

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

<ParamField body="label_set_id" type="str" required>
  ID of the label set.
</ParamField>

<ParamField body="filter_valid_labels" type="bool" default="False">
  If `True`, only return labels that fully match the label set schema including
  required fields. Default returns all labels.
</ParamField>

***

## Tags

Lightweight string annotations on agent runs.

### Add a Tag

```python theme={null}
client.tag_transcript("my-collection-id", "run-id-123", "needs-review")
```

### Get Tags

```python theme={null}
# All tags in a collection
all_tags = client.get_tags("my-collection-id")

# Filter by value
review_tags = client.get_tags("my-collection-id", value="needs-review")

# Tags for a specific run
run_tags = client.get_tags_for_agent_run("my-collection-id", "run-id-123")
```

### Delete a Tag

```python theme={null}
client.delete_tag("my-collection-id", tag_id="tag-456")
```

***

## Comments

Free-text notes on agent runs.

### Get Comments

```python theme={null}
# All comments in a collection
comments = client.get_comments("my-collection-id")

# Comments for a specific run
run_comments = client.get_comments_for_agent_run("my-collection-id", "run-id-123")
for c in run_comments:
    print(f"{c.get('created_by')}: {c.get('text')}")
```