Metadata-Version: 2.4
Name: superkernels
Version: 0.9.6
Summary: A local ipykernel adapter for remote Super Kernel runtimes.
Author-email: Leo Li <leoustc@icloud.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://superkernel.leoustc.com
Project-URL: Source, https://github.com/leoustc/collection-pip/tree/main/jupyter-superkernel/superkernels
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Classifier: Framework :: Jupyter
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ipykernel>=6.29
Requires-Dist: pydantic>=2.7
Requires-Dist: requests>=2.31
Dynamic: license-file

# SuperKernel

SuperKernel brings remote compute into your daily notebook.

It is a Jupyter-compatible Python kernel that connects a local notebook to a
configured SuperKernel runtime. Your existing Jupyter tools continue to manage
the notebook connection while code runs on the selected remote Python, MPI, or
PyTorch environment.

## Features

- Works as a standard Jupyter kernel in JupyterLab and VS Code.
- Streams remote output back to notebook cells as it is produced.
- Preserves a separate Python namespace for each notebook session.
- Executes cells sequentially and supports interrupt and restart actions.
- Reconnects interrupted output streams without submitting the cell twice.
- Keeps authentication tokens out of Jupyter kernelspecs and command-line
  arguments.

This is the shared host adapter for both the VS Code and Jupyter plugins.
Local runtime records describe notebook sessions, not remote runner health.
Publication and shutdown cleanup use the shared client-state lock, and each
record retains its last cell-start timestamp across heartbeat refreshes.

Silent requests still execute but suppress notebook output. If a connection
failure leaves an execution unresolved, rerun its original code to resume it;
different code is rejected until the previous result is recovered or the kernel
is restarted. Code is never automatically replayed after a lost reply handle.

## Installation

SuperKernel requires Python 3.10 or newer.

```bash
uv pip install superkernels
```

The JupyterLab or VS Code SuperKernel integration normally installs and
configures the notebook kernels for you. A configured kernel can then be
selected from the standard Jupyter kernel picker like any other kernel.

This package contains the notebook runtime only. Gateway login, remote runtime
creation, and local kernel registration are handled by a compatible
SuperKernel client integration.

The PyPI distribution and Python import are both named `superkernels`.

## Python API

The kernel class is available for integrations that need to inspect or extend
the local runtime:

```python
from superkernels import SuperKernel
```

The supported process entry point for a configured Jupyter kernelspec is:

```text
python -m superkernels.kernel
```

Its connection and authentication arguments are generated by the client
integration and are not intended to be entered manually.

## Security

SuperKernel reads authentication from a client-managed local file immediately
before each remote request. Credentials are not embedded in the kernelspec,
stored by this package, or passed directly on the process command line. The
runtime fails closed when its authentication file is missing or invalid.
It validates the version-1 session metadata, expiry, and Gateway binding before
every request; renewing the private file takes effect without restarting it.

## Tests

Run `python -m pytest -q superkernels/tests` from the repository root with
the runtime and pytest installed. Tests use temporary private state and do not
read or modify saved user credentials.

## Project status

Version 0.9.6 is the current public beta release. Version 0.9.5 remains the
first beta, version 0.9.0 remains the compatibility baseline, and the
integration contract may still evolve before 1.0.

Learn more at [superkernel.leoustc.com](https://superkernel.leoustc.com).
