---
name: jupyter_exec
kind: function
lang: py
domain: notebook
version: "1.0.0"
purity: impure
signature: "jupyter_append_execute(notebook_path: str, code: str, server_url: str, token: str) -> dict"
description: "Ejecuta codigo en kernels de Jupyter via WebSocket. Tres modos: append (añade celda al notebook y la ejecuta), cell (ejecuta celda existente por indice), kernel (ejecuta en el kernel sin tocar ningun notebook)."
tags: [jupyter, notebook, kernel, websocket, execution, cells]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: [jupyter_kernel_client, jupyter_nbmodel_client]
params:
  - name: notebook_path
    desc: "Ruta relativa al notebook"
  - name: code
    desc: "Código a ejecutar"
  - name: server_url
    desc: "URL del servidor Jupyter (default localhost:8888)"
  - name: token
    desc: "Token de autenticación (default vacío)"
output: "Dict con cell_index y outputs del código ejecutado, o resultados del kernel"
tested: false
tests: []
test_file_path: ""
file_path: "python/functions/notebook/jupyter_exec.py"
---

## Funciones

### `jupyter_append_execute(notebook_path, code, server_url, token)`

Añade una celda de codigo al final del notebook y la ejecuta. Usa el protocolo
colaborativo de Jupyter, por lo que tanto el agente como el usuario ven la celda
y su output en tiempo real en JupyterLab.

```python
from notebook.jupyter_exec import jupyter_append_execute

result = jupyter_append_execute(
    "notebooks/analisis.ipynb",
    "import pandas as pd\nprint(pd.__version__)",
    server_url="http://localhost:8888",
    token="",
)
# {"cell_index": 5, "outputs": ["2.2.1"]}
```

### `jupyter_execute_cell(notebook_path, cell_index, server_url, token)`

Ejecuta una celda existente del notebook por su indice (0-based).

```python
from notebook.jupyter_exec import jupyter_execute_cell

result = jupyter_execute_cell("notebooks/analisis.ipynb", 3)
# {"cell_index": 3, "outputs": ["42"]}
```

### `jupyter_kernel_execute(code, server_url, token)`

Ejecuta codigo directamente en el kernel sin modificar ningun notebook. Util para
consultas rapidas, inspeccion de variables o verificacion de estado del kernel.

```python
from notebook.jupyter_exec import jupyter_kernel_execute

result = jupyter_kernel_execute("len(df)")
# {"outputs": ["1500"], "status": "ok"}
```

## CLI

```bash
# Añadir celda y ejecutar
python -m notebook.jupyter_exec append notebooks/mi.ipynb "print('hola')" --server http://localhost:8888 --token mytoken

# Ejecutar celda existente
python -m notebook.jupyter_exec cell notebooks/mi.ipynb 2 --server http://localhost:8888

# Ejecutar en kernel directamente
python -m notebook.jupyter_exec kernel "x = 42; print(x)"
```

Output siempre JSON. En error retorna `{"error": "..."}` por stderr con exit code 1.

## Extraccion de outputs

| output_type | campo leido |
|---|---|
| stream | `text` |
| display_data / execute_result | `data.text/plain` |
| error | `traceback` (joined con `\n`) |

## Notas

- Las funciones `append` y `cell` son async internamente; las publicas usan `asyncio.run()`.
- `jupyter_kernel_execute` es sincrona directamente porque `KernelClient.execute` es bloqueante.
- El token puede ser cadena vacia si el servidor tiene autenticacion deshabilitada.
- `NbModelClient` requiere que el servidor tenga habilitado el endpoint colaborativo (`/api/collaboration/`), disponible en JupyterLab >= 4 con `jupyter-collaboration` instalado.
- **Auto-init**: `jupyter_append_execute` crea el notebook automaticamente si no existe (via REST PUT /api/contents) y arranca una sesion con kernel si no hay ninguna activa para ese notebook (via POST /api/sessions). No es necesario abrir el notebook manualmente en el navegador.
- **Auto-session**: `jupyter_execute_cell` tambien garantiza que exista una sesion con kernel antes de ejecutar.
- **Fix Issue 006**: `jupyter_execute_cell` normaliza la celda antes de ejecutar. Las celdas creadas manualmente (no via la UI de Jupyter) pueden carecer de `outputs` o `execution_count` en el modelo CRDT, lo que causaba `KeyError: 'outputs'` dentro de `execute_cell` al hacer `del ycell["outputs"][:]`. El fix lee la celda con `nb[cell_index]`, detecta los campos faltantes, y reemplaza la celda via `nb[cell_index] = _normalize_code_cell(cell)` — que usa `set_cell` internamente para re-crear el mapa CRDT completo preservando el source original.