.env.example

# av-causal-dataset-tools — environment variables
#
# Copy this file to `.env` and fill in real values. `.env` is gitignored;
# never commit it.
#
# Who auto-loads `.env`:
#
#   ✓ The annotator (`cascade-annotate` / `make annotator-dev`) — walks
#     up from the working directory at startup, populates `os.environ`
#     without overriding existing shell vars.
#   ✓ IDE test runners (PyCharm, VS Code Python extension).
#   ✓ Docker Compose, `dotenv-cli`, explicit `python-dotenv` callers.
#
#   ✗ Plain shell (`bash`, `zsh`) — `source .env` it yourself.
#   ✗ `uv run` and the rest of the Makefile targets — prefix with the
#     var, or `set -a; source .env; set +a` first.
#
# See AGENTS.md § Security & data handling for the full policy.

# Path to the directory of annotation JSONs (and/or videos for the
# unlabelled-clip flow). Required for examples, notebooks, and any
# test that iterates the real corpus. Unit tests do not need it.
CASCADE_AV_DATASET_ROOT=/path/to/json_annotations

# Per-file detail in dataset-scan warnings (e.g. the "N clip_id(s) had
# multiple annotation files" warning). Default 0; set to 1 to enable.
#CASCADE_AV_VERBOSE=0

# HuggingFace Hub token. Required for `cascade-annotate --video-source=hf`
# (and the `auto` mode's HF fallback) when the underlying dataset is gated —
# including the parent `nvidia/PhysicalAI-Autonomous-Vehicles` repo. Two ways
# to provide it:
#
#   a) Set HF_TOKEN here (or in the shell environment).
#   b) Run `uv run huggingface-cli login` once — the token is written to
#      `~/.huggingface/token` and the HuggingFace client picks it up
#      automatically; no env var needed.
#
# Generate a token at https://huggingface.co/settings/tokens (read scope is
# sufficient).
#HF_TOKEN=