7.5 KiB
Step 6: Text interpretation and coordinated composition
Objective and prerequisites
Implement Step 6 of the amended approved plan. Read the continuation decision
and accepted report_5_fix.md: standard MIDI fallback profiles now exist and
were independently verified. Their normal/sustain-only limitation is explicit;
real vendor maps and native/application acceptance are not claimed.
Build genuine deterministic text -> intent -> score -> mapped MIDI behavior, not a generic loop unrelated to the text. Do not implement MCP service wiring, native serialization, later prompts, or extra scope. No commits or delegation.
Owned files
- Create
src/riff_groove_builder/description.py. - Create
src/riff_groove_builder/compose.py. - Create
tests/unit/test_description.py. - Create
tests/unit/test_compose.py. - Create
tests/integration/test_text_to_midi.py. - Add small text/JSON cases under
tests/fixtures/descriptions/if useful. - Update
README.mdanddocs/architecture.mdwith the actual supported grammar, template/default policies, limitations, and focused validation commands. - Write
prompts/report_6.md.
Reuse the authoritative request/intent/score models, profile registry, compiler, exact tick helpers, writer and named errors. Explain/test any necessary tightly coupled shared change rather than replacing existing working contracts.
Text-resolution requirements
- Provide a small typed API resolving GenerateMusicRequest into MusicalIntent plus explicit assumptions/override records for future GenerationResult.
- Extract numeric tempo (
120 BPM), bar count (4 bars), meter (in 7/8), key (E minor), and explicit selected part words (lead/guitar,bass,drums). No external model API, network, audio, or new parser framework. - Structured override values win over text and are disclosed. Contradictory text without an applicable override is an actionable named error. Never silently choose one of two distinct numeric tempos/keys/meters.
- Omitted tempo/bars/meter/key resolve to 120 BPM, four bars, 4/4, E minor, with assumptions. If no explicit part-selection language exists, default to all three and disclose that assumption; structured parts win over text.
- Support a documented bounded vocabulary for riff/lead/bass groove/drum groove, straight quarter/eighth/sixteenth-note subdivisions, rests, and optional eighth-note triplets if represented exactly. Document deterministic rules for qualitative slow/fast and simple rock/metal/groove pattern terms if used. Do not add a general genre engine, song sections, or extra modes.
- Meaningful unsupported instructions (unrecognized instrument/technique, unsupported mode, tempo changes, polyrhythm, audio requests, etc.) must fail explicitly rather than disappear into a default loop. Ignore only documented filler. Match whole words, including negation/part-only selection, not accidental substrings. Do not treat "no drums" as a request for drums.
- Recognize canonical technique phrases such as palm mute without pretending the standard profile can realize them. Validate techniques against selected profiles and return UnsupportedArticulationError for unavailable techniques. Normal/sustain must work. Do not map palm mute to softer generic MIDI.
- Keep parsing and composition separate. Do not select production instruments by guessing vendor names from text; registry selection remains authoritative.
Composition requirements
- Compose selected tracks over exactly bars * numerator * 4/denominator quarter-note beats on the common rational grid. Each track shares start/end.
- Generate original simple musical content from the resolved intent: scale-based lead/riff patterns, root/fifth-oriented bass, and kick/snare/hat drum grooves with documented meter/subdivision behavior. Use seeded local variation, not copied factory/demo sequences.
- Respect major/minor key pitch classes, selected profile ranges/voices and supported articulations. Define the MIDI octave-number convention explicitly. Prefer sensible lead/bass registers, but choose notes within the actual map.
- Use exact fractions and supported tick divisions. Gate notes/rests to avoid ambiguous same-pitch overlap; truncate only as an explicit composition policy at the shared bar/end boundary, never alter requested musical duration.
- Drum voice names resolve through the selected profile's aliases. Do not assume every profile contains every GM sound or use guessed physical notes.
- No global random state, unsafe pitch/velocity clamping, silent out-of-range notes, per-track drift, or dropped requested techniques. Invalid/narrow maps that cannot support the pattern must produce useful named errors.
- Enforce the event budget before constructing excessive notes; account for at least note-on/off pairs and leave final control-event validation to the existing compiler. Keep resource use bounded for extreme valid inputs.
- Do not change the current Step 3 server handler; the pipeline is exercised directly until Step 9 connects it.
Required unit tests
- Valid structured/text values; defaults and assumption records; override precedence/disclosure; contradictory numeric/key/meter instructions.
- Part inference/ordering, exclusions, only-selection, explicit parts override, and unsupported instrument/mode/technique/material instruction failures.
- Whole-word extraction, filler, case/spacing, malformed/empty descriptions, fraction/tempo/bar boundaries, and unsupported tempo changes.
- Different meters, exact bar/end boundaries, seed reproducibility/variation, key/register/range compliance, no same-pitch overlaps, and subdivision/rest effects on actual generated content.
- Standard normal/sustain succeeds; requested palm mute fails honestly under standard-only maps. Synthetic switch profiles may test real compiler coupling but must never be advertised as vendor compatibility.
- Missing voices, unrepresentable timing, and event-budget rejection.
Required integration tests
- Lead-only, bass-only, drums-only and all-parts descriptions resolve/compose, select real standard profiles, compile, write actual MIDI and read it back.
- Independently assert tempo/meter, musical duration, parts/channels, key/range, rhythm changes from text, and emitted note pairing, not merely file existence.
- Include 3/4, 6/8, 7/8 and nondefault tempo/key/length cases.
- Same input/seed yields deterministic output; changed supported intent changes measurable output. Compare precise expected events for simple cases.
- Unsupported vendor techniques fail without artifacts.
- Preserve all existing contracts/compiler/MIDI/protocol/package regressions.
Validation and acceptance
Run focused new tests, relevant prior checks, Ruff lint/format, strict mypy, and the full current suite after shared changes. The known working venv pytest CLI fallback is acceptable. Clean up owned test files/children.
Accept only tested text-driven, bounded, aligned standard-MIDI composition. Real vendor articulation/native/application gates remain open and documented.
Required report
When complete, write your end-of-step report to ./prompts/report_6.md including: what was implemented, test results (pass/fail with details), any issues encountered, and whether you're ready for the next step
Put the complete report inside exactly one plain triple-backtick fence. Include APIs, exact supported grammar/default policies, measurable text-to-MIDI evidence, exact commands/results/skips, limitations and next-step readiness.