Assurance Levels (A0--A3)¶

Four tiers of verification depth -- from "someone said so" to "forensically verified with identity-checked sources."

The Simple Version¶

Figure 5. Assurance levels A0-A3 explained through everyday ID card analogies: every attribution claim carries a trust level from no data (A0) to artist-verified (A3), enabling music industry professionals to assess how much evidence supports each music credit.

Think of different forms of identification:

Music attribution works the same way. When someone claims "I wrote this song," how much evidence backs that claim? A0 means no evidence at all -- just a claim in a file tag. A3 means multiple independent databases agree, and the person has a verified industry identity (ISNI).

The higher the assurance level, the more sources agree and the harder the evidence is to forge.

For Music Industry Professionals¶

What Each Level Means in Practice¶

Industry Identifier Mapping¶

Figure 6. Assurance levels mapped to music industry standard identifiers (ISRC, ISWC, ISNI, IPI): each level requires progressively stronger evidence, from no provenance at A0 to artist-verified identity at A3, while the analog hole warning acknowledges that no level guarantees tamper-proof attribution.

For Engineers¶

Implementation in Schemas¶

Figure 7. The assurance level decision tree evaluates top-down from A3 to A0: artist verification yields A3, cross-database agreement yields A2, any standard identifier yields A1, and absence of all evidence defaults to A0 as a fail-safe classification.

The assurance level is computed at two points in the pipeline: entity resolution and credit aggregation.

Entity Resolution (src/music_attribution/resolution/orchestrator.py):

def _compute_assurance_level(self, records: list[NormalizedRecord]) -> AssuranceLevelEnum:
    """Compute assurance level from available evidence."""
    sources = {r.source for r in records}
    has_isni = any(r.identifiers.isni for r in records)
    has_any_id = any(
        r.identifiers.isrc or r.identifiers.iswc or r.identifiers.mbid
        for r in records
    )

    if has_isni and len(sources) > 1:
        return AssuranceLevelEnum.LEVEL_3
    if len(sources) > 1 and has_any_id:
        return AssuranceLevelEnum.LEVEL_2
    if has_any_id:
        return AssuranceLevelEnum.LEVEL_1
    return AssuranceLevelEnum.LEVEL_0

Credit Aggregation (src/music_attribution/attribution/aggregator.py):

def _compute_assurance(self, entities: list[ResolvedEntity]) -> AssuranceLevelEnum:
    """Compute minimum assurance level across all contributors."""
    levels = [e.assurance_level for e in entities]
    level_order = [
        AssuranceLevelEnum.LEVEL_0,
        AssuranceLevelEnum.LEVEL_1,
        AssuranceLevelEnum.LEVEL_2,
        AssuranceLevelEnum.LEVEL_3,
    ]
    min_idx = min(level_order.index(level) for level in levels)
    return level_order[min_idx]

Threshold Logic¶

The scaffold uses confidence thresholds from src/music_attribution/constants.py to drive review decisions:

CONFIDENCE_HIGH_THRESHOLD: float = 0.85   # Green tier
CONFIDENCE_MEDIUM_THRESHOLD: float = 0.50  # Amber tier
REVIEW_THRESHOLD: float = 0.50             # Below this -> needs_review=True

Assurance level and confidence score interact in the AttributionRecord:

graph TD
    A[AttributionRecord] --> B{confidence_score >= 0.85?}
    B -->|Yes| C[High Confidence<br/>Green tier]
    B -->|No| D{confidence_score >= 0.50?}
    D -->|Yes| E[Medium Confidence<br/>Amber tier]
    D -->|No| F[Low Confidence<br/>Red tier<br/>needs_review=True]

    A --> G{assurance_level?}
    G -->|A3| H[Forensic<br/>Identity-verified]
    G -->|A2| I[Certified<br/>Multi-source]
    G -->|A1| J[Documented<br/>Single identifier]
    G -->|A0| K[Self-declared<br/>No identifiers]

    style C fill:#e8f5e9,stroke:#2e7d32
    style E fill:#fff3e0,stroke:#e65100
    style F fill:#ffebee,stroke:#c62828
    style H fill:#e8f5e9,stroke:#2e7d32
    style I fill:#e1f5fe,stroke:#0277bd
    style J fill:#fff3e0,stroke:#e65100
    style K fill:#f5f5f5,stroke:#757575

Sample Data Distribution¶

The 9 Imogen Heap works in the scaffold demonstrate the full assurance spectrum:

Key Source Files¶

How This Maps to Code¶

The assurance level flows through the entire pipeline:

1. ETL collects identifiers into IdentifierBundle (ISRC, ISWC, ISNI, MBID, etc.)
2. Entity Resolution computes assurance from identifier presence and source count
3. Attribution Engine takes the minimum assurance across all credits
4. API/MCP exposes assurance level as a first-class field on every record
5. Frontend renders assurance as color-coded badges (green/blue/amber/gray for A3/A2/A1/A0)