Metadata-Version: 2.4
Name: jupyterlab-ds-snapshot
Version: 0.3.6
Summary: Capture data science evidence, notes, and documentation snapshots in JupyterLab.
Project-URL: Homepage, https://github.com/xwang0176/jupyterlab-ds-snapshot
Project-URL: Repository, https://github.com/xwang0176/jupyterlab-ds-snapshot
Project-URL: Issues, https://github.com/xwang0176/jupyterlab-ds-snapshot/issues
Author: Xu Wang
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: data-science,documentation,evidence,jupyterlab,notebook,reproducibility
Classifier: Framework :: Jupyter
Classifier: Framework :: Jupyter :: JupyterLab
Classifier: Framework :: Jupyter :: JupyterLab :: 4
Classifier: Framework :: Jupyter :: JupyterLab :: Extensions
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Description-Content-Type: text/markdown

[![JupyterLab](https://img.shields.io/badge/JupyterLab-4.0%2B-orange)](#)
[![VS Code](https://img.shields.io/badge/VS%20Code-supported-blue)](#)
[![License](https://img.shields.io/badge/license-Apache--2.0-green)](LICENSE)

# DS Snapshot

A lightweight JupyterLab extension for capturing data science evidence, review notes, and documentation snapshots directly from notebooks. 

Available for:

- JupyterLab 4.0+
- VS Code

[![Watch the DS Snapshot demo](https://img.youtube.com/vi/78vUEQvzyrg/maxresdefault.jpg?v=2)](https://youtu.be/78vUEQvzyrg)

DS Snapshot helps data scientists keep a structured record of important spot checks, intermediate outputs, review notes, and supporting evidence without turning every notebook check into a formal workflow step. It is designed for local-first analytical work, model review, reproducibility, audit trails, and handoff.

## Why DS Snapshot?

Clean notebooks are useful, but real data science work often includes many small checks that are easy to lose: row-count checks, missing-value checks, outlier investigations, comparison tables, chart inspections, and review notes. DS Snapshot creates a lightweight evidence archive under a JupyterLab-root path that you choose and can export a review package that is easier to share than a long notebook.

## Features

- Capture selected notebook evidence into a structured archive
- Save review notes and evidence summaries as Markdown and HTML
- Maintain a registry of captured evidence
- Generate an evidence hub for quick navigation
- Export a review package for review, audit, or handoff
- Works locally inside JupyterLab

## Demo

### Capture

Save important evidence from your workflow as you work.

<img src="https://raw.githubusercontent.com/xwang0176/Public-Asset/main/DS_Snapshot_Demo_Capture.gif"
     alt="DS Snapshot Capture Demo"
     width="800">

### Hub

Review captured evidence in one place.

<img src="https://raw.githubusercontent.com/xwang0176/Public-Asset/main/DS_Snapshot_Demo_Hub.gif"
     alt="DS Snapshot Capture Demo"
     width="800">

### Package

Select and export evidence for review, documentation, or handoff.

<img src="https://raw.githubusercontent.com/xwang0176/Public-Asset/main/DS_Snapshot_Demo_Package.gif"
     alt="DS Snapshot Capture Demo"
     width="800">

## Tutorials

### Panel Overview

- [Panel Overview](https://youtu.be/bPMHgIceMok)

### Capture Evidence

- [Python + Excel](https://youtu.be/SXMhVT5giOI)
- [SQL + Excel](https://youtu.be/hEOJQ7qF-t8)
- [Validate AI Work](https://youtu.be/H1J1FrBiwo0)
- [Model Comparison](https://youtu.be/kNCk9yL-Ae8)

### Evidence Management

- [Evidence Management](https://youtu.be/HPBtkpNvNWg)
  
## Installation

Public package release is planned. After release, the target installation command will be:

```bash
pip install jupyterlab-ds-snapshot
```

For local development:

```bash
git clone https://github.com/<your-username>/jupyterlab-ds-snapshot.git
cd jupyterlab-ds-snapshot
pip install -e .
npm install
npm run build
jupyter lab
```

## Quick start

1. Open JupyterLab.
2. Open the **DS Snapshot** side panel.
3. Choose an absolute JupyterLab archive path, such as `/ds-snapshot-archive` or `/project/ds-snapshot-archive`.
4. Capture evidence from the active notebook.
5. Open the hub or export a review package.

The extension creates files under the selected archive path. If multiple notebooks use the same path, they share the same registry and hub. For example:

```text
/ds-snapshot-archive/
  registry.json
  hub.md
  hub.html
  reviews/
  evidence/
  review_packages/
```


### Archive path rule

The archive path must start with `/` and is resolved under the JupyterLab file browser root. It is not a Windows or macOS local OS path.

Use the same archive path across multiple notebooks to create one shared evidence hub. Use different archive paths when you want separate archives.

## Review packages

The review package export currently collects review notes, evidence summaries, and navigation pages into a shareable folder. The archive remains complete; the exported package is intended for review or handoff:

```text
/ds-snapshot-archive/
  review_packages/
    review_package_<timestamp>/
      index.html
      hub.html
      hub.md
      README.md
      manifest.json
      reviews/
      evidence/
```

This package is intended to help reviewers, future maintainers, or AI agents understand what was checked and where the supporting evidence lives.

## Development

Build the TypeScript source and JupyterLab prebuilt extension:

```bash
npm run build
```

Run JupyterLab locally:

```bash
jupyter lab
```

Build the Python package:

```bash
python -m build
```

## Status

This project is an early public preview. APIs, folder layouts, and generated documentation formats may change before a stable release.

## License

Apache License 2.0. See [LICENSE](LICENSE).
