feat: mejoras notebook functions — discover multi-servidor, write batch ops

jupyter_discover: soporte multi-servidor, detección de modo colaborativo mejorada.
jupyter_write: operaciones batch (insert, edit, delete), manejo robusto de Y.js.
jupyter_exec: mejoras en ejecución directa al kernel.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

python/functions/notebook/jupyter_write.md

@@ -3,11 +3,11 @@ name: jupyter_write
 kind: function
 lang: py
 domain: notebook
-version: "1.0.0"
+version: "1.1.0"
 purity: impure
 signature: "def jupyter_append_code(notebook_path: str, source: str, server_url: str = 'http://localhost:8888', token: str = '') -> dict"
-description: "Operaciones de escritura sobre celdas de un notebook Jupyter via colaboracion en tiempo real (WebSocket). Expone cinco operaciones: append_code, append_markdown, insert, edit, delete. NO ejecuta celdas — solo modifica la estructura del notebook."
-tags: [jupyter, notebook, websocket, cell, write, append, insert, edit, delete, nbmodel]
+description: "Operaciones de escritura sobre celdas de un notebook Jupyter via colaboracion en tiempo real (WebSocket) y API REST. Expone siete operaciones: append_code, append_markdown, insert, edit, delete, create y batch. NO ejecuta celdas — solo modifica la estructura del notebook. create usa PUT /api/contents para crear notebooks nuevos sin necesidad de websocket. batch abre una unica conexion WebSocket para insertar N celdas en una sola operacion."
+tags: [jupyter, notebook, websocket, cell, write, append, insert, edit, delete, create, batch, nbmodel, rest]
 uses_functions: []
 uses_types: []
 returns: []
@@ -29,6 +29,8 @@ file_path: "python/functions/notebook/jupyter_write.py"
 | `jupyter_insert_cell(notebook_path, cell_index, source, cell_type, server_url, token)` | Inserta celda en posicion especifica |
 | `jupyter_edit_cell(notebook_path, cell_index, source, server_url, token)` | Sobrescribe contenido de celda existente |
 | `jupyter_delete_cell(notebook_path, cell_index, server_url, token)` | Elimina una celda |
+| `jupyter_create_notebook(notebook_path, kernel_name, server_url, token, force)` | Crea un notebook vacio nbformat 4 via API REST |
+| `jupyter_batch_write(notebook_path, cells, server_url, token)` | Anade N celdas en una sola conexion WebSocket |
 
 ## Ejemplo
 
@@ -39,14 +41,38 @@ from notebook.jupyter_write import (
     jupyter_insert_cell,
     jupyter_edit_cell,
     jupyter_delete_cell,
+    jupyter_create_notebook,
+    jupyter_batch_write,
 )
 
+# Crear notebook nuevo
+result = jupyter_create_notebook(
+    notebook_path="notebooks/01_analisis.ipynb",
+    kernel_name="python3",
+    server_url="http://localhost:8888",
+)
+# {"action": "create", "notebook": "notebooks/01_analisis.ipynb", "created": true}
+
+# Si ya existe, lanza FileExistsError. Usar force=True para sobreescribir:
+result = jupyter_create_notebook("notebooks/01.ipynb", force=True)
+
+# Anadir multiples celdas de golpe (una sola conexion WebSocket)
+cells = [
+    {"type": "markdown", "source": "## Analisis inicial"},
+    {"type": "code", "source": "import pandas as pd"},
+    {"type": "code", "source": "df = pd.read_csv('data.csv')\ndf.head()"},
+]
+result = jupyter_batch_write(
+    notebook_path="notebooks/01_analisis.ipynb",
+    cells=cells,
+    server_url="http://localhost:8888",
+)
+# {"action": "batch", "cells_added": 3, "notebook": "notebooks/01_analisis.ipynb"}
+
 # Anadir celda de codigo al final
 result = jupyter_append_code(
     notebook_path="notebooks/01_analisis.ipynb",
     source="import pandas as pd\ndf = pd.read_csv('data.csv')",
-    server_url="http://localhost:8888",
-    token="mi-token",
 )
 # {"action": "append_code", "cell_index": 5, "notebook": "notebooks/01_analisis.ipynb"}
 
@@ -55,7 +81,7 @@ result = jupyter_append_markdown(
     notebook_path="notebooks/01_analisis.ipynb",
     source="## Resultados\n\nAnalisis de los datos obtenidos.",
 )
-# {"action": "append_markdown", "cell_index": 6, "notebook": "notebooks/01_analisis.ipynb"}
+# {"action": "append_markdown", "cell_index": 6, "notebook": "..."}
 
 # Insertar celda en posicion 2
 result = jupyter_insert_cell(
@@ -85,6 +111,21 @@ result = jupyter_delete_cell(
 ## CLI
 
 ```bash
+# Crear notebook nuevo
+python -m notebook.jupyter_write create notebooks/01.ipynb
+python -m notebook.jupyter_write create notebooks/01.ipynb --kernel python3
+python -m notebook.jupyter_write create notebooks/01.ipynb --force
+
+# Anadir multiples celdas desde archivo JSON
+python -m notebook.jupyter_write batch notebooks/01.ipynb --from cells.json
+
+# O via stdin
+cat cells.json | python -m notebook.jupyter_write batch notebooks/01.ipynb --from -
+echo '[{"type":"code","source":"import pandas"}]' | python -m notebook.jupyter_write batch notebooks/01.ipynb
+
+# Formato JSON de entrada para batch:
+# [{"type": "markdown", "source": "# Titulo"}, {"type": "code", "source": "import pandas"}]
+
 # Anadir celda de codigo
 python -m notebook.jupyter_write append-code notebooks/01.ipynb "print('hola')" --server http://localhost:8888 --token mi-token
 
@@ -104,8 +145,11 @@ python -m notebook.jupyter_write delete notebooks/01.ipynb 3
 ## Notas
 
 - Todas las funciones son sincronas publicamente. Internamente usan `asyncio.run()` sobre corutinas async que se comunican via WebSocket con `NbModelClient`.
+- `create` es la excepcion: usa urllib (PUT /api/contents) sin WebSocket. Crea un nbformat 4 con celdas vacias. Lanza `FileExistsError` si el notebook ya existe y `force=False`.
+- `batch` es mucho mas eficiente que N llamadas a `append-code`/`append-markdown`: abre una sola conexion WebSocket y hace un unico `asyncio.sleep(2)` de sincronizacion al final.
 - El `notebook_path` es relativo al servidor Jupyter (no al filesystem local).
 - Si el servidor no esta corriendo o el token es incorrecto, lanza excepcion de conexion de `jupyter_nbmodel_client`.
-- NO ejecuta celdas — solo modifica la estructura. Para ejecutar, usar el MCP de Jupyter o la API REST de Jupyter.
+- NO ejecuta celdas — solo modifica la estructura. Para ejecutar, usar `jupyter_exec`.
 - `server_url` y `token` tienen defaults convenientes para desarrollo local (`http://localhost:8888`, token vacio).
 - El campo `cell_index` en el resultado refleja la posicion final de la celda en el notebook.
+- Patron tipico: `create` para crear el notebook, luego `batch` para poblar las celdas iniciales.