Blame for docs/hosting-plan.md

# Hosting plan: BeamPilot demo on Hugging Face Spaces

Status: **approved 31 Oct 2026**, built on branch `add-hosting`. Decisions taken
by the maintainer:

1. **Plan:** HF PRO, subscribed by the maintainer and kept until after the
   community-vote result on 16 Nov 2026.
2. **Lens replays:** ship **both**: the v3 L5 run and the seed-920 smoke run, so
   five replay files in total.
3. **Delivery:** upload with the `hf` CLI (section 6).

Goal: a public URL where anyone can **replay** saved agent runs (no key needed)
and, while the budget lasts, start **live runs** of the Muse Spark agent.

## 1. Platform: what the Hugging Face docs say (checked 31 Oct 2026)

| Topic | What the docs say | Source |
|---|---|---|
| Free CPU tier | CPU Basic (2 vCPU, 16 GB) has no hourly cost, **but** Gradio and Docker Spaces "require a paid plan to create" (PRO for personal accounts). Only static Spaces are free for everyone. | [Spaces overview](https://huggingface.co/docs/hub/spaces-overview#hardware-resources), [GPU Spaces, CPU table note](https://huggingface.co/docs/hub/spaces-gpus) |
| Free-account exception | Free accounts in good standing (verified email, account older than 30 days) can host up to 2 Gradio Spaces on **ZeroGPU**. | [ZeroGPU](https://huggingface.co/docs/hub/spaces-zerogpu) |
| PRO price | $9 per month; the list includes "Host ZeroGPU, Gradio & Docker Spaces". | [Pricing](https://huggingface.co/pricing) |
| Sleep | A `cpu-basic` Space sleeps when inactive "currently, 48 hours"; the next visitor restarts it automatically. You can't change the sleep time on free hardware. | [GPU Spaces, sleep time](https://huggingface.co/docs/hub/spaces-gpus#sleep-time) |
| Secrets | Secrets are private. Their value can't be read back from the settings page, and they are not copied when someone duplicates the Space. The app sees them as environment variables (`os.getenv`). | [Spaces overview, secrets](https://huggingface.co/docs/hub/spaces-overview#managing-secrets) |
| Variables | Variables are public and are copied to duplicates. Use them for non-secret settings only. | same |
| Front matter | Keys in a YAML block at the top of `README.md`: `title`, `emoji`, `colorFrom`, `colorTo`, `sdk`, `sdk_version`, `python_version`, `app_file`, `short_description`, `license`, `pinned`, `suggested_hardware`. | [Config reference](https://huggingface.co/docs/hub/spaces-config-reference) |
| Dependencies | `requirements.txt` is installed by the runtime; `sdk_version` sets the Gradio version. | [Gradio Spaces](https://huggingface.co/docs/hub/spaces-sdks-gradio) |
| Rebuild | Every new commit rebuilds and restarts the Space. | [Spaces overview](https://huggingface.co/docs/hub/spaces-overview) |
| Network | Outbound requests may use ports 80, 443 and 8080 only. The Meta Model API is HTTPS on port 443. | same |
| Git auth and large files | Push access needs a login (`hf auth login`, or a token in the git credential prompt). Binary files go through Git Xet. | [Repositories: getting started](https://huggingface.co/docs/hub/repositories-getting-started), [Xet](https://huggingface.co/docs/hub/xet/using-xet-storage) |

**Verdict: the free CPU tier does not fit as asked.** A free account can no
longer create a Gradio Space on CPU Basic.

**Alternative (recommended): HF PRO for one month ($9).** Everything else in this
plan stays the same: Gradio SDK, `cpu-basic`, and the same secrets. Cancel after
the judging period.

Not recommended: ZeroGPU on a free account. ZeroGPU is built for functions that
use the `@spaces.GPU` decorator, and BeamPilot runs no GPU code. It would be an
untested misuse of GPU hardware, and the 30-day account-age rule may not be met.

**Decision 1 (taken):** PRO.

## 2. Replay without a key

Replay reads JSON files from `docs/runs/` and calls no API. It works with no
secret set. Five files ship; three were already tracked:

| File | What it shows | Status |
|---|---|---|
| `docs/runs/mystery_s7.json` | Mystery beam (632.8 nm, M² ≈ 1.43) with a built-in **laser power ×3** fault: the agent met 6 saturated frames, lowered the exposure, and reached `iso_compliant` in 18 positions ($0.09). | tracked |
| `docs/runs/clean_room_light_live.json` | Clean beam with a **room-light fault** added by the operator before measurement 6: +3 counts of background ($0.07). | tracked |
| `docs/runs/clean_operator_note.json` | Operator note ("stage blocked 60–80 mm") respected ($0.05). | tracked |
| `docs/runs/lens_v3_L5.json` (byte-identical copy of `runs/evaluation-v3/L5_agent.json`) | **Lens run** from the pre-registered v3 evaluation: the waist lies outside the stage; the agent inserts +750 mm at −20 mm and reaches `iso_compliant` with the back-calculated original beam ($0.12). | added |
| `docs/runs/lens_smoke_s920.json` (byte-identical copy of `runs/20261031-183949_waist_outside_range_s920_muse-spark-1.2.json`) | **Lens run**, the change_lens smoke run before v3: +25 mm at −20 mm, `iso_compliant` ($0.13). | added |

**Decision 2 (taken):** ship both lens runs.

**Labels.** Every replay is labelled on the page as "Recorded run, <date>,
muse-spark-1.2", both in the run list and above the replay, so that a visitor
never takes a replay for a live run. The model name comes from the file
(`config.model`).

The run files themselves hold no date. So the date comes from a small manifest,
`docs/runs/recorded.csv` (file, date, source of the date):

- the two lens runs: 31 Oct 2026, from the original file timestamps;
- the three older runs: 27 Oct 2026, the date of commit becabe2, which added
  them. Their original timestamped files are no longer kept.

A test checks that every replay file has a manifest entry. An uploaded file is
labelled "Recorded run, date unknown, <model>".

Read-only checks done on all five candidates on 31 Oct:

- Searched for `C:\`, `Users`, `farsh`, the maintainer's e-mail domain, `MODEL_API_KEY`, `BASETEN`, `sk-`, `api_key`, `Bearer`, `.env`: **0 matches in every file**.
- Searched for path-like strings (`X:\…`, `/home/…`, `/Users/…`): **none**.
- Top-level keys are only scenario/case, seed, positions, truth, scenario
  parameters, fault events, lens changes, tool log, config (model name and limits),
  operator note, stop reason, usage, cost, report and steps.
- `load_run` and `replay_events` load L5 (68 events), seed 920 (88) and
  mystery_s7 (59) without errors.



A new test (section 5) repeats this scan for every `docs/runs/*.json` file, so a

file added later can't leak a path or key.



## 3. Live runs: only with a secret, and capped



A live run is possible only when the Space secret `MODEL_API_KEY` is set **and**

the live switch is on. The protections:



| Protection | Today in `app.py` | Planned |

|---|---|---|

| Queue concurrency | `queue(default_concurrency_limit=2)`, `MAX_CONCURRENT_RUNS = 2` | **1 live run at a time.** Set `concurrency_limit=1, concurrency_id="live"` on the Start event only, and `MAX_CONCURRENT_RUNS = 1`. Replay events keep the default concurrency, so replay never waits behind a 15-minute live run. |

| Per-run caps | `AgentConfig`: $0.50, 1.5 M tokens and 60 model calls (lens: 80 calls, 28 positions); 15-minute timeout | Normal runs unchanged. **Live lens runs use the v3 limits:** 80 model calls, 3 M tokens, $0.50 and 28 positions. |

| Per-tab caps | 3 runs and 2 M tokens per tab (convenience only) | 3 runs; **3 M tokens** per tab, so that one lens run can use its full v3 token limit. |

| Process caps | 50 runs; `BEAMPILOT_TOKEN_CAP` (default 60 M tokens, about $20) | unchanged, plus the spend cap below |

| **Spend cap per restart** | none | New env var `BEAMPILOT_SPEND_CAP_USD`, **default 5**. A thread-safe running total adds `run.cost_usd` after each run. A run starts only if spent + $0.55 (the per-run cap plus one call of overshoot) ≤ cap. So the cap cannot be exceeded, even by the last run. |

| **Live switch** | none | New env var `BEAMPILOT_LIVE_RUNS` (`on`/`off`, default `on` so local use is unchanged). On the Space it is a public **Variable**. Setting it to `off` turns live runs off without a code push. |

| **Clear messages** | a "needs MODEL_API_KEY" text, shown only after Start is clicked | A banner when the page loads, and the Start button disabled, in three cases (checked in this order): **switched off** ("Live runs are switched off on this demo right now. Replay works."), **no key** ("Live runs are not set up on this demo (no MODEL_API_KEY). Replay works without one."), **budget used** ("This demo has used its live-run budget for now; use Replay."). The server-side check stays the real guard; the banner is only information. |



Caveat: the $5 budget counter lives in process memory. It resets on every restart:

a push, a settings change, or waking from sleep after 48 h. Visitors can't force a

restart, but the cap is per restart, not lifetime. A typical live run costs

$0.05–0.13, so $5 is roughly 40–100 runs. If the Meta Model API console offers a

spending limit on the key, set it as a lifetime backstop (I have not checked

whether it does).



Scope: all changes are in `src/beampilot/app.py` (the UI) and new files. The

agent, prompt and tools stay frozen. With `change_lens` off, nothing changes, so
the hash test still holds.

## 4. The key is never logged, printed or saved

- **Where the key lives:** only in the Space secret `MODEL_API_KEY`. `make_client()` reads it from the environment; there is no `.env` on the Space. The UI never asks for a key.
- **What can leak today:** nothing found. API errors are already shown by type and HTTP status only, never by message text. `app.py` and `agent.py` contain no `print` or `logging` calls. Run files store the model name and limits, not the client.
- **New test:** set `MODEL_API_KEY` to a sentinel string and run a live run against a fake client. Then assert the sentinel appears in none of: the saved run JSON, the UI outputs (log, report, messages), and the captured stdout and stderr.
- **Hard rules:**
  - no Gradio `debug=True`;
  - no `show_error=True`;
  - no `OPENAI_LOG` variable on the Space;
  - live run files stay on the Space's temporary disk (`runs/`) and are not offered for download.
- **Baseten:** the Baseten key is **not** set on the Space. The app uses only the Meta Model API.

## 5. Files needed

1. **Space README `space/README.md`.** The GitHub `README.md` gets **no** front
   matter. The deploy step copies `space/README.md` over `README.md` in the
   exported folder only. The Space README has the front matter below, plus a few
   plain lines:
   - what the demo does;
   - that all data is simulated;
   - that replays need no key;
   - a link to the GitHub repository.

   ```yaml

   ---

   title: BeamPilot

   emoji: 🎯

   colorFrom: indigo

   colorTo: blue

   sdk: gradio

   sdk_version: 6.30.0

   python_version: "3.12"

   app_file: scripts/space_app.py

   short_description: Muse Spark agent measures laser M² to ISO 11146

   license: mit

   pinned: false

   suggested_hardware: cpu-basic

   ---

   ```

   A test reads `space/README.md` and checks the front matter against the
   project:
   - `sdk_version` equals the Gradio pin in `pyproject.toml`;
   - `app_file` exists;
   - `short_description` is at most 60 characters.
2. **`requirements.txt`**, pinned to the versions tested locally. Gradio is
   **not** listed, because `sdk_version` pins it (6.30.0, the same pin as the
   `demo` extra).

   ```text

   numpy==2.5.4

   scipy==1.18.1

   scikit-image==0.26.0

   matplotlib==3.11.2

   openai==3.38.0

   python-dotenv==1.2.4

   ```

   A test checks that these names match `[project] dependencies` in `pyproject.toml`.
3. **Entry point `scripts/space_app.py`** (about 10 lines). It puts `src/` on

   `sys.path` and calls `beampilot.app.main()`. This keeps the src layout and the

   `REPO_ROOT` lookup that finds `docs/runs/`; a root `app.py` would also work. The

   package is not pip-installed on the Space, because an installed copy would

   not find `docs/runs/`.

4. **`docs/runs/lens_v3_L5.json`, `docs/runs/lens_smoke_s920.json`, and
   `docs/runs/recorded.csv`**: the two lens replays and the manifest of

   recording dates (section 2).

5. **Code and tests:**
   - the `app.py` changes from section 3 and the replay labels;
   - tests for the spend cap (fake costs), the live switch, the no-key banner, the key sentinel, the run-file scan and the requirement pins;
   - the run-file scan looks for drive and home paths, e-mail addresses and key-like strings. It also looks for the local user name, home folder and git e-mail of whoever runs the tests, read at test time, so no personal data is written into the test;
   - the new env vars added to `.env.example` as comments (no values; Baseten entries untouched).
6. **README:** a "Hosted demo" line with the Space URL, added after the first
   successful deploy.

## 6. Code delivery: a git remote is a problem, so upload instead

You asked for a separate git remote for the Space and a push of `main`. Two
problems block a plain push:

1. **History contains a binary file.** `docs/figures/hero.png` (330 kB) is stored
   as a plain git blob in commits 18397f1 and 6c1b414. Forum reports show the Hub
   rejects pushes that contain binary files not stored through Xet, and that
   removing the file from the latest commit is not enough. Examples:
   [HF forum: push rejected due to binary files](https://discuss.huggingface.co/t/push-reject-due-to-binary-files/88990),
   [an example error log](https://huggingface.co/spaces/Alexramsal/AcuarelaPortraits/blob/main/git_error.txt).
   The fix would be **rewriting history**, which our rules forbid.
2. **A new Space already has a first commit** (`.gitattributes`, `README.md`),
   created by the Hub. Pushing `main` on top of it is not a fast-forward, so it
   would need a **force push** (forbidden) or a merge of the Space's commit into
   `main`.

**Recommended instead: upload a clean export of `main` with the `hf` CLI.**

- `git archive main` exports exactly the committed files: no `.env`, no `runs/`, no `.venv`.
- `hf upload` sends them as one new commit on top of the Space's first commit. That is no force push and no history rewrite. The CLI handles the PNG through Xet by itself.
- GitHub stays the only git history. The Space is a deploy target.

**Decision 3 (taken):** upload with the `hf` CLI.

**`.gitattributes`:** the repository has none (checked 31 Oct 2026). So the
upload cannot overwrite the Space's own `.gitattributes`, which the Hub created
for Xet/LFS handling. The deploy command still passes
`--exclude ".gitattributes"`, so that a file added later can't replace it.

## 7. Steps for the maintainer (browser and PowerShell)

I will not handle any token or password. Steps 1–4 are in the browser; steps 5–7
are in PowerShell, run by you.

1. **Plan:** subscribe to PRO (Decision 1), and keep it until after the vote result
   on 16 Nov: https://huggingface.co/subscribe/pro
2. **Create the Space:** https://huggingface.co/new-space. Settings:
   - Owner: your user; name `beampilot`; licence MIT;
   - SDK **Gradio**; hardware **CPU Basic (free)**; visibility **Public**.
3. **Add the secret and variables** under the Space's *Settings → Variables and secrets*:
   - **New secret** `MODEL_API_KEY`: paste the key there yourself.

     If the Meta Model API console allows a second key, create a **dedicated

     key for the Space**, and revoke it after judging; then the Space can never

     spend from your main key. (Unverified whether the console allows a second

     key.)

   - **New variable** `BEAMPILOT_LIVE_RUNS` = `off` for the first deploy. Turn it on after the replay check.

   - **New variable** `BEAMPILOT_SPEND_CAP_USD` = `5`.

4. **Create a write token** at https://huggingface.co/settings/tokens. Choose

   *Fine-grained*, with write access to this one Space only.

5. **Install the `hf` CLI in its own tools venv** (not in the project venv):


   ```powershell

   py -3.12 -m venv C:\dev\hf-tools

   C:\dev\hf-tools\Scripts\python.exe -m pip install -U huggingface_hub

   C:\dev\hf-tools\Scripts\hf.exe auth login

   ```

   `hf auth login` asks for the token in a hidden prompt; paste it there. Answer
   **n** to "Add token as git credential?" (we don't push with git).
6. **Deploy main** (replace `<HF_USER>`; run from `C:\dev\beampilot` on a clean,
   up-to-date `main`):

   ```powershell

   git switch main

   git status

   git pull

   Remove-Item -Recurse -Force "$env:TEMP\beampilot-space" -ErrorAction SilentlyContinue

   git archive --format=zip -o "$env:TEMP\beampilot-space.zip" main

   Expand-Archive "$env:TEMP\beampilot-space.zip" -DestinationPath "$env:TEMP\beampilot-space" -Force

   Copy-Item "$env:TEMP\beampilot-space\space\README.md" "$env:TEMP\beampilot-space\README.md" -Force

   C:\dev\hf-tools\Scripts\hf.exe upload <HF_USER>/beampilot "$env:TEMP\beampilot-space" . --repo-type space --exclude ".gitattributes" --commit-message "Deploy main $(git rev-parse --short main)"

   ```

   What each line does:
   1. `git switch main`: switch to `main`.
   2. `git status`: check there are no local changes.
   3. `git pull`: fetch the latest `main` from GitHub.
   4. `Remove-Item`: delete the previous export.
   5. `git archive`: export the committed files of `main` (no `.env`, no `runs/`) as a zip.
   6. `Expand-Archive`: unzip it.
   7. `Copy-Item`: put the Space README, with its front matter, in place of the GitHub README.
   8. `hf upload`: upload the folder as one commit to the Space, keeping the Space's own `.gitattributes`.

   The Space builds and restarts. Watch the *Logs* tab on the Space page.
7. **Later deploys:** repeat step 6. Files deleted from `main` are not deleted on
   the Space by an upload; remove them in the Space's *Files* tab, if any.
8. **Optional:** `C:\dev\hf-tools\Scripts\hf.exe auth logout` when done; revoke the
   token after the hackathon.

## 8. Dry run on the Space (after the first deploy)

1. With `BEAMPILOT_LIVE_RUNS=off`, check:
   - the banner says live runs are off;
   - the Start button is disabled;
   - all **five** replays play, each labelled "Recorded run, <date>,
     muse-spark-1.2", including both lens runs with their segment plots.

2. Search the build and run logs for the first characters of the key; there

   should be no match. Check by eye, and never paste the key anywhere.

3. Set `BEAMPILOT_LIVE_RUNS=on` and do one live run (about $0.05–0.13).

   - Check that a second tab queues instead of running in parallel.

   - Check the cost line in the report.

4. Temporarily set `BEAMPILOT_SPEND_CAP_USD=0.3` and confirm that the budget

   message appears; then set it back to 5.

5. Record the Space URL in the README (one commit), then upload again.


## 9. Time estimate

| Work | Who | Time |
|---|---|---|
| Code: switch, spend cap, concurrency, banner, entry point, requirements, front matter, lens replay file | Claude | 1.5 h |
| Tests (section 4–5) and the ruff/pytest gate, small commits on a branch | Claude | 1 h |
| Browser steps 1–4 and CLI steps 5–6 | maintainer | 20–30 min |
| First build, dry run (section 8), fixes | both | 1 h |
| Buffer for Space-specific surprises | — | 1 h |
| **Total** | | **about 4.5–5 h**; API cost ≤ $1 for the dry run |

This fits comfortably before the deadline (Wed 4 Nov, 21:00 ET), leaving the
video script as the next step.