fn_registry/dev/issues/0050-jupyter-exec-collab-client-failure.md

0050 — jupyter_exec falla por cliente colaborativo (workaround documentado)

APP Metadata

Campo	Valor
ID	0050
Estado	pendiente
Prioridad	media
Tipo	bug — python/functions/notebook/jupyter_exec.py

Dependencias

Ninguna. Independiente del resto.

---

Sintoma

Al ejecutar jupyter_exec.py append <notebook> <code> contra un Jupyter Lab arrancado con el launcher estandar de los analyses (run-jupyter-lab.sh, flag --collaborative), la operacion falla con:

{"error": "HTTP Error 405: Method Not Allowed"}

jupyter_write.py append-code y append-markdown SI funcionan (no usan el canal colaborativo). El bug solo afecta a jupyter_exec, que necesita ejecutar la celda en el kernel y para eso usa jupyter_nbmodel_client con websocket Y.js.

Reproducido en 2026-05-04 durante la construccion del analysis projects/osint_graph/analysis/gliner_glirel_tuning/. El resto de funciones del modulo notebook/ quedan intactas:

$JX append <nb> <code>            # ❌ HTTP 405
$JW append-code <nb> <code>       # ✅ OK (sin ejecucion)
$JW append-markdown <nb> <md>     # ✅ OK
$JX cell <nb> <idx>               # 🔁 No probado, pero usa el mismo cliente
$JX kernel <code>                 # 🔁 No probado

---

Diagnostico (parcial)

jupyter_nbmodel_client espera que el server tenga la extension jupyter_collaboration activa y montada en /api/collaboration/.... El launcher arranca jupyter con el flag CLI --collaborative, que en versiones recientes (jupyter_server >= 2.x, jupyter-collaboration >= 4.x) ya no es suficiente — la extension se carga via entry-point y se controla con flags distintos (--YDocExtension.disable_rtc o equivalente), o requiere un fichero de config explicito.

Salida de jupyter_discover.py confirma el sintoma indirectamente:

{ "url": "http://localhost:8888", "collaborative": false, ... }

aunque --collaborative esta en el launch command. Es decir: el server arranca, expone la API REST, pero la capa colaborativa NO esta activa.

---

Workaround usado en gliner_glirel_tuning

Cambio de tactica: en lugar de construir el notebook con jupyter_exec append celda a celda, se ejecutan los experimentos en un script externo y se empotran las celdas (codigo + outputs ya generados) con nbformat directo a fichero. El notebook resultante es persistente y no necesita el canal colaborativo.

# build_notebook.py
import nbformat as nbf
nb = nbf.v4.new_notebook()
for src, stdout in cells:
    cell = nbf.v4.new_code_cell(src)
    cell.outputs = [nbf.v4.new_output("stream", name="stdout", text=stdout)]
    nb.cells.append(cell)
nbf.write(nb, "notebooks/01_foo.ipynb")

Si se quieren outputs reales (DataFrames como HTML, figuras matplotlib), ejecutar despues con nbconvert:

IPYTHONDIR=$(pwd)/.ipython ./.venv/bin/jupyter nbconvert \
  --to notebook --execute notebooks/01_foo.ipynb \
  --output 01_foo.ipynb --ExecutePreprocessor.timeout=300

Esto bypassa completamente el canal colaborativo y produce un .ipynb funcional, abrible en Jupyter Lab para ver / iterar / re-ejecutar.

Ver projects/osint_graph/analysis/gliner_glirel_tuning/build_notebook.py y build_notebook_e2e.py para ejemplos vivos.

---

Causas raiz a investigar

1. Verificar la version de jupyter-collaboration en el venv del analysis. Si es >=4.x, el flag --collaborative ya no aplica y el launcher (write_jupyter_launcher_bash_io) tiene que actualizarse.
2. El cliente jupyter_nbmodel_client puede tener su propia ventana de versiones soportadas — comprobar pinning en python/.venv y en los venvs de analyses.
3. El endpoint /api/collaboration/document debe responder a un GET con HTTP 200 cuando la extension esta activa. Si responde 405, el cliente intenta una operacion (POST/PUT) sobre un endpoint que solo acepta GET, sintoma de mismatch.

---

Tareas

1. Reproducir el HTTP 405 con un notebook nuevo y un kernel nuevo en un analysis recien creado.
2. Capturar la URL exacta y el metodo HTTP que dispara el 405 (anadir logging a jupyter_exec.py linea ~192/229 donde llama a get_jupyter_notebook_websocket_url).
3. Verificar version de jupyter-collaboration en el venv y comparar con la matriz de compatibilidad de jupyter_nbmodel_client.
4. Una de dos:
   • (a) Corregir el flag/config en write_jupyter_launcher_bash_io para activar correctamente la colaboracion en versiones nuevas.
   • (b) Si la API colaborativa cambio mucho, migrar jupyter_exec.py a usar el JupyterClient clasico (REST + WebSocket directo al kernel sin Y.js) que es estable a traves de versiones. jupyter_kernel.py ya hace algo asi y funciona.
5. Anadir un test e2e basico en tests/ que arranca jupyter, lanza jupyter_exec append, verifica que la celda se ejecuto y captura stdout. Sin esto el bug puede regresar.

---

Out of scope

• Reescribir el sistema completo de notebook collaboration.
• Migrar a un MCP. La regla notebook_collaboration.md es explicita: estas funciones reemplazan al MCP jupyter.

---

Riesgos

• Si la causa es la matriz de versiones, la opcion (a) puede generar fricion futura cada vez que jupyter-collaboration haga un breaking change. La opcion (b) es mas robusta a largo plazo aunque pierde la capacidad de ver cambios en tiempo real desde el navegador.

Notas operativas

Mientras este bug exista, el patron recomendado para construir notebooks desde un agente Claude en un analysis es:

1. build_notebook.py con nbformat para estructura + outputs estaticos.
2. nbconvert --execute para outputs reales (HTML, plots).
3. Si necesitas tiempo real con el browser, abre el notebook ya generado en Jupyter Lab y reejecuta a mano.

El propio analysis gliner_glirel_tuning es referencia.