| --- |
| title: Iris |
| emoji: 🧠 |
| colorFrom: red |
| colorTo: gray |
| sdk: docker |
| app_port: 7860 |
| pinned: false |
| license: mit |
| tags: |
| - track:wood |
| - sponsor:openbmb |
| - sponsor:openai |
| - achievement:offgrid |
| - achievement:offbrand |
| - achievement:llama |
| - minicpm |
| --- |
| |
| # Iris |
|
|
| **[▶ Live Space](https://huggingface.co/spaces/build-small-hackathon/iris-pressure-studio) · [🎬 Demo video](https://youtu.be/YTFo2cYE53k) · [🐦 Social post](https://x.com/khaledyusuf44/status/2066014978079932853)** |
|
|
| Iris is an ideation game for the Build Small Hackathon where the AI does not |
| think for you; it applies pressure that makes you think deeper. A fuzzy idea |
| enters a focused pressure studio, MiniCPM returns four sharp pressure cards, |
| and the user keeps sharpening the idea until it is ready to export as a concise |
| brief. |
|
|
| Status: local demo candidate. Day 2 is focused on turning the validated |
| pressure engine into a polished Gradio Space. Latest validation note: Iris UI |
| v2 preserves deep single-frame memory across many ideations while keeping the |
| MiniCPM model load-bearing. See |
| `docs/validation/day2-v2-deep-frame-memory.md`. |
|
|
| ## Current Status |
|
|
| - Repository initialized on `main`. |
| - Remote: `https://github.com/khaledyusuf44/iris.git`. |
| - Python validation engine: Day 1 gate passed. |
| - Gradio UI: Iris pressure studio flow passing local smoke; four-direction |
| pressure cards, repeat ideation, final brief export, and deep frame memory |
| are ready for Khalid review. |
| - Hugging Face Space path: Docker + llama.cpp + local MiniCPM GGUF, with no |
| external model API required at runtime. |
| - Project docs: see `docs/`. |
| - Hackathon build guidance: see `docs/BUILD_SMALL_FIELD_GUIDE.md`. |
|
|
| ## Repo Layout |
|
|
| ```text |
| AGENTS.md AI/core contributor operating notes |
| CONTRIBUTING.md Human contributor workflow |
| app.py Hugging Face Spaces / Gradio entrypoint |
| Dockerfile Self-contained Docker Space runtime |
| docs/ Project planning, roadmap, and architecture notes |
| docs/BUILD_SMALL_FIELD_GUIDE.md |
| Hackathon badge, demo, and submission guidance |
| docs/DEPLOY_HF_SPACE.md Docker Space deploy notes |
| docs/CODEX_LOG.md Codex work log and validation history |
| iris/ Python package for the constraint engine |
| scripts/check_repo.sh Lightweight repository health check |
| scripts/space_entrypoint.sh |
| Starts llama.cpp locally before Gradio in the Space |
| scripts/validate_gate.py Seed spiral run plus automated sharpness gate |
| stitch_iris_atomic_infinite_zoom/ |
| Earlier Google Stitch atomic UI export/reference |
| tests/ Tests, once added |
| ``` |
|
|
| Local task prompts and strategy notes should stay untracked. |
|
|
| ## Getting Started |
|
|
| ```bash |
| git clone https://github.com/khaledyusuf44/iris.git |
| cd iris |
| python3 -m venv .venv |
| source .venv/bin/activate |
| pip install -r requirements.txt |
| ./scripts/check_repo.sh |
| ``` |
|
|
| ## MiniCPM Endpoint Setup |
|
|
| Iris calls an OpenAI-compatible `/v1/chat/completions` endpoint. Keep real API |
| keys in your local environment only. |
|
|
| ```bash |
| ollama pull openbmb/minicpm4.1 |
| export IRIS_API_BASE_URL="http://localhost:11434/v1" |
| export IRIS_MODEL="openbmb/minicpm4.1" |
| export IRIS_API_KEY="not-needed" |
| export IRIS_ENABLE_THINKING=1 |
| ``` |
|
|
| For MLX, vLLM, SGLang, or hosted fallback, point `IRIS_API_BASE_URL` at that |
| server's OpenAI-compatible `/v1` endpoint and set `IRIS_MODEL` to the served |
| model name. |
|
|
| ## Validate the Spiral |
|
|
| Run the seeded Day 1 ideas: |
|
|
| ```bash |
| python3 -m iris.cli --all |
| ``` |
|
|
| Run the seeded ideas with automated gate scores: |
|
|
| ```bash |
| ./scripts/validate_gate.py --all |
| ``` |
|
|
| Run a custom idea: |
|
|
| ```bash |
| python3 -m iris.cli "A tool that helps new founders pick their first customer" |
| ``` |
|
|
| ## Run the UI |
|
|
| ```bash |
| python3 app.py |
| ``` |
|
|
| The Gradio UI calls the same Iris engine as the CLI and gate. Keep the MiniCPM |
| endpoint environment variables set before launching. |
|
|
| ## Run the Hugging Face Space Container |
|
|
| ```bash |
| docker build -t iris-space . |
| docker run --rm -p 7860:7860 iris-space |
| ``` |
|
|
| The container downloads a pinned prebuilt `llama-server`, bakes in a small |
| MiniCPM GGUF, points Iris at the local OpenAI-compatible endpoint, and serves |
| the Gradio app on port |
| `7860`. |
|
|
| ## Build Small Submission |
|
|
| ### What it is, how it's built |
|
|
| Iris is a thinking instrument: the AI never hands you an answer, it applies |
| **pressure**. You drop a fuzzy idea into a focused studio; a small MiniCPM model |
| returns four sharp, idea-specific pressure questions (Constraints, Limitations, |
| Capabilities, Reality Contact); you sharpen the idea and go again, ring by ring, |
| until you export a one-page brief. |
|
|
| - **Tech:** Python constraint engine wrapping an OpenAI-compatible |
| `/v1/chat/completions` endpoint; a custom HTML/CSS/JS "pressure studio" |
| frontend embedded in a Gradio Space (well past stock Gradio components); |
| MiniCPM as the load-bearing engine. Python only validates, formats, and |
| re-prompts — it never writes the pressure itself. |
| - **Runtime:** Hugging Face **Docker Space** that downloads a pinned prebuilt |
| `llama-server` (llama.cpp) and bakes a MiniCPM3-4B GGUF into the image, so |
| the whole app runs on the local model with **no cloud model API**. |
|
|
| ### Declared tags (parsed by the official submission tool) |
|
|
| - `track:wood` — Thousand Token Wood (a delightful, AI-native thinking game). |
| - `sponsor:openbmb` — MiniCPM is the core, load-bearing model. |
| - `sponsor:openai` — built with Codex; commits are Codex-attributed. |
| - `achievement:offgrid` — no cloud APIs; the model runs locally in the Space. |
| - `achievement:offbrand` — custom frontend beyond the default Gradio look. |
| - `achievement:llama` — the model is served through the llama.cpp runtime. |
|
|
| ### Also eligible (judged, not self-tagged) |
|
|
| - **Tiny Titan** (≤4B) — the Space runs MiniCPM3-4B. |
| - **Best Demo** — once the demo video + social post are in. |
| - **Bonus Quest Champion** — most bonus criteria met. |
|
|
| ### Submission links |
|
|
| - **Live Space:** https://huggingface.co/spaces/build-small-hackathon/iris-pressure-studio |
| - **Demo video:** https://youtu.be/YTFo2cYE53k |
| - **Social post:** https://x.com/khaledyusuf44/status/2066014978079932853 |
|
|
| ## Working Agreements |
|
|
| - Keep `main` clean and working. |
| - Add Python engine code under `iris/`. |
| - Add tests under `tests/`. |
| - Keep secrets out of Git. Use `.env.example` for documented configuration. |
| - Record substantive Codex work in `docs/CODEX_LOG.md`. |
| - Update `docs/ARCHITECTURE.md` when the project structure or runtime changes. |
|
|
| ## Next Inputs Needed |
|
|
| - Final badge/tag wording after Khalid confirms the submission strategy. |
|
|
