129 lines
7.5 KiB
Markdown
129 lines
7.5 KiB
Markdown
# 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.md` and `docs/architecture.md` with 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
|
|
|
|
1. Provide a small typed API resolving GenerateMusicRequest into MusicalIntent
|
|
plus explicit assumptions/override records for future GenerationResult.
|
|
2. 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.
|
|
3. 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.
|
|
4. 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.
|
|
5. 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.
|
|
6. 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.
|
|
7. 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.
|
|
8. Keep parsing and composition separate. Do not select production instruments
|
|
by guessing vendor names from text; registry selection remains authoritative.
|
|
|
|
## Composition requirements
|
|
|
|
1. Compose selected tracks over exactly bars * numerator * 4/denominator
|
|
quarter-note beats on the common rational grid. Each track shares start/end.
|
|
2. 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.
|
|
3. 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.
|
|
4. 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.
|
|
5. Drum voice names resolve through the selected profile's aliases. Do not
|
|
assume every profile contains every GM sound or use guessed physical notes.
|
|
6. 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.
|
|
7. 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.
|
|
8. 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.
|