.env.example

# =============================================================================
# .env.example — schema for environment variables.
# -----------------------------------------------------------------------------
# Copy this file to `.env` (which is gitignored) and fill in real values.
# `pydantic-settings` automatically reads `.env` at startup and validates each
# field.
#
# Two prefixes are read by the application:
#   BACKEND_*               -> backend/app/core/config.py (BackendSettings)
#   CAPTIONING__<sec>__<k>  -> src/captioning/config/schema.py (AppConfig)
# Nested AppConfig fields use a double-underscore delimiter:
#   CAPTIONING__TRAIN__BATCH_SIZE=32  overrides AppConfig.train.batch_size
# =============================================================================

# ---- App-wide ----------------------------------------------------------------
APP_ENV=development                          # development | staging | production
LOG_LEVEL=INFO                               # DEBUG | INFO | WARNING | ERROR

# ---- BackendSettings (FastAPI process) --------------------------------------
BACKEND_CONFIG_PATH=configs/base.yaml
BACKEND_WEIGHTS_PATH=models/v1.0.0/model.h5
BACKEND_TOKENIZER_DIR=models/v1.0.0
BACKEND_MODEL_VERSION=v1.0.0
BACKEND_API_VERSION=0.1.0
BACKEND_WARMUP=true
BACKEND_REQUEST_ID_HEADER=x-request-id

# ---- AppConfig overrides (research-side hyperparameters) --------------------
# CORS allow-list lives in configs/base.yaml under `serve.cors_allowed_origins`.
# Override it for prod by setting the env var below to a JSON list.
# CAPTIONING__SERVE__CORS_ALLOWED_ORIGINS=["https://your-frontend.vercel.app"]
# CAPTIONING__SERVE__MAX_UPLOAD_BYTES=10485760
# CAPTIONING__INFERENCE__DECODE_STRATEGY=beam
# CAPTIONING__INFERENCE__BEAM_WIDTH=3

# ---- TensorFlow runtime tuning (optional, for HF Spaces cpu-basic) ----------
# TF_CPP_MIN_LOG_LEVEL=2          # silence INFO/WARNING from TF
# OMP_NUM_THREADS=2               # match cpu-basic vCPU count
# TF_NUM_INTEROP_THREADS=1
# TF_NUM_INTRAOP_THREADS=2

# ---- HuggingFace Hub (model artefact storage — wired up in WS-A4) -----------
# Public model repo holding the trained weights + vocab.json.
HF_REPO_ID=your-username/captioning-weights
HF_REVISION=v1.0.0                           # Pin a specific tag for reproducibility
# Optional: only needed for private repos or higher rate limits.
# Generate at https://huggingface.co/settings/tokens (read-only is enough).
HF_TOKEN=
# HF_HOME=/home/user/.cache/huggingface

# ---- Backend Hub weights pull (read by BackendSettings) ---------------------
# When BACKEND_WEIGHTS_HUB_REPO is set, the FastAPI lifespan calls
# huggingface_hub.snapshot_download at startup and ignores the local
# BACKEND_WEIGHTS_PATH / BACKEND_TOKENIZER_DIR values. Leave unset to keep
# loading weights from the locally mounted models/ directory.
# BACKEND_WEIGHTS_HUB_REPO=your-username/captioning-weights
# BACKEND_WEIGHTS_HUB_REVISION=v1.0.0
# BACKEND_WEIGHTS_HUB_FILENAME=model.h5
# BACKEND_WEIGHTS_CACHE_DIR=/home/user/.cache/captioning

# ---- Experiment tracking (MLflow) --------------------------------------------
# Local SQLite during dev; DagsHub URL in production.
MLFLOW_TRACKING_URI=sqlite:///mlruns/mlflow.db
# MLFLOW_TRACKING_URI=https://dagshub.com/your-username/captioning.mlflow
# MLFLOW_TRACKING_USERNAME=your-username
# MLFLOW_TRACKING_PASSWORD=your-dagshub-access-token
MLFLOW_EXPERIMENT_NAME=captioning

# ---- Observability (Phase 4) -------------------------------------------------
# Sentry: error tracking. Free tier = 5k errors/mo. Get a DSN at sentry.io.
# SENTRY_DSN=
# SENTRY_TRACES_SAMPLE_RATE=0.1                # 10% of requests traced

# ---- Frontend (Next.js) — also in frontend/.env.local ------------------------
# NEXT_PUBLIC_API_URL=http://localhost:8000    # Backend base URL for client fetches