fn_registry/python/functions/notebook/jupyter_exec.md

name, kind, lang, domain, version, purity, signature, description, tags, uses_functions, uses_types, returns, returns_optional, error_type, imports, params, output, tested, tests, test_file_path, file_path

name	kind	lang	domain	version	purity	signature	description	tags	uses_functions	uses_types	returns	returns_optional	error_type	imports	params	output	tested	tests	test_file_path	file_path
jupyter_exec	function	py	notebook	1.0.0	impure	jupyter_append_execute(notebook_path: str, code: str, server_url: str, token: str) -> dict	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).	jupyter notebook kernel websocket execution cells				false	error_go_core	jupyter_kernel_client jupyter_nbmodel_client	name desc notebook_path Ruta relativa al notebook name desc code Código a ejecutar name desc server_url URL del servidor Jupyter (default localhost:8888) name desc token Token de autenticación (default vacío)	Dict con cell_index y outputs del código ejecutado, o resultados del kernel	false			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.

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).

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.

from notebook.jupyter_exec import jupyter_kernel_execute

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

CLI

# 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.