gpu/single-gpu/home_benjamin_hdbasin/code/web/README.md

HD-BasinFlow Web MVP

This is the first product-facing web app for HD-BasinFlow.

It is intentionally scoped to the strongest current evidence:

• binary text classification
• DistilBERT-style fine-tuning
• fixed-budget hyperparameter search
• A100-backed job queue
• report-first delivery

It should not be marketed as broad AutoML, image optimization, or a universal Optuna replacement.

Run Locally

cd web
npm install
npm run dev

Open the Vite URL printed by the command.

For the Cloudflare Pages API routes as well as the Vite frontend:

cp .dev.vars.example .dev.vars
# Fill .dev.vars after Supabase and Stripe are created.
npm run pages:dev

Public deploy target:

npm run pages:deploy

Cloudflare Pages settings:

• Project name: hdbasin
• Production URL: https://hdbasin.pages.dev
• Build command: npm run build
• Build output directory: dist
• Root directory: web

Intended Production Flow

1. User uploads a CSV or JSONL dataset.
2. The API validates that the selected label column has exactly two classes.
3. User chooses a fixed budget: 8, 12, or 20 trials.
4. Stripe checkout creates a paid run reservation.
5. A job record is inserted into the queue.
6. The A100 worker downloads the private dataset and runs HD-BasinFlow.
7. The worker writes the report, plots, best config, and optional checkpoint.
8. The user downloads the report from the dashboard.

Backend Endpoints To Add

POST /api/uploads/presign
POST /api/datasets/validate
POST /api/checkout/session
POST /api/jobs
GET  /api/jobs/:id
GET  /api/jobs/:id/events
GET  /api/jobs/:id/report
POST /api/jobs/:id/cancel

Implemented now:

GET  /api/health
POST /api/uploads/presign
POST /api/datasets/validate
POST /api/checkout/session
POST /api/demo/session
POST /api/stripe/webhook
GET  /api/jobs/:id
GET  /api/jobs/:id/events
POST /api/jobs/:id/cancel

The public page also includes a Sample button plus Run free demo, which creates a zero-cost queued job without Stripe.

A100 Worker Contract

The web app should enqueue a job payload like:

{
  "jobId": "job_123",
  "datasetUri": "s3://private-bucket/job_123/input.csv",
  "textColumn": "text",
  "labelColumn": "label",
  "modelFamily": "distilbert",
  "budget": 20,
  "optimizer": "hdbasinflow",
  "taskType": "binary_text_classification"
}

The worker should return:

{
  "jobId": "job_123",
  "status": "succeeded",
  "bestValidationLoss": 0.6598,
  "bestConfigUri": "s3://private-bucket/job_123/best_config.json",
  "reportUri": "s3://private-bucket/job_123/report.pdf",
  "plotsUri": "s3://private-bucket/job_123/plots.zip"
}

Payment Notes

Use Stripe Checkout first. Do not run the GPU job until the checkout session is paid and the webhook marks the job as funded.

Minimum webhook events:

• checkout.session.completed
• checkout.session.expired
• payment_intent.payment_failed

Safety Limits

• Reject datasets above the configured size limit.
• Reject multiclass labels in the first public version.
• Store uploads privately.
• Delete raw uploads after a fixed retention window.
• Cap job runtime and GPU memory.
• Return an honest report even when HD-BasinFlow loses to the baseline.