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

```bash
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:

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

Public deploy target:

```bash
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

```text
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:

```text
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:

```json
{
  "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:

```json
{
  "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.