docs/HACKATHON_SUBMISSION_READINESS.md

Phantom Grid — Build Small Hackathon Submission Readiness Report

Date: 2026-06-15 Project: Phantom Grid (Shadow Commission: London) Target: Hugging Face Build Small Hackathon

---

TL;DR

Not submittable as-is. The game logic, AI usage, and model-size compliance are in good shape, but the project fails the hackathon's two hard delivery requirements: it is not deployed as a Gradio Space in the official org, and it cannot run on Hugging Face Spaces in its current form (Windows-only, requires native local compilation of llama.cpp and a ~12 GB local model download). The required demo video, social post, and Space README metadata (track tags / badges) are also missing.

The official deadline is June 15, 23:59 UTC — today. Closing the deployment gap before the deadline is not realistic; this is a multi-day porting effort.

---

Hackathon Requirements Checklist

#	Requirement	Status	Notes
1	Every model under 32B parameters	✅ Pass	Uses MiniCPM4.1-8B (text, default) and MiniCPM-o-4.5 (~8B, optional voice). Both well under 32B.
2	App is a Gradio app	✅ Pass	Uses gr.Server() with a custom HTML/JS frontend. The field guide explicitly encourages this: "gr.Server is your friend — go well beyond the stock components and make it yours" (the Off Brand bonus badge). Custom, non-traditional Gradio interfaces are rewarded, not penalized.
3	Deployed as a Hugging Face Space in the build-small-hackathon org	❌ Fail	No Space exists. No Space README YAML header, no Spaces-compatible config.
4	App actually runs on Spaces (Docker or Gradio SDK, Linux)	❌ Fail	Windows-only runtime. See blockers below.
5	Demo video showing the app working	❌ Missing	Not produced.
6	Social media post linked from the Space README	❌ Missing	Not produced.
7	README with track tag (Backyard AI / Thousand Token Wood) + prize badges	❌ Missing	Current README.md is a local-setup guide; lacks Space frontmatter, track tags, badges, and video/social links.
8	Submit before June 15, 23:59 UTC	⏰ At risk	Deadline is today.

---

Critical Blockers (Deployment)

The architecture is built for a local Windows machine, which is fundamentally incompatible with the Hugging Face Spaces Linux container runtime:

1. Windows-specific code throughout. 51 occurrences of .exe, plus ctypes.windll, msvcrt file locking, and subprocess.CREATE_NO_WINDOW in app.py and scripts/provision_local_runtime.py. These will not run on a Linux Space.

2. Runtime provisioning at first launch. The app expects to download sources, compile llama.cpp-omni natively (cmake/ninja/zig), install PyTorch, and pull a ~12 GB GGUF model into a local runtime/ directory. Spaces cannot perform multi-minute native builds and large downloads as part of normal app startup, and the free/ZeroGPU tier has no persistent build env for this.

3. Launcher is .ps1 / .cmd. Entry is PowerShell-driven (run_game.ps1, run_game.cmd), not a Spaces app.py Gradio SDK entrypoint or a portable Dockerfile. (The only Dockerfile present is inside the vendored runtime/MiniCPM-o-Demo/, not the app's.)

4. No Spaces hardware story. The model needs GPU or slow CPU inference plus the gateway process. There is no configuration mapping this to ZeroGPU or a Spaces GPU tier.

---

What's Already Good

• Model compliance is solid — both models are comfortably under the 32B cap.
• Real, non-trivial AI use — LLM drives witness interviews and story generation, matching the "AI doing the fun thing" spirit of the delightful / Thousand Token Wood track.
• Working game locally on Windows: map, notices, witnesses, tactics, turn engine, save/load, and a test suite (pytest).
• gradio and huggingface_hub are already dependencies, so the toolchain is partially aligned.

---

What It Would Take to Submit (Path Forward)

Ordered by necessity. Items 1–4 are mandatory for a valid entry.

1. Make it run on Linux/Spaces. Replace the build-from-source runtime with a hosted inference path:
   • Easiest: swap the local llama.cpp backend for the Hugging Face Inference API / Inference Endpoints (or a hosted OpenAI-compatible endpoint) using huggingface_hub, gated to an under-32B model. This removes native compilation and the 12 GB download entirely.
   • Alternative: a Dockerfile Space that ships a prebuilt llama-server + a Q4 GGUF, downloaded via hf_hub_download at build time, on a GPU Space. Heavier and slower to set up.
2. Provide a Spaces entrypoint. A Docker Space is the right fit (the org allows Docker "as long as the interface is a Gradio Space", and gr.Server qualifies). The custom HTML frontend is fine to keep — it even qualifies for the Off Brand bonus badge — so no rewrite to stock Gradio components is needed.
3. Add a Space README with YAML frontmatter (sdk: gradio or sdk: docker, app_file/app_port), the track tag, prize-category badges, a short description, and links to the demo video and social post.
4. Record a demo video and publish one social post, then link both from the README.
5. Strip the repo for upload — exclude .venv/, runtime/, and other vendored multi-GB trees from the Space (these are present locally and would bloat/break the push).

---

Recommendation

Do not attempt to submit before today's deadline — the Linux/Spaces port (Blocker #1–4) is the dominant risk and cannot be completed and verified responsibly in the time remaining.

If a later round or deadline extension applies, the fastest credible path is: HF Inference API backend → Gradio Blocks (or Docker) Space → README + video + social post. The game itself is the hard part and it already works; the remaining work is deployment and packaging, not gameplay.