Hackathon Advisor is a live map of the Build Small Hackathon and a small-model originality coach for builders. It opens on an atlas of public build-small-hackathon Spaces, then lets a builder search the field, inspect project clusters, see quest evidence, and open The Unwritten Almanac to evaluate an idea against the work already on the trail.

The Build Small Hackathon asks participants to build under a 32B parameter cap, solve a concrete problem for someone nearby or make a delightful AI-native experience, and submit a Space, demo video, and social post. Hackathon Advisor treats that setting as the data surface: every public Space becomes part of a continuously refreshed project atlas, and every advisor response is grounded in that shared map.

• Live app: build-small-hackathon-hackathon-advisor.hf.space
• Demo video: YouTube
• Social post: X

Why it exists

Builders enter a fast-moving hackathon with limited context. A promising idea can already be crowded, a quiet niche can be hard to see, and prize alignment can be scattered across READMEs, tags, and app files. Hackathon Advisor turns the field itself into the starting point: it shows where projects cluster, which submissions sit near each other, which quests they appear to satisfy, and where a new idea may still have room to breathe.

A public hackathon organization is already a living corpus of Spaces, READMEs, model declarations, app files, tags, and demos. Once it is indexed, builders can see what others are making, which methods they use, and which results are emerging. The author compares this visibility to the creative force of OpenAI's Parameter Golf challenge: participants can find adjacent work, recognize overlap, borrow useful patterns, extend ideas into new domains, and connect with people working on similar problems — a faster open-source feedback loop.

The atlas is the default experience because the map is the evidence. Behind Open advisor, the advisor uses the same project snapshot to cite overlap, propose whitespace, score the idea, draft a build plan, and export the session evidence.

What you can do

• Full-screen t-SNE atlas of public hackathon Spaces, with KMeans clusters and nearest-neighbor links.
• BM25 project search over titles, slugs, summaries, tags, declared models, cluster labels, quest evidence, README text, and declared app-file source.
• Filter and inspect by cluster or quest, viewing each project's summary, Space link, tags, quest matches, and evidence hints.
• Chat with the atlas: the "Ask the atlas" drawer answers questions like "who completed the most quests" or "what clusters exist" through the base MiniCPM5-1B model's native tool calling, with thinking enabled — the reasoning trace streams live into a collapsible block. Verified tool results render as cards that can filter or highlight the map; the model's prose is grounded on a compact digest of the same result.
• Refresh the atlas from the Space backend; validated artifacts are written to the mounted cache directory and swapped into the live app atomically.
• Advisor workspace for idea comparison, gap exploration, score seals, profile-aware plans, voice input, and shareable exports.
• Exports: build notes, the Almanac chapter, and the page PNG from the UI; trace JSONL, demo bundle, submission packet, LoRA dataset, and LoRA training kit through the API.

How it works

The refresh path snapshots public Spaces in the build-small-hackathon organization, reads each README and declared main app file, rebuilds the EmbeddingGemma project index, resolves official track:*, sponsor:*, and achievement:* metadata tags first, then asks MiniCPM only for quest evidence that metadata did not declare. The dashboard contains project points, nearest links, clusters, quest coverage, provenance, and refresh state.

ADVISOR_CACHE_DIR is the artifact store — the mounted Storage Bucket on Hugging Face Spaces, or a normal directory such as .cache/advisor-dashboard locally. Each refresh writes projects.json, project_index.json, dashboard.json, quest_analysis.json, and manifest.json under runs/{run_id}/, then updates latest.json through an atomic swap. Quest analysis is cached per project using the prompt hash, taxonomy hash, MiniCPM model id, adapter id/revision, local adapter digest, and generation config.

The app can run an hourly scheduler when ADVISOR_CACHE_DIR is configured. The submitted Space keeps scheduled refresh disabled and updates the mounted bucket from local builds, so index construction and quest analysis do not run inside the public demo runtime. Refreshes acquire a refresh.lock, heartbeat while active, and leave the current validated dashboard in place if a new run fails validation.

Models and data

Role	Model	Runtime	Notes
Advisor	openbmb/MiniCPM5-1B + hackathon-advisor-minicpm5-lora	ZeroGPU, Transformers, PEFT	The 1.08B OpenBMB model plans which tool to call each turn; advisor prose is rendered from deterministic templates grounded in retrieved tool results
Quest analysis	Official Space metadata + openbmb/MiniCPM5-1B + hackathon-advisor-quest-minicpm5-lora	ZeroGPU, Transformers, PEFT	Trusts official README tags for tracks, sponsor prizes, and badges, then uses a task-specific MiniCPM LoRA to classify remaining evidence into strict quest JSON
Project retrieval	embeddinggemma-300m-qat-q8_0-GGUF	Local llama.cpp index build and query embeddings	The atlas and retrieval index use a GGUF embedding model through llama.cpp
Voice input	nvidia/nemotron-speech-streaming-en-0.6b	ZeroGPU, NVIDIA NeMo ASR	Voice notes are transcribed with the same Nemotron model locally and in deployment

MiniCPM is loaded following the official demo shape (trust_remote_code=True, bfloat16, and enable_thinking=False in apply_chat_template) for stable tool calls and strict quest JSON. The largest single model is MiniCPM5-1B at about 1.08B; the full runtime stack totals about 1.98B.

