Core Concepts

The five-agent pipeline

Every metadata record passes through five agents in a fixed sequence. Candidate issues accumulate through the first two passes; the critic filters them; the categorizer labels the survivors; the severity scorer assigns impact and closes the pipeline.

Agent	Receives	Outputs	Role
primary	The raw metadata record	JSON array of candidate issues	Independent first-pass scan for all issue types. Precision is preferred, but obvious errors must not be omitted.
secondary	The raw metadata record	JSON array of candidate issues	An independent re-scan that does not rely on the primary's output, to surface issues the primary may have missed.
critic	Combined list from primary + secondary	Filtered JSON array	Removes false positives by applying the general, field-level, and data-state exclusion rules (see Advanced Usage). Only unambiguous issues pass.
categorizer	The critic's filtered list	Same array, with issue_category added	Annotates each surviving issue with exactly one category. Adds or removes nothing.
severity_scorer	The categorizer's list	Final array, with issue_severity added	Assigns a 1–5 impact score to each issue and emits the termination signal that ends the run.

Why two detectors?

Running two independent first-pass scans (primary and secondary) increases recall: a single pass tends to miss issues, while a second, independent pass catches them. The critic then trims the combined list back down to only the certain errors, trading a little extra LLM cost for higher coverage.

Issue categories

The categorizer assigns exactly one label to each confirmed issue. The bundled default manifest uses these five categories:

Category	Meaning
Typo / Language	Clear typos, spelling, grammar, punctuation, or wording errors.
Formatting / Structure	Malformed text, invalid format patterns, or broken structure.
Missing / Redundant Information	Unquestionably missing required information, or accidental duplication.
Inconsistency / Conflict	Direct contradictions across fields.
Incorrect / Invalid Content	Clearly wrong facts, values, units, methods, or invalid values.

Severity scale

The severity scorer assigns an integer from 1 to 5 based on impact, not certainty — every issue reaching this stage has already passed the certainty filter, so even minor issues are scored rather than dropped.

Score	Label	Meaning
1	Trivial	A clear error, but cosmetic with minimal practical impact.
2	Low	A minor confirmed quality issue; the meaning remains mostly clear.
3	Moderate	A confirmed issue that may confuse users or reduce trust.
4	High	A confirmed issue likely to mislead or to affect correct use.
5	Critical	A confirmed issue with serious risk of misuse or reputational harm.

Output schema

The pipeline returns a JSON array. Each element describes one detected issue using the following fields:

Field	Description
detected_issue	A brief description of the problem identified.
issue_category	One of the category labels from Issue categories.
issue_severity	An integer 1–5 from the severity scale.
current_metadata	A single-entry object mapping the problematic field's key path to its current value.
suggested_metadata	A single-entry object mapping the same key path to the proposed corrected value.

Key paths use dot notation with array indices in brackets — for example series_description.name or series_description.topics[0].name. Both current_metadata and suggested_metadata contain exactly one item, so an issue always points at one specific field.

Architecture: Client, Core, and Job

The implementation is split across three classes with distinct responsibilities:

Class	Responsibility
MetadataReviewerClient	The public entry point. Builds the model client, submits jobs (synchronously or asynchronously), tracks job state, and exposes cancellation and cleanup. This is the only class most users touch.
MetadataReviewerCore	The pipeline engine. On each run it loads the agent manifest, constructs the AutoGen agents, assembles the team, runs the conversation, and extracts the final JSON. It holds no provider-specific logic.
Job	A handle for one submitted request. Carries the job_id, current status, the result once complete, and any error. Returned immediately from every submission.

The client owns the model_client (the LLM connection) and passes it down to the core, which in turn passes it to every agent. This is what keeps the design provider-agnostic: all LLM communication flows through that single injected reference.