docs/HOSTING.md

# Hosting (DPLY-01)

**Decided:** 2026-08-27
**Chosen path:** `zerogpu-free`

| Field | Value |
|---|---|
| Space | WolfDavid/japanese-learning-avatar |
| Space page | https://huggingface.co/spaces/WolfDavid/japanese-learning-avatar |
| SPACE_URL (direct, used by E2E `--space-url`) | https://wolfdavid-japanese-learning-avatar.hf.space |
| Visibility | public (`private: false`) |
| Hardware requested | `zero-a10g` (ZeroGPU) |
| Hardware applied | not yet allocated — `runtime.hardware.current` is `null` because `runtime.stage` is `NO_APP_FILE`. See "Why `hardware.current` is null" below. |
| sdk / sdk_version | gradio / **6.26.0 on the Space today** — must be corrected to **6.22.0** by plan 01-05. See "Open handoff to plan 01-05". |
| python_version | **`'3.12'` on the Space today** — must be corrected to **3.12.12** by plan 01-05. |
| Sleep timeout | 48 h (`gcTimeout: 172800`) |
| Space repo SHA at time of writing | `b70455dcf67ff7db6b1f48f08153982d37a63dd2` (two files: `.gitattributes`, `README.md`) |
| Created | 2026-08-27T02:13:12Z |

## The decisive finding: `cpu-basic` is no longer creatable, and it fails with a payment error

Creating this Space on the default `cpu-basic` hardware was **rejected with HTTP 402 Payment
Required**. The message, verbatim:

> Static Spaces are free for everyone, but hosting Gradio and Docker Spaces on free cpu-basic
> requires a PRO subscription.

Re-issuing the identical creation request with ZeroGPU (`space_hardware="zero-a10g"`) **succeeded
immediately, with no payment prompt and no charge.**

This is empirical confirmation of the claim in `01-RESEARCH.md` and `CLAUDE.md` that Gradio Spaces
on a free personal account are PRO-gated *except* for the ZeroGPU carve-out. It is no longer a
documentation reading — it is an observed platform response on this account.

**Consequence:** ZeroGPU is now the **only** free hosting path for this project. A future phase
**cannot** silently fall back to `cpu-basic` to save a ZeroGPU slot — that fallback does not exist
for a Gradio Space on a non-PRO personal account. Any plan that proposes it is proposing a $9/mo
purchase.

## Account eligibility evidence (verified against the live public API, 2026-08-27)

Queried in this task, not quoted from RESEARCH:

- `isPro: false`; account created `2023-11-27T01:45:12.000Z` — about 2.7 years old, so the ZeroGPU
  ">30 days in good standing" criterion is satisfied with enormous margin.
- Email: verified (account is in good standing; ZeroGPU allocation was accepted, which requires it).
- **8 pre-existing Gradio Spaces, every one of them `requested: cpu-basic`, and zero on ZeroGPU** —
  so both free ZeroGPU slots were open before this Space was created:

  | Space | sdk_version | python | hardware requested | stage |
  |---|---|---|---|---|
  | `WolfDavid/dino` | 6.9.0 | 3.11 | cpu-basic | RUNNING |
  | `WolfDavid/fea-surrogate` | 5.9.1 | 3.11 | cpu-basic | SLEEPING |
  | `WolfDavid/mechspec-qwen-demo` | 5.9.1 | 3.11 | cpu-basic | SLEEPING |
  | `WolfDavid/agentic-market-analyzer` | 5.9.1 | 3.11 | cpu-basic | SLEEPING |
  | `WolfDavid/log-anomaly-detector` | 5.9.1 | 3.11 | cpu-basic | RUNNING |
  | `WolfDavid/vision-edge` | 5.9.1 | 3.11 | cpu-basic | SLEEPING |
  | `WolfDavid/nllb-translator` | 5.9.1 | 3.11 | cpu-basic | SLEEPING |
  | `WolfDavid/blip-captioner` | 5.9.1 | 3.11 | cpu-basic | SLEEPING |

- `WolfDavid/dino` runs `sdk_version: 6.9.0`, so Gradio 6 is proven to work on this account.
- Note for anyone re-running this check: **`runtime.hardware.current` is `null` for every SLEEPING
  Space.** `current` reports what is running right now, not what the Space is entitled to. Read
  `runtime.hardware.requested` when auditing hardware tiers, or six of these eight Spaces look
  unallocated.
