README.md

---
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`