feat(detect): chunked validation with validator pools

[lipikaramaswamy]

Summary

Replaces the single per-row entity-validation LLM call with a chunked dispatch that partitions each row's candidates and rotates them across a configurable pool of validator aliases. This unblocks rows with many candidates (which can exceed the validator's context window or the provider's rate limits as a single call), gives users a quota-aggregation knob, and hardens validation against transient provider issues — all without changing defaults or single-validator behaviour.

• New Detect config knobs. validation_max_entities_per_call (default 100) bounds per-call candidate count; validation_excerpt_window_chars (default 500) bounds the text context per chunk. Rows under the candidate limit dispatch as one call, exactly equivalent to the prior path.
• entity_validator accepts list-form. A single alias remains valid (normalized to a one-element list); multiple aliases form a validator pool. Pools now serve two jobs:
  1. Load spreading. Chunks are dispatched round-robin by chunk index, aggregating quota across equivalent endpoints to work around per-alias rate limits.
  2. Failover. If a chunk's assigned alias can't complete the call (unrecoverable rate limit, persistent 5xx, malformed response), the same chunk is automatically retried against the other aliases in the pool before the row is dropped. A chunk only fails once every alias in the pool has failed for it. Single-alias pools behave exactly as before.
• Internal helper split (not user-facing). The list-form change to entity_validator required splitting anonymizer.engine.ndd.model_loader.resolve_model_alias into a scalar helper (unchanged for the 12 still-scalar roles) and a new plural helper resolve_model_aliases() that returns list[str] for list-valued roles and wraps scalars in a one-element list for uniformity. resolve_model_alias("entity_validator", ...) now raises TypeError rather than silently returning a list. All in-repo callers are updated. These helpers are not re-exported from anonymizer.__init__ and are not part of the public package surface, so no supported external consumers are affected; the TypeError is a loud, trivially-triagable signal for anyone who had imported the private path directly.
• Row-level failure contract. A row is only dropped when every alias in the pool has failed on at least one of its chunks. Dropped rows surface on result.failed_records with step="detection", not as silent passthrough with un-scrubbed text. anonymizer validate reports unknown pool aliases by index.
• Chunked validation via CustomColumnConfig in a new chunked_validation module: position-ordered chunking, per-chunk text excerpts with forced-consistent tag notation per row, per-chunk Jinja prompt rendering, dispatch through sync ModelFacade.generate (wrapped in asyncio.to_thread for per-row chunk concurrency) + PydanticResponseRecipe, and merged output back into COL_VALIDATION_DECISIONS. The sync facade path is required because DataDesigner's default thread-pool engine hands custom columns sync-mode HttpModelClient facades whose agenerate raises; it is also forward-compatible with the async engine after Anonymizer#119 + DD#545 land, since DD#545 bridges sync .generate() calls to agenerate transparently. Decisions for ids outside the candidate set are dropped, mirroring the legacy enrich_validation_decisions filter.
• Operator warning when len(pool) > 1, noting that max_parallel_requests is enforced per alias so pooling multiplies total in-flight calls — rate-limit budget accordingly.
• Docs. New "Chunked validation" section on the detection concept page covering both knobs and tuning direction. Updated "Validator pools" subsection on the models page covering both load-spreading and failover roles with YAML example, plus a "What happens when a row can't be validated" subsection on the detection page documenting the row-drop + failed_records contract.
• Tests. Unit coverage of every pure helper in the chunked module; async chunked_validate_row coverage for pool-of-one, pool-of-two round-robin, multi-chunk reassembly, missing-id drop, and bad-config guards; cross-alias failover coverage (primary-fails-secondary-succeeds, whole-pool-exhausted, single-alias-no-failover, wrap-around order); workflow-level tests for the new CustomColumnConfig wiring and kwarg threading; regression test pinning the DD-exposed wrapper as sync (guards against re-introducing the coroutine-return bug); behavioural regression test pinning 1-chunk vs 3-chunk parity for COL_VALIDATION_DECISIONS and COL_DETECTED_ENTITIES under identical deterministic LLM behaviour.
• Verified against build.nvidia.com. 3-row smoke run with validation_max_entities_per_call=3 and a {gpt-oss-120b, nemotron-30b-thinking} pool dispatched 30 chunks across the pool, hit a live 429 on one chunk, failed over to the other alias, recovered, and completed with 0 dropped rows.

What users write

Chunking knobs on the Python Detect config — safe defaults mean most users never touch these:

from anonymizer import Anonymizer, AnonymizerConfig, Detect, Redact
config = AnonymizerConfig(
    detect=Detect(
        validation_max_entities_per_call=50,   # smaller chunks -> more calls, less context per call
        validation_excerpt_window_chars=800,   # more text context per chunk
    ),
    replace=Redact(),
)

List-form entity_validator in the models YAML to spread validation across aliases:

selected_models:
  detection:
    entity_detector: gliner-pii-detector
    entity_validator:
      - gpt5-primary
      - gpt5-secondary
    entity_augmenter: gpt5-primary
    latent_detector: claude-sonnet

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Refactoring

Testing

• make test passes locally
• make check passes locally (format + lint + typecheck + lock-check)
• Added/updated tests for changes

Documentation

• If docs changed: make docs-build passes locally

[andreatgretel]

Additional comments on unchanged lines:

src/anonymizer/engine/ndd/model_loader.py:95 - str(value) in load_workflow_selections will silently mangle a list - now that entity_validator supports list-form, this becomes a trap if someone adds a pool to the bundled detection.yaml. maybe preserve native types here (return {str(key): value for ...}) or at least add a comment warning about it?

src/anonymizer/engine/detection/custom_columns.py:138 - build_validation_skeleton is no longer used in the detection pipeline (replaced by build_chunk_skeleton in the chunked path). worth removing to avoid confusion about which skeleton builder is authoritative?

[andreatgretel]

LGTM! Two minor follow-ups:

1. merge_chunk_decisions: seen.add() runs before null-decision filtering - a null entry can shadow a valid decision for the same ID from another chunk. Unlikely since candidates partition cleanly, but the insertion order is technically wrong.

2. Single-chunk rows now go through build_chunk_excerpt() with a 500-char window instead of getting the full tagged text. A fast path for len(chunks) == 1 would preserve parity with the old behavior.

[lipikaramaswamy]

smoke_chunked_validation.py
Just tracking the file i used to test chunked validation