- Note also that `GET /api/spaces?author=WolfDavid` still returned only the original 8 shortly after
  creation; the list endpoint lags. `GET /api/spaces/WolfDavid/japanese-learning-avatar` returns the
  new Space immediately and is the authoritative read.

## Why `hardware.current` is null, and why that is correct

```
"runtime": { "stage": "NO_APP_FILE",
             "hardware": { "current": null, "requested": "zero-a10g" },
             "gcTimeout": 172800 }
```

The Space repo contains only `.gitattributes` and an auto-generated `README.md`. With no `app.py`
there is nothing to schedule, so no hardware is attached. **This is the correct pre-deploy state and
is not a failure.** `requested: zero-a10g` is the binding fact — it is the tier the Space will start
on the moment plan 01-05 pushes an app.

Reachability today, measured three times consecutively with identical results:

| URL | HTTP | Meaning |
|---|---|---|
| https://huggingface.co/spaces/WolfDavid/japanese-learning-avatar | **200** | The Space exists and is public |
| https://wolfdavid-japanese-learning-avatar.hf.space | **503** | `Your space is in error, check its status on hf.co` — no `app.py` yet |

The direct subdomain **is** provisioned (`runtime.domains[0].stage: READY`, `subdomain:
wolfdavid-japanese-learning-avatar`), it simply has nothing to serve. **Plan 01-05 turns this 503
into a 200**, and `tests/e2e/test_avatar_loop.py::test_space_reachable` — which plan 01-05 creates —
is what actually satisfies DPLY-01. DPLY-01 is **not** satisfied by this plan.

## Open handoff to plan 01-05 (which owns `README.md`)

Space creation auto-generated a `README.md` whose front-matter **conflicts with the pinned stack**:

| Key | Auto-generated value | Required value | Source of the requirement |
|---|---|---|---|
| `sdk_version` | `6.26.0` | `6.22.0` | `requirements.txt` line 1 pins `gradio==6.22.0`; `CLAUDE.md` says pin exactly |
| `python_version` | `'3.12'` | `3.12.12` | ZeroGPU provides only 3.10.13 and 3.12.12; `.python-version` is `3.12.12` |

Left uncorrected, the Space SDK would install Gradio 6.26.0 while `requirements.txt` asks for
6.22.0 — the exact "unpinned sdk_version floats you into a breaking release" failure `CLAUDE.md`
warns about, arrived at from the other direction. This plan does **not** edit `README.md`; that file
belongs to plan 01-05.

## Why not the alternatives

- **`cpu-basic` (free)** — no longer available. Attempting it returned **HTTP 402 Payment Required**
  (quoted verbatim above). This option is closed, not merely discouraged.
- **`sdk: static`** — free for everyone, but VOICEVOX cannot run in a browser, so there would be no
  mora timings and AVTR-02 collapses entirely. ZeroGPU is also Gradio-SDK-only, so Phase 3 would
  need a rewrite. Rejected.
- **PRO ($9/mo)** — **not purchased, and not needed**: the free ZeroGPU path worked. PRO does not
  improve the anonymous **visitor's** 2 min/day quota, so it would change nothing about the
  free-tier design that Phase 1 is built around. No payment was made by any step of this plan.

## GPU posture

Phase 1 calls **no** GPU function. `DISABLE_GPU=1` is to be set as a Space variable and every future
GPU entry point must raise when it is set. Proof lives in `tests/test_no_gpu_on_turn_path.py` (static
AST scan) and a `DISABLE_GPU=1` deployed E2E run.

A ZeroGPU Space that never calls `@spaces.GPU` runs its web process on CPU and consumes **zero**
visitor quota, so taking the ZeroGPU tier costs nothing at runtime in Phase 1. Plan 01-04 already
established that speech synthesis is CPU-only and AST-verified free of `spaces`/`torch` imports.

## ZeroGPU slot budget

**1 of 2 free ZeroGPU slots is now consumed by this Space. 1 slot remains** for the other four
HF-profile projects. Because `cpu-basic` Gradio creation is 402-gated on this account, that final
slot is the last free Gradio Space this account can create without PRO — spend it deliberately.

## Git remote

`git remote add space https://huggingface.co/spaces/WolfDavid/japanese-learning-avatar`

Authentication is a cached fine-grained token held by the `hf` CLI (`hf auth whoami` reports
`WolfDavid`), scoped `repo.write` / `repo.content.read` / `repo.access.read` on the WolfDavid entity.
The token value is never written to this repository, any commit message, or any log.

**No application code has been pushed to this remote.** Deployment is plan 01-05's task and is gated
behind its own spike verdict.