# Agent Pitch Map

> AI-navigable pitch decision engine for piano-to-guitar mapping, ranked playable routes, scales, chords, sound, and tab.

This public agent-readable pitch map helps humans and AI agents inspect how a musical pitch maps across piano keys, standard 6-string guitar frets, scale/chord membership, sound playback, and simple tab placement.

## Start Here

- Human UI: https://www.agentpitchmap.com/
- Agent guide: https://www.agentpitchmap.com/agent
- Agent examples: https://www.agentpitchmap.com/examples
- OpenAPI: https://www.agentpitchmap.com/openapi.json
- Full docs dump: https://www.agentpitchmap.com/llms-full.txt
- Capabilities JSON: https://www.agentpitchmap.com/api/capabilities
- Health check: https://www.agentpitchmap.com/api/health
- Example note query: https://www.agentpitchmap.com/api/note?note=C4
- Example fretboard query: https://www.agentpitchmap.com/api/fretboard?note=C&maxFret=12
- Example map query: https://www.agentpitchmap.com/api/map?note=D4&root=C&scale=major&piano=49-key
- Example frequency map query: https://www.agentpitchmap.com/api/map?frequencyHz=195.998&intervalSemitones=7&scaleLengthIn=25.5
- Example chord query: https://www.agentpitchmap.com/api/chord?root=C&chord=major&limit=3
- Example voicing query: https://www.agentpitchmap.com/api/voicings?root=C&chord=major
- Example route query: https://www.agentpitchmap.com/api/route?notes=C4,D4,E4,G4&root=C&scale=major&position=first
- Example scale query: https://www.agentpitchmap.com/api/scale?root=C&scale=lydian&note=G2
- Example top-3 voice-leading query: https://www.agentpitchmap.com/api/voice-leading?fromRoot=G&fromChord=dominant7&toRoot=C&toChord=major7&limit=3
- Example composer query: https://www.agentpitchmap.com/api/composer?note=G2&root=C&scale=major
- Example composition query: https://www.agentpitchmap.com/api/compose?key=D&scale=dorian&chord=minor7&motif=dorian-compass
- Example chord-scale query: https://www.agentpitchmap.com/api/chord-scale?root=G&chord=dominant7&contextRoot=C
- Example containing-scales query: https://www.agentpitchmap.com/api/scales/containing?notes=C,E,G,Bb
- Example tab recipe query: https://www.agentpitchmap.com/api/recipes/tab?key=D&scale=naturalMinor&style=beginner-riff

## Agent Instructions

- Prefer `/api/map` for exact music reasoning instead of scraping the visual UI.
- Use query parameters: `note`, `midi`, `frequencyHz`, `intervalSemitones`, `scaleLengthIn`, `fret`, `root`, `layer`, `scale`, `chord`, and `piano`.
- Treat exact pitch, same note name across octaves, theory membership, and interval function as separate concepts.
- Treat `translation.frequencyToMidi` as deterministic A440 12-TET routing from a continuous acoustic frequency to an integer MIDI note.
- Treat `physicalModel.fretCoordinate` as a theoretical equal-temperament fret-line coordinate, not a calibrated actuator press location.
- Use `/api/note`, `/api/fretboard`, `/api/chord`, and `/api/scale` when an agent wants stable narrow endpoints before composing larger calls.
- Use `/api/voicings` for playable guitar chord shapes, optimization scores, and machine-checkable chord-tone coverage proof.
- Use `/api/route` when the answer needs the best playable string/fret path for a note, melody fragment, arpeggio, or pitch-class sequence.
- Use `/api/voice-leading?limit=3` when the answer needs ranked playable guitar chord resolutions such as G7 to Cmaj7; compare `transitions[0..2]` by score, source/target frets, common tones, guide tones, and movement proof.
- Use `transitionLinks[]` from `/api/voice-leading` when an answer should open a specific ranked resolution in the workbench; each link carries the rank, transition id, full app URL, compact URL, and derived ASCII tab.
- Use `/api/formal-proof` to translate supported natural-language music-combinatorics claims into finite formal statements, Lean-style sketches, and proof certificates.
- Use `/api/extremal-search` to ask for cap-set-style extremal constructions with independent verification certificates.
- Use `/api/geometry-proof` to solve supported Euclidean proof schemas with both symbolic certificates and human-readable proof steps.
- Use `/api/proof-repair` when a proof attempt uses the wrong invariant and needs a repaired certificate.
- Use `/api/composer` for circle-of-fifths neighbors, common-tone pivots, guide-tone moves, and guitar anchor notes.
- Use `/api/compose` when the answer should return a complete playable project, compact URL, ASCII tab, and semantic overlays from musical constraints.
- Use `/api/scales`, `/api/scale-map`, `/api/chord-scale`, and `/api/scales/containing` for scale reasoning instead of treating scales as a flat list.
- Use `/api/recipes/tab` when an explanation needs a quick live example; return its `appUrl` for the playable workbench and `asciiTab` for plain text.
- Use `/api/project` for portable project JSON, `/api/project/compact` for shorter `zproject` URLs, and `/api/tab/export` for derived ASCII tab from encoded project state.
- Use `POST /api/tab` when the agent already has structured note/string/fret events and needs ASCII tab plus a canonical ProjectState.
- Use `POST /api/project/render` when the agent already has a ProjectState and needs derived ASCII tab and share URLs.
- Treat `project.overlays` as semantic teaching annotations. Roles and selectors are durable; UI colors are presentation.
- Browser agents can use stable attributes such as `data-testid="piano-key-D4"`, `data-testid="fret-S2-F3"`, `data-note`, `data-midi`, and `data-agent-role`.
- All public endpoints in this version are read-only and have no side effects.

