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.