tutorial-sdk 0.1.0

A declarative, configuration-driven SDK for building, validating, and deploying reproducible tutorial packages.

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.

[!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.

---

Documentation

For comprehensive guides, API references, and architecture details, refer to the following documentation files:

• Getting Started: Features, quickstart commands, and standard project layouts.
• Configuration Schema: Reference manual for all options in tutorial.yml.
• Architecture & Design: Deep dive into the modular layers, container validation model, and extension override blocks.
• CLI Reference: Reference details for CLI commands and usage examples.
• Public API & Full SDK API References: API surface specifications and implementation details for Orchestration (TutorialProject), Spec Models (TutorialSpec), Scaffolding, Generators, Builders, and Validators.

[!NOTE] Online Documentation: https://bnl-peso-hub.github.io/tutorial-sdk/

---

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.