AI Topics APIClassify with evidence. Evaluate with care.

Define the classification task first

Decide what the system should classify: a sentence, a whole article, a transcript segment, or a collection of documents. The choice changes what context is available. A short headline may imply a subject that the full article only mentions in passing.

Write a definition and several contrasting examples for each category. Include a boundary example where the correct decision is debatable. Those cases often expose an unclear policy before any model is involved. Editors and developers should be able to explain the same label in similar terms.

Choose a baseline you can inspect

A simple keyword rule can be a useful starting point for a narrow, well-defined category. A trained classifier or language model may recognize wording that the rule misses, but it also introduces new failure modes. Compare approaches on the same documents and the same label definitions.

Record the model or rule version separately from the taxonomy version. A change to the decision engine is different from a change to the meaning of a topic. Keeping both visible helps you investigate whether a shift in assignments reflects content, model behavior, or editorial policy.

Measure the errors that matter

Precision asks how many assigned labels are correct; recall asks how many relevant labels were found. Those questions serve different workflows. An automatic public label may need stricter review than a suggestion shown privately to an editor.

Inspect results by topic, language, document length, and source type. A single average can hide a category that never receives a correct assignment. Keep a held-out set that is separate from examples used to adjust prompts or rules, and record the decisions made when reviewers disagree.

Build a review path into the record

Let uncertain documents move into an explicit review state. Preserve the text excerpt that supports an assignment when your data permissions permit it, and make the reason easy to inspect. An explanation should point to the document rather than simply repeat the category name.

Monitor a sample of accepted assignments after launch. Changes in writing style or subject matter can make earlier evaluation results less representative. Use those observations to update the review set deliberately, with a record of what changed and why.

An illustrative record

This example highlights fields worth discussing when you design your own contract. Define their meanings, allowed values, and review rules before an application relies on them.

{
  "document_id": "example-brief",
  "model_version": "example-classifier-v1",
  "topic_ids": [
    "ai.evaluation"
  ],
  "evidence": "The team compared label errors.",
  "review_status": "needs_review"
}

Illustrative schema and example values; adapt them to your data and review process.

Questions about AI Topics API