Files
product-vamp/docs/composer/evaluation_contract.md
T
khodowany ef62af892b Cleanup
2026-10-04 22:29:06 -05:00

2.7 KiB

Authoritative action evaluation

selection.Selector.evaluate returns Evaluation(version='action-selection-1'): raw normalized values, enabled weights, exact rational contributions, total and denominators. Ranking uses exactly the sum of reported contributions. Tied continuations merge before evaluation; repeated attacks remain distinct.

The scope is one complete musical action, not a chorus. Alternatives compete by cost per exact quarter; compound routes remain indivisible. Prefix and reporting-phrase totals sum local decisions. They are diagnostics, not global objectives or partition-invariant phrase quality scores. Computational partitioning that preserves the action objects does not change evaluation. Changing musical action boundaries can change the local search objective.

Fixed priors address excessive leaps, register distance outside a soft corridor, oscillation, repeated attacks, unprepared space, repeated rests, source interval relationships, actual theme relationships, sustained chord-tone arrivals and directed steps. Shared integer coefficients can distinguish action kind, duration, chord-relative pitch role, incoming interval, relative metric position, motion direction, register band, source rhythm, realized theme evidence and context of silence. Title, filename, absolute bar index, reference hash and event lookups are not allowed features.

Silence has no pitch/register value. A rest after an arrival differs from an interruption or repeated rest. A sustain is one attack with its complete duration. Approved expression is validated by contract rather than automatically rewarded or penalized as chromatic.

Hard validity remains separate: mapped collections, typed exceptions, exact target register/time/duration, pending deadlines, rhythm groups, physical domain, monophony and source-derived allocation. Pending obligations filter the frontier before pruning. Final placement cannot change selected pitches or rhythm.

The optional fitter uses an integer early-update structured perceptron, at most 200 passes. Coefficients are shared between songs within each role. Its checkpoint prefers fewer incorrect rollouts, then longer exact prefixes, then smaller coefficients. This differs from minimizing whole-output discrepancy; full export comparison remains the acceptance gate. Fitted artifacts stay under build/ until a verified model is deliberately promoted. Constructibility alone is not grounds for promotion.

Synthetic tests check contribution sums, weight counterfactuals, tied-event invariance, forbidden feature names and a learnable two-choice fitting problem. They establish mechanics, not that this finite feature set expresses the four desired decisions or predicts musical preference.