# Handoff Prompt — Ship Phantom Grid as a Hugging Face Space

> Paste the block below to the agent taking over. It is self-contained.

---

## Task

Ship the **Phantom Grid** game (this repo) as a **Docker Hugging Face Space** in the
`build-small-hackathon` org, for the Build Small Hackathon. The app already works locally on
Windows; your job is to make it run on a Linux Space and submit it. **Do not rewrite the
gameplay** — only do deployment/packaging.

## Hard facts (already verified — do not re-litigate)

- **Models are compliant:** MiniCPM4.1-8B (text, default) and MiniCPM-o-4.5 (~8B, optional
  voice). Both under the 32B cap. Keep the text model as the default backend.
- **Custom interface is allowed and encouraged.** The app uses `gr.Server()` with a custom
  HTML/JS frontend. The field guide says *"gr.Server is your friend — go well beyond the stock
  components"* (Off Brand badge). **Do NOT convert it to stock Gradio Blocks.**
- **llama.cpp is the blessed inference path.** The org's recommended pattern is
  `llama-server -hf <repo>:Q4_K_M` exposing an OpenAI-compatible API at `:8080/v1`, with the
  Gradio app pointing at it. The app already supports this via its
  `llama_cpp_server` / `external_llama_cpp_server` provider (`PHANTOM_GRID_LLAMACPP_BASE_URL`).
- **Account:** logged-in HF user is `unity4ar`, a member of `build-small-hackathon`. ⚠️ The
  cached token is **read-only** — obtain a **write** token and `huggingface-cli login` before
  pushing, or repo creation/push will fail.
- **HF home on this machine:** `D:\AppData\Local\huggingface`.

## The core problem to solve

The current app cannot run on a Linux Space because it is Windows-only and builds its runtime at
first launch:
- Windows APIs: `ctypes.windll`, `msvcrt`, `subprocess.CREATE_NO_WINDOW`, `.exe` paths in
  `app.py` and `scripts/provision_local_runtime.py`.
- First-launch native compile of `llama.cpp-omni` + ~12 GB model download into `runtime/`.
- PowerShell/cmd launchers (`run_game.ps1`, `run_game.cmd`).

## Required deliverables (all mandatory for a valid submission)

1. **A Docker Space that runs on Linux** (Docker is allowed "as long as the interface is a
   Gradio Space"; `gr.Server` qualifies).
2. **Space README** with YAML frontmatter (`sdk: docker`, `app_port`), the **track tag**
   (this is the *delightful / Thousand Token Wood* track — an AI-driven game), **prize-category
   badges**, a short description, and links to the demo video and social post.
3. **Demo video** of the app working (judges may not be able to run it live).
4. **One social-media post**, linked from the README.

## Implementation plan

1. **Write a `Dockerfile`** at repo root (Linux base, e.g. `python:3.12-slim` or an
   `nvidia/cuda` base if using a GPU Space):
   - Install `requirements.txt` (drop Windows-only bits; `audioop-lts` is Py3.13-only and
     optional).
   - Obtain `llama-server` for Linux — either `pip install llama-cpp-python[server]` or fetch a
     prebuilt llama.cpp Linux binary. **Do not** compile the vendored `llama.cpp-omni` tree.
   - Download the GGUF at **build time** via `huggingface_hub.hf_hub_download` (text model:
     a MiniCPM 8B Q4_K_M GGUF) into a known path — no first-run provisioning.
   - Copy app code. **Exclude** `.venv/`, `runtime/`, `tools/*/Lib`, and other multi-GB vendored
     trees (add a `.dockerignore`).
2. **Add a Linux entrypoint** (shell script or a small supervisor) that:
   - Starts `llama-server` on `:8080` pointing at the downloaded GGUF.
   - Sets env so the app uses the external server:
     `PHANTOM_GRID_LLM_PROVIDER=llama_cpp_server` (or `external_llama_cpp_server`),
     `PHANTOM_GRID_LLAMACPP_BASE_URL=http://127.0.0.1:8080/v1`,
     `PHANTOM_GRID_WITNESS_CHAT_TTS=0` (text backend has no voice).
   - Launches `app.py` and binds the Gradio/`gr.Server` port to the Space's `app_port`
     (default 7860; expose it).
3. **Make `app.py` import on Linux.** Guard or remove the Windows-only code paths that run at
   import/startup (`msvcrt`, `ctypes.windll`, `CREATE_NO_WINDOW`, `.exe` lookups). The in-app
   "setup/provisioner" screen should be disabled or hidden on Spaces since the model is baked
   into the image — `new_case` requires a healthy backend, so ensure the baked server reports
   healthy.
4. **Pick hardware.** A GPU Space is realistic for an 8B model; CPU works but is slow. If using
   ZeroGPU, remember the 10-apps-per-user cap. Document the choice in the README.
5. **Create & push the Space** to `build-small-hackathon/<name>` with a **write** token:
   `huggingface-cli login`, then create the Space (SDK: Docker) and `git push` (or use
   `huggingface_hub.HfApi.create_repo(repo_type="space", space_sdk="docker")` + upload).
6. **Verify it boots** on the Space, the server reports healthy, and a new case starts.
7. **Record the demo video**, **publish the social post**, and finalize the README with both
   links + track tag + badges.

## Acceptance criteria

- The Space builds and runs on HF Spaces (Linux), starts a case, and answers a witness question
  using the under-32B model.
- README has track tag, badges, description, video link, social link.
- Space lives under the `build-small-hackathon` org.
- No Windows-only call runs in the container; no multi-GB build-from-source at startup.

## Pitfalls

- Read-only token → push fails. Get a write token first.
- Pushing `.venv/`/`runtime/` → bloated/broken Space. Use `.dockerignore`.
- Model download at startup instead of build time → Space times out. Bake it into the image.
- Leaving `PHANTOM_GRID_LLM_PROVIDER=minicpm_omni` → needs the heavy omni stack. Use the plain
  text llama.cpp server provider.





dont upload anything but make a script to do all the requirements to ship everything... i will copy the present folder to another system and will run this script from that system....but test to make sure that it will run....only one step left must be to run this script