Metadata-Version: 2.4
Name: datalab-kernel
Version: 0.1.0
Summary: A standalone Jupyter kernel for DataLab with optional live synchronization
Author-email: DataLab Platform Developers <p.raybaut@codra.fr>
License: BSD-3-Clause
Project-URL: Homepage, https://github.com/DataLab-Platform/DataLab-Kernel
Project-URL: Documentation, https://datalab-kernel.readthedocs.io/
Project-URL: Repository, https://github.com/DataLab-Platform/DataLab-Kernel.git
Project-URL: Issues, https://github.com/DataLab-Platform/DataLab-Kernel/issues
Keywords: jupyter,kernel,datalab,scientific,data processing
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Jupyter
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ipykernel>=6.0
Requires-Dist: jupyter-client>=7.0
Requires-Dist: numpy>=1.22
Requires-Dist: h5py>=3.0
Requires-Dist: matplotlib>=3.5
Requires-Dist: sigima>=1.0
Provides-Extra: webapi
Requires-Dist: httpx>=0.25.0; extra == "webapi"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: httpx>=0.25.0; extra == "dev"
Provides-Extra: doc
Requires-Dist: sphinx>=7.0; extra == "doc"
Requires-Dist: pydata-sphinx-theme>=0.14; extra == "doc"
Requires-Dist: myst-nb>=1.0; extra == "doc"
Requires-Dist: sphinx-design>=0.5; extra == "doc"
Requires-Dist: sphinx-copybutton>=0.5; extra == "doc"
Provides-Extra: datalab
Requires-Dist: datalab-platform>=1.0; extra == "datalab"
Dynamic: license-file

# DataLab-Kernel

**A standalone Jupyter kernel providing seamless, reproducible access to DataLab workspaces, with optional live synchronization to the DataLab GUI.**

---

## Overview

**DataLab-Kernel** is a custom Jupyter kernel designed to bridge **DataLab** and the **Jupyter** ecosystem.

It enables scientists and engineers to:

- run reproducible analyses in Jupyter notebooks,
- interact transparently with DataLab’s internal workspace when DataLab is running,
- share notebooks that can be replayed **with or without DataLab**,
- combine narrative, code, and results without sacrificing interactive visualization.

DataLab-Kernel is **not** a replacement for DataLab’s GUI.  
It is a **complementary execution layer** that turns DataLab into a hybrid scientific platform:
**GUI-driven when needed, notebook-driven when appropriate.**

---

## Key Features

- **Single, stable user API**
  - `workspace` for data access and persistence
  - `plotter` for visualization
  - `sigima` for scientific processing

- **Two execution modes, one notebook**
  - **Live mode**: automatic synchronization with a running DataLab instance
  - **Standalone mode**: notebook-only execution, fully reproducible

- **Reproducibility by design**
  - Analyses can be saved and reloaded using `.h5` files
  - Notebooks run unchanged across environments

- **Performance-aware**
  - Optimized data handling when DataLab is attached
  - No unnecessary serialization for large datasets

- **Decoupled architecture**
  - Installable independently of DataLab
  - DataLab is a privileged host, not a requirement

---

## Typical Usage

```python
img = workspace.get("i042")
filtered = sigima.proc.image.butterworth(img, cut_off=0.2)
workspace.add("filtered_i042", filtered)
plotter.plot("filtered_i042")
```

Depending on the execution context:

- the result appears inline in the notebook,
- and, if DataLab is running, it also appears automatically in the DataLab GUI,
  with views and metadata kept in sync.

---

## Execution Modes

### Live Mode (DataLab-attached)

- DataLab launches a Jupyter server and starts `kernel-datalab`.
- The kernel detects DataLab at runtime.
- Workspace operations and visualizations are synchronized with the GUI.

Two connection methods are supported:

- **Web API** (recommended): HTTP/JSON connection using `DATALAB_WORKSPACE_URL` and `DATALAB_WORKSPACE_TOKEN` environment variables
- **XML-RPC** (legacy): Automatic connection when DataLab is running with remote control enabled

### Standalone Mode (Notebook-only)

- The kernel is used like any standard Jupyter kernel.
- No DataLab installation or GUI is required.
- Data are managed locally and persisted to `.h5` files.

**The same notebook runs unchanged in both modes.**

---

## Installation

### Standalone usage

```bash
pip install datalab-kernel sigima
jupyter lab
```

Then select **DataLab Kernel** from the kernel list.

### With DataLab

When installed alongside DataLab, the kernel is automatically available and can be launched directly from the DataLab interface.

---

## Persistence and Sharing

Workspace state can be saved and reloaded:

```python
workspace.save("analysis.h5")
workspace.load("analysis.h5")
```

This enables:

- sharing notebooks and data with collaborators,
- replaying analyses without DataLab,
- resuming workflows inside DataLab by reopening the associated project.

---

## Documentation

- **User contract and behavior**: see `plans/specification.md`
- **Vision and architectural principles**: see `plans/architecture.md`

---

## Project Status

DataLab-Kernel is under active design and development.

---

## License

This project is released under an open-source license (see `LICENSE` file).
