Sync: Complete project state with all MEGA SPRINT V1-V3 features and Codex stubs

2026-04-08 17:58:47 -03:00
parent c9d3528900
commit 6d080d43b3
372 changed files with 189715 additions and 8590 deletions
--- a/docs/SPRINT_v0.1.2_CHANGES.md
+++ b/docs/SPRINT_v0.1.2_CHANGES.md
@@ -0,0 +1,293 @@
+# Sprint v0.1.2 - Cambios Realizados (Documentacion de Realidad)
+
+Fecha: 2026-03-30
+Estado: Documentacion post-verificacion
+
+## Resumen Ejecutivo
+
+Este sprint buscaba cerrar la brecha entre "parece mejor" y "esta validado". Se verifico el estado real del codigo sin ejecutar pruebas en Live.
+
+**Hallazgo principal**: Mucho codigo que parecia pendiente estaba ya implementado, pero sin validacion runtime.
+
+---
+
+## Tareas Analizadas y Estado Real
+
+### 1. clear_all_tracks
+
+**Estado: IMPLEMENTADO, FALTA VALIDACION RUNTIME**
+
+**Evidencia encontrada:**
+- Implementacion: `abletonmcp_init.py:2664-2698`
+- Funcion `_clear_all_tracks()` con logica completa:
+  - Loop while elimina tracks desde el final (evita index shifting)
+  - Mantiene 1 track (requirement de Ableton)
+  - Limpia clip slots del track restante
+  - Elimina devices del track restante
+  - Resetea nombre a "1-MIDI" y color a 0
+- Compilacion: OK (verificado con `python -m py_compile`)
+
+**Problema documentado:**
+- Error blando "Couldn't delete track." al finalizar (CLAUDE.md:35)
+- Aun asi la sesion queda limpia
+- Necesita 3 validaciones consecutivas sin error
+
+**Por hacer:**
+- [ ] Validar en Live real con tracks y clips existentes
+- [ ] Verificar no hay "Audio queue timeout"
+- [ ] Confirmar estado final consistente
+
+---
+
+### 2. Async Job Infrastructure
+
+**Estado: COMPLETAMENTE IMPLEMENTADO**
+
+**Tools MCP expuestas (4 funciones):**
+
+1. `generate_track_async()` - `server.py:6503-6535`
+   - Params: genre, style, bpm, key, structure
+   - Retorna: job_id, session_id, status="queued"
+
+2. `generate_song_async()` - `server.py:6539-6575`
+   - Params: genre, style, bpm, key, structure, auto_play, apply_automation
+   - Retorna: job_id, session_id, status="queued"
+
+3. `get_generation_job_status()` - `server.py:6579-6588`
+   - Param: job_id
+   - Retorna: estado completo del job + future_done flag
+
+4. `cancel_generation_job()` - `server.py:6592-6614`
+   - Param: job_id
+   - Cancela future si aun no empezo
+
+**Infrastructure interna:**
+- `_generation_jobs: Dict[str, Any]` - server.py:4734
+- `_generation_job_lock = threading.RLock()` - server.py:4735
+- `_submit_generation_job()` - server.py:5084-5101
+  - Crea job_id con uuid
+  - Somete a ThreadPoolExecutor
+  - Estados: queued -> running -> completed/failed
+- ThreadPoolExecutor para procesamiento background
+
+**Smoke test disponible:**
+- `temp\smoke_test_async.py` - 547 lineas
+- Importa server.py directamente (arquitectura correcta)
+- Clase `MCPServerClient` para invocar tools
+- Soporta flags: --use-track, --genre, --bpm, --poll-interval
+
+**Por hacer:**
+- [ ] Ejecutar smoke test con Live abierto
+- [ ] Verificar flujo: queued -> running -> completed
+- [ ] Confirmar tracks aparecen en Live
+- [ ] Validar manifest retornado
+
+---
+
+### 3. Z.ai Backoff, Retry y Cache
+
+**Estado: COMPLETAMENTE IMPLEMENTADO**
+
+**Implementacion (`zai_judges.py`):**
+
+**Configuracion:**
+- `MAX_RETRIES = 3` - linea 33
+- `BACKOFF_DELAYS = [1.0, 2.0, 4.0]` - linea 34
+- `CACHE_TTL_SECONDS = 300` (5 minutos) - linea 29
+
+**Funciones de cache:**
+- `_generate_cache_key()` - lineas 37-53
+  - SHA256 de prompt + payload
+  - Incluye: genre, style, bpm, key, judge_role, candidate_ids
+- `_get_cached_result()` - lineas 56-68
+  - Retorna None si expirado o no existe
+- `_set_cached_result()` - lineas 71-74
+
+**Retry loop (`_call()` method):**
+- Lineas 155-205
+- Maneja: HTTPError 429, URLError, TimeoutError
+- Loguea: "Judge API 429 on attempt X/Y, retrying in Zs..."
+- Retorna {} si todos fallan (trigger fallback)
+
+**Fallback heuristico:**
+- Lineas 225-242
+- Cuando API no disponible, selecciona top candidate
+- Mode: "heuristic_fallback"
+- Directivas default para rhythm_density, bass_motion, arrangement_emphasis, vocal_strategy
+
+**Por hacer:**
+- [ ] Validar comportamiento real ante 429 de Z.ai
+- [ ] Confirmar cache hit evita llamadas redundantes
+
+---
+
+### 4. Same-Pack Selection para atmos_fx y vocal_shot
+
+**Estado: COMPLETAMENTE IMPLEMENTADO**
+
+**Implementacion (`sample_selector.py`):**
+
+**Deteccion de roles estrictos:**
+- Lineas 1222-1243
+- Roles: atmos_fx, vocal_shot, fill_fx, snare_roll
+- Aplica `_calculate_same_pack_strict_bonus()`
+- Peso adicional: +0.25 para same-pack
+
+**Funcion de scoring:**
+- `_calculate_same_pack_strict_bonus()` - lineas 1578-1632
+- Retorna: (bonus, selection_type, reason)
+- Tipos:
+  - "same_pack" (exact folder match): 2.0
+  - "same_pack" (subfolder): 1.8
+  - "same_parent" (sibling): 1.3
+  - "fallback": 0.0
+
+**Coherence groups:**
+- `vocal_fx_group` - linea 798
+  - Roles: vocal_loop, vocal_shot, atmos_fx, fill_fx
+
+**Section-aware selection:**
+- Diferentes pesos por seccion (intro, build, drop, break, outro)
+- atmos_fx primario en: intro, break, outro
+- vocal_shot primario en: drop, verse
+
+**Por hacer:**
+- [ ] Inspeccionar paths elegidos en generacion real
+- [ ] Confirmar coherencia de pack entre roles
+
+---
+
+### 5. Groove Extractor
+
+**Estado: IMPLEMENTADO, FALTA CORNISA REAL**
+
+**Implementacion (`groove_extractor.py`):**
+
+**Clase principal:**
+- `DembowGrooveExtractor` - linea 65
+
+**Directorios escaneados:**
+- `SCAN_DIRS = ['drumloops', 'perc loop', 'oneshots']` - linea 72
+
+**Ignorados:**
+- Carpetas: .sample_cache, .segment_rag, .git, trash, recycle, deleted, __pycache__
+- Archivos: .json, .txt, .md, .doc, .docx
+- Ocultos (empiezan con .)
+
+**Estructura de template:**
+```python
+@dataclass
+class GrooveTemplate:
+    source_file: str
+    bpm: float
+    kick_positions: List[float]      # Normalizado 0-4 beats
+    snare_positions: List[float]
+    hat_positions: List[float]
+    kick_velocities: List[float]      # 0.0 - 1.0
+    snare_velocities: List[float]
+    hat_velocities: List[float]
+    timing_variance_ms: float
+    density: float
+    style: str = "dembow"
+```
+
+**Cache:**
+- Ubicacion: `~/.abletonmcp_ai/dembow_groove_templates.json`
+- Deduplicacion por hash de contenido
+
+**Por hacer:**
+- [ ] Verificar `libreria/reggaeton/` existe con loops .wav
+- [ ] Ejecutar escaneo y contar templates
+- [ ] Confirmar variedad de templates (no todos identicos)
+
+---
+
+## Validaciones Sintacticas Realizadas
+
+**Archivos compilados exitosamente:**
+```
+python -m py_compile "AbletonMCP_AI/AbletonMCP_AI/MCP_Server/server.py"        # OK
+python -m py_compile "AbletonMCP_AI/AbletonMCP_AI/MCP_Server/groove_extractor.py" # OK
+python -m py_compile "AbletonMCP_AI/AbletonMCP_AI/MCP_Server/zai_judges.py"        # OK
+python -m py_compile "abletonmcp_init.py"                                           # OK
+```
+
+**Metricas del server:**
+- Tools totales: 89
+- Nombres unicos: 89 (no hay duplicados)
+- Async tools: 4 (generate_track_async, generate_song_async, get_generation_job_status, cancel_generation_job)
+
+---
+
+## Issues Conocidos (Sin Resolver)
+
+1. **clear_all_tracks**: Error blando "Couldn't delete track." al final
+2. **Async validation**: Ninguna prueba async ha corrido end-to-end en Live
+3. **Groove corpus**: Depende de libreria/reggaeton/ con loops reales
+4. **Z.ai 429**: Implementado retry pero no validado contra API real
+
+---
+
+## Proximo Trabajo Recomendado
+
+### Alta Prioridad (Bloqueantes)
+
+1. **Validar clear_all_tracks en Live**
+   - Ejecutar 3 veces consecutivas
+   - Confirmar no crash ni timeout
+   - Documentar si error blando persiste
+
+2. **Ejecutar temp\smoke_test_async.py**
+   - Con Live abierto
+   - Verificar flujo completo de jobs
+   - Confirmar tracks creados
+
+### Media Prioridad
+
+3. **Verificar groove templates**
+   - Escanear libreria/reggaeton/
+   - Contar templates extraidos
+   - Evaluar calidad/variedad
+
+4. **Validar Z.ai retry**
+   - Probar contra API real
+   - Forzar 429 si es posible
+   - Confirmar cache funciona
+
+---
+
+## Lecciones Aprendidas
+
+1. **No asumir estado de tarea**: Muchas tareas marcadas como "pendientes" estaban implementadas
+2. **Verificar con codigo**: grep + read > confiar en documentacion
+3. **Separar implementacion de validacion**: Codigo puede estar listo pero sin probar
+4. **Documentar lineas exactas**: Facilita handoffs futuros
+
+---
+
+## Archivos Relevantes (Con Lineas)
+
+**Implementaciones completas:**
+- `abletonmcp_init.py:2664-2698` - clear_all_tracks
+- `server.py:6503-6614` - async tools (4 funciones)
+- `server.py:4734-5101` - async infrastructure
+- `zai_judges.py:29-205` - retry/cache logic
+- `sample_selector.py:1222-1632` - same-pack selection
+- `groove_extractor.py` - completo (663 lineas)
+- `temp\smoke_test_async.py` - test suite (547 lineas)
+
+**Documentacion actualizada:**
+- `docs/SPRINT_v0.1.2_NEXT.md` - sprint activo
+- `KIMI_K2_ACTIVE_HANDOFF.md` - estado real verificado
+- `docs/SPRINT_v0.1.2_CHANGES.md` - este archivo
+
+---
+
+## Metricas Finales
+
+- **Tareas implementadas**: 4 de 5 (80%)
+- **Tareas validadas**: 0 de 5 (0%)
+- **Codigo compilable**: 100%
+- **Lineas verificadas**: ~1100 en server.py + 663 groove_extractor + 362 zai_judges
+
+**Conclusion**: El codigo esta listo. Falta validacion en vivo.