Metadata-Version: 2.4
Name: kernelbox
Version: 0.1.0
Summary: A lightweight IPython kernel utility for agents.
Author: KernelBox maintainers
License: MIT
Keywords: agents,execution,ipython,jupyter,kernel
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: fastapi[standard]>=0.115.0
Requires-Dist: jupyter-client>=8.6
Provides-Extra: dev
Requires-Dist: ipykernel>=6.29; extra == 'dev'
Requires-Dist: mike>=2.1; extra == 'dev'
Requires-Dist: mkdocs-material>=9.5; extra == 'dev'
Requires-Dist: mkdocs>=1.6; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# kernelbox

`kernelbox` is a lightweight utility package for managing IPython kernels from agents, scripts, and small tools. It talks directly to kernels through `jupyter_client`: no notebook server, web server, browser, or daemon process.

## Install

This project is set up for `uv`.

```powershell
python scripts/bootstrap.py
```

The bootstrap script detects Windows, macOS, or Linux, installs `uv` if it is missing, creates `.venv` with `uv venv`, and installs project dependencies with `uv sync --extra dev`.

## Python API

```python
from kernelbox import destroy, execute, get_or_create

kernel = get_or_create("data-analysis")
result = execute(kernel, "sum([1, 2, 3])")

print(result.status)
print(result.return_value)

destroy("data-analysis")
```

## Retry API

```python
from kernelbox import execute_with_retry, get_or_create

kernel = get_or_create("repair-loop")

def on_error(result, attempt):
    return "x = 41\nx + 1"

result = execute_with_retry(kernel, "x + 1", on_error_fn=on_error)
```

`on_error_fn` receives the structured `ExecutionResult` and the current attempt number. If it returns a new code string, the retry loop uses that code for the next attempt. If it returns `None`, the same code is retried.

## CLI

The HTTP service uses the official FastAPI CLI.

```powershell
uv run fastapi dev
uv run fastapi run
```

Swagger UI is available at `http://127.0.0.1:8000/docs`, ReDoc at `http://127.0.0.1:8000/redoc`, and the OpenAPI schema at `http://127.0.0.1:8000/openapi.json`.

The lower-level kernel management CLI remains available for scripts:

```powershell
uv run kernelbox create --name my-kernel
uv run kernelbox list
uv run kernelbox exec --name my-kernel "print(1+1)"
uv run kernelbox exec --name my-kernel --bash "echo hello"
uv run kernelbox restart --name my-kernel
uv run kernelbox status --name my-kernel
uv run kernelbox destroy --name my-kernel
uv run kernelbox wipe
```

## Configuration

Settings can be controlled with environment variables.

| Variable | Default | Purpose |
|---|---:|---|
| `KERNELBOX_MAX_RETRIES` | `5` | Max retry attempts per execution |
| `KERNELBOX_KERNEL_IDLE_TIMEOUT` | `1800` | Idle timeout in seconds |
| `KERNELBOX_EXECUTION_TIMEOUT` | `60` | Code execution timeout in seconds |
| `KERNELBOX_OUTPUT_CHAR_LIMIT` | `10000` | Truncate stdout/stderr/rich text output |
| `KERNELBOX_STORE_BACKEND` | `file` | `file` or `memory` |
| `KERNELBOX_REGISTRY_PATH` | `.kernelbox/registry.json` on Windows, temp dir elsewhere | File registry path |
| `KERNELBOX_RUNTIME_DIR` | `.kernelbox/runtime` on Windows, temp dir elsewhere | Jupyter connection files |
| `KERNELBOX_STARTUP_CODE` | unset | Code run after kernel creation |
| `KERNELBOX_KERNEL_TYPE` | `python3` | Kernel name from Jupyter kernelspecs |

## Development

```powershell
uv run pytest
```

The tests are standard `unittest` tests, so they can also run without installing `pytest` if the package is on `PYTHONPATH`.
