README.md

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