## Example Prompts

- Show D4 on standard guitar and explain every other D across octaves.
- Is B3 inside C major, and where does it appear on guitar?
- Give me the exact fret positions for C4 and same-note-name positions for every other C.
- Explain the difference between exact pitch and same note name using the current map.
- Find playable C major guitar voicings and identify each interval.
- Route C4, D4, E4, and G4 through first-position guitar and explain the lowest-cost path.
- Find the top three G7 to Cmaj7 guitar resolutions and explain why the first is best.
- Convert 195.998 Hz to a MIDI integer, add a perfect fifth, and calculate the theoretical 25.5-inch 7th-fret coordinate.
- Prove there exists a playable C major triad voicing on standard guitar within span 4.
- Find the largest pitch-class subset with no modular three-term arithmetic progression.
- Prove that a segment joining equal-ratio moving points on two sides of a triangle is parallel to the third side.
- Repair the failed proof that an 8x8 board with opposite corners removed can be tiled because its area is even.
- Suggest composition moves from G2 in C major and show common tones on guitar.
- Compose a D dorian two-measure guitar idea with a compact share URL.
- Suggest scale choices for G7 in a C major context.
- Find scales containing C, E, G, and Bb.
- Generate a beginner D natural minor tab and show the live annotated workbench URL.
- Export the current tab/project state as JSON, then derive ASCII tab from it.

## POST /api/tab Example

```json
{
  "title": "C major arpeggio",
  "tuning": "standard",
  "tempo": 96,
  "timeSignature": "4/4",
  "events": [
    { "note": "C3", "string": 5, "fret": 3, "beat": 1 },
    { "note": "E3", "string": 4, "fret": 2, "beat": 2 },
    { "note": "G3", "string": 3, "fret": 0, "beat": 3 },
    { "note": "C4", "string": 2, "fret": 1, "beat": 4 }
  ]
}
```

The route returns `ascii`, `project`, `eventProof`, `appUrl`, `compactUrl`, `zproject`, and `warnings`. It rejects mismatches where the declared MIDI/note does not match the supplied guitar string and fret.

## Error Contract

All JSON API errors use HTTP 400 with:

```json
{ "error": "Human-readable error message." }
```

## Boundaries

