Metadata-Version: 2.4
Name: superkernel-adapter
Version: 0.9.7
Summary: SuperKernel Adapter: a shared local Jupyter kernel for remote compute.
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/superkernel/tree/main/superkernel-adapter
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 Adapter

SuperKernel Adapter connects ordinary Jupyter notebooks to remote Super Kernel compute.

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 Adapter requires Python 3.10 or newer.

```bash
uv pip install superkernel-adapter
```

Until this renamed distribution is published, install a provided wheel instead:

```bash
uv pip install superkernel_adapter-0.9.7-py3-none-any.whl
```

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 distribution is `superkernel-adapter`, the Python import is
`superkernel_adapter`, the console launcher is `superkernel`, and the kernel
class remains `SuperKernel`.

## Python API

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

```python
from superkernel_adapter import SuperKernel
```

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

```text
superkernel
```

Its connection and authentication arguments are generated by the client
integration and are not intended to be entered manually.
Clients use the selected Python environment's absolute scripts path, such as
`/opt/jupyterhub/bin/superkernel` (or `Scripts/superkernel.exe` on Windows),
not a PATH lookup or `python -m` wrapper. Installing this package creates that
launcher automatically with the environment's Python interpreter.

## Upgrading from superkernels

Upgrade both management plugins together with this adapter. They regenerate
canonical kernelspec launch commands while retaining the existing
`~/.superkernel` version-1 records, sessions, kernel IDs and workspace files.
Restart notebook kernels and reload the VS Code window after installation.
The retired distribution/import has no runtime alias; the root local install
workflow removes it after installing the new adapter. An already-running old
process may be recognized only for explicit, identity-checked shutdown.
The `superkernel` command launches a notebook adapter; it is not a Gateway or
infrastructure-management CLI.

## 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 superkernel-adapter/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.7 is the first renamed adapter build. Publishing is a separate
release step. The execution and shared-state protocols remain unchanged from
the 0.9.6 beta backend; the integration contract may still evolve before 1.0.

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