ableton-mcp-ai/KIMI_K2_NOTE_API_FIX.md

# Kimi K2 Handoff: Fix del Error `Clip.add_new_note`

## Estado General

Kimi avanzo parte importante del handoff anterior. Verificado en disco:

- `AbletonMCP_AI/__init__.py` y `AbletonMCP_AI/Remote_Script.py` ahora priorizan `abletonmcp_init.py`
- `server_v2.py` fue movido a `obsoletos`
- `server.py` ya no tiene tools duplicadas
  - verificado: `tool_count=85`, `unique_tool_names=85`

Conclusion:

- el handoff anterior no quedo 100% terminado
- pero si hubo progreso real en arquitectura

## Problema Nuevo

Error observado por Claude:

```text
AttributeError: 'Clip' object has no attribute 'add_new_note'
```

Evidencia del log de Ableton:

- archivo: `C:\Users\ren\AppData\Roaming\Ableton\Live 12.0.15\Preferences\Log.txt`
- timestamp del fallo visto: `2026-03-29 22:09:46`
- traceback:
  - `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\abletonmcp_init.py`
  - `line 2223, in _generate_track`

## Hallazgo Clave

El `abletonmcp_init.py` actual en disco ya no llama `add_new_note` dentro de `_generate_track`.

Líneas actuales alrededor de `2208..2228`:

- crea el clip
- si hay notas, solo pone el nombre del clip y loggea `notes pending`
- ya no escribe notas

Eso significa que el error visto en el log probablemente vino de una version anterior en memoria o de una version cargada antes del parche.

Pero eso no cierra el problema.

## El Problema Real Que Sigue Abierto

Aunque el crash puntual de `add_new_note` parece haber sido quitado del `_generate_track` actual, el runtime quedo incompleto:

- ya no crashea por `add_new_note`
- pero tampoco escribe las notas MIDI del track generado

Hoy `_generate_track` en `abletonmcp_init.py` hace esto:

- crea tracks
- crea clips
- detecta que hay notas
- no las inserta
- deja un log de `notes pending`

Eso no es una solucion completa.

## Contrato De Notas: Otro Bug Importante

El helper canonico que si escribe notas en `abletonmcp_init.py` es:

- `_add_notes_to_clip(...)`

Ese helper usa:

- `clip.set_notes(tuple(live_notes))`

Pero espera notas con la clave:

- `start_time`

Mientras que `song_generator.py` emite notas con la clave:

- `start`

Verificado:

- `song_generator.py` contiene multiples ocurrencias de `'start'`
- no contiene `'start_time'`

Conclusion:

- si solo conectas `_generate_track` con `_add_notes_to_clip` sin normalizar el esquema, la escritura de notas va a quedar mal o en `0.0`

## Archivos Que Importan

### Canonicos

- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\abletonmcp_init.py`
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\__init__.py`
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\Remote_Script.py`
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\song_generator.py`

### Fallback legacy que sigue siendo peligroso

- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI_BAK_20260328_200801\Remote_Script.py`

Ese fallback todavia contiene `clip.add_new_note(...)` al menos en dos lugares.

## Que Hay Que Arreglar

### 1. Completar la escritura de notas en el runtime canonico

Archivo:

- `abletonmcp_init.py`

Objetivo:

- `_generate_track()` debe volver a escribir notas reales
- no solo crear clips vacios con un log de `notes pending`

Forma correcta:

- reutilizar `clip.set_notes(...)`
- no volver a `add_new_note(...)`

### 2. Normalizar el schema de notas

Antes de construir `live_notes`, aceptar ambas claves:

- `start`
- `start_time`

Regla recomendada:

```python
start_time = note.get("start_time", note.get("start", 0.0))
```

Aplicarlo en:

- `_add_notes_to_clip(...)`
- `_add_notes_to_arrangement_clip(...)`
- cualquier helper nuevo que inserte notas durante `_generate_track(...)`

### 3. Conectar `_generate_track(...)` con el helper real

Ahora mismo `_generate_track(...)` hace un placeholder.

Hay que reemplazar ese bloque por una llamada real a escritura de notas:

- crear clip si no existe
- normalizar notas del `clip_cfg`
- escribirlas con `set_notes(...)`

No dejar el parche en un estado donde:

- desaparece el crash
- pero toda la generacion queda muda

### 4. Parchear tambien el fallback

Archivo:

- `AbletonMCP_AI_BAK_20260328_200801/Remote_Script.py`

Aunque ya no sea la prioridad, sigue en el path de fallback.

Hay que sacar todos los `add_new_note(...)` de ahi tambien y moverlos a `set_notes(...)` o a un helper compatible.

Si no:

- el proximo cambio de shim
- o una carga inesperada del fallback
- reintroduce exactamente el mismo bug

### 5. Validar que Ableton cargue el archivo correcto

No confiar en el archivo en disco solamente.

Despues del parche:

1. cerrar Ableton completo
2. abrir Ableton
3. confirmar en el log que carga el runtime nuevo
4. correr un test minimo que cree un clip con notas

Si queres dejar una marca temporal de validacion, usar un log unico y luego removerlo.

## Fix Recomendado

### Opcion simple y correcta

En `abletonmcp_init.py`:

1. crear un helper interno para convertir notas del generador al formato Live
2. aceptar `start` o `start_time`
3. usar `clip.set_notes(tuple(live_notes))`
4. llamar ese helper desde `_generate_track(...)`

Pseudocodigo:

```python
def _coerce_live_notes(self, notes):
    live_notes = []
    for note in notes:
        pitch = int(note.get("pitch", 60))
        start_time = float(note.get("start_time", note.get("start", 0.0)))
        duration = float(note.get("duration", 0.25))
        velocity = int(note.get("velocity", 100))
        mute = bool(note.get("mute", False))
        live_notes.append((pitch, start_time, duration, velocity, mute))
    return tuple(live_notes)
```

Luego:

```python
if "notes" in clip_cfg and clip_slot.has_clip:
    clip = clip_slot.clip
    live_notes = self._coerce_live_notes(clip_cfg["notes"])
    if live_notes:
        clip.set_notes(live_notes)
```

Y reusar el mismo helper en `_add_notes_to_clip(...)`.

## Que No Hacer

- no volver a `add_new_note(...)`
- no dejar `notes pending` como solucion final
- no asumir que porque el log viejo fallo, el archivo actual en disco sigue igual
- no parchear solo el backup y olvidarte del runtime canonico
- no cerrar el issue sin verificar notas reales dentro del clip

## Verificacion Obligatoria

### A. Sanity check de codigo

Buscar y confirmar:

- no hay `add_new_note(` en `abletonmcp_init.py`
- no hay `add_new_note(` en el fallback activo

### B. Compile

```powershell
python -m py_compile "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\abletonmcp_init.py"
python -m py_compile "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\__init__.py"
python -m py_compile "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\Remote_Script.py"
```

### C. Runtime

Test minimo:

- generar un track MIDI simple con un clip y pocas notas
- confirmar que no hay `AttributeError`
- confirmar que el clip no queda vacio

### D. Log

En el log de Ableton no debe aparecer:

- `AttributeError: 'Clip' object has no attribute 'add_new_note'`

Y deberia aparecer:

- carga del runtime esperado
- recepcion del comando
- finalizacion sin traceback

## Diagnostico Final

Mi lectura actual es esta:

- Kimi si arregló parte del handoff anterior
- el bug nuevo es real
- el crash observado viene de una version previa del runtime canonico
- el archivo actual ya fue tocado para evitar `add_new_note`, pero el arreglo quedo incompleto
- ahora falta cerrar bien la escritura de notas con `set_notes(...)` y schema compatible con `song_generator.py`

Ese es el arreglo que hay que terminar. No hace falta reinventar la arquitectura otra vez.