Interpolator

FastAPI + PyTorch backend with a Next.js frontend for training and serving a 5D regressor. This README covers setup, environment variables, running in dev/prod (local and Docker), and testing.

Prerequisites

• Python 3.12
• Node.js 20+
• Docker and docker compose (optional but recommended)

Environment Variables

Edit these in a .env or export them before running.

Name	Description	Default	Required
BACKEND_PORT	Port the FastAPI backend binds to (and that the frontend calls)	8000	No
FRONTEND_PORT	Port the Next.js frontend binds to	3000	No
FRONTEND_HOST	Hostname the backend should allow for CORS (mirrors where the frontend is served)	localhost	No
NEXT_PUBLIC_API_BASE_URL	Full backend URL baked into the frontend bundle (overrides host/port detection)	http://localhost:${BACKEND_PORT}	No
MODE	dev or prod (controls frontend build mode)	prod	No

Local development (no Docker)

Script (Recommended if not using Docker)

From the repo root run:

./script_start.sh

Notes:

• Respects BACKEND_PORT/FRONTEND_PORT/MODE (defaults: 8000/3000/prod).
• Creates backend/.venv and installs backend deps if missing.
• Installs frontend deps, builds (prod), and starts both services.
• Auto-builds docs via build_docs.sh before starting.

Manually

1. Backend

   cd backend
   python -m venv .venv
   source .venv/bin/activate
   pip install -e .
   uvicorn fivedreg.main:app --reload --host 0.0.0.0 --port ${BACKEND_PORT:-8000}

2. Frontend

   cd frontend
   npm install
   npm run dev -- --hostname 0.0.0.0 --port ${FRONTEND_PORT:-3000}

3. Open http://localhost:${FRONTEND_PORT:-3000}.

Docker & docker compose (Recommended)

Script (Recommended)

From the repo root run:

./docker_start.sh    # accepts extra docker compose args, e.g. -d

Notes:

• Respects .env plus BACKEND_PORT/FRONTEND_PORT/MODE/NEXT_PUBLIC_* exports.
• Auto-builds docs via build_docs.sh before bringing containers up.
• Uses docker compose up --build (falls back to docker-compose binary if needed).

Manually

1. Set any overrides in .env (alongside docker-compose.yaml), e.g.:

   BACKEND_PORT=8000
   FRONTEND_PORT=3000
   MODE=prod
   

2. Build/run:

   MODE=dev docker compose up --build      # dev frontend (hot reload)
   MODE=prod docker compose up --build     # prod frontend (built)

3. Access:
   • Backend: http://localhost:${BACKEND_PORT}
   • Frontend: http://localhost:${FRONTEND_PORT}

Usage flow

1. Upload a dataset via the frontend (Upload page) or POST /upload with a .pkl containing X, y, metadata. Any rows containing NaNs are dropped automatically; the returned metadata includes dropped_nan_samples and the cleaned n_samples.
2. Start training from the frontend (Train page) or POST /train with hyperparameters; poll /train/{job_id} for progress.
3. Predict from the frontend (Predict page) or POST /predict with a list of exactly 5 finite floats (bad payloads return HTTP 400).
4. Health/reset endpoints: /health, /reset.

Testing

Run tests (uses pytest):

cd backend
python -m venv .venv
source .venv/bin/activate
pip install -e ".[test]"
pytest tests

Documentation

• Install doc deps inside the backend venv (bundled pandoc, no global install): cd backend && source .venv/bin/activate && pip install -e ".[docs]"
• Build: ./build_docs.sh (or cd docs && make html), automatically runs from the start scripts.
• Open: after a build, open docs/_build/html/index.html in your browser (e.g., open docs/_build/html/index.html on macOS or xdg-open docs/_build/html/index.html on Linux) for the full docs (getting started, user guides, API references, profiling notebook).

Notes

• Next.js dev mode requires MODE=dev passed to the container/environment; otherwise it runs in prod.
• Ports are controlled by env vars; docker compose maps host ↔ container using the same values. If you change the host/port for the frontend, also set FRONTEND_HOST so backend CORS stays aligned.
• To hardcode a backend URL into the frontend bundle (instead of using the current host + backend port), set NEXT_PUBLIC_API_BASE_URL.