docs/SHIP_AS_HF_SPACE_PROMPT.md

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