Spaces:
Running
Running
| title: BranchForge | |
| emoji: 🌿 | |
| colorFrom: green | |
| colorTo: gray | |
| sdk: docker | |
| app_port: 7860 | |
| pinned: false | |
| # BranchForge | |
| **Don't trust the first patch. Prove the best one.** | |
| BranchForge is an evidence-first coding agent that explores several repairs from one exact | |
| repository state, executes each candidate in an isolated branch, and selects a patch from test | |
| evidence—not model confidence. | |
| Built for the **Coding and Agentic Engineering** track of the 2026 Nebius × NVIDIA Global AI | |
| Hackathon. | |
| ## Why it exists | |
| Most coding agents commit to the first plausible patch they generate. A fluent answer can still | |
| hide precision loss, weakened validation, or a fix that passes the happy path and breaks at the | |
| boundary. | |
| BranchForge makes alternative-search visible and empirical: | |
| 1. NVIDIA Nemotron generates three genuinely different repair hypotheses. | |
| 2. Nebius Sandboxes (ConTree) creates one reproducible base checkpoint. | |
| 3. The base state forks into three independent execution branches. | |
| 4. Every branch runs the same regression suite and emits a durable receipt. | |
| 5. Nemotron judges only the observed results, risks, and invariants. | |
| 6. A hard evidence floor prevents any failing patch from being selected. | |
| The result is a reviewable patch tournament rather than an opaque one-shot answer. | |
| ## The demo | |
| The included Ledger Lite incident reproduces a real class of money bug: Python's `round` uses | |
| ties-to-even, while the product policy requires half-up rounding in the customer's favor. | |
| Three branches compete under the same tests. A large-value regression above `2**53` exposes | |
| fixes that quietly detour through IEEE-754. The winning branch must preserve validation, pass all | |
| ten tests, and explain its invariant. | |
| ## Architecture | |
| ```mermaid | |
| flowchart LR | |
| UI[BranchForge workspace] --> API[FastAPI orchestrator] | |
| API --> N1[NVIDIA Nemotron\nstrategy pass] | |
| N1 --> B[Immutable ConTree checkpoint] | |
| B --> A[Branch A\npatch + tests] | |
| B --> C[Branch B\npatch + tests] | |
| B --> D[Branch C\npatch + tests] | |
| A --> E[Evidence packet] | |
| C --> E | |
| D --> E | |
| E --> N2[NVIDIA Nemotron\nevidence judge] | |
| N2 --> G[Verified winning diff] | |
| ``` | |
| ### NVIDIA Nemotron | |
| - Strategy model: `nvidia/Nemotron-3_5-Lightning` for fast, diverse patch generation | |
| - Evidence judge: a second constrained Nemotron 3.5 Lightning pass for a sub-second, | |
| schema-checked risk/evidence decision | |
| - Runtime: Nebius Token Factory's OpenAI-compatible inference API | |
| - Strategy pass: returns three structured full-file candidates with distinct theses and risks | |
| - Judge pass: receives compact observed evidence only; it cannot see or reward unsupported claims | |
| - Reliability: strict JSON extraction, candidate source validation, unique branch IDs, and a | |
| deterministic safety fallback when a provider is temporarily rate-limited | |
| ### Nebius Sandboxes / ConTree | |
| - `python:3.12-slim` becomes the base runtime. | |
| - Source and regression tests are written once to a non-disposable checkpoint. | |
| - All candidates call `base.run(...)` from that same parent state. | |
| - Branches execute concurrently and return stdout, stderr, exit code, duration, and checkpoint UUID. | |
| - The UI labels local development fallback honestly; production is configured to require Nebius. | |
| ## Run locally | |
| Requirements: Python 3.12+ and a Nebius Token Factory project. | |
| ```bash | |
| python -m venv .venv | |
| source .venv/bin/activate | |
| pip install -r requirements-dev.txt | |
| cp .env.example .env | |
| ``` | |
| Set these values in `.env` or your deployment secret manager: | |
| ```bash | |
| NEBIUS_API_KEY=... | |
| NEBIUS_PROJECT_ID=... | |
| LLM_BASE_URL=https://api.tokenfactory.nebius.com/v1 | |
| NEMOTRON_MODEL=nvidia/Nemotron-3_5-Lightning | |
| NEMOTRON_JUDGE_MODEL=nvidia/Nemotron-3_5-Lightning | |
| MODEL_TIMEOUT_SECONDS=35 | |
| SANDBOX_BACKEND=nebius | |
| ``` | |
| Then run: | |
| ```bash | |
| set -a; source .env; set +a | |
| python -m app.main | |
| ``` | |
| Open <http://localhost:7860>. | |
| ## Test and quality gates | |
| ```bash | |
| pytest -q | |
| ruff check . | |
| ``` | |
| The automated suite verifies API health, sample loading, JSON hardening, three-branch execution, | |
| the ten-regression fixture, and evidence-based winner selection. | |
| ## Deploy | |
| The repository includes a non-root, health-checked Docker image suitable for Hugging Face Docker | |
| Spaces or any OCI runtime: | |
| ```bash | |
| docker build -t branchforge . | |
| docker run --rm -p 7860:7860 \ | |
| -e NEBIUS_API_KEY \ | |
| -e NEBIUS_PROJECT_ID \ | |
| -e SANDBOX_BACKEND=nebius \ | |
| branchforge | |
| ``` | |
| Never expose the Nebius key to the browser. All inference and sandbox calls happen server-side. | |
| ## Trust and safety choices | |
| - Repository and issue text are explicitly treated as untrusted prompt data. | |
| - Candidate output is schema-checked and limited to the target source file. | |
| - No arbitrary shell text from the model is executed; files are base64-encoded by trusted code and | |
| the test command is fixed. | |
| - A model-selected branch with a non-zero test exit is rejected automatically. | |
| - Secrets are environment-only and excluded from the image and repository. | |
| - The development fallback is visible in the product receipt so demos cannot be mistaken for | |
| Nebius execution. | |
| ## Nebius and NVIDIA feedback | |
| What worked especially well: | |
| - Token Factory's OpenAI-compatible surface made the model layer easy to isolate and test. | |
| - Nemotron 3.5 Lightning's speed is well suited to parallel strategy generation. | |
| - ConTree's filesystem branching is a natural primitive for evidence-first coding agents; it avoids | |
| reinstalling dependencies for every hypothesis and gives every candidate a fair starting state. | |
| - Checkpoint UUIDs turn an ephemeral agent run into something reviewable and reproducible. | |
| What would make the workflow even stronger: | |
| - A first-class endpoint that returns execution CPU, peak memory, and wall-clock metrics in one | |
| stable schema would improve branch scoring. | |
| - Token Factory's structured-output docs could include a Nemotron-specific strict JSON example. | |
| - Project IDs should be copyable from the API-key screen because both inference and ConTree use the | |
| same project context. | |
| - A low-cost hackathon sandbox quota independent of inference billing would reduce onboarding | |
| friction for first-time builders. | |
| ## Hackathon provenance | |
| BranchForge was created from scratch during the hackathon submission period, beginning August 28, | |
| 2026. It does not reuse a pre-existing project. | |
| ## License | |
| [MIT](LICENSE) © 2026 Skyler Hoberman | |