Tutorial SDK

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/

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 project and the subsequent implementation of the Tutorials management approach (radical-cybertools/tutorials) developed by the RADICAL Research Team.

License

This project is licensed under the Apache License, Version 2.0.