README.md

metadata

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

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.

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:

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:

set -a; source .env; set +a
python -m app.main

Open http://localhost:7860.

Test and quality gates

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:

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 © 2026 Skyler Hoberman