| --- |
| title: ContextForge |
| emoji: ⚒️ |
| colorFrom: blue |
| colorTo: green |
| sdk: gradio |
| sdk_version: 5.50.0 |
| app_file: app.py |
| pinned: true |
| --- |
| |
| # ContextForge / Agent Prompt Compiler |
|
|
| ContextForge compiles messy software, app, and agent ideas into executable prompt architectures. It is a compiler pipeline, not a generic prompt generator. |
|
|
| **GitHub:** https://github.com/rthgit/ContextForge |
|
|
| **Competition Gradio Space:** https://huggingface.co/spaces/build-small-hackathon/ContextForge |
|
|
| **Backup Gradio Space:** https://huggingface.co/spaces/RthItalia/ContextForge |
|
|
| **Demo video:** https://raw.githubusercontent.com/rthgit/ContextForge/main/artifacts/contextforge-demo.mp4 |
|
|
| **Tagline:** From fuzzy brief to build-ready agent blueprint. |
|
|
| ## Backyard AI Fit |
|
|
| - Built for real builders using AI coding agents. |
| - Real problem: vague briefs make Codex and other agents produce wrong code, generic UI, or incomplete workflows. |
| - Real use evidence: this architecture was used to coordinate Trollsona development, including UI refactor, model cascade, QA, packaging, and video automation. |
| - Small-model fit: ContextForge decomposes a hard prompt-writing task into seven smaller calls so a small model can handle it. |
|
|
| The backend always executes seven isolated modules sequentially: |
|
|
| 1. intake analysis |
| 2. topology decision |
| 3. Vital Few / Vital Spot extraction |
| 4. reasoning architecture selection |
| 5. prompt pack generation |
| 6. QA / repair |
| 7. final assembly |
|
|
| Every module attempts its own small-model call. If one call fails, only that stage uses a deterministic fallback and the pipeline continues. Runtime Details shows the source used by every stage. |
|
|
| Each module also has a bounded token budget appropriate to its contract. `CONTEXTFORGE_MAX_NEW_TOKENS` is the global ceiling, while stage budgets keep the seven-call CPU path practical. |
|
|
| ## Topologies |
|
|
| - Single Prompt |
| - Cascade |
| - Context Pack |
| - Agent Workflow |
|
|
| Auto topology uses Cascade when multiple expertise areas or dependent outputs are required. Agent Workflow is preferred for agentic or critical-risk work. Context Pack stabilizes incomplete briefs. |
|
|
| ## Safety |
|
|
| - Private reasoning remains internal. |
| - Generated prompts never request full chain of thought. |
| - Controlled Tree of Thought exposes only `strategy | upside | risk | cost | selected`. |
| - Public reasoning fields are limited to decision summary, assumptions, risks, verification steps, and final answer. |
| - QA repairs missing tags, contracts, verification, repair logic, and unsafe reasoning requests. |
|
|
| ## Runtime |
|
|
| Recommended Hugging Face Space variables: |
|
|
| ```text |
| CONTEXTFORGE_ENABLE_MODEL=1 |
| CONTEXTFORGE_MODEL_ID=Qwen/Qwen2.5-0.5B-Instruct |
| CONTEXTFORGE_MID_MODEL_ID=RthItalia/nano_compact_3b_qkvfp16 |
| CONTEXTFORGE_HIGH_MODEL_ID=Qwen/Qwen3-32B |
| CONTEXTFORGE_OPENBMB_ENABLE=0 |
| CONTEXTFORGE_OPENBMB_MODEL_ID=openbmb/MiniCPM5-1B |
| CONTEXTFORGE_OPENBMB_REASONING_MODEL_ID=openbmb/MiniCPM4.1-8B |
| CONTEXTFORGE_MAX_NEW_TOKENS=1800 |
| ``` |
|
|
| Runtime selection: |
|
|
| 1. high model only when CUDA is available |
| 2. compact mid model when CUDA is available |
| 3. Qwen 0.5B on public CPU Space |
| 4. deterministic stage-level fallback |
|
|
| ## OpenBMB / MiniCPM Mode |
|
|
| ContextForge can optionally run with OpenBMB MiniCPM models as the text reasoning engine for its staged compiler. |
|
|
| - [`openbmb/MiniCPM5-1B`](https://huggingface.co/openbmb/MiniCPM5-1B) is the preferred lightweight, local-first path. It is attempted first when OpenBMB mode is enabled. |
| - [`openbmb/MiniCPM4.1-8B`](https://huggingface.co/openbmb/MiniCPM4.1-8B) is an optional stronger reasoning path. ContextForge attempts it only when CUDA and sufficient memory are available. |
| - If a MiniCPM model is unavailable, incompatible, blank, too short, immediate-EOS, or gibberish, only that stage moves to the existing model cascade. |
| - If all model paths fail, that stage uses its deterministic fallback and the final output still assembles. |
|
|
| ContextForge is well suited to small models because it decomposes one hard prompt-engineering task into seven focused calls with explicit contracts. |
|
|
| The default Space runtime remains unchanged. For an OpenBMB-compatible local environment, install the optional dependency set: |
|
|
| ```powershell |
| pip install -r requirements-openbmb.txt |
| ``` |
|
|
| Then enable both OpenBMB and the existing fallback model path: |
|
|
| ```powershell |
| $env:CONTEXTFORGE_OPENBMB_ENABLE='1' |
| $env:CONTEXTFORGE_OPENBMB_MODEL_ID='openbmb/MiniCPM5-1B' |
| $env:CONTEXTFORGE_OPENBMB_REASONING_MODEL_ID='openbmb/MiniCPM4.1-8B' |
| $env:CONTEXTFORGE_ENABLE_MODEL='1' |
| python app.py |
| ``` |
|
|
| Runtime Details reports `stage`, `model attempted`, `source`, `fallback reason`, and `duration ms`. These details remain outside the main Prompt Pack. |
|
|
| For a fast local deterministic run: |
|
|
| ```powershell |
| $env:CONTEXTFORGE_ENABLE_MODEL='0' |
| python app.py |
| ``` |
|
|
| ## Local QA |
|
|
| ```powershell |
| python -m py_compile app.py |
| python test_contextforge.py |
| python app.py |
| ``` |
|
|
| The QA script verifies all four topologies, independent stage execution, required tags, chain-of-thought safety, controlled Tree of Thought output, and stage-level fallback continuity. |
|
|
| ## Demo Assets |
|
|
| - Demo video: `artifacts/contextforge-demo.mp4` |
| - Recording guide: `artifacts/VIDEO_RECORDING_GUIDE.md` |
| - Submission pack: `SUBMISSION.md` |
|
|
