Training Dashboard

A full-stack control plane for running, monitoring, and comparing ML training experiments locally or on Hugging Face Jobs.

• A FastAPI backend for job orchestration, logs, trial indexing, and real-time websocket updates.
• A SvelteKit frontend with dedicated pages for:
  • Home command center (job submission + quick status)
  • Live logs and job controls
  • Trial leaderboard
• A run.ps1 execution bridge that supports both local execution and Hugging Face job submission.

• backend/: API service, orchestration logic, training script, and runtime output files.
• frontend/: SvelteKit dashboard.
• docs/: project notes, architecture flow, and implementation guidance.

Component documentation:

• Backend details: backend/README.md
• Frontend details: frontend/README.md

• Python 3.12+
• Node.js 18+ and npm
• PowerShell (pwsh recommended on Windows)
• uv package manager for Python dependency sync
• Optional for cloud jobs: Hugging Face CLI (hf)

Create a .env file in the repository root (recommended) using .env.example.

Required for Hugging Face flows:

• HF_TOKEN: Hugging Face token.

Optional:

• ANANA_RESULTS_REPO: Hugging Face dataset repository in owner/repo format, used by training sync logic.
• VITE_API_BASE: frontend API base URL (default is http://localhost:8000).

Notes:

• backend/run.ps1 reads .env from both backend/.env and the repository root .env.
• The FastAPI app attempts to load .env files when python-dotenv is available.

cd backend
python -m venv .venv
.\.venv\Scripts\Activate.ps1
uv sync
uv run uvicorn main:app --reload --port 8000

Backend health check:

Invoke-RestMethod http://127.0.0.1:8000/health

cd frontend
npm install
npm run dev -- --port 5173

Open: http://localhost:5173

Generated runtime artifacts are stored under backend/.anana-results/:

• configs/: generated JSON config payloads for started jobs.
• logs/: per-job log files (<job_id>.log).
• anana_v3/tune/: trial JSON outputs (trial_*.json) consumed by leaderboard endpoints.

• /: Command Center + quick trial table + status footer.
• /logs: live log monitoring, websocket spawner, stop controls.
• /leaderboard: sorted trial leaderboard.

• GET /health: backend state, HF token availability, and active job count.

• POST /jobs/start: low-level job submission endpoint.
• POST /api/jobs/start: UI-compatible form endpoint (maps form fields to CLI args).
• GET /jobs: list tracked jobs.
• GET /jobs/{job_id}: get one job.
• POST /jobs/{job_id}/stop: request graceful stop/termination.

• GET /jobs/{job_id}/logs?since=<cursor>&limit=<n>: incremental log polling.
• WS /ws/logs/{job_id}: live log stream for one tracked job.
• WS /ws/train: spawn and stream a run command over websocket.

• GET /trials: raw trial result listing.
• GET /api/trials: flattened/sorted leaderboard rows.
• WS /ws/trials: push notification when trial_*.json files change.
• POST /api/sync: force pull/sync from Hugging Face results (when configured).

From backend/:

# Local run
.\run.ps1 train.py --local -- tune --n-trials 5

# Hugging Face run
.\run.ps1 train.py --flavor a10g-small --timeout 3h -- tune --n-trials 10

• Job metadata is tracked in memory and cleared when backend restarts.
• Runtime artifacts are local filesystem based (no database persistence layer).
• Cloud execution behavior depends on external Hugging Face service/CLI availability.

• Never commit real tokens to source control.
• If a token is exposed, rotate it immediately in Hugging Face settings.
• Keep .env out of version control and use .env.example as the template.