Files

T

can1357 1d414c1383 feat: added IPython-backed Python tool with streaming output and Jupyter integration

- Added IPython-backed Python tool with streaming output and image/JSON rendering.
- Implemented Jupyter kernel gateway integration with WebSocket communication.
- Added Python prelude with 30+ shell-like utility functions for file operations.
- Migrated environment variables from PI_ to OMP_ prefix with automatic migration.
- Added streaming output system with automatic spill-to-disk for large outputs.
- Reorganized settings interface into behavior, tools, display, voice, status, lsp, and exa tabs.

2026-01-18 19:32:27 +01:00

2.8 KiB

Raw Blame History

Python REPL (Jupyter Kernel Gateway)

Requirements

Python 3 available on PATH (or via an active virtualenv)
jupyter-kernel-gateway (kernel_gateway module) and ipykernel installed in the selected Python environment

Install:

python -m pip install jupyter_kernel_gateway ipykernel

How It Works

The Python tool starts a Jupyter Kernel Gateway process locally, which manages an IPython kernel. All code execution goes through the gateway's REST and WebSocket APIs.

Startup flow:

Spawn python -m kernel_gateway on a random available port
Wait for gateway to become ready (GET /api/kernelspecs)
Create a kernel (POST /api/kernels)
Connect WebSocket for execution messages
Run prelude code (helper functions)

External Gateway Support

Instead of spawning a local gateway, you can connect to an already-running Jupyter Kernel Gateway:

# Connect to external gateway
export OMP_PYTHON_GATEWAY_URL="http://127.0.0.1:8888"

# Optional: auth token if gateway requires it (KG_AUTH_TOKEN)
export OMP_PYTHON_GATEWAY_TOKEN="your-token-here"

When OMP_PYTHON_GATEWAY_URL is set:

No local gateway process is spawned
Kernels are created on the external gateway
The gateway process is not killed on shutdown
Availability check uses /api/kernelspecs endpoint instead of local module check

This is useful for:

Remote kernel execution
Shared kernel environments
Pre-configured gateway setups

Environment Propagation

The kernel inherits a filtered environment (explicit allowlist + denylist)
PYTHONPATH includes the working directory and any existing PYTHONPATH value
Virtual environments are detected via VIRTUAL_ENV, .venv/, or venv/ and preferred when present

Kernel Modes

Settings under python control exposure and reuse:

toolMode: ipy-only (default), bash-only, both
kernelMode: session (default, queued), per-call

Shell Bridge

The Python prelude exposes bash() which:

Sources the shell snapshot when OMP_SHELL_SNAPSHOT is set
Runs via bash -lc when available, with OS fallbacks

Output Handling

Streams stdout/stderr as text
image/png display data renders inline in TUI
application/json display data renders as a collapsible tree
text/html display data is converted to basic markdown

Troubleshooting

Kernel unavailable: Ensure python + jupyter-kernel-gateway + ipykernel are installed; the session will fall back to bash-only.
External gateway unreachable: Check the URL is correct and the gateway is running. If auth is required, set OMP_PYTHON_GATEWAY_TOKEN.
IPC tracing: Set OMP_PYTHON_IPC_TRACE=1 to log kernel message flow.
Stdin requests: Interactive input is not supported; refactor code to avoid input() or provide data programmatically.

2.8 KiB Raw Blame History