Metadata-Version: 2.4
Name: specfix
Version: 0.1.7
Summary: Speculative Sandbox Framework Using State-Graph Rollback Checkpoints for Automated Code Repair
License-Expression: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: gitpython>=3.1.40
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: ruff>=0.16.0
Requires-Dist: pytest>=7.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-timeout>=2.2; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Dynamic: license-file

# SpecFix — Speculative Sandbox Framework Using State-Graph Rollback Checkpoints for Automated Code Repair

<div align="center">

![Version](https://img.shields.io/badge/version-0.1.7-cyan.svg)
![Python](https://img.shields.io/badge/python-3.11+-blue.svg)
![Tests](https://img.shields.io/badge/tests-348%20passed-emerald.svg)
[![License](https://img.shields.io/badge/license-MIT-purple.svg)](LICENSE)
[![Dashboard](https://img.shields.io/badge/UI-Bundled%20Web%20Dashboard-orange.svg)](src/specfix/dashboard_dist/)

**Autonomous AI Bug Repair with a 0% Production Regression Guarantee.**  
*Every proposed patch is executed inside an isolated speculative sandbox and verified against test suites before committing. Failed patches trigger automatic Git rollbacks and feed detailed error diagnostics back into subsequent AI retry attempts.*

</div>

---

## 📌 Executive Overview

Software engineering teams spend 30–50% of their time on manual bug triage and repair. While modern Large Language Models (LLMs) can generate code fixes, applying AI-generated patches directly to software repositories introduces significant risk: hallucinated code, broken syntax, or unexpected side-effects can corrupt production codebases.

**SpecFix** eliminates this risk through a **Speculative Sandbox Framework**:

1. **Speculative Execution**: No AI patch is ever committed directly. Every fix is treated as an unverified speculation.
2. **Git Rollback Checkpoints**: Before applying a patch, SpecFix tags an atomic rollback checkpoint (`git tag`). If verification fails, the repository is instantly reset (`git reset --hard` & `git clean -fdx`).
3. **Polyglot Automated Test & Strategy Discovery**: Automatically discovers whether a project uses `pytest`, `unittest`, built-in `specfix-runner`, `mvn test` (Maven), `gradle test` (Gradle), `npm test`, or runs as a standalone executable script (`Main.java`, `app.py`, `main.py`, `app.js`), executing tests in an isolated disposable sandbox.
4. **Zero-Dependency Built-in Test Runner**: Includes a standalone, zero-dependency Python test runner (`specfix.test_runner`) with per-test timeout protection against thread deadlocks and infinite loops—no external packages required.
5. **Self-Correction Retry Loop**: Test failure outputs, compiler diagnostics (`javac`, `gcc`), and runtime tracebacks (`stderr`) are captured deterministically and injected into retry prompts, enabling AI models to self-correct on subsequent attempts.
6. **State-Graph Audit DAG**: Every attempt—successful or failed—is stored as an immutable node in a SQLite-backed Directed Acyclic Graph (DAG), providing full operational auditability.
7. **Dynamic Tiered Model Routing & Cascade**:
   - **Tier 1 (SIMPLE)**: Ultra-fast reasoning via Groq (`openai/gpt-oss-20b`, `openai/gpt-oss-120b`) cascading to Google Gemini (`gemini-3.5-flash-lite`, `gemini-3.1-flash-lite`).
   - **Tier 2 (COMPLEX / MEDIUM)**: High-capacity multi-file and concurrency reasoning via Google Gemini (`gemini-3.8-flash`, `gemini-3.7-flash`, `gemini-3.6-flash`) cascading to Groq (`openai/gpt-oss-120b`).
8. **Real-time Multithreaded Web Dashboard**: Built on `ThreadingHTTPServer` with a live 7-stage execution pipeline, real-time Git status tracking, and a clean "Quit Web" shutdown control.
9. **Interactive Review & Commit Guard**: In the Web Dashboard or terminal, verified patches are presented for manual inspection before committing, giving developers complete control over repository changes.
10. **Evidence-Grounded Patch Explanation & Selection Rationale**: Rather than asking an LLM to hallucinate self-justifications, SpecFix grounds patch explanations directly in concrete AST diff analysis and deterministic sandbox test execution outcomes. Breaks down Root Cause, What Changed, Why It Fixes the Bug, Verification Evidence, Selection Rationale, and Confidence Levels (🟢 HIGH / 🟡 MEDIUM / 🔴 LOW).

---

## 🏗️ System Architecture Pipeline

<div align="center">

![SpecFix Architecture Pipeline](pipeline.png)

</div>

---

## ✨ Key Features

- 🛡️ **Zero-Commit Guarantee**: Zero unverified or broken code ever reaches tracked Git branches.
- 🔄 **Automatic Rollback & Recovery**: Instant `git reset --hard` and `git clean -fdx` restores pristine repository state whenever tests fail.
- 🎯 **YAGNI Prompt Discipline**: Restricts AI models to generate surgical, minimal unified diffs without introducing unnecessary refactoring or extraneous dependencies.
- 🌐 **Polyglot Multi-Language Support**: Supports Python, Java (Maven / Gradle / standalone `javac`), JavaScript / TypeScript (npm / Node), C/C++, C#, Go, and Rust.
- 🔍 **Automated Validation Strategy Discovery**: Deterministically detects `pytest`, `unittest`, built-in `specfix-runner`, `mvn test`, `gradle test`, `npm test`, or standalone executable scripts (`Main.java`, `app.py`, `main.py`, `app.js`).
- ⏱️ **Zero-Dependency Built-in Test Runner**: Built-in runner supporting `unittest` and bare `def test_*()` functions with automatic 10s per-test deadlock protection.
- 🩹 **Robust Diff Normalization**: Resiliently handles variations in AI patch generation, including missing line counts, bare `@@` hunk headers, and trailing commentary.
- 🧹 **Zero-Cost Static Analysis**: Deterministically identifies undefined variables and syntax issues via a zero-cost linter pre-pass before calling LLMs.
- 🧠 **Deterministic Complexity Analyzer**: Scores bugs by call-stack depth, multi-file references, and concurrency keywords to select optimal model tiers.
- ⚡ **Dual-Engine Priority Cascade**:
  - **Tier 1 (Fast Reasoning SLM)**: Groq API (`openai/gpt-oss-20b`, `openai/gpt-oss-120b`) cascading to Google Gemini (`gemini-3.5-flash-lite`, `gemini-3.1-flash-lite`) for rapid, low-latency reasoning and surgical fixes.
  - **Tier 2 (Deep Reasoning LLM)**: Google Gemini (`gemini-3.8-flash`, `gemini-3.7-flash`, `gemini-3.6-flash`) cascading to Groq (`openai/gpt-oss-120b`) for multi-file context and concurrency repairs.
- 📊 **SQLite State-Graph Audit DAG**: Comprehensive attempt tracing with parent-child retry trees, test stdout/stderr captures, timestamps, and model attribution.
- 💻 **Built-in Zero-Config Web Dashboard**: Modern dark-mode React application packaged directly inside the Python distribution. Run `specfix web` to launch instantly.
- 🚦 **Real-Time Dynamic Stepper**: Multithreaded API server updates the 7-stage repair pipeline live without blocking.
- 🔌 **Graceful Web & Terminal Exit**: Clean "Quit Web" shutdown button in the dashboard, plus instant `Ctrl+C` interrupt handling in terminal mode.
- 🛡️ **Interactive Review & Commit Guard**: Preview color-coded unified diffs directly in your browser or terminal with one-click commit or discard.

---

## ⚡ Quick Start

### Prerequisites & System Requirements

Before using SpecFix, verify that your environment meets these straightforward requirements:

| Component | Requirement | Purpose / Verification |
| :--- | :--- | :--- |
| **Python** | `3.11` or higher | Core runtime. Verify with `python --version` (3.11, 3.12, 3.13 supported). |
| **Git CLI** | Installed & in `PATH` | Required for atomic rollback checkpoints (`git tag`, `git reset --hard`). Verify with `git --version` (get it from [git-scm.com](https://git-scm.com)). |
| **Target Repo** | Initialized Git repository | The project folder being repaired must have Git initialized with at least one commit (`git init && git add . && git commit -m "initial"`). |
| **API Keys** | Groq & Gemini keys | Required for AI patch generation: <br>• **`GROQ_API_KEY`** (free at [console.groq.com](https://console.groq.com))<br>• **`GEMINI_API_KEY`** (free at [aistudio.google.com](https://aistudio.google.com)) |

> [!NOTE]
> **No Node.js or npm Required**: The Web Dashboard is fully pre-compiled and bundled directly inside the Python distribution. You do **not** need Node.js, npm, or frontend build tools installed. All dependencies (`gitpython`, `ruff`, `pytest`, `python-dotenv`) are installed automatically by `pip`.

### 1. Installation

#### Install from TestPyPI (Latest Release):

```bash
pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple specfix==0.1.7
```

#### Or Install from PyPI:

```bash
pip install specfix
```

#### For Local Development:

```bash
# Clone repository
git clone https://github.com/Siddharth2027/SpecFix.git
cd SpecFix

# Create & activate virtual environment
python -m venv .venv
.\.venv\Scripts\activate   # Windows PowerShell
# source .venv/bin/activate  # Linux / macOS

# Install package in editable mode with dev dependencies
pip install -e ".[dev]"
```

### 2. Verify Installation

Run the complete test suite to confirm everything is configured properly (all 348 tests pass without requiring API keys):

```bash
pytest
```

---

## 🗝️ Model Provider Configuration

SpecFix supports automated repair using a **Dual-Engine Priority Cascade Architecture** across **Groq** (Fast Reasoning LPUs) and **Google Gemini** (Deep Cloud Reasoning):

| Tier | Complexity | Cascade Priority Order | Target Repair Scope |
|:---:|:---:|:---|:---|
| **Tier 1** | **`SIMPLE`** (Score $\le 2$) | 1. Groq (`openai/gpt-oss-20b`)<br>2. Groq (`openai/gpt-oss-120b`)<br>3. Gemini (`gemini-3.5-flash-lite`)<br>4. Gemini (`gemini-3.1-flash-lite`) | Localized logic errors, single-function fixes, off-by-one errors |
| **Tier 2** | **`COMPLEX`** (Score $\ge 3$) | 1. Gemini (`gemini-3.8-flash`)<br>2. Gemini (`gemini-3.7-flash`)<br>3. Gemini (`gemini-3.6-flash`)<br>4. Groq (`openai/gpt-oss-120b`) | Thread deadlocks, race conditions, async queues, cross-file context |

You can configure your credentials using any of these methods:

1. **In-Dashboard Settings**: Click the key icon in the Web Dashboard to enter your keys. Click **"Test Connection"** to verify live connectivity. Keys are saved locally to `~/.specfix/config.json`.
2. **Interactive CLI Wizard**: Running `specfix` in your terminal prompts for missing API keys automatically.
3. **Environment Variables**:
   - `GROQ_API_KEY`: Groq API key (**compulsory**).
   - `GEMINI_API_KEY`: Google Gemini API key (**compulsory**).

#### Setting Environment Variables:

**Windows PowerShell:**

```powershell
$env:GROQ_API_KEY="gsk_your-groq-key-here"
$env:GEMINI_API_KEY="AIzaSy-your-gemini-key-here"
```

**Linux / macOS Bash:**

```bash
export GROQ_API_KEY="gsk_your-groq-key-here"
export GEMINI_API_KEY="AIzaSy-your-gemini-key-here"
```

---

## 🚀 Running SpecFix

### 1. Built-in Web Dashboard (`specfix web`)

The easiest and most powerful way to use SpecFix is through its built-in Web Dashboard:

```bash
cd /path/to/your/project

specfix web
```

SpecFix will start the local server and automatically open `http://127.0.0.1:8000` in your browser.

#### Web Dashboard Highlights:

- 🛠️ **Workspace & Live Repair**: Browse project files in the integrated file explorer, type a natural-language description of the issue, and click **"Synthesize fix"**.
- 🚦 **Real-Time Dynamic Stepper**: Powered by `ThreadingHTTPServer`, the 7-stage execution pipeline animates live as SpecFix creates checkpoints, localizes code, scores complexity, routes to Tier 1/2, and tests in the sandbox.
- 🌳 **Real-Time Git Status Tracking**: Automatically tracks branch name, commit SHA, dirty/clean status, and modified file count every 4 seconds and upon window focus.
- 🔍 **Interactive Code & Diff Viewer**: Inspect color-coded unified diffs with live line addition/deletion statistics and execution times.
- 🛡️ **Review & Commit Guard**: Sandboxed patches are verified with exit code 0. Click **"Commit Patch to Git"** to stage and commit, or **"Discard"** to cleanly roll back.
- 🔌 **Graceful Quit Web**: Click **"Quit Web"** in the top navigation bar to stop the server cleanly from the browser with zero socket disconnect tracebacks in the terminal.
- 📊 **State-Graph Audit DAG**: Inspect all past repair attempts with human-readable titles, parent-child retry relationships, and raw test logs.

---

### 2. User Interactive CLI Repair (`specfix repair`)

Run repairs directly from your terminal with vibrant VT100/ANSI styling, box-aligned formatting, and standard `[y/n]: ` prompts:

```bash
cd /path/to/your/project

specfix repair
```

Or provide the issue description non-interactively:

```bash
specfix repair --problem "divide() crashes on zero divisor. Fix divide() in calculator.py so zero divisor raises ValueError('Cannot divide by zero')" -y
```

#### CLI Options:

- `--repo PATH`: Path to target repository directory (default: current working directory `.`).
- `--problem TEXT`: Problem description string.
- `--db PATH`: Path to SQLite audit database (default: `specfix.db`).
- `--retries N`: Maximum repair retry attempts (default: `3`).
- `-y, --yes`: Non-interactive mode; automatically commit verified patches without prompting.
- `--clear-keys`: Remove all saved API keys from `~/.specfix/config.json`.

---

### 3. Developer Benchmark Evaluation (`specfix run`)

To evaluate automated repair against a benchmark bug fixture:

```bash
specfix run --bug path/to/bug_report.json --repo path/to/clean_target_repo
```

To run the full evaluation corpus:

```bash
python -m tests.evaluation.run_evaluation
```

---

## 🧪 Empirical Evaluation Benchmark

SpecFix includes an evaluation harness testing 4 representative bug categories:

| Benchmark Bug Category             | Class  | Primary Provider       | Success Rate          | Attempt Recovery                          |
| ---------------------------------- | ------ | ---------------------- | --------------------- | ----------------------------------------- |
| **Arithmetic / Logic**       | SIMPLE | Tier 1 (Groq / Gemini) | **100% (PASS)** | Attempt 1/5                               |
| **Boundary / Off-by-One**    | SIMPLE | Tier 1 (Groq / Gemini) | **100% (PASS)** | Attempt 1/5                               |
| **Data / Collection Logic**  | SIMPLE | Tier 1 (Groq / Gemini) | **100% (PASS)** | Attempt 1/5                               |
| **Error-Handling Exception** | SIMPLE | Tier 1 (Groq / Gemini) | **100% (PASS)** | Attempt 2/5 *(Self-Corrected via Retry)* |

---

## 📂 Project Structure

```
SpecFix/
├── pyproject.toml              # Package configuration, dependencies & CLI entrypoint (v0.1.7)
├── README.md                   # Comprehensive project documentation
├── PROJECT_PLAN.md             # Architectural specification & roadmap
├── dashboard/                  # React + TypeScript + Vite + Tailwind CSS Web Dashboard
│   ├── src/                    # UI Components (Workbench, LivePipelineStepper, StateGraphDAG, Header)
│   ├── package.json            # Frontend dependencies
│   └── vite.config.ts          # Vite production build configuration
├── src/
│   └── specfix/
│       ├── __init__.py         # Package initialization (v0.1.7)
│       ├── __main__.py         # CLI entry point, ANSI formatter & repair orchestrator
│       ├── server.py           # Multithreaded REST API server (ThreadingHTTPServer)
│       ├── dashboard_dist/     # Bundled compiled React production distribution
│       ├── test_runner.py      # Zero-dependency built-in test runner with deadlock protection
│       ├── config_store.py     # Local credentials store (~/.specfix/config.json)
│       ├── explanation.py      # Evidence-grounded patch explanation & rationale generator
│       ├── test_discovery.py   # Polyglot test runner & standalone script discoverer
│       ├── localization.py     # Multi-signal source code localizer (Python, Java, JS, etc.)
│       ├── static_analysis.py  # Zero-cost linter pre-pass (ruff)
│       ├── traceback_parser.py # Compiler & runtime stack-trace parser
│       ├── intake.py           # Bug report intake & Git repo state validation
│       ├── yagni.py            # YAGNI prompt discipline & unified diff validator/normalizer
│       ├── complexity.py       # Deterministic heuristic complexity analyzer
│       ├── router.py           # Multi-cloud cascade router (Tier 1 vs Tier 2)
│       ├── checkpoint.py       # Git rollback tag creation, reset & commit manager
│       ├── sandbox.py          # Isolated patch execution & process-tree timeout protection
│       ├── verifier.py         # VerificationResult dataclass & test runner output parser
│       ├── state_graph.py      # SQLite-backed attempt DAG audit database
│       ├── config.py           # Typed configuration thresholds & system defaults
│       └── llm/
│           ├── base.py         # Abstract ModelProvider interface & diff extractor
│           ├── groq.py         # Groq API Provider (Tier 1 Reasoning SLM)
│           ├── gemini.py       # Google Gemini API Provider (Tier 2 Cloud LLM)
│           └── mock.py         # Deterministic mock provider for offline testing
├── tests/                      # Comprehensive test suite (348 unit & integration tests)
│   ├── test_checkpoint.py     # Git checkpoint creation & rollback tests
│   ├── test_complexity.py     # Complexity analyzer scoring tests
│   ├── test_discovery.py      # Polyglot test framework & standalone script discovery tests
│   ├── test_evaluation.py     # Evaluation corpus & benchmark runner tests
│   ├── test_explanation.py    # Evidence-grounded explanation & rationale tests
│   ├── test_gemini.py         # Gemini API integration & mock tests
│   ├── test_groq.py           # Groq API provider tests
│   ├── test_intake.py         # Bug intake validation tests
│   ├── test_integration.py    # End-to-end pipeline integration tests
│   ├── test_localization.py   # Multi-language code localization tests
│   ├── test_router.py         # Model router tier assignment tests
│   ├── test_sandbox.py        # Sandbox execution & timeout tests
│   ├── test_server_git_and_progress.py # Web server Git tracking & multithreaded test suite
│   ├── test_state_graph.py    # SQLite DAG state graph tests
│   ├── test_static_analysis.py# Static analysis linter tests
│   ├── test_test_runner.py    # Built-in zero-dependency test runner tests
│   ├── test_traceback_parser.py # Multi-language traceback parser tests
│   ├── test_verifier.py       # Verifier parsing tests
│   ├── test_yagni.py          # YAGNI prompt enforcement tests
│   └── evaluation/            # Empirical benchmark suite runner & fixtures
└── scripts/
    └── setup_eval_targets.py  # Benchmark repository fixture setup utility
```

---

## 📄 License

This project is licensed under the MIT License — see the [LICENSE](LICENSE) file for details.