Data and released material:

• Project corpus: public Spaces in build-small-hackathon, crawled as the live field for the atlas, search, advisor citations, and quest coverage.
• Project snapshot and embedding index: data/projects.json, data/project_index.json.
• Quest SFT dataset: hackathon-advisor-quest-dataset, used to train the MiniCPM quest classifier.
• Codex session traces: hackathon-advisor-codex-traces, published after selection, minimization, and OpenAI Privacy Filter redaction.
• Advisor LoRA training kit: /api/lora-training-kit.zip, regenerating chat JSONL examples, recipe metadata, and the adapter card from real advisor sessions.

Advisor workspace

The advisor workspace preserves the working loop from the original app:

• Ink compares the current idea against the project index.
• Gap rotates through unused whitespace candidates.
• Plan drafts a practical build path.
• Compare rescans the saved idea board to select the strongest page.
• Profile adds skills, time, preferences, and constraints so the plan can treat "one evening", "frontend prototyping", or "CPU-only Space" as real scoping facts.

Each scored page includes a deterministic wood_map: background dots for indexed Spaces, red dots for the closest cited echoes, and a green/red point for the current idea. The live UI and PNG export share the same Pillow renderer.

How Codex was used

Codex served as the engineering partner: translating hackathon requirements into implementation slices, inspecting the codebase, building the atlas refresh/storage/cache path, adding the search and quest-evidence UI, running local tests and browser checks, reviewing deployed Space behavior, preparing commits and deployments, and revising the README. The demo video used the same agentic workflow — Codex helped draft the narrated storyboard, drive the live app, capture screen footage, generate voice-over, compose the cut, and verify frames and ASR transcripts. That media workflow ran outside the submitted runtime and is not counted in the model budget. The full history is public on GitHub.

Hackathon submission

The project targets the Thousand Token Wood main track, plus the OpenBMB, OpenAI/Codex, NVIDIA, and Modal sponsor awards and six bonus-quest badges:

• OpenBMB: MiniCPM5-1B is the central language model for both tool planning and quest classification.
• Off the Grid: every model runs from open weights on the Space's own GPU/CPU (or a local box); no third-party inference API is called at runtime.
• Well-Tuned: two MiniCPM5-1B PEFT LoRA adapters (advisor + quest classifier) are published on the Hub, and the training kit reproduces them.
• Off-Brand: a custom gradio.Server frontend with no default Gradio UI in the runtime path.
• Llama Champion: EmbeddingGemma GGUF vectors and every runtime query embedding run through llama.cpp.
• Sharing is Caring / Field Notes: Codex session traces are public; a build report on the quest-classifier fine-tune is at docs/quest-classification-lora.md, and the app exports session Field Notes.
• Tiny Titan: the largest model is about 1.08B, well under the 4B ceiling.
• Best Agent: each turn MiniCPM5 selects one tool; the engine then orchestrates the search → whitespace → score → plan chain over the live project field.
• NVIDIA / Modal: voice input uses Nemotron ASR; Modal trains the quest-classifier LoRA and offers a remote index-build path (the shipped index was built locally).

More prize evidence is in docs/submission-notes.md.

Run locally

Bash

python3.11 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
mkdir -p .cache/advisor-dashboard
ADVISOR_CACHE_DIR=.cache/advisor-dashboard \
ADVISOR_MODEL_BACKEND=minicpm-transformers \
ADVISOR_MODEL_ID=openbmb/MiniCPM5-1B \
ADVISOR_ADAPTER_ID=build-small-hackathon/hackathon-advisor-minicpm5-lora \
ADVISOR_ADAPTER_REVISION=25de69bcde397e1bcdd852923b56a42f10222650 \
ADVISOR_QUEST_ANALYZER_BACKEND=minicpm-transformers \
python app.py

Then open http://127.0.0.1:7860. The atlas refresh button uses the same artifact swap path locally as in deployment. To refresh the project snapshot:

Bash

python scripts/crawl_hf_spaces.py --org build-small-hackathon --out data/projects.json
python scripts/build_project_index.py --location modal --projects data/projects.json --out data/project_index.json

On macOS, the app automatically runs llama.cpp query embedding in a worker process so the MiniCPM PyTorch runtime and llama.cpp stay isolated from each other's OpenMP runtime.

Main API

Surface	Purpose
GET /api/dashboard	Atlas points, links, clusters, quest report, provenance, and refresh status
GET /api/dashboard/search?q=...	BM25 search over project, cluster, quest, README, and app-file text
POST /api/dashboard/chat	Atlas chat turn (NDJSON stream): base-model tool call, verified result + map action, grounded answer
POST /api/dashboard/refresh	Starts one background refresh job
POST /api/transcribe	Transcribes voice notes with NVIDIA NeMo and Nemotron ASR
GET /api/prize-ledger	Model stack, parameter budget, runtime status, and prize evidence
GET /api/demo-bundle.zip	Demo session, prize ledger, trace, notes, chapter, LoRA files, submission packet, and PNG
GET /api/lora-training-kit.zip	SFT data, recipe, adapter card, and training command

Links

• Hugging Face Space: build-small-hackathon/hackathon-advisor
• GitHub: JacobLinCool/hackathon-advisor
• Demo video: YouTube

Built by JacobLinCool.