Expose per-label detection examples in the public configuration API

Priority Level

Medium (Nice to have)

Is your feature request related to a problem?

Entity-label examples are an important quality lever for datasets containing domain-specific formats, such as vendor API keys, account handles, or organization-specific identifiers. Today these examples are stored in the internal anonymizer.engine.constants.ENTITY_LABEL_EXAMPLES mapping.

Users can technically mutate that mapping before calling run() or preview(), but this is not a supported API. It also changes process-global state, can leak between jobs with different requirements, may affect detection, substitution, and evaluation unexpectedly, and does not automatically activate a newly added label in the default detection set.

This came up while tuning detection for developer-agent task transcripts. Narrow positive examples could help distinguish vendor-prefixed API keys and actual account handles, while broad examples such as generic hexadecimal strings, UUIDs, and complete file paths could reinforce false positives such as message_hash values or repository names.

Describe the solution you'd like

Expose per-label positive examples as supported, per-run user configuration. One possible API is:

config = AnonymizerConfig(
    detect=Detect(
        entity_labels=["api_key", "user_name", "email"],
        entity_label_examples={
            "api_key": [
                "sk-ant-api03-abc123def456xyz",
                "OPENAI_API_KEY=sk-proj-abc123def456",
            ],
            "user_name": ["jsmith", "alice.chen", "@trudy-spies"],
        },
    ),
    replace=Annotate(),
)

Suggested behavior:

• Configuration is resolved independently for each run and never mutates module-level defaults.
• User examples merge with built-in examples by default. The merge/replace behavior should be documented explicitly.
• Label names are normalized consistently with Detect.entity_labels.
• When entity_labels is explicit, example-map keys must belong to that list; unmatched keys should produce a clear validation error.
• Adding examples for a new label must not silently add that label to the active detection set.
• Resolved examples are passed to the detection validator and augmenter prompts.
• Any use by substitute or evaluation workflows should be intentional and documented rather than occurring as a side effect of global state.
• Examples are documented as positive examples, not as a mechanism for expressing guaranteed exclusions.

Acceptance criteria:

• A public typed configuration field supports per-label examples.
• Two configurations with different examples can run in the same process without cross-run contamination.
• Validation covers empty labels/examples, normalized duplicate keys, and keys outside an explicit entity_labels list.
• Detection prompt tests verify that configured examples appear only for the corresponding active labels.
• Public documentation includes a dataset-specific example and explains when deterministic exclusions or data_summary are more appropriate.
• The bundled anonymizer agent skill is updated if its public configuration template is affected.

Describe alternatives you've considered

• Mutating anonymizer.engine.constants.ENTITY_LABEL_EXAMPLES. This works only as an internal, process-global workaround and is unsuitable as a supported recommendation.
• Encoding positive examples in data_summary. This mixes dataset context with label ontology and provides no structured validation.
• Using only custom label names. Label names constrain the ontology but do not demonstrate domain-specific value formats.
• Using a larger validation model. This may improve contextual reasoning but increases cost and does not replace explicit domain examples.

Additional context

This complements, rather than replaces, the existing quality controls:

• Explicit entity_labels constrain which labels augmentation may emit.
• data_summary supplies contextual guidance, including negative distinctions, but does not enforce exclusions.
• validation_excerpt_window_chars provides additional surrounding context.
• Deterministic rules remain preferable for guaranteed exclusions such as known non-sensitive JSON fields.