midifier: Instructions file for Codex

AGENTS.md

Guidance for agents working in this repo. CLAUDE.md is a symlink to this file, so there is one set of instructions rather than two that drift.

What this is

An API that turns a recording into a multi-track General MIDI file: it identifies which instruments are playing, transcribes each, and names and assigns the tracks. It feeds kinesthesia, which renders MIDI as falling notes to practise against.

Toolchain

uv for everything. Never call pip or a bare python.

uv sync --extra dev          # install
uv run pytest                # tests
uv run mypy src tests        # types, strict
uv run ruff check --fix .    # lint
uv run ruff format .         # format
uv run prek run -a     # everything CI runs
uv run python -m midifier    # serve the API

uvx for one-off tools that are not dependencies.

Non-negotiables

• mypy strict. No Any, no untyped defs, no # type: ignore without a reason on the same line. If typing something is hard, that usually means the design is unclear.
• One import per line. force-single-line = true; do not group with commas or parentheses.
• Coverage stays at or above 80%. Add tests with the code, not afterwards.
• Every check runs as a prek hook, and CI runs prek. Adding a check anywhere else splits the definition of "clean" in two.
• No bare except Exception. Catch what can actually be raised.

Style

Comments are rare and earn their place. The code says what it does; a comment exists only for a non-obvious why, a constraint, or a trap that would invite a wrong "simplification". Never narrate a change ("was X, now Y") — write code as though it always looked this way.

Prefer deleting to adding. The pipeline reached its current quality mostly by removing stages that sounded clever and measured worse; treat new stages with the same suspicion.

Where things are

src/midifier/
  config.py        settings, all from the environment, prefix MIDIFIER_
  api.py           REST surface, async job pattern
  mcp.py           MCP tools over the same job store
  storage.py       local filesystem or S3/MinIO behind one protocol
  fetch.py         SSRF-guarded URL fetching
  jobs.py          job model and in-memory store
  midi/
    cleanup.py     repairs the decoder's characteristic defects
    segments.py    where to cut a long decode
    parts.py       decides the song's instruments from every segment at once
tests/             mirrors src; e2e/ needs the model and is opt-in