Metadata-Version: 2.4
Name: jupyter-superkernel
Version: 0.9.0
Summary: JupyterLab UI and server integration for Super Kernel.
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/jupyter-superkernel
Classifier: Development Status :: 3 - Alpha
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: jupyter-client>=8.6
Requires-Dist: jupyter-server>=2.14
Requires-Dist: requests>=2.31
Requires-Dist: superkernel>=0.9.0
Dynamic: license-file

# Jupyter SuperKernel

Bring remote Python, MPI, and PyTorch compute into JupyterLab with the
**Super Kernels** sidebar.

`jupyter-superkernel` adds the JupyterLab interface for signing in to a
SuperKernel Gateway, creating remote kernels, selecting them from the normal
Jupyter kernel picker, and managing their lifecycle. Notebook execution is
provided by the companion [`superkernel`](https://pypi.org/project/superkernel/)
runtime, which is installed automatically.

## Features

- Add and manage multiple SuperKernel Gateways.
- Create Base Python, MPI, and PyTorch kernels from available runtime images.
- Choose node, CPU, and memory settings from a compact native JupyterLab UI.
- See preparing, ready, busy, idle, paused, and error states.
- Pause, resume, restart, or delete remote kernels.
- Inspect and clean up local notebook runtime sessions.
- Use standard Jupyter notebook execution, interruption, and restart actions.
- Share the same local Gateway and kernel configuration with the SuperKernel
  VS Code extension.

## Requirements

- Python 3.10 or newer
- JupyterLab 4
- Access to a SuperKernel Gateway and a valid API key

## Installation

Install the package into the same Python environment that runs JupyterLab:

```bash
uv pip install jupyter-superkernel
```

For a JupyterHub installation, select its Python environment explicitly:

```bash
uv pip install --python /path/to/jupyterhub/bin/python jupyter-superkernel
```

Restart JupyterLab or JupyterHub after installation. The Python server
extension and prebuilt JupyterLab extension are included in the wheel; no
Node.js build is required.

## Getting started

1. Open JupyterLab and select the **Super Kernels** icon in the left sidebar.
2. Under **Gateways**, choose **Add Gateway** and enter the Gateway URL and API
   key supplied by your administrator.
3. Under **Kernels**, choose **Add Kernel**.
4. Select a logged-in Gateway, runtime image, and compute configuration.
5. Create or open a notebook and select the new kernel from Jupyter's standard
   kernel picker.

Kernel cards show their current configuration and status. Lifecycle controls
on each card let you pause or resume compute when it is not needed, restart a
kernel, or delete it. Local runtime rows identify notebook sessions currently
using that remote kernel and provide a targeted cleanup action.

Cells run in submission order. Normal Python cells keep a persistent namespace
for that notebook session. Cells beginning with `!` or `%` run as shell
commands in the selected remote runtime.

## Security

The API key is used only during Gateway login and is not stored. The resulting
session is saved in a private local authentication file and never embedded in
notebooks or Jupyter kernelspecs. Installed kernelspecs contain only the
Gateway address, remote kernel identifier, and a reference to that private
authentication file.

Local SuperKernel state is stored under `~/.superkernel` with restrictive file
permissions so the JupyterLab and VS Code integrations can safely share the
same Gateway logins and kernel registrations.

## Troubleshooting

If the sidebar does not appear after installation, restart Jupyter and verify
that both extensions are enabled:

```bash
jupyter server extension list
jupyter labextension list
```

Both lists should show `jupyter_superkernel` or `jupyter-superkernel` as
enabled and valid.

## Project status

Version 0.9.0 is the first public alpha release. It is intended for evaluation,
and its integration contract may still evolve before 1.0.

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