README.md

metadata

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 · 🎬 Demo video · 🐦 Social post

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

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

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.

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:

python3 -m iris.cli --all

Run the seeded ideas with automated gate scores:

./scripts/validate_gate.py --all

Run a custom idea:

python3 -m iris.cli "A tool that helps new founders pick their first customer"

Run the UI

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

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.