Imported from danielperebinos/slowfast-thesis (AGENTS.md). Install upstream with npx skills add danielperebinos/slowfast-thesis. Copyright stays with the author.

AGENTS.md

Project map for AI agents. Keep this file up-to-date as the project evolves.

Project Overview

Thesis codebase for action anticipation on video using four SlowFast variants (baseline, attention, YOLO-ROI guidance, hybrid), trained on AVA and tracked with MLflow. See .ai-factory/DESCRIPTION.md for details.

Tech Stack

• Language: Python 3.10 (managed with uv, lint with ruff)
• Framework: PyTorch 2.0.1 (CUDA 11.8) + PyTorchVideo 0.1.5
• Detection: Ultralytics YOLOv8 (yolov8n.pt)
• Database: PostgreSQL 15 (MLflow backend only — not a project DB)
• Artifact store: MinIO (S3-compatible)
• Experiment tracking: MLflow ≥ 3.9

Project Structure

slowfast-thesis/
├── AVA/                         # local .mp4 training clips (gitignored via *.mp4)
├── AGENTS.md                    # this file — AI agent project map
├── README.md                    # Romanian-language thesis scope document
├── compose.experiments.yml      # MLflow stack: postgres + minio + mlflow server
├── dashboard/                   # Inference-only Streamlit demo (port 8501)
│   ├── app.py                   # Streamlit entry (variant + stream picker, live inference)
│   ├── config.py                # variant registry + preprocessing constants (mirror of core/data_loader)
│   ├── inference/               # preprocess, model_loader, engine (CUDA-sync timing), metrics (TTA + latency)
│   ├── ui/                      # Streamlit components + session-state helpers
│   ├── tests/                   # CPU smoke tests (label-map parity, preprocess shapes, per-variant forward)
│   ├── Dockerfile               # CUDA 11.8 + Python 3.10 + Streamlit
│   ├── compose.yml              # slowfast-dashboard stack — read-only bind mounts of ../experiments & ../AVA
│   ├── Makefile                 # install / run / smoke / up / down / logs (no destructive targets)
│   └── pyproject.toml           # own deps: streamlit + opencv-headless + pinned torch/pytorchvideo
├── deployment/
│   └── docker/
│       └── Dockerfile.mlflow    # MLflow server image (psycopg2 + boto3)
├── experiments/
│   ├── core/                    # shared primitives used by every variant
│   │   ├── data_loader.py       # AvaAnticipationDataset + PackPathway + factory
│   │   ├── loss.py              # ActionAnticipationLoss (BCE + temporal penalty)
│   │   └── metrics.py           # multilabel/topk accuracy, AverageMeter, TTA
│   ├── dataset/                 # data prep and download helpers
│   │   ├── build_splits.py      # AVA → train.csv / test.csv by video_id
│   │   ├── download_all.py      # yt-dlp batch fetch
│   │   └── fetch.py             # single-video fetch helper
│   ├── experiment_01/           # Baseline SlowFast R50
│   ├── experiment_02/           # + Non-Local / Self-Attention
│   ├── experiment_03/           # + YOLOv8 ROI mask on Fast pathway
│   ├── experiment_04/           # Hybrid ROI + local attention
│   ├── experiments.md           # one-pager registry of variants
│   ├── verify_setup.py          # environment sanity check
│   └── yolov8n.pt               # YOLO checkpoint (shared by experiments 03/04)
├── volumes/                     # Docker volumes: postgres + minio data (DO NOT DELETE)
├── volumes.zip                  # archived snapshot of the above (DO NOT DELETE)
├── mlruns/                      # legacy local MLflow runs (pre-server switchover)
├── main.py                      # placeholder PyCharm entry point (not used)
├── pyproject.toml               # uv / ruff config, dependency list
├── uv.lock                      # locked dependency graph
├── .python-version              # 3.10
├── .env                         # Postgres / MinIO / MLflow env (gitignored)
├── Makefile                     # wraps uv, compose, ruff, experiments (see `make help`)
├── .github/
│   └── workflows/
│       └── lint.yml             # GitHub Actions: ruff check + ruff format --check
└── .ai-factory/                 # AI agent context layer
    ├── DESCRIPTION.md           # project spec & tech stack (authoritative)
    ├── ARCHITECTURE.md          # architecture decisions (generated by /aif-architecture)
    ├── config.yaml              # AIF config: language, paths, git, workflow
    └── rules/
        └── base.md              # project conventions for AI agents

Key Entry Points

Documentation

AI Context Files

Common Commands (Makefile)

Not provided on purpose: no clean-volumes, no stack-wipe, no down -v. See rules below.

Critical Project Rules

• Never delete Docker volumes (./volumes/postgres, ./volumes/minio) — they hold the MLflow tracking DB and trained-model artifacts. Use docker compose down without -v. Never use docker volume rm, docker system prune --volumes, or delete volumes/ / volumes.zip.
• Training checkpoints in experiments/experiment_0*/ (checkpoint.pth, best_*.pth) are also protected — they are expensive to regenerate.
• See .ai-factory/rules/base.md for the full rule set (naming, training-loop template, MLflow conventions, reproducibility, data handling).

Agent Rules

• Never combine shell commands with &&, ||, or ; — execute each command as a separate Bash tool call. This applies even when a skill, plan, or instruction provides a combined command — always decompose it into individual calls.
  • ❌ Wrong: git checkout master && git pull
  • ✅ Right: Two separate Bash tool calls — first git checkout master, then git pull origin master