CLAUDE.md

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

Project Overview

This is a Quarto-based educational website for AI and robotics courses. The site covers topics including deep learning, computer vision, LLMs, reinforcement learning, kinematics, and robotics.

Common Commands

Development

# Start fresh environment
make start

# Install dependencies
make install          # Production dependencies
make install-dev      # Dev dependencies (pytest, ruff, mypy)

# Format and lint
make format           # Auto-format code with ruff
make lint             # Lint and auto-fix with ruff
make lint-check       # Lint without fixing
make style            # Run both format and lint

# Type checking
make type-check       # Run mypy
make quality          # Run lint-check + type-check

# Quick fix for modified files only
make fixup

Testing

make test             # Run pytest
make test-cov         # Run with coverage report
make test-examples    # Test examples directory only

Quarto Site

quarto preview        # Preview site on port 4100
quarto render         # Build static site to _site/
docker-compose --profile quarto up quarto-preview  # Via Docker

Docker

docker-compose up engineering-ai-agents     # CPU (includes Jupyter on 8888)
UV_EXTRA=cu128 docker-compose up engineering-ai-agents  # CUDA 12.8

Architecture

Content Structure

  • book/ - Main educational content organized by topic (foundations, dnn, llm, rl, kinematics, etc.)
  • courses/ - Course-specific pages (ai, cv, robotics, data-mining)
  • aiml-common/ - Git submodule with shared lectures, assignments, and projects
  • bibliography/ - Git submodule with BibTeX references

Configuration

  • _quarto.yml - Main Quarto config (site structure, navbar, bibliography)
  • sidebar-*.yml - Per-topic sidebar navigation files (loaded via metadata-files)
  • _brand-light.yml / _brand-dark.yml - Theme branding
  • scss/custom.scss - Custom styling

Key Files

  • pyproject.toml - Python dependencies and tool config (ruff, mypy, pytest)
  • Makefile - Development workflow commands
  • .devcontainer/ - VS Code dev container config

Development Notes

  • Use uv for all Python package management (not pip/venv directly)
  • Use $ and $$ for LaTeX math in Quarto documents
  • The project requires Python 3.12.12
  • PyTorch variants: cpu (default) or cu128 (CUDA 12.8)
  • Quarto extensions are in _extensions/ (pseudocode rendering, etc.)

Git Submodules

This repository uses git submodules for shared content. Always be aware that changes in these directories affect separate repositories.

Submodule Path Repository Purpose
aiml-common aiml-common/ github.com/pantelis/aiml-common Shared lectures, assignments, and projects
bibliography bibliography/ github.com/pantelis/bibliography BibTeX references for citations

Submodule Commands

# Initialize after cloning
git submodule update --init --recursive

# Pull latest changes from submodule remotes
git submodule update --remote

# Check submodule status
git submodule status

Important Notes

  • Changes inside aiml-common/ or bibliography/ must be committed to their respective repositories first, then the parent repo updated to point to the new commit
  • When switching branches, run git submodule update to sync submodule versions
  • The main repo tracks specific commits of each submodule (visible in git status as modified submodule references)

Bibliography Management

The bibliography/paperpile.bib file is synced from Paperpile and is automatically split into category-specific files on push to main.

Split Files

File Entry Types
paperpile-books.bib (BOOK?), (INBOOK?)
paperpile-papers.bib (ARTICLE?), (INPROCEEDINGS?), (THESIS?), (PHDTHESIS?), (REPORT?)
paperpile-videos.bib (VIDEO?) (YouTube)
paperpile-software.bib (SOFTWARE?) (GitHub)
paperpile-misc.bib (MISC?), (ONLINE?), (PATENT?), (DATASET?)

Manual Split

python utils/split_bibliography.py

The GitHub Action .github/workflows/split-bibliography.yml runs this automatically when paperpile.bib changes.