Metadata-Version: 2.4
Name: tutorial-sdk
Version: 0.1.2
Summary: A declarative, configuration-driven SDK for building, validating, and deploying reproducible tutorial packages.
Author: Mikhail Titov
License-Expression: Apache-2.0
Project-URL: Homepage, https://bnl-peso-hub.github.io/tutorial-sdk/
Project-URL: Documentation, https://bnl-peso-hub.github.io/tutorial-sdk/
Project-URL: Repository, https://github.com/BNL-PESO-Hub/tutorial-sdk.git
Project-URL: Issues, https://github.com/BNL-PESO-Hub/tutorial-sdk/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: pydantic>=2.0
Requires-Dist: PyYAML>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=9.0.0; extra == "dev"
Requires-Dist: pytest-cov>=7.0.0; extra == "dev"
Requires-Dist: ruff>=0.16.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs~=1.6; extra == "docs"
Requires-Dist: mkdocs-material~=9.7; extra == "docs"
Requires-Dist: mkdocstrings[python]~=1.0; extra == "docs"
Dynamic: license-file

![logo](https://raw.githubusercontent.com/BNL-PESO-Hub/tutorial-sdk/main/docs/assets/images/tutorial-sdk-banner-modern.png)

# Tutorial SDK
[![PyPI version](https://img.shields.io/pypi/v/tutorial-sdk.svg?color=blue)](https://pypi.org/project/tutorial-sdk/)
[![Python versions](https://img.shields.io/pypi/pyversions/tutorial-sdk.svg)](https://pypi.org/project/tutorial-sdk/)
[![License](https://img.shields.io/badge/license-Apache--2.0-green.svg)](LICENSE)
[![Docs](https://img.shields.io/badge/docs-MkDocs-blue)](docs/index.md)

A **declarative, reproducible tutorial packaging system** and command-line tool that bridges the gap between technical content and stable containerized runtimes.

> 💡 **Focus on teaching. We'll handle the runtime.**

Tutorial environments tend to drift over time: Dockerfiles diverge from notebooks, dependencies go unpinned, and validation is left to CI pipelines assembled by hand. `tutorial-sdk` addresses this by driving the full lifecycle — resolving and locking dependencies, synthesizing deterministic Dockerfiles, validating notebooks locally and inside built containers, and publishing images through a standardized CI workflow — all from a single declarative config.

**Online Documentation:** https://bnl-peso-hub.github.io/tutorial-sdk/

> [!IMPORTANT]
> _This project is currently under active development. While we strive for stability, expect API changes and evolving best practices as we approach our first official release._

---

## Key Features

* **Declarative Configuration (`tutorial.yml`)**: Declare the whole tutorial surface - metadata, contents, package environments, and validation rules - in a single, Pydantic-validated YAML file.
* **Deterministic Environment Synthesis**: Generates cache-friendly, reproducible Dockerfiles matching the exact dependency graph specified in your config.
* **Notebook-Aware Container Validation**: Runs comprehensive local checks (assets, dependencies, notebook error detection) as well as full container validation (verifying built containers start successfully and that JupyterLab runs flawlessly inside).
* **GitHub Actions Integration**: Built-in support for standard, thin CI workflows (`tutorial-sdk ci`) that validate, build, test, and publish images from pull requests and releases.
* **Extensible Scaffolding Templates**: Starter templates to quickly spin up beginner workshops, notebooks, course modules, or custom lab exercises.

---

## Acknowledgments

This project was inspired by and carries the core ideas of the [ExaWorks](http://exaworks.org) project and the subsequent implementation of the Tutorials management approach ([radical-cybertools/tutorials](https://github.com/radical-cybertools/tutorials)) developed by the [RADICAL Research Team](https://radical-cybertools.github.io).

---

## License

This project is licensed under the [Apache License, Version 2.0](LICENSE).
