Imported from ruliana/pytorch-katas (AGENTS.md). Install upstream with npx skills add ruliana/pytorch-katas. Copyright stays with the author.

PyTorch Katas: Agent Guide

Purpose and scope

This is a practice gym for PyTorch, not a theory course. Learners reinforce concepts they are studying elsewhere through small, synthetic-data problems and explicit neural-network implementations—even when a simpler non-neural solution would suffice.

Only Dan 1 (Temple Sweeper) is in scope. Retain all six existing Dan 1 exercises; this is the current collection, not a permanent numerical limit. Do not generate higher levels or maintain a higher-level roadmap. Add a new Dan 1 kata only when explicitly requested; otherwise prioritize repairing and reviewing existing exercises. The later existing katas are stretch practice, not permission to expand the curriculum.

Repository

• dan_1/: starter notebooks and explicitly labeled solutions.
• README.md: learner-facing setup, index, and review status.
• AGENTS.md: canonical, tool-independent contributor instructions.
• .claude/commands/create-kata.md: thin Claude Code entry point; follows this guide.
• kata-creation.txt: optional Dan 1 prompt ideas, not a published exercise index.
• pyproject.toml, .python-version, uv.lock: shared environment definition.

Environment and validation

Run commands from the repository root:

uv sync --locked
uv run --locked jupyter lab
uv run --locked python scripts/check_environment.py

Python 3.12 is the supported local baseline. PyTorch uses CPU by default; no GPU, model download, or external dataset is required. Intel macOS is a legacy compatibility target pinned to PyTorch 2.2.2, with NumPy 1.x for its NumPy bridge. Other platforms use the newer PyTorch range in pyproject.toml. Do not silently upgrade these pins without checking wheel availability and tensor/NumPy interoperability.

Use PyTorch, NumPy, and Matplotlib for new exercises. Seaborn and scikit-learn are included for existing Kata 5; do not introduce more dependencies without justification. Declare every new dependency in pyproject.toml and regenerate uv.lock with uv lock.

The environment smoke check verifies dependencies, autograd, plotting, and a fresh Jupyter kernel. It does not certify that unfinished notebooks work. Never execute arbitrary learner notebooks or overwrite their outputs without permission. Preserve untracked solutions and local environments.

Characters and voice

Keep the temple setting, but make the coding task easy to find. Use one or two characters per exercise and address the learner as you or Grasshopper.

• Master Pai-Torch: cryptic gradient koans; appears when you are stuck.
• Master Ao-Tougrad: quiet keeper of backpropagation; leaves practical hints.
• Cook Oh-Pai-Timizer: hands-on optimization advice through cooking analogies.
• He-Ao-World: apologetic janitor whose convenient accidents create messy data. Secretly skilled; the masters do not know.
• Suki: the temple cat whose behavior supplies observations.

Use gender-neutral language for every character except Suki (she/her). Keep narrative in prose and comments, not in core training variable names.

Notebook contract

New starter filenames: dan_1/kata_XX_descriptive_name_unrevised.ipynb. Remove _unrevised only after human review. Reference solutions use the same stem with _solved.ipynb; “solved” does not imply human-reviewed. Update the README index and all links when renaming.

Each new or comprehensively revised kata contains:

1. Header: title, Dan 1, realistic estimated time, practiced concepts, and Colab badge pointing to that exact notebook on ruliana/pytorch-katas, branch main.
2. Challenge: two short story paragraphs, explicit prerequisites, and measurable objectives.
3. Setup and synthetic data: all imports/configuration in the first code cell; complete generator and visualization with documented shapes and labels.
4. Starter implementation: small nn.Module and training function with bounded TODOs and actionable hints. Use NotImplementedError for unfinished callable paths rather than obscure None failures where practical.
5. Run and check: explicit model creation, training call, loss plot, predictions, and invocation of test_your_wisdom(). State that TODOs must be completed first.
6. Extensions: four short, optional experiments that change one thing at a time. Do not hide a second course inside extensions.
7. Completion: concise recap and encouragement. Optional debugging practice must be clearly labeled and excluded from normal execution.

Starter versus solution: TODOs are expected in learner-owned model/training code. Supplied setup, data, plotting, and tests must work. Provide a separate runnable reference solution for new or comprehensively revised katas. Do not claim an existing starter is broken merely because its intentional TODOs are incomplete.

PyTorch conventions

• Use import torch, import torch.nn as nn, and import torch.optim as optim.
• Prefer features, target, predictions, loss, criterion, and optimizer; ordinary attributes such as self.linear and self.hidden.
• Thematic names are fine for dataset/plotting helpers and descriptive model classes.
• Set torch.manual_seed(42) once in setup. Allow configurable seeds for experimentation. Generators needing independent reproducibility should use local torch.Generator objects instead of resetting global RNG state. Seed NumPy if it is used for randomness.
• Training: model.train(), optimizer.zero_grad(), forward pass, loss, loss.backward(), optimizer.step().
• Evaluation: model.eval() plus torch.no_grad() where gradients are unnecessary. Evaluation mode alone does not disable autograd.
• Binary classification: prefer logits with nn.BCEWithLogitsLoss; apply sigmoid only when converting logits to probabilities. An explicit sigmoid/BCELoss exercise is acceptable when that distinction is the stated practice objective. Never apply sigmoid twice.
• Multi-class classification: feed raw logits to nn.CrossEntropyLoss; use integer class targets. Apply softmax only for probability reporting.
• Inspect tensors with .detach(), not .data. Convert plotting tensors with .detach().cpu().numpy() when appropriate.
• Document input/output shapes, dtypes, class mappings, and normalization. Ensure the model can represent the intended relationship.
• Keep default computations small and CPU-friendly. Validate generator sizes and noise parameters. Avoid division by zero in metrics or progress intervals.
• Give helpers and classes docstrings. Keep training functions independent of hidden notebook globals where practical.

Quality gate

Before adding or extensively revising a kata:

1. Read README.md and relevant existing notebooks; avoid duplicates.
2. Check data labels against narrative, plots, and tests. Validate tensor shapes and valid PyTorch APIs.
3. Validate notebook structure with nbformat; use valid notebook v4 JSON and unique cell IDs.
4. Run the reference solution from a fresh kernel using the locked environment. Test supplied starter scaffolding separately. Run deliberate debugging failures only as separate, explicit tests.
5. Verify finite/decreasing losses, correct shapes, and meaningful predictions. Calibrate thresholds using the reference solution and several seeds; distinguish training fit from generalization. Use a separately generated evaluation set when claiming generalization.
6. Ensure plots use actual predictions and no unintended activation transforms. Include a simple baseline for accuracy where class imbalance matters.
7. Clear execution counts and outputs before publishing starters. Do not alter learner-owned or untracked notebooks. Strip machine-specific paths and stale kernel metadata from published material.
8. Update README status, concepts, and links. Report exactly what was tested and what remains unverified. Automated execution never substitutes for human review.

Existing notebooks predate parts of this contract; fix them deliberately rather than claiming they already comply.