# TASK-011 ## Title Music DNA Builder --- ## Objective Implement the Music DNA Builder. The Music DNA Builder transforms the extracted analyzer features into a normalized, versioned MusicDNA object. This object becomes the canonical musical representation used by all future systems: - Similarity Engine - Embedding Engine - Recommendation Engine - Playlist Generator - Neural Model Training This task introduces no similarity calculations and no machine learning. Its only responsibility is to build a deterministic MusicDNA object from analyzer features. --- # Expected Commit Message Add Music DNA Builder --- # Requirements Read before implementation: - docs/00_PROJECT_PRINCIPLES.md - docs/01_SPEC.md - docs/02_ARCHITECTURE.md - docs/03_ANALYZER_API.md - docs/04_MUSIC_DNA_SCHEMA.md - docs/04a_FEATURE_REGISTRY.md - docs/04b_NORMALIZATION_RULES.md - docs/05_AI_DEVELOPER_GUIDE.md These documents are authoritative. --- # Scope Create a new package src/music_dna/ containing __init__.py music_dna.py builder.py normalizer.py exceptions.py --- ## MusicDNA Implement an immutable MusicDNA dataclass. Required fields track_id schema_version created_at values metadata --- ### values Dictionary key canonical feature identifier Examples signal.rms signal.peak dynamic.range spectral.centroid rhythm.tempo harmony.key ... value normalized feature value --- ### metadata Contains builder_version feature_count normalization_version source_analyzer_versions The metadata must be immutable. --- ## MusicDNABuilder Implement build() Responsibilities Load latest features for one track Validate that every feature exists in FeatureRegistry Normalize every feature Create immutable MusicDNA Return MusicDNA Builder must be deterministic. Running twice on the same input must produce identical output. --- ## Normalizer Implement a dedicated Normalizer. Do NOT place normalization logic inside the builder. Normalization strategy comes from FeatureDefinition. Supported strategies identity minmax log zscore categorical none --- ### Initial implementation For this task identity returns value unchanged categorical returns original value none returns original value minmax returns original value log returns original value zscore returns original value In other words build the architecture Do NOT implement mathematical normalization yet. That will be implemented later. --- ## Validation Builder must verify missing features duplicate features unknown features unsupported normalization strategy invalid values missing registry definitions Raise dedicated exceptions. --- ## Builder output MusicDNA must contain every registered feature. If a feature is missing the builder must fail. No partial MusicDNA objects. --- ## Repository integration Use the existing FeatureRepository. Do NOT create a MusicDNA repository yet. Persistence is the next task. --- ## CLI Add a new command musimuse dna Workflow Load tracks Build MusicDNA Validate Print summary Do NOT save anything yet. Example Music DNA Summary Tracks processed: 42 Successful: 42 Failed: 0 Schema version: 1.0 Average features: 55 --- ## Logging Add structured logging dna.started dna.track dna.validation_failed dna.completed --- ## Forbidden Do NOT implement Similarity Embeddings Recommendations Vector search ANN indexes Database persistence Neural networks Feature weighting Distance metrics --- # Tests Add complete tests covering MusicDNA immutability Builder Normalizer Validation Missing features Unknown features Duplicate features Deterministic output Registry integration CLI command Builder metadata Use synthetic FeatureSets. Do not depend on analyzer execution. --- # Documentation Update Architecture if necessary. Document the MusicDNA Builder workflow. --- # Definition of Done ✓ MusicDNA implemented ✓ MusicDNABuilder implemented ✓ Normalizer implemented ✓ Validation implemented ✓ Registry integration implemented ✓ Deterministic output verified ✓ CLI dna command implemented ✓ Structured logging added ✓ Tests pass ✓ Ruff passes ✓ Black passes ✓ isort passes --- ## Important This task intentionally builds only the MusicDNA object. Do NOT persist it. Do NOT compare it. Do NOT search it. Persistence, similarity, embeddings and recommendation systems will be implemented in subsequent tasks.