Spaces:
Sleeping
Sleeping
File size: 4,131 Bytes
03d531b 0b5f0f0 03d531b e07820e | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 | # Interactive supervised extraction UX
This directory contains the supplied interactive-UX design documents, aligned with the implementation as of 2026-05-12.
The product direction is to turn drum sample extraction from a one-shot batch process into an interactive, supervised, progressively improving workflow. User edits should become constraints, preferences, and examples that improve clustering, review priority, labeling, and cleanup instead of only changing a visible table row.
## Current implementation status
The project now has a first supervised-editing foundation layered on top of the immutable extraction manifest:
- `supervised_state.py` persists `supervision_state.json` beside each completed run manifest.
- The state contains hits, clusters, confidence scores, review queue entries, constraints, events, suggestions, and undo snapshots.
- The FastAPI backend exposes state, move, pull-out, lock, suppress, review/favorite, suggestion, explanation, and undo endpoints.
- The browser UI includes an interactive supervision panel with a review queue, cluster board, suggestion inbox, constraint/event log, and cluster explanation drawer.
- The supervised layer now rewrites edited sample WAVs, MIDI, target reconstruction, full-context reproduced audio, and ZIP artifacts under `supervised/` while preserving original batch outputs.
## Documents
| Document | Purpose | Alignment status |
|---|---|---|
| [`FEATURE_REQUIREMENTS.md`](./FEATURE_REQUIREMENTS.md) | Functional requirements for interaction-driven quality improvements | Updated with implemented/partial/not-started status |
| [`SCOPE.md`](./SCOPE.md) | MVP, v2, and research/backlog boundaries | Updated to reflect delivered MVP foundation |
| [`FEASIBILITY_MATRIX.md`](./FEASIBILITY_MATRIX.md) | Feasibility, complexity, effort, UX value, quality value table | Kept as design prioritization with implementation notes |
| [`TASKS.md`](./TASKS.md) | Implementation task breakdown with dependencies and acceptance criteria | Updated with current task statuses |
| [`PROGRESS.md`](./PROGRESS.md) | Current status, completed work, open work, next actions | Updated after this development pass |
| [`ARCHITECTURE_NOTES.md`](./ARCHITECTURE_NOTES.md) | Required state model and technical approach | Updated with actual module/API mapping |
## Principle
Good interaction:
```text
user moves one hit into another cluster
→ system creates force-cluster/must-link constraints
→ semantic state recomputes confidence and review priority
→ similar ambiguous hits are proposed as suggestions
→ the UI explains the state/event/constraint changes
```
Bad interaction:
```text
user moves one hit
→ only that one visible DOM row changes
→ future clustering ignores the correction
```
## Current build recommendation
Next implementation should close the gap between semantic edits and artifact output:
1. Re-export edited sample pack from `supervision_state.json` without rerunning Demucs/onset detection.
2. Add waveform click-to-add missed onset backed by `force-onset` constraints.
3. Add restore for suppressed hits and batch accepted suggestions.
4. Make move/pull-out trigger a real local reclustering pass using cached feature vectors.
5. Add visible diff previews before accepting grouped suggestions.
6. Add browser-level tests for the interactive supervision panel.
The strongest technical foundation remains constraint-aware clustering plus uncertainty-driven review. The current pass implements the persistent state and UI/API shell needed for that foundation.
## Pass 5 implementation status
Implemented after initial alignment:
- supervised edited-state export under `supervised/`,
- add-onset waveform mode backed by `POST /api/jobs/{job_id}/hits/force-onset`,
- suppressed-hit restore backed by `POST /api/jobs/{job_id}/hits/{hit_id}/restore`,
- exact suggestion diff previews in API state and UI,
- validation via `scripts/test_supervised_export_and_force_onset.py`.
Still open:
- cluster merge/relabel/split workflows,
- cached feature-vector local reclustering,
- edited-vs-original comparison,
- browser-level UI tests.
|