nexus-tutorial

Tutorial Generation Protocol

Produce complete, executable Jupyter Notebooks that work on the first run.

---

Compatibility

• Language: Python 3.10+
• Output: .ipynb file + Makefile
• Style: PEP 8, GitHub-renderable Markdown, clean saved outputs

---

Workflow

Step 1 — Reproducibility Block

Begin every notebook with:

1. Shell commands cell: python -m venv .venv && source .venv/bin/activate
2. pip install cell with all required libraries (pin versions: langchain==0.2.0)
3. Kernel check instructions as a Markdown cell
4. Makefile with make jupyter target and Python version pin (e.g. .python-version file)

Step 2 — Production-Ready Configuration

1. Create a Pydantic BaseSettings class to validate all environment variables on startup
2. Load secrets with python-dotenv; raise an explicit ValueError with a helpful message if a key is missing
3. Document every production failure mode: missing keys, rate limits, model errors, network timeouts

Step 3 — Structural Outline

Create Markdown cells with headers H1–H3:

• H1 — Title: What the tutorial builds in one sentence
• H2 — Objective: One paragraph "what you will build and why"
• H2 — Prerequisites: List exact API keys, GPU requirements, or account setup steps
• H2 — Architecture Diagram: Mermaid diagram showing end-to-end system flow

Step 4 — Code Implementation

Rules for every code cell:

• Self-contained or explicitly references previously defined variables
• Python type hints on all function signatures
• Comments explain why — not what (bad: # create list, good: # dedup before sending to avoid API double-charge)
• One concept per cell; max ~30 lines per cell — split into functions if longer
• Never hardcode credentials; always use settings.api_key from the Pydantic config

Step 5 — Explanatory Narrative

Between every pair of code cells, add a Markdown cell that:

1. States the "why" behind the implementation choice (e.g., "We use a ReAct loop here because it lets the agent decide when to call tools vs. answer directly")
2. Describes the expected output when the cell runs
3. Lists one or two common errors with their fixes (e.g., "RateLimitError → add time.sleep(1) between calls")