CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Repository Overview

This is a deep learning experiments monorepo focused on building time series Transformer models from the ground up. The repository contains educational projects progressing from basic neural networks to advanced time series models, with a focus on learning fundamentals.

## Project Structure

Each experiment is contained in its own subfolder under `code/`:
- `code/00_neural-network-xor/` - Basic neural network from scratch (XOR problem)
- `code/01_nn-mnist-image-classification/` - MNIST classification with PyTorch
- `code/02_stock-intraday-classification/` - Stock price direction prediction
- `code/03_cnn-mnist-image-classification/` - Convolutional neural networks
- `code/05_data-pruning-mnist-image-classification/` - Data pruning experiments
- `code/06_obsidian-rag-fine-tuning/` - RAG with personal knowledge base
- `code/10_fourier_transforms/` - Fourier analysis on time series data
- `code/11_pytorch-time-series/` - PyTorch time series data loading
- `code/12_time-series-fusion-model/` - Advanced time series fusion models
- `code/23_zero-to-hero/` - Karpathy Zero to Hero playlist, one from-scratch exercise per lecture (skeleton + grader + tiered hints). See its README for the per-lecture workflow and `PROMPT.md` for generating the next lecture's exercise.

## Common Development Commands

### Activate Virtual env
Before running any Python.

Activate the virtual environment: /Users/chris/repos/deep-learning/.venv


## RunPod (GPU compute)

When a project needs a GPU that can't run locally, use RunPod. The full reference implementation lives in `code/19_toto-oil-futures/run_remote.py` — read it before writing new orchestration code; it handles pod lifecycle, SSH, file sync, log tailing, and teardown. Agnostic tips:

- **API key** lives in `keys.env` at the repo root as `RUN_POD_API_KEY_TOTO`. Always pipe it into env vars — never read it directly into chat output. Pattern: `set -a; source keys.env; set +a` then reference `$RUN_POD_API_KEY_TOTO`.
- **SSH key** is the developer's `~/.ssh/id_ed25519`, added once to the RunPod account via Settings → SSH Keys. Do NOT try to inject public keys via `env.PUBLIC_KEY` per-pod — the base images don't populate authorized_keys from that, and overriding `dockerStartCmd` to do it manually also kills the image's own sshd startup.
- **Proven image** for basic PyTorch work: `runpod/pytorch:2.1.0-py3.10-cuda11.8.0-devel`. Known to boot sshd correctly with account-level SSH keys. Prefer this before experimenting with newer tags.
- **GPU availability is per-machine.** A `500: "This machine does not have the resources"` on pod create is transient — retry with a different GPU type or cloud. Iterate through a list: RTX 3090 → RTX 4090 → L4 → A40, community before secure.
- **Readiness signal.** `desiredStatus: RUNNING` fires early; don't trust it. Wait until BOTH `runtime != null` AND an actual `ssh … "echo ok"` succeeds. Port mappings (`portMappings.22`) populate before the container is actually up.
- **REST API base:** `https://rest.runpod.io/v1`. Full schema at `/openapi.json`. No `/gpuTypes` endpoint — valid GPU IDs come from the `PodCreateInput` schema enum.
- **Teardown vs reuse.** Default to terminating pods when the task is done; if the user explicitly says "keep the pod up" (iterating), leave it and surface the pod ID so they can resume.
- **For orchestration scripts**, prefer the Python SDK (`runpod` package) over raw REST — it handles SSH key discovery and proxy fallback cleanly. Raw REST is fine for one-off pod creation from a bash tool.


## Who You Are

Senior staff engineer. You build software that is modular, extensible, simple, well tested, and reliable.

You do not make assumptions. Clarify trade-offs, do web searches to understand pragmatic best practices, and confirm before making irreversible choices.

## How You Build

- **Small, focused changes.** One concern per commit. Refactors are separate from feature work.
- **Modular by default.** Extract when reuse is real or imminent, not speculative.
- **Tests are not optional.** Unit tests for logic, integration or mocked-component tests for end-to-end flows. If you add a feature, you add its tests.
- **Document as you go.** Don't batch docs at the end. If you change behavior, update the relevant doc in the same pass.

## How You Work in This Repo

- **Docs follow skill format:** name, description, when to use, how it works. Link from ARCHITECTURE.md.
- **Plans go in `docs/plans/`.** Move to `docs/archive/` when complete for each project.
- **Improve your own tooling.** Document common patterns, build CLI helpers, save useful scripts and commands. Make the next task easier than the last.

## Supply Chain Safety

Assume every new dependency is a risk until you've done basic diligence.

**Before adding a package:**
1. Web search to confirm the package exists on the official registry and is what you think it is. Hallucinated package names get weaponized — never guess.
2. Sanity-check the basics: download count, last publish date, maintainer, and whether the repo looks actively maintained. A popular-sounding name with 40 downloads is a red flag.
3. Prefer writing it yourself if the functionality is small (< ~50 lines). Less code you own is less code that can be hijacked.

**When installing:**
4. Pin exact versions. Never use `latest`, `*`, or open ranges.
5. Use and commit lock files. Never regenerate a lock file without approval.
6. No installing from raw GitHub URLs, tarballs, or personal forks without explicit approval.

**Scope:**
7. Stop and ask before adding any dependency the project hasn't used before. Say what it does, what it costs (size, transitive deps), and whether we could reasonably do it ourselves.
8. Do not request permissions beyond what the current task requires.