276 lines
15 KiB
Markdown
276 lines
15 KiB
Markdown
```
|
|
Step 6 report — deterministic description and coordinated Standard MIDI
|
|
Date: 2026-10-19
|
|
|
|
OUTCOME: IMPLEMENTED, PERSISTENT AND VERIFIED.
|
|
FINAL VALIDATION: 868 passed; 0 failed; 0 skipped.
|
|
STANDARD MIDI ONLY: no verified vendor maps, native formats or application acceptance.
|
|
NEXT-STEP STATUS: ready for Step 6 review; native evidence gates remain open.
|
|
|
|
SCOPE
|
|
|
|
Read prompts\step_6.md, the amended approved plan's continuation decision and
|
|
Step 6 scope, accepted report_5_fix.md, current request/intent/score/result/error
|
|
contracts, profile models/registry, compiler, exact timing helpers and writer.
|
|
Implemented only the owned Step 6 surfaces:
|
|
|
|
Created:
|
|
- src\riff_groove_builder\description.py
|
|
- src\riff_groove_builder\compose.py
|
|
- tests\unit\test_description.py
|
|
- tests\unit\test_compose.py
|
|
- tests\integration\test_text_to_midi.py
|
|
- prompts\report_6.md
|
|
|
|
Updated:
|
|
- README.md
|
|
- docs\architecture.md
|
|
|
|
No shared contract, profile/resource, compiler, MIDI writer, Step 3 handler,
|
|
dependency manifest or earlier report/plan was changed by this step.
|
|
No network/model service, audio, native codec, MCP wiring, later-prompt work,
|
|
commit or delegation. Existing unrelated/pre-existing worktree changes remain.
|
|
|
|
APIS AND RESOLUTION
|
|
|
|
resolve_description(request: GenerateMusicRequest) -> DescriptionResolution
|
|
returns intent: MusicalIntent, assumptions: unique list[str], overrides:
|
|
unique list[str]. These records are suitable for future ResolvedGeneration,
|
|
not a fabricated GenerationResult. It revalidates mutable request graphs.
|
|
|
|
compose_score(intent: MusicalIntent, selected_profiles:
|
|
dict[Part, InstrumentProfile], *, ppq=960) -> Score revalidates intent/profiles.
|
|
Call the authoritative registry's select(intent.parts, request.profiles or
|
|
ProfileSelection()), compose, compile_score, then write_midi. Nondefault PPQ
|
|
must also be passed to compile_score. No parser/composer filesystem IO occurs.
|
|
|
|
Structured non-null tempo/bars/meter/key/parts win over text, even contradictory
|
|
or out-of-bounds scalar candidates for that field. Every structured value is
|
|
disclosed with its text candidates, including when none were present.
|
|
Null remains unresolved. Unknown material/changing instructions cannot be
|
|
authorized by these overrides. Equivalent repeated values and enharmonic keys
|
|
are not contradictions; distinct unresolved candidates are actionable errors.
|
|
Textual part order is lead,bass,drums; structured order is preserved.
|
|
|
|
EXACT SUPPORTED GRAMMAR AND DEFAULTS
|
|
|
|
This is a closed grammar, not free-form language or a general genre engine.
|
|
Case is folded, whitespace collapsed, whole words matched. Clauses may appear
|
|
in any order. The following are global instructions, not per-part schedules:
|
|
|
|
- Numeric BPM: signed decimal number followed by BPM, optional whitespace,
|
|
final 20-300 quarter-note beats/minute. Example: 137.5 BPM. No fractional
|
|
notation, exponent, textual numbers, beat-unit conversion or tempo changes.
|
|
- Bars: signed numeric value followed by bar/bars; integer-valued 1-256.
|
|
4.0 bars is accepted as four; 1.5 bars is not.
|
|
- Meter: n/d, optional spaces around slash; optional in/meter filler.
|
|
Numerator 1-16; denominator 1,2,4,8,16. No changing or mixed meters.
|
|
- Key: A-G, optional one ASCII #/b, major/minor. Natural minor only.
|
|
Existing canonical sharp spelling is retained: Bb major -> A# major.
|
|
- Lead aliases: lead, lead guitar, guitar, riff.
|
|
- Bass aliases: bass, bass guitar, bass riff/groove, bass guitar riff/groove.
|
|
Here riff/groove means either word, not a literal slash.
|
|
- Drum aliases: drum, drums, optionally followed by groove.
|
|
- Part lists: comma, and, &, +; separate positive mentions also combine.
|
|
Prefix only or suffix only selects that whole contiguous list.
|
|
Example: only bass and drums; lead and bass only.
|
|
- Exclusions: no/without/exclude plus a contiguous part list.
|
|
no drums selects lead+bass; without bass and drums selects lead.
|
|
Exclusions alone subtract from all three and disclose that baseline.
|
|
Positive/excluded overlap, an outside positive part after only-selection,
|
|
or an empty selection is an error unless structured parts override it.
|
|
Ambiguous negated-only syntax is rejected.
|
|
- Subdivision: quarter, eighth, sixteenth, optionally " note"/" notes" or
|
|
"-note"/"-notes". Exact slots are 1,1/2,1/4 quarter-note beats.
|
|
- Rest policy: rest/rests omits the final slot of every bar;
|
|
no rest/no rests omits none. No arbitrary rest schedule.
|
|
- Template: rock or metal; simple original policies, not genre fidelity.
|
|
- slow/fast are fixed tempo candidates 80/160 BPM. Distinct numeric/qualitative
|
|
candidates conflict without a structured tempo override.
|
|
- normal and sustain are the same global normal technique, not CC64.
|
|
- palm mute, palm-mute, palm muted, palm-muted retain canonical palm_mute.
|
|
Composition must validate it against every selected profile, even for silence.
|
|
|
|
Defaults, each disclosed as an assumption when omitted:
|
|
120 BPM, four bars, 4/4, E minor, lead+bass+drums,
|
|
eighth, rock, no_rests, normal. Seed is the existing request seed (default 0),
|
|
not a parsed text instruction.
|
|
|
|
Only these exact filler words are ignored:
|
|
please create generate make write a an the some simple music pattern groove
|
|
for with and at in of on notes note key tempo meter straight
|
|
|
|
Comma, period, semicolon, colon, !, ?, &, + are separators. Other unknown
|
|
tokens/punctuation fail. Require a recognized instruction or music/pattern/
|
|
groove: filler-only "please" fails. No bassoon->bass or leadership->lead match.
|
|
Negation is supported only for the documented part and rest grammar.
|
|
|
|
Unsupported instruments, modes, other techniques, vendor-name selection,
|
|
triplets, swing, polyrhythm, sections, audio and changing instructions fail,
|
|
not disappear into a default. then/to/from, changes/changing, ramp,
|
|
accelerando/ritardando/rallentando, speed up and slow down are rejected.
|
|
No song sections, per-part instructions, arbitrary dynamics/rests/durations,
|
|
chord/individual-note syntax or extra modes are claimed.
|
|
|
|
DescriptionConflictError is an UnsupportedDescriptionError subtype with
|
|
UNSUPPORTED_DESCRIPTION and the field to correct. Other unsupported/invalid
|
|
text uses UnsupportedDescriptionError; invalid mutated request models use
|
|
InvalidRequestError. The composer uses named CompositionError for unsafe
|
|
intent/range/voice/channel/coverage/budget conditions and preserves exact
|
|
timing/profile errors. UnsupportedArticulationError identifies part, profile
|
|
and unavailable requested technique. No raw network/vendor inference exists.
|
|
|
|
COMPOSITION POLICY
|
|
|
|
- Common score origin 0 and exact end bars*numerator*4/denominator quarter
|
|
beats. Each part and actual MIDI EOT share this duration, including rests.
|
|
- Slots restart per bar. Only the final slot may shorten to the bar boundary,
|
|
e.g. quarter notes in 7/8 end with 1/2 beat. This is explicit truncation of
|
|
a note slot, never a change to requested musical length.
|
|
- Rests remove the final slot/hits of every bar. A single-slot bar can be
|
|
entirely silent and still retain its full shared duration.
|
|
- Major intervals 0,2,4,5,7,9,11; natural minor 0,2,3,5,7,8,10.
|
|
Require the full lead scale or bass root/fifth pair inside actual map range.
|
|
Choose the root nearest 64 for lead, 40 for bass among valid palettes;
|
|
lower root breaks ties. MIDI octave convention C4=60, E4=64, E2=40.
|
|
No clamping, dropped degrees, chromatic pitches or invented vendor ranges.
|
|
- Lead zero-based rock degrees (0,2,4,6), metal (0,0,4,1), with each bar's
|
|
first slot root; other slots add seeded 0/1 modulo seven.
|
|
Bass rock alternates root/fifth; metal uses root,root,fifth,root.
|
|
- Drums resolve closed_hat, kick and snare aliases through the selected map.
|
|
Hat each active slot; pulse=max(subdivision,4/denominator).
|
|
At pulse-aligned slots alternate kick/snare from kick each bar.
|
|
Metal adds off-pulse kick. This explicit odd/compound-meter policy is not
|
|
automatic grouping or a claim of idiomatic 6/8 accents.
|
|
- Pitched gates fill slots; drum gates=min(slot length,1/4 beat).
|
|
Same-pitch notes never overlap; compiler releases before boundary retriggers.
|
|
- Intensities are seeded choices 0.5,0.625,0.75, shared by simultaneous hits.
|
|
Profiles perform their supported real velocity conversion.
|
|
- Local Random(seed+0/1/2 for lead/bass/drums) never changes global state.
|
|
Adding/reordering parts does not perturb another part's notes.
|
|
- Before note allocation, exact active-slot/hit counts reserve at least
|
|
note-on/off pairs within 100,000 events. The compiler still validates extra
|
|
controls. Extreme valid requests fail early without excessive allocation.
|
|
- Existing exact tick helpers check total/slot/gate timing; no rounding.
|
|
Default 960 PPQ supports every documented straight grid and meter.
|
|
|
|
Only existing real standard.lead.v1, standard.bass.v1, standard.gm-drums.v1
|
|
are selected in production integration, with normal/sustain and channels 0/1/9.
|
|
No keyswitches/CCs/pedal/program/bank/GM initialization are invented.
|
|
Standard palm mute fails before any artifact, never becomes softer generic MIDI.
|
|
One synthetic switch-profile unit test proves real compiler/pre-roll coupling,
|
|
explicitly test-only and never vendor compatibility.
|
|
Keys affect actual pitches; the unchanged writer does not add key-signature meta.
|
|
|
|
MEASURABLE ACTUAL-DISK EVIDENCE
|
|
|
|
Tests resolve, compose, select real standard profiles, compile, exclusively
|
|
write MIDI, validate actual bytes, and independently read them with Mido.
|
|
Assertions cover tempo/meter, common end, track names/channels, in-key/range
|
|
pitches, physical GM voices, positive velocities, and complete note pairing.
|
|
|
|
Representative descriptions and independently checked ends at 960 PPQ:
|
|
- Lead only: 90 BPM, 2 bars, 3/4, D major, quarter -> 5760 ticks.
|
|
- Bass only: 72.5 BPM, 3 bars, 6/8, Bb minor, eighth -> 8640 ticks.
|
|
- Drums only: 155 BPM, 2 bars, 7/8, sixteenth -> 6720 ticks.
|
|
- All parts: 137.5 BPM, 4 bars, 4/4, F# minor, eighth -> 15360 ticks.
|
|
- No drums: 111 BPM, 1 bar, 7/8, Eb major, quarter rests -> 3360 ticks.
|
|
|
|
Independent exact bass case: "bass only 1 bar C major quarter", seed 0:
|
|
channel 1, pitches 36/43/36/43, velocities 64/96/64/80;
|
|
onsets 0/960/1920/2880, offs 960/1920/2880/3840.
|
|
Independent exact drum case: quarter, 1 bar, seed 0:
|
|
channel 9, kick/snare/kick/snare 36/38/36/38 plus closed hat 42;
|
|
onsets 0/960/1920/2880, each gate 240 ticks;
|
|
slot velocities 64/64/64/80, common EOT 3840.
|
|
Expected event payloads/order are hand-specified, not copied from compiler output.
|
|
|
|
For one 4/4 bar, read-back note-on counts bass/drums:
|
|
quarter 4/8; eighth 8/12; sixteenth 16/20;
|
|
eighth rests 7/11; eighth metal 8/16.
|
|
Bass onsets are independently asserted as 960/480/240 tick grids; rest omits
|
|
the final eighth onset at 3360 while EOT remains 3840.
|
|
Same input/seed produces identical score/events and actual file bytes;
|
|
changed seed changes content. Key changes pitches; tempo changes conductor
|
|
metadata without changing tick positions; bars/meter change exact common end.
|
|
Unsupported palm mute/slide/audio cases create no file or child artifact.
|
|
|
|
VALIDATION — EXACT FINAL COMMANDS AND OUTCOMES
|
|
|
|
Environment: existing .venv, CPython 3.13.13, Windows AMD64.
|
|
No additional runtime/OS/plugin configuration is certified.
|
|
No dependencies were installed/restored or manifests changed.
|
|
Shell setup for test/build subprocesses (repository-local scratch):
|
|
|
|
$scratch = New-Item -ItemType Directory -Force '.test-artifacts\scratch'
|
|
$env:TEMP = $scratch.FullName
|
|
$env:TMP = $scratch.FullName
|
|
$env:TMPDIR = $scratch.FullName
|
|
$env:PIP_NO_INDEX = '1'
|
|
|
|
Focused final command:
|
|
& '.\.venv\Scripts\python.exe' -m pytest tests\unit\test_description.py tests\unit\test_compose.py tests\integration\test_text_to_midi.py -q --tb=short
|
|
PASS: 168 passed in 1.12s; 0 failed; 0 skipped.
|
|
|
|
Full current suite:
|
|
& '.\.venv\Scripts\python.exe' -m pytest -q --tb=short
|
|
PASS: 868 passed in 32.41s; 0 failed; 0 skipped.
|
|
Includes previous schemas/errors, profile/standard-map/compiler/MIDI,
|
|
protocol/stdio, packaging/distribution and installed-wheel/resource regressions.
|
|
|
|
Owned-file formatting:
|
|
& '.\.venv\Scripts\python.exe' -m ruff format src\riff_groove_builder\description.py src\riff_groove_builder\compose.py tests\unit\test_description.py tests\unit\test_compose.py tests\integration\test_text_to_midi.py
|
|
PASS: 5 files reformatted.
|
|
|
|
& '.\.venv\Scripts\python.exe' -m ruff check .
|
|
PASS: All checks passed.
|
|
|
|
& '.\.venv\Scripts\python.exe' -m ruff format --check .
|
|
PASS: 48 files already formatted.
|
|
|
|
& '.\.venv\Scripts\python.exe' -m mypy --strict src tests
|
|
PASS: Success: no issues found in 28 source files.
|
|
|
|
Editor problems: no errors in all five new Python files.
|
|
Editor runTests reported no discovered tests for supplied absolute paths;
|
|
the actual repository-venv pytest CLI fallback above is the execution evidence.
|
|
No failing/skipped pytest result is hidden by that discovery limitation.
|
|
|
|
ISSUES ENCOUNTERED AND RESOLVED
|
|
|
|
- Initial collection failed with two errors because standalone TypeAdapter(Key)
|
|
used Pydantic's default Rust regex engine, which cannot compile the existing
|
|
key contract's lookaround. Configured this owned adapter with strict=True and
|
|
python-re, matching the authoritative contract. No shared contract was changed.
|
|
- Initial Ruff found three local issues (zip strictness and long lines).
|
|
Replaced zip with enumerated names and wrapped/formatted the owned code.
|
|
Final whole-project lint/format and strict mypy pass without new suppressions.
|
|
- Explicit tempo bounds are checked as Fraction before float conversion, so
|
|
an extreme 3500-digit textual BPM yields a named error, not OverflowError.
|
|
The same scalar can be replaced by a valid disclosed structured override.
|
|
- Bass guitar is parsed as the bass phrase rather than accidentally requesting
|
|
lead as well. Negation/only/conflict/whole-word tests verify actual behavior.
|
|
- Intermediate focused checks passed 141 then 156 tests; final expanded focused
|
|
count is 168 and the full suite is 868. No implementation blocker remains.
|
|
|
|
CLEANUP AND LIMITATIONS
|
|
|
|
All owned UUID test/build/stdio/MIDI children cleaned up; final relevant child
|
|
workspace count 0, root build directory absent. Existing scratch, caches, venv,
|
|
dist products and unrelated worktree content were preserved.
|
|
No background processes/services were started or left running.
|
|
|
|
This is tested bounded Standard MIDI composition, not a neural model,
|
|
instrument emulation, genre engine, native writer or end-to-end MCP service.
|
|
Real Eclips/Ray/SD3 maps, installed versions/presets, keyswitch/control behavior,
|
|
vendor layering, AGP/SDP layouts and plugin/Cubase load/save/reload acceptance
|
|
remain unverified. No application acceptance was run or counted as a pytest skip.
|
|
RNG behavior is verified on the tested interpreter, not certified cross-runtime.
|
|
|
|
Step 6 is complete and ready for review/next permitted work.
|
|
Steps 7/8 real native serialization still require their existing evidence gates;
|
|
this report does not claim readiness to bypass them. Step 9 service wiring is
|
|
not implemented: the unchanged Step 3 handlers still list no profiles and reject
|
|
valid generation requests as unfinished. No later prompt was executed. Stop here.
|
|
```
|