LLM Topics APITurn language into a useful contract.

Constrain the vocabulary before the output

An open-ended request for topics may produce a different spelling or level of detail each time. That can be useful during exploration, but a stable application usually needs a defined set of concepts. Supply IDs, definitions, and the permitted assignment range, including zero when no topic fits.

Separate discovery from classification. Discovery helps you notice a subject missing from the vocabulary. Classification applies the vocabulary that already exists. A proposed new concept should enter an editorial review process rather than immediately becoming a production category.

Validate shape and meaning separately

A JSON contract can describe required fields, permitted values, and the expected type of each field. A valid object is easier for software to consume. It does not establish that the selected topic is justified by the source text.

Add semantic checks after structural validation. Confirm that the selected IDs exist in the intended taxonomy version, that quoted evidence appears in the document, and that the result follows your policy for primary and secondary subjects. Route failures to a clear review state.

Treat document text as untrusted input

The content being classified may contain instructions, quoted prompts, code, or deliberately misleading text. Keep the classification policy separate from the document and instruct the workflow to treat the document as evidence rather than as authority over the task.

A prompt is one part of a larger boundary. Use constrained output where available, limit the model’s privileges, and validate before downstream use. A topic labeling step rarely needs the ability to send messages, execute document instructions, or change unrelated records.

Make retries observable and bounded

If a response fails validation, capture the reason and use a limited retry policy. Avoid unlimited attempts that quietly increase cost or eventually accept a different interpretation. A reviewable failure is often more useful than a successful-looking record with unknown reliability.

Track model configuration, prompt version, and taxonomy version with each evaluation run. When an output changes, these details help you reproduce the conditions and decide whether the new behavior improves the actual reader or editor task.

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.

{
  "taxonomy_version": "demo-v1",
  "topic_ids": [
    "publishing.metadata"
  ],
  "evidence": [
    "The archive uses structured subject labels."
  ],
  "status": "review"
}

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

Questions about LLM Topics API