An evidence-driven AI code repair agent that doesn't just suggest fixes — it executes tests and shows you what it fixed.
ProofLoop investigates Python bugs, generates code patches using Meta's Model API, executes tests inside an isolated Docker environment, and produces evidence-backed repair reports.
A repair is only marked Verified when the required execution evidence supports the result.
Don't just trust the fix. Prove it.
AI coding assistants can generate plausible code fixes, but generating a patch does not prove that a bug has been fixed.
Developers still need to:
- Reproduce the original failure.
- Understand the affected code.
- Apply and inspect a patch.
- Run regression tests.
- Confirm that the original failure is resolved.
- Review evidence before trusting the result.
ProofLoop brings these steps together in a controlled, evidence-driven repair workflow.
- Accepts a bug report — Submit a bug description or upload a Python repository.
- Analyzes the repository — Examines available source files and test context.
- Investigates the issue — Uses Meta's Model API to help identify the cause and propose a fix.
- Reproduces the failure — Executes baseline tests before applying the patch.
- Applies the patch — Modifies the relevant source code in the isolated workspace.
- Runs regression tests — Executes tests again after the patch.
- Collects evidence — Records execution results, patch information, and integrity information.
- Reports the outcome — Presents the repair status and supporting evidence.
- AI-assisted bug investigation using Meta's Model API.
- Repository ZIP uploads for analyzing Python projects.
- Automated patch generation based on bug reports and repository context.
- Baseline failure reproduction before patch application.
- Docker-based test execution with isolation and resource restrictions.
- Post-patch regression testing to evaluate proposed fixes.
- Evidence-backed repair reports with execution and patch information.
- Repair history for reviewing previous jobs.
- Repair Assistant for asking questions about completed repairs and their evidence.
| Principle | Description |
|---|---|
| Evidence before verification | A generated patch alone is never sufficient to mark a repair verified. |
| Reproducibility | The original failure should be reproduced before claiming it was fixed. |
| Isolation | Repository code is executed inside a restricted Docker environment. |
| Traceability | Repair reports retain execution results and patch information. |
| Integrity | Reports undergo integrity validation. |
| Honest verification | Verification is limited to the evidence and tests actually executed. |
flowchart TD
U[Developer] --> FE[Next.js Frontend]
FE --> API[FastAPI Backend]
API --> RS[Repair Services]
RS --> RA[Repository Analysis]
RS --> RE[Repair Engine]
RE --> META[Meta Model API]
RE --> WS[Workspace Service]
WS --> DOCKER[Docker Sandbox]
DOCKER --> BASE[Baseline Tests]
DOCKER --> PATCH[Patch Application]
DOCKER --> REG[Post-Patch Tests]
BASE --> EV[Evidence Collection]
PATCH --> EV
REG --> EV
EV --> REPORT[Repair Report]
REPORT --> API
API --> FE
- Frontend: Provides the repair workspace, repository upload, repair sessions, history, evidence views, and Repair Assistant.
- Backend API: Handles requests, validation, job management, and report retrieval.
- Repository Analysis: Examines uploaded repository source and test files.
- Repair Engine: Coordinates investigation, patch generation, execution, and evidence collection.
- Meta Model API: Supports AI-assisted investigation and patch generation.
- Docker Sandbox: Executes baseline and post-patch tests in a restricted environment.
- Evidence and Reporting: Collects execution information and determines the resulting repair status.
| Layer | Technology |
|---|---|
| Frontend | Next.js, React, TypeScript |
| Styling | Tailwind CSS |
| Backend | Python, FastAPI |
| AI Integration | Meta Model API |
| Execution Isolation | Docker |
| Testing | Pytest |
| API Communication | REST |
| Data Validation | Pydantic |
proofLoop/
├── backend/
│ ├── app/
│ │ ├── agent/
│ │ ├── schemas/
│ │ ├── services/
│ │ └── main.py
│ ├── sandbox/
│ │ └── Dockerfile
│ ├── scripts/
│ │ └── setup_sandbox.py
│ ├── tests/
│ └── requirements.txt
│
├── frontend/
│ ├── src/
│ │ ├── app/
│ │ ├── components/
│ │ └── lib/
│ └── package.json
│
├── demo-projects/
│ ├── 01-discount-calculator/
│ ├── 02-username-normalizer/
│ ├── 03-pagination/
│ └── 04-password-validator/
│
├── docs/
│ ├── architecture.md
│ └── repair-lifecycle.md
│
├── fixtures/
├── artifacts/
├── .env.example
├── README.md
└── LICENSE
You can run ProofLoop locally without depending on the hosted application.
The local installation uses:
- Your own Meta Model API key.
- A locally running FastAPI backend.
- A locally running Next.js frontend.
- Docker for isolated test execution.
No local demo access code, invitation, or workspace activation is required.
Install the following before proceeding:
| Requirement | Purpose |
|---|---|
| Python 3.11 or later | Backend runtime |
| Node.js and npm | Frontend runtime |
| Docker Desktop or Docker Engine | Isolated repair execution |
| Git | Repository cloning |
| Meta Model API key | AI-assisted investigation and patch generation |
Make sure Docker Desktop or Docker Engine is installed and running before executing repair workflows.
git clone https://github.com/WizKnight/proofLoop.git
cd proofLoopCreate a Python virtual environment from the repository root.
python -m venv .venv
.\.venv\Scripts\Activate.ps1If PowerShell prevents activation, you can use:
.\.venv\Scripts\activate.batpython3 -m venv .venv
source .venv/bin/activateFrom the repository root:
python -m pip install --upgrade pip
pip install -r backend/requirements.txtCreate your local environment file.
Windows PowerShell:
Copy-Item .env.example .envLinux / macOS:
cp .env.example .envOpen the root .env file and configure your Meta API credentials.
MODEL_API_KEY=your_meta_api_key
MODEL_NAME=muse-spark-1.3
MODEL_API_BASE_URL=https://api.meta.ai/v1
MODEL_API_TIMEOUT_SECONDS=60
PROOFLOOP_AUTH_ENABLED=falseReplace your_meta_api_key with your own Meta Model API key.
The local authentication setting disables the backend demo-token requirement for local development.
| Variable | Description |
|---|---|
MODEL_API_KEY |
Your Meta Model API key. |
MODEL_NAME |
Model identifier used by ProofLoop. |
MODEL_API_BASE_URL |
Meta Model API endpoint. |
MODEL_API_TIMEOUT_SECONDS |
API request timeout. |
PROOFLOOP_AUTH_ENABLED |
Enables or disables the backend demo-token authentication middleware. Set to false for the documented local development workflow. |
Security: Keep .env private. Never commit API keys or production credentials to GitHub.
ProofLoop uses a dedicated Docker image to execute tests inside its isolated repair environment.
A setup script is included to check Docker, build the sandbox image when it is missing, and run a smoke test.
From the repository root, execute:
python backend/scripts/setup_sandbox.pyThe setup script:
- Checks whether the Docker CLI is installed.
- Checks whether the Docker daemon is running.
- Checks whether the
proofloop-sandbox:localimage already exists. - Builds the image if it is missing.
- Runs a sandbox smoke test.
- Confirms that the sandbox can access its mounted workspace and runs as a non-root user.
A successful setup should finish with:
Sandbox smoke test passed
ProofLoop Docker sandbox is ready.
If the image already exists and passes the smoke test, it is reused instead of being rebuilt.
The Docker image is defined in:
backend/sandbox/Dockerfile
The sandbox:
- Uses Python 3.12 slim.
- Installs pytest 9.2.0.
- Disables automatic third-party pytest plugin loading.
- Uses
/workspaceas its working directory. - Runs test execution as an unprivileged user (
65534:65534).
The repair execution workflow applies additional restrictions, including:
- Disabled network access.
- Read-only container filesystem.
- Read-only workspace mount.
- Dropped Linux capabilities.
- No-new-privileges security option.
- Process, memory, and CPU limits.
- Restricted temporary filesystem.
Important: Docker must remain running while ProofLoop executes repairs.
From the repository root, with your virtual environment activated:
python -m uvicorn backend.app.main:app --reload --host 127.0.0.1 --port 8000 --env-file .envThe backend will be available at:
http://127.0.0.1:8000
Open:
http://127.0.0.1:8000/health
Expected response:
{
"status": "ok"
}FastAPI provides interactive API documentation at:
http://127.0.0.1:8000/docs
Keep the backend terminal running while using the application.
Open another terminal and navigate to the frontend directory:
cd frontendInstall dependencies:
npm installCreate frontend/.env.local with the local backend URL:
NEXT_PUBLIC_API_URL=http://127.0.0.1:8000Important: Use the local backend URL above for local development. Do not point the frontend to the hosted backend when testing your local installation.
Start the frontend:
npm run devOpen:
http://localhost:3000
You can now use your local ProofLoop workspace directly.
From the repository root, with the Python virtual environment activated:
python -m pytest backend/tests -vUse the repair workspace to submit a bug report against a built-in controlled demonstration fixture.
A typical workflow:
- Open the ProofLoop workspace.
- Select the bug report workflow.
- Describe the issue and expected behavior.
- Submit the repair request.
- Follow the repair job.
- Review the generated patch and execution evidence.
- Inspect the final repair status.
ProofLoop schedules the repair workflow and returns a job ID that can be used to retrieve the execution result.
You can upload a ZIP archive of a Python repository for investigation and repair.
- Prepare a ZIP archive of your Python repository.
- Open the ProofLoop repair workspace.
- Upload the repository.
- Provide a clear bug description.
- Specify the expected failing test identifier.
- Submit the repair request.
- Review the repair execution and evidence.
- Inspect the generated patch and final status.
Repository uploads are subject to a 25 MiB archive size limit. The uploaded project must contain discoverable Python source files and pytest test files.
ProofLoop includes four intentionally buggy Python projects for demonstrating different classes of defects.
| Demo | Bug category | Intended behavior |
|---|---|---|
| Discount Calculator | Business logic | Correctly handles a 100% discount. |
| Username Normalizer | String processing | Removes leading and trailing whitespace. |
| Pagination | Off-by-one error | Returns the correct items for each page. |
| Password Validator | Boundary condition | Accepts passwords at the minimum permitted length. |
Each project contains its own source code, tests, README, and dependencies.
The projects are intentionally designed to fail before repair. They can be uploaded individually through the repository ZIP workflow.
ProofLoop exposes REST endpoints through its FastAPI backend.
For local development, the backend authentication middleware is disabled through:
PROOFLOOP_AUTH_ENABLED=falseThe following endpoints are available:
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /health |
Check backend health. |
| POST | /api/v1/repairs |
Submit a built-in fixture repair request. |
| POST | /api/v1/repairs/repository |
Upload a repository for repair. |
| GET | /api/v1/repairs/{job_id} |
Retrieve repair job details and report. |
| GET | /api/v1/repairs?limit=20 |
Retrieve repair history. |
| POST | /api/v1/repairs/{job_id}/conversation |
Ask the Repair Assistant about a completed repair. |
| GET | /api/v1/repairs/{job_id}/conversation |
Retrieve repair conversation history. |
POST /api/v1/repairs
Content-Type: application/jsonExample request:
{
"bug_report": "Describe the bug and expected behavior."
}POST /api/v1/repairs/repository
Content-Type: multipart/form-dataThe request accepts:
repository— Python repository ZIP archive.bug_report— Description of the reported issue.expected_failure— Expected failing pytest identifier.
GET /api/v1/repairs/{job_id}POST /api/v1/repairs/{job_id}/conversation
Content-Type: application/jsonThe conversation feature is available after the repair job completes and uses the saved repair report as context.
For detailed request and response schemas, refer to the API documentation available at /docs when the backend is running.
ProofLoop also provides a hosted demonstration environment.
Frontend: https://proofloop-xi.vercel.app/
The hosted application connects to its deployed backend. Its access configuration is managed separately from the local development setup.
The hosted demo is intended for reviewers who want to explore ProofLoop without installing the project locally.
| Local setup | Hosted demo | |
|---|---|---|
| Frontend | localhost:3000 |
Vercel |
| Backend | 127.0.0.1:8000 |
Deployed backend |
| Meta API key | Supplied by user | Configured on backend |
| Authentication | Disabled for the documented local workflow | Managed separately by the hosted deployment |
| Docker | Required locally | Configured on backend |
| Installation | Required | Not required |
Local environment configuration does not change the hosted deployment's authentication or API configuration.
ProofLoop distinguishes between generating a patch and verifying a repair.
The expected successful verification sequence is:
- The baseline failure is reproduced.
- The proposed source modification is applied.
- Post-patch regression tests pass.
- Required execution evidence is collected.
- The report passes integrity validation.
A repair is only marked verified when the required evidence supports the outcome.
A passing test suite is evidence for the tests that were actually executed. It is not a universal guarantee that every possible bug has been eliminated.
Uploaded repository code is treated as untrusted input.
ProofLoop uses a Docker-based execution environment with restrictions designed to limit execution risks, including network access and resource consumption.
Important considerations:
- Do not upload credentials or secrets.
- Review the sandbox configuration before using untrusted repositories.
- Treat generated patches as proposals that require review.
- Do not interpret a verified repair as a guarantee of production security.
- Keep your Meta API key private.
- Do not expose a locally running backend directly to untrusted public traffic without appropriate access controls.
The sandbox is a security boundary that should be independently reviewed and tested before exposing the application to untrusted public traffic.
Check whether Docker is installed:
docker --versionIf the command is unavailable:
- Install Docker Desktop on Windows or macOS.
- Install Docker Engine and the Docker CLI on Linux.
- Restart your terminal after installation.
Check Docker:
docker infoIf the daemon is unavailable, start Docker Desktop or the Docker Engine service and try again.
Run the setup script from the repository root:
python backend/scripts/setup_sandbox.pyYou can also inspect the image manually:
docker image inspect proofloop-sandbox:localCheck the following:
- Docker is installed and running.
- Your current user can communicate with the Docker daemon.
- The Dockerfile exists at
backend/sandbox/Dockerfile. - Docker has sufficient resources to build and run containers.
Run the setup script again after resolving the issue.
Check that:
- The backend is running on port
8000. - The frontend
.env.localcontains:
NEXT_PUBLIC_API_URL=http://127.0.0.1:8000- You restarted the frontend after changing its environment configuration.
- The browser is accessing the correct local frontend URL.
Check that:
MODEL_API_KEYis valid.MODEL_NAMEis configured correctly.MODEL_API_BASE_URLis correct.- Your Meta API account has the required access and available API credits.
- The configured timeout is sufficient for the request.
Restart the backend after changing .env.
Check that:
- Docker is running.
- The
proofloop-sandbox:localimage exists. - The sandbox setup script completes successfully.
- The backend terminal logs do not report an underlying execution error.
- The selected test target exists in the uploaded repository.
Make sure:
- The root
.envfile exists. - You started the backend from the repository root.
- You used the documented
--env-file .envoption. - The environment variable names and values are correct.
Restart the backend after modifying .env.
Additional project documentation:
ProofLoop currently focuses on Python bug investigation and repair.
The MVP includes:
- Bug report submission.
- Python repository ZIP upload.
- Repository analysis.
- AI-assisted patch generation.
- Baseline failure reproduction.
- Docker-based execution.
- Post-patch regression testing.
- Evidence-backed repair reports.
- Repair session tracking and history.
- Repair Assistant with persistent conversation history.
Verification remains bounded by the repository context, tests, and execution environment available to the repair workflow.
Potential areas for future development include:
- Support for additional programming languages.
- Automated regression test generation.
- More advanced repository-level debugging.
- Pull request integration.
- CI/CD integration.
- Stronger independent patch validation.
- Expanded security and execution controls.
These are future possibilities, not claims about existing functionality.
Built for the Meta Global AI Developer Hackathon 2026.
ProofLoop explores a simple principle:
A coding agent should not just tell you what it fixed. It should show you the evidence.
Copyright 2026 Swapnil Jikar.
Licensed under the Apache License, Version 2.0. See LICENSE for details.
You may obtain a copy of the License at:
https://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under this License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.