The Connector Graveyard: What Multi-Model Pipeline Code Actually Looks Like.

tag = token["entity"] word = token["word"] score = token["score"]

    if tag.startswith("B-"):
        if current_entity is not None:
            avg_score = sum(current_scores) / len(current_scores)
            if avg_score >= confidence_threshold:
                assembled = "".join(
                    t.replace("##", "") for t in current_tokens
                )
                start_idx = max(0, current_start - 30)
                end_idx = min(len(original_text), token["start"] + 30)
                context = original_text[start_idx:end_idx]

                entities.append({
                    "text": assembled,
                    "entity_type": current_entity,
                    "context_window": context,
                    "threshold": confidence_threshold
                })

        current_entity = tag[2:]
        current_tokens = [word]
        current_start = token.get("start", 0)
        current_scores = [score]

    elif tag.startswith("I-") and current_entity is not None:
        current_tokens.append(word)
        current_scores.append(score)
    else:
        current_entity = None
        current_tokens = []
        current_scores = []

if current_entity is not None:
    avg_score = sum(current_scores) / len(current_scores)
    if avg_score >= confidence_threshold:
        assembled = "".join(t.replace("##", "") for t in current_tokens)
        entities.append({
            "text": assembled,
            "entity_type": current_entity,
            "context_window": original_text[-60:],
            "threshold": confidence_threshold
        })

return entities

def transform_classifier_outputs_to_scorer_input( classifier_outputs: list, policy_id: str, strict_mode: bool = True ) -> dict: """ Aggregate classifier results into scorer input format.

NOTE: scorer expects "role" not "obligation_type" - same concept, different name
NOTE: scorer expects "party" not "text" - same concept, different name
NOTE: prior_confidence is in metadata.confidence in v2.1+, top-level in v2.0

If classifier returns no obligations above 0.8, scorer returns 422.
Handle that in the caller. See bug 1089.
"""
obligations = []

for item in classifier_outputs:
    if isinstance(item, list):
        result = item[0] if item else None
    elif isinstance(item, dict):
        result = item
    else:
        continue

    if result is None:
        continue

    role = result.get("obligation_type") or result.get("role")
    party = result.get("text") or result.get("party")

    metadata = result.get("metadata", {})
    confidence = metadata.get("confidence") or result.get("confidence", 0.0)

    if role and party:
        obligations.append({
            "party": party,
            "role": role,
            "prior_confidence": confidence
        })

return {
    "obligations": obligations,
    "policy_id": policy_id,
    "strict_mode": strict_mode
}

**Architecture Decisions & Implementation Strategy:**
1. **Intermediate Representation (IR)**: Define a unified schema that all models must conform to before/after inference. Example: `ExtractedEntity`, `ClassifiedObligation`, `ComplianceScore`.
2. **Strict Pydantic/JSON Schema Contracts**: Replace ad-hoc dict parsing with validated models. Enforce field names, types, and versioning at ingestion.
3. **Declarative Transformation DAG**: Map raw model outputs → IR → downstream inputs using configuration-driven transformers instead of imperative functions.
4. **Validation Gates**: Inject pre-flight schema checks that catch 422 errors, threshold violations, and tokenization mismatches before pipeline execution.
5. **Context Window Standardization**: Replace hardcoded offsets (`-30`, `+30`, `-60`) with character-boundary-aware slicing tied to the original document span.

## Pitfall Guide
1. **Wordpiece Tokenization Reassembly Blindness**: BERT-based extractors split words into subword tokens (`##c`, `##me`). Naive string concatenation or ignoring the `##` prefix corrupts entity boundaries. Always implement explicit reassembly logic that strips prefixes and respects token indices.
2. **Semantic Field Name Drift**: Different models use divergent keys for identical concepts (`obligation_type` vs `role`, `text` vs `party`). Relying on `.get()` fallback chains masks schema changes. Enforce canonical field names via IR mapping and fail-fast on missing keys.
3. **Context Window Boundary Miscalculation**: Fixed character offsets (`-30`, `+60`) ignore token/character alignment and document length. This causes `IndexError` or truncated context. Use span-aware slicing anchored to `start`/`end` indices with explicit boundary clamping.
4. **Version-Dependent Metadata Parsing**: Confidence scores and model metadata shift between versions (e.g., `metadata.confidence` in v2.1 vs top-level `confidence` in v2.0). Hardcoded dict traversal breaks on minor updates. Implement version-aware parsers with explicit fallback contracts.
5. **Hardcoded Thresholds & Error Suppression**: Filtering low-confidence entities or catching 422s without explicit contracts leads to silent data loss. Thresholds should be configurable pipeline parameters, not magic numbers embedded in translation logic.
6. **Pairwise Connector Proliferation**: Writing N² connectors for N models creates unmanageable technical debt. Each new model requires rewriting existing bridges. Adopt a hub-and-spoke IR pattern to reduce complexity to O(N).

## Deliverables
- **📘 Schema Contract & IR Architecture Blueprint**: Step-by-step guide to designing intermediate representations, defining Pydantic/JSON Schema contracts, and implementing validation gates for multi-model pipelines. Includes DAG execution patterns and versioning strategies.
- **✅ Pre-Deployment Schema Validation Checklist**: 14-point audit covering field name standardization, tokenization reassembly, context window boundaries, threshold configurability, metadata versioning, and 422 error handling. Use before merging any connector code.
- **⚙️ Configuration Templates**: Production-ready Pydantic models and YAML transformation specs for NER → IR, Classifier → IR, and Scorer → IR stages. Includes fallback mappings, threshold injection hooks, and span-aware context extraction utilities.