Music Attribution Scaffold

<p align="center"> <a href="https://youtu.be/7wuUiH8YmSQ?si=6TwuK7evAKFHoi_i"> <img src="docs/figures/repo-figures/screenshots/youtube_demo.png" width="720" alt="Watch the 1-minute MVP demo on YouTube — confidence scoring, provenance timelines, and MCP permission queries in action." /> </a> </p> <p align="center"><strong>▶ <a href="https://youtu.be/7wuUiH8YmSQ?si=6TwuK7evAKFHoi_i">Watch the 1-minute demo</a></strong> · <strong>📄 <a href="https://dx.doi.org/10.2139/ssrn.6109087">Read the paper</a></strong> (supplementary material includes an annotated screenshot walkthrough)</p>

Research-grade music attribution infrastructure with calibrated confidence scoring, multi-source entity resolution, and machine-readable consent.

Music metadata is broken — over 40% of records are incorrect or incomplete across databases that don't talk to each other. When generative AI adds millions of new tracks per month, knowing who made what becomes both a legal and economic emergency. This scaffold provides the open-source infrastructure to address it.

<p align="center"> <img src="docs/figures/repo-figures/assets/fig-repo-01-hero-overview.jpg" width="720" alt="Overview of the Music Attribution Scaffold: editorial frontend with confidence gauges, assurance badges, review queue, and agentic sidebar for natural-language attribution queries across multi-source music metadata." /> </p> <p align="center"><em>The scaffold unifies fragmented music metadata into confidence-scored attribution records with transparent provenance.</em></p>

---

What It Does

| Capability | What It Means | Deep Dive | |---|---|---| | Multi-source ETL | Fetches and normalizes metadata from MusicBrainz, Discogs, AcoustID, audio file tags, and artist self-reports | src/music_attribution/etl/ · Docs | | Entity resolution | 5-strategy cascade: identifiers → fuzzy strings → embeddings → graph → LLM disambiguation | src/music_attribution/resolution/ · Docs | | Calibrated confidence | Per-field scores via conformal prediction — "90% confident" actually means ≥90% coverage | src/music_attribution/attribution/ · Docs | | Permission patchbay | MCP server for machine-readable AI training consent (ALLOW / DENY / ASK) | src/music_attribution/mcp/ · Docs | | Agentic UI | PydanticAI agent + CopilotKit sidebar for natural-language attribution queries | src/music_attribution/chat/ · Docs | | Voice agent | Pipecat voice pipeline with 5-dimension persona, drift detection, and domain tools | src/music_attribution/voice/ · Guide | | Editorial frontend | Next.js 15 with confidence gauges, assurance badges, review queue | frontend/ · Docs |

<details> <summary><strong>How does the 5-strategy entity resolution cascade work?</strong></summary>

Entity resolution answers: "Is the 'Imogen Heap' in MusicBrainz the same person as 'I. Heap' in a Discogs release?" The cascade progresses from cheap/certain to expensive/uncertain:

1. Identifier matching — Exact ISRC, ISWC, ISNI, or MBID match. Cheapest and most reliable.
2. String similarity — Jaro-Winkler and token-sort ratio on canonical names and aliases. Handles typos and transliterations.
3. Embedding similarity — Sentence-transformer embeddings compared via cosine similarity. Catches semantic equivalences that string metrics miss (e.g., "紫雨林" ↔ "Jaurim").
4. Graph evidence — Shared collaborators, labels, or recordings boost match probability via Jaccard coefficient.
5. LLM disambiguation — For remaining ambiguous cases, an LLM evaluates contextual evidence. Cost-gated and cached.

Each stage produces a confidence score. The cascade short-circuits: if Stage 1 finds a high-confidence match, Stages 2–5 are skipped.

References: Fellegi & Sunter (1969) — foundational probabilistic record linkage model; Papadakis et al. (2021) — modern entity resolution survey.

</details>

---

Architecture

Five sequential pipelines connected by typed Pydantic boundary objects:

<p align="center"> <img src="docs/figures/repo-figures/assets/fig-repo-02-five-pipeline-architecture.jpg" width="720" alt="Architecture diagram: five-pipeline data flow for music attribution showing ETL ingestion from MusicBrainz and Discogs, entity resolution with fuzzy matching, transparent confidence scoring engine, FastAPI REST and MCP permission server, and PydanticAI chat interface." /> </p>

  I. ETL          II. ENTITY         III. ATTRIBUTION    IV. API/MCP      V. CHAT
  PIPELINE         RESOLUTION         ENGINE
  ┌─────────┐     ┌─────────────┐    ┌────────────┐     ┌──────────┐    ┌──────┐
  │ Discogs │     │ Fuzzy match │    │ Confidence │     │ FastAPI  │    │ AI   │
  │ MBrainz │────▶│ + dedupe    │───▶│ scoring +  │────▶│ REST +   │───▶│ Chat │
  │ AcoustID│     │ + graph     │    │ provenance │     │ MCP      │    │      │
  └─────────┘     └─────────────┘    └────────────┘     └──────────┘    └──────┘
       │                │                  │                  │              │
  NormalizedRecord  ResolvedEntity   AttributionRecord    JSON + MCP     AG-UI SSE

  Cross-cutting: BatchEnvelope · DriftDetector · PipelineFeedback
  Storage:       PostgreSQL + pgvector

Each boundary crossing carries validation, confidence scores, and provenance metadata. Reverse feedback flows (dispute signals, recalibration requests) travel upstream via PipelineFeedback objects.

Full architecture docs: Architecture Overview · Backend Guide · docs/architecture/

---

Quick Start

Prerequisites

• Python 3.13+ and uv
• Docker and Docker Compose (for PostgreSQL + pgvector)
• Node.js 18+ and npm (for the frontend)

Setup

git clone https://github.com/petteriTeikari/music-attribution-scaffold.git
cd music-attribution-scaffold

# Install deps, start Docker, run migrations, seed Imogen Heap data
make setup

# Start the backend API + PostgreSQL
make dev
# → http://localhost:8000 (Swagger at /docs)

# In a second terminal: start the frontend
make dev-frontend
# → http://localhost:3000

# Or: full agentic UI (backend + CopilotKit sidebar)
make agent

<details> <summary><strong>Environment variables</strong></summary>

| Variable | Required | Default | Purpose | |---|---|---|---| | DATABASE_URL | Yes | — | PostgreSQL connection string | | ANTHROPIC_API_KEY | For agent | — | Anthropic API key for the PydanticAI agent | | ATTRIBUTION_AGENT_MODEL | No | anthropic:claude-haiku-4-5 | PydanticAI model string | | CORS_ORIGINS | No | http://localhost:3000 | Comma-separated CORS origins | | NEXT_PUBLIC_API_URL | No | http://localhost:8000 | Backend URL for the frontend | | LOG_LEVEL | No | INFO | Python logging level | | ENVIRONMENT | No | development | Runtime environment |

Create a .env file in the project root, or export directly. See src/music_attribution/config.py for all options.

</details> <details> <summary><strong>Make commands reference</strong></summary>

| Command | What It Does | |---|---| | make setup | Full setup: deps + Docker + migrations + seed data | | make dev | Start backend API + PostgreSQL | | make dev-frontend | Start frontend dev server | | make agent | Start full agentic UI (backend + CopilotKit) | | make test-local | Run 687 unit + 43 integration tests locally | | make test | Run 744 tests in Docker (CI-parity) | | make test-frontend | Run 560 Vitest tests + WCAG checks | | make test-all | Full CI: lint + typecheck + backend + frontend | | make lint-local | ruff check + ruff format --check | | make typecheck | mypy (strict) | | make test-cov | pytest with coverage report | | make format | Auto-format with ruff |

</details>

---

Assurance Levels (A0–A3)

Every attribution carries an assurance level indicating verification depth. These are mapped to international music industry identifiers:

<p align="center"> <img src="docs/figures/repo-figures/assets/fig-frontend-05-assurance-badge-system.jpg" width="720" alt="Assurance badge system: four tiers from A0 (no data, unverified) through A1 (single source, ISRC), A2 (multi-source agreement, ISWC), to A3 (artist-verified identity, ISNI) showing progressive verification depth for music attribution." /> </p>

| Level | Verification | Evidence | Typical Identifier | Example | |---|---|---|---|---| | A0 | None | Self-declared | — | "I wrote this song" (no external confirmation) | | A1 | Single source | One database confirms | ISRC | MusicBrainz lists the recording | | A2 | Multi-source | Independent sources agree | ISWC | MusicBrainz + Discogs + file metadata agree | | A3 | Identity-verified | Full provenance chain | ISNI / IPI | Artist self-report + ISNI + multiple databases |

<details> <summary><strong>How are assurance levels computed?</strong></summary>

Assurance levels are determined by the entity resolution cascade and the number of independent sources that agree:

• A0: No external data available. The system has only what the user claimed.
• A1: Exactly one external source confirms (e.g., MusicBrainz has a matching ISRC). Confidence is moderate but un-corroborated.
• A2: Two or more independent sources produce consistent information. Cross-source agreement significantly increases confidence.
• A3: Identity-verified through a chain that includes artist self-report AND an identity standard (ISNI or IPI) AND at least one database match. This is the highest tier — reserved for attributions where the creator's identity is cryptographically or administratively confirmed.

The mapping between assurance levels and identifiers is project-defined and reflects industry best practices, not a formal standard.

Concept page: [Assurance Levels](https://petteriTeikari.github.io/music-a