- Tuning: standard 6-string guitar, frets 0-24.
- Pitch model: 12-tone equal temperament, MIDI 0-127.
- Current route planner: first/low/middle/upper/all fret windows, exact MIDI notes, pitch-class-only notes, route proof, and structured tab events.
- Current voice-leading engine: top-N standard-guitar chord transitions ranked by common tones, retained fretted positions, guide-tone motion, fret motion, MIDI voice motion, and structured tab events.
- Current theory layers: modal, pentatonic, blues, jazz, symmetric, synthetic, major/minor/diminished/dominant7/major7/minor7 chords.
- Current composer bridge: circle neighbors, common tones, guide-tone pivots, chromatic mediants, and standard-guitar anchors.
- Current scale atlas: scale catalog, scale maps, chord-scale advisor, and containing-scale search.
- Current agent project model: selected pitch, theory layer, mapping preferences, transport state, tuning, structured tab events, and semantic overlay marks.
- Current share model: full `project` URLs and compressed `zproject` URLs are both read-only portable state.
- No write-capable agent task execution is exposed yet.


## Endpoint Catalog

- GET /api/health: Return service status and the public agent discovery routes. Example: https://www.agentpitchmap.com/api/health
- GET /api/note: Resolve note or MIDI input to canonical MIDI, note name, octave, frequency, and map URL. Example: https://www.agentpitchmap.com/api/note?note=C4
- GET /api/fretboard: Return standard-guitar string/fret coordinates, optionally filtered to an exact note or pitch class. Example: https://www.agentpitchmap.com/api/fretboard?note=C&maxFret=12
- GET /api/chord: Stable chord endpoint alias for optimized standard-guitar voicings. Example: https://www.agentpitchmap.com/api/chord?root=C&chord=major&limit=3
- GET /api/scale: Stable scale endpoint alias for rooted scale maps and selected-note membership. Example: https://www.agentpitchmap.com/api/scale?root=C&scale=lydian&note=G2
- GET /api/map: Resolve a note, MIDI pitch, or acoustic frequency to piano keys, standard guitar positions, same-note-name matches, theory membership, interval targets, and theoretical fret coordinates. Example: https://www.agentpitchmap.com/api/map?frequencyHz=195.998&intervalSemitones=7&scaleLengthIn=25.5
- GET /api/voicings: Discover and optimize playable standard-guitar chord voicings for a root and chord quality. Example: https://www.agentpitchmap.com/api/voicings?root=C&chord=major
- GET /api/route: Rank playable guitar routes for notes or pitch-class sequences, including fret movement, string movement, span, theory membership proof, tab events, and share URLs. Example: https://www.agentpitchmap.com/api/route?notes=C4,D4,E4,G4&root=C&scale=major&position=first
- GET /api/voice-leading: Rank playable guitar chord-to-chord transitions with top-N options, common-tone, guide-tone, fret-motion, voice-motion, tab-event, and share URL proof. Example: https://www.agentpitchmap.com/api/voice-leading?fromRoot=G&fromChord=dominant7&toRoot=C&toChord=major7&limit=3
- GET /api/formal-proof: Formalize supported natural-language music-combinatorics problems and prove them by finite exhaustive check over the MIDI-backed model. Example: https://www.agentpitchmap.com/api/formal-proof?problem=Prove%20there%20exists%20a%20playable%20C%20major%20triad%20voicing%20on%20standard%20guitar%20within%20span%204
- GET /api/extremal-search: Search for cap-set-style extremal constructions in pitch-class or F_3 finite-field spaces and return independently verifiable certificates. Example: https://www.agentpitchmap.com/api/extremal-search?space=pitch-class&modulus=12
- GET /api/geometry-proof: Solve supported natural-language Euclidean geometry proof schemas with analytic/vector certificates and human-readable proof steps. Example: https://www.agentpitchmap.com/api/geometry-proof?problem=In%20triangle%20ABC,%20M%20moves%20on%20AB%20with%20AM:MB=1:1%20and%20N%20moves%20on%20AC%20with%20AN:NC=1:1.%20Prove%20MN%20is%20parallel%20to%20BC
- GET /api/proof-repair: Diagnose a supported failed olympiad-style proof attempt, repair the core invariant, and return a minimal formal certificate. Example: https://www.agentpitchmap.com/api/proof-repair?problem=An%208x8%20chessboard%20has%20two%20opposite%20corners%20removed.%20Can%20it%20be%20tiled%20by%2031%20dominoes?&attempt=The%20area%20is%2062,%20so%2031%20dominoes%20should%20tile%20it.
- GET /api/composer: Return literature-informed composer moves from the current pitch state: circle neighbors, common tones, guide-tone pivots, chromatic mediants, and nearby guitar anchors. Example: https://www.agentpitchmap.com/api/composer?note=G2&root=C&scale=major
- GET /api/compose: Generate a complete read-only composition project from musical constraints, including ProjectState, ASCII tab, app URL, compact URL, and semantic overlays. Example: https://www.agentpitchmap.com/api/compose?key=D&scale=dorian&chord=minor7&motif=dorian-compass
- GET /api/scales: Return the structured scale catalog with intervals, degrees, families, common chords, and characteristic tones. Example: https://www.agentpitchmap.com/api/scales?family=jazz
- GET /api/scale-map: Map a rooted scale to pitch classes, selected-note degree membership, and guitar anchors. Example: https://www.agentpitchmap.com/api/scale-map?root=C&scale=lydian&note=G2
- GET /api/chord-scale: Rank chord-scale choices for a chord in optional key context, including available tensions and guitar anchors. Example: https://www.agentpitchmap.com/api/chord-scale?root=G&chord=dominant7&contextRoot=C
- GET /api/scales/containing: Find rooted scales that contain arbitrary pitch material such as notes, chord tones, or riff fragments. Example: https://www.agentpitchmap.com/api/scales/containing?notes=C,E,G,Bb
- GET /api/recipes/tab: Generate a complete shareable beginner tab recipe with project JSON, ASCII tab, app URL, tab export URL, and semantic teaching overlays. Example: https://www.agentpitchmap.com/api/recipes/tab?key=D&scale=naturalMinor&style=beginner-riff
- GET /api/project: Return canonical Agent Pitch Map project JSON from query state or an encoded project URL parameter. Example: https://www.agentpitchmap.com/api/project?note=D4&root=C&scale=major&piano=49-key
- GET /api/project/compact: Return a compressed zproject token and compact workbench URL for a project or query-derived state. Example: https://www.agentpitchmap.com/api/project/compact?project=<encoded-project-state>
- POST /api/tab: Generate ASCII tab and canonical ProjectState from structured MIDI/string/fret tab events. Example: https://www.agentpitchmap.com/api/tab
- GET /api/tab/export: Export ASCII tab from an encoded read-only project state URL parameter. Example: https://www.agentpitchmap.com/api/tab/export?project=<encoded-project-state>
- POST /api/project/render: Render a supplied ProjectState into ASCII tab, full workbench URL, compact URL, and render proof. Example: https://www.agentpitchmap.com/api/project/render
- GET /api/capabilities: Return this manifest as JSON for agent discovery. Example: https://www.agentpitchmap.com/api/capabilities

## Deterministic Proof Fields

- Route decisions expose `objective`, `cost`, `efficiencyScore`, and `routes[].proof` with total fret movement, total string movement, route span, open-string count, hand window, outside-layer notes, and all-notes-mapped status.
- Voice-leading decisions expose common pitch classes, retained fretted positions, guide-tone motion, fret motion on shared strings, total MIDI voice motion, maximum single-voice motion, and per-transition workbench links.
- Chord voicings expose optimization cost and proof that required chord pitch classes are covered.
- Tab generation exposes `eventProof[]`, proving each structured event's MIDI value matches its standard-guitar string/fret coordinate.
- Project rendering exposes `renderProof`, proving ASCII tab is derived from structured `TabProject` events.
- Frequency maps expose `translation.frequencyToMidi`, proving the continuous MIDI value, `Math.round` operation, routed MIDI integer, and rounding delta.
- Physical fret maps expose `physicalModel.fretCoordinate` with a theoretical equal-temperament basis and explicit hardware-calibration caveat.

## Composition Pattern

1. Discover the surface at https://www.agentpitchmap.com/llms.txt or https://www.agentpitchmap.com/openapi.json.
2. Resolve pitch identity with https://www.agentpitchmap.com/api/note?note=C4 or full instrument context with https://www.agentpitchmap.com/api/map?note=C4&root=C&scale=major.
3. Use https://www.agentpitchmap.com/api/route?notes=C4,D4,E4,G4&root=C&scale=major&position=first for playable guitar routing.
4. Verify the returned proof fields before explaining a fingering.
5. Use returned `tabNotes`, `asciiTab`, `appUrl`, or `compactUrl` to compose the final user answer.