Text2Avatar PGX Control Plane

A complete operations dashboard for the ISC-HEI/PGX_setup Text2Avatar API running on an NVIDIA DGX Spark (PGX).

The dashboard connects directly to the FastAPI service, follows its real queue and artifact contracts, and remains useful while disconnected through a clearly labelled preview dataset.

What is included

• Operations overview with active jobs, average duration, success rate, artifact count, performance trend, current stage progress, and the runtime health fields the API currently exposes.
• Pipeline studio for the complete text → image → static mesh → rig → animation job, including all PGX parameters, a one-second execution heartbeat, ETA/regression warnings, and live progress polling.
• Stage lab for every smaller execution boundary exposed by the API:
  • prompt → static GLB (POST /api/jobs)
  • uploaded image → static GLB (POST /api/jobs, multipart)
  • completed static GLB → rigged and animated GLB (POST /api/jobs/:id/animate)
• Benchmark workspace for prompt corpora, repeats, seeds, resolution profiles, aggregate comparisons, P50/P95 timing, and stage cost analysis.
• Jobs & runs with search, status/source filters, continuously updated elapsed time, estimated progress, stage telemetry, effective parameters, errors, and raw job summaries.
• Artifact library with generated PNGs, static/rigged/final variants, a GLB viewer, and protected download links.
• Connection settings with bearer-token auth, health checks, API contract inventory, an SSH tunnel guide, and explicit notes for telemetry the current backend does not expose.

Run locally

Requirements: Node.js 20 or later.

npm install
npm run dev

Open http://localhost:5173 and choose Connect PGX.

For a production check:

npm run build
npm run preview

Connect to the DGX Spark

The safest local setup keeps FastAPI on the PGX loopback interface and forwards it over SSH:

# on the PGX host, from the PGX_setup repository
export API_TOKEN='replace-with-a-long-random-value'
uvicorn server.app:app --host 127.0.0.1 --port 8000

# on the dashboard workstation
ssh -N -L 8000:127.0.0.1:8000 user@your-pgx-host

Then connect the dashboard to http://127.0.0.1:8000 with the same token.

The API already enables CORS. The URL and token are runtime settings saved only in browser local storage; they are not compiled into the bundle. The upstream artifact endpoints require the token as a query parameter, which the dashboard follows for image and GLB viewer URLs.

API coverage

Dashboard capability	PGX_setup endpoint
Health and GPU identity	GET /api/health
Full four-stage pipeline	POST /api/pipeline
Prompt or image static generation	POST /api/jobs
Rig and animate a finished model	POST /api/jobs/:id/animate
Batch benchmarks	POST /api/benchmark
Queue, history, and details	GET /api/jobs, GET /api/jobs/:id
Aggregate metrics	GET /api/stats
Protected artifacts	GET /api/image/:id, GET /api/glb/:id
Live worker logs (optional upgrade)	GET /api/jobs/:id/logs?after=:cursor&limit=:limit

The current backend combines some internal model stages into one API call. The Stage lab labels those boundaries explicitly rather than presenting image-only or rig-only actions that the service cannot execute.

Runtime monitoring boundary

GET /api/health currently returns API status, mock mode, GPU name, and whether the main model is loaded. Job records provide queue status, per-stage pipeline state, timings, mesh counts, and errors. The dashboard polls the selected job once per second, updates elapsed time locally between responses, compares active runs with matching historical medians, and clearly labels its ETA as estimated.

When GET /api/jobs/:id/logs is available, the execution console consumes cursor-based log records shaped like { lines: [{ id, timestamp, level, source, message }], next_cursor }. Until then it shows only real job-state transitions and provides the Spark journalctl command; it does not present synthetic events as raw worker output.

GPU utilization, unified-memory usage, temperature, power, model-load duration, and worker heartbeat are intentionally shown as an optional backend upgrade, not fabricated as live values.

Project structure

client/src/
├── api/pgxClient.js          PGX FastAPI client and artifact URLs
├── context/PgxContext.jsx    connection, polling, actions, preview mode
├── components/               dashboard shell, execution console, charts, shared UI
├── hooks/useJobTelemetry.js  one-second job/log polling and elapsed-time tracking
├── data/demoData.js          labelled offline preview telemetry
├── pages/                    overview, studio, lab, benchmarks, jobs, artifacts, settings
└── styles/                   ISC tokens and responsive control-plane UI

The legacy server/ workspace from the ISC starter remains isolated and is not needed by the dashboard. npm run dev starts the client only.

Visual identity

The dashboard keeps the ISC logo assets, font system, and faceted ridge accent from ISC-HEI/isc-logos (CC BY-NC-SA 4.0) while adapting them for a dense operations interface.