Labels, General Labels, Tags & Comments

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"],
    },
)

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

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)

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)

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,
)

updated = client.update_label(
    "my-collection-id",
    label_set_id,
    label_id="label-123",
    label_value={"quality": "acceptable", "notes": "Resolved after review"},
)
print(updated["id"])

preview = client.delete_labels(
    "my-collection-id",
    label_set_id,
    ["label-123", "label-456"],
)

for label in preview.labels:
    print(label.id, label.label_value)

# Perform the deletion after reviewing the preview.
result = client.delete_labels(
    "my-collection-id",
    label_set_id,
    ["label-123", "label-456"],
    dry_run=False,
)
print(result.message)

from docent.sdk import DeletedLabelPreview, DeleteLabelsResult

general_label_set = client.create_general_label_set(
    "my-collection-id",
    name="Review Findings",
    description="Annotations over runs, transcript slices, and reading results",
    label_schema={
        "type": "object",
        "properties": {
            "severity": {"type": "string", "enum": ["low", "medium", "high"]},
            "summary": {"type": "string"},
        },
        "required": ["severity", "summary"],
    },
    metadata={"source": "human-review"},
)

general_label_sets = client.get_general_label_sets("my-collection-id")
general_label_set = client.get_general_label_set(
    "my-collection-id",
    general_label_set_id,
)

general_label = client.create_general_label(
    "my-collection-id",
    general_label_set_id,
    target={
        "items": [
            {
                "object_type": "transcript_slice",
                "transcript_id": "transcript-123",
                "transcript_slice_start_idx": 4,
                "transcript_slice_end_idx": 8,
            }
        ]
    },
    label_value={
        "severity": "medium",
        "summary": "The answer misses a constraint from the prompt.",
    },
)

general_label = client.get_general_label(
    "my-collection-id",
    label_id="label-123",
)
print(general_label.label_value)

updated = client.update_general_label(
    "my-collection-id",
    general_label_set_id,
    label_id="label-123",
    label_value={
        "severity": "high",
        "summary": "The response violates the core task requirement.",
    },
    metadata={"reviewed_by": "human-reviewer"},
)
print(updated.updated_at)

preview = client.delete_general_labels(
    "my-collection-id",
    general_label_set_id,
    ["label-123", "label-456"],
)

for label in preview.labels:
    print(label.id, label.target)

result = client.delete_general_labels(
    "my-collection-id",
    general_label_set_id,
    ["label-123", "label-456"],
    dry_run=False,
)
print(result.message)

client.tag_transcript("my-collection-id", "run-id-123", "needs-review")

# 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")

client.delete_tag("my-collection-id", tag_id="tag-456")

# 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')}")