[ 01 ] Multi-agent AI · Live project
SoundReverse
A multi-agent audio analyst that turns a song’s sonic fingerprint into a mastering blueprint, JSON preset, and trace of the agent reasoning.
Python rules set EQ, compression, and gain. The current Groq model writes grounded explanations and correction hints; four deterministic checks validate the result.


Inside the build
The Agent Graph
A LangGraph StateGraph chains MCP → Gateway → Musician → Analyst ⇄ Critic, with output generation after the graph finishes. Python rules compute EQ, compression, and gain; the current Groq model (openai/gpt-oss-20b) supplies structured explanations and correction language.
MCP — Audio Sonic MCP on Modal
Audio analysis runs in a separate MCP server — the cloud-GPU build of my open-source Audio Sonic MCP — so the SoundReverse app carries zero audio libraries. The MCP node has two branches behind one output contract: an uploaded mp3/wav is streamed to Modal for HTDemucs 4-stem separation, CLAP, and FFmpeg/librosa metrics (~30–90s with cold start), while a demo track loads a pre-computed SignalSignature from cache instantly. Both branches must satisfy the same Pydantic schema, so the rest of the graph never knows which one ran.
Gateway — Schema Gate
Pure Python, no LLM. It validates the raw MCP output against the SignalSignature Pydantic v2 model via model_validate(); on any violation it sets an error, marks the run final, and routes straight to output — so a contract drift between the MCP server and the app fails loudly here instead of silently corrupting the downstream math.
Musician — Signal to Plain Language
A hybrid node. Deterministically, it reads each stem's fundamental frequency and maps it to the nearest note via equal-temperament math (48 Hz → G1, 36 Hz → D1), then derives plain-language tonal tags — Bass-forward, Warm/dark, Mono-solid — from energy ratios, spectral tilt, and stereo correlation. The Groq model then writes a tonal-character line and tuning tip under a string-only tool schema, so it cannot touch a single Hz value; if the call fails, the node falls back to the deterministic text rather than failing the run.
Analyst — Python Sets the Numbers
Phase one evaluates rules.yaml against the signal in pure Python — shelves keyed to spectral tilt, a low peak matched to the kick fundamental, bus-compression ratios drawn from dynamic range, and a makeup-gain target from LUFS. Phase two hands those fixed settings to the Groq model under a ReasonBundle schema, which writes one grounded engineer justification per decision. On a re-run, the Critic's prior critique is appended so the new reasons address exactly what was flagged.
Critic — Deterministic Validation Loop
The Critic runs four hardcoded physical-impossibility checks in pure Python: over-compression (dynamic range < 4 dB), bright-boost contradiction (high-shelf boost on spectral tilt > 0.75), loudness ceiling (positive makeup gain above −9 LUFS), and kick-frequency drift (EQ boost > 20 Hz off the measured kick fundamental). Confidence is simply checks-passed over total; below 0.8 it has the Groq model write targeted correction hints and loops back to the Analyst, capped at three iterations. The demo track HUMBLE. deliberately overshoots its kick boost by +30 Hz on iteration one to exercise the full reject-and-correct cycle.
Output — Producer Session Pack
The output generator runs after app.invoke() returns — by design, since LangSmith's share_run() only resolves once the graph finishes, letting the real public trace URL be embedded in every file. It writes three artifacts per run, each prefixed by job_id: a two-page fpdf2 blueprint (a musician-first page and a technical-reference page), a JSON preset, and a metadata log of timings, models, and every critic round.
