onlycoding135/constrained-refactor-gauntlet

1---2title: Constrained Refactor Gauntlet3emoji: 🔧4colorFrom: blue5colorTo: purple6sdk: docker7pinned: false8---9 10# Constrained Refactor Gauntlet11 12An OpenEnv RL environment where an agent refactors a legacy Python codebase while obeying **150 cascading engineering rules**.13 14$$R_{total} = (W_{test} \cdot S_{test}) \times \left( \frac{1}{N} \sum_{i=1}^{N} C_i \right) - P_{efficiency} - P_{hack}$$15 16## 🎯 Hackathon17 18Meta PyTorch OpenEnv Hackathon — Long‑Horizon Planning & Instruction Following19 20## 🏗️ Architecture Overview21 22```mermaid23flowchart TD24    subgraph Env[Environment Server]25        Reset["/reset"] --> EpisodeGen[Episode Generator]26        EpisodeGen --> Corrupt[Corruption Pipeline]27        Corrupt --> State[Initial State]28        State --> Step[/step]29        Step --> Eval[Evaluation Engine]30        Eval --> Reward[Reward Function]31        Reward --> Step32    end33    subgraph Train[Training Pipeline]34        Model[(Base Model\nQwen/Qwen2.5‑Coder‑7B‑Instruct)] --> LoRA[LoRA Adapters]35        LoRA --> GRPO[GRPO Trainer]36        GRPO --> Dataset[Generated Episodes]37        Dataset --> GRPO38    end39    subgraph Eval[Evaluation Tracks]40        TrackA[Track A – Code Quality]41        TrackB[Track B – Compliance]42        TrackC[Track C – Green‑Code]43        Reward --> TrackA & TrackB & TrackC44    end45    Env --> Train46    Train --> Infer[/infer]47```48 49### Core Components50 51- **Episode Generator (`environment/episode_generator.py`)** – Loads a clean codebase, applies a random subset of corruptions (circular imports, cryptic renames, dead code, hard‑coded secrets, etc.), and produces the initial episode state together with an active set of engineering rules. Difficulty is scaled via a `CurriculumManager` based on recent agent performance.52- **Curriculum Manager** – Tracks rolling reward history (last 150 episodes) and escalates rule count (up to 150) once the agent consistently exceeds a 0.7 success threshold.53- **FastAPI Server (`server.py`)** – Exposes a standard RL interface:54  - `GET /` – Project info55  - `GET /health` – Health check56  - `POST /reset` – Start a new episode57  - `POST /step` – Submit an action (XML‑formatted file edits)58  - `POST /infer` – Run the trained agent on the current state (GPU required)59  - `GET /dashboard/co2/{episode_id}` – Visualise CO₂‑savings from Track C60- **Evaluation Engine** – Implements three orthogonal tracks that feed the final reward:61  - **Track A – Code Quality** – Fast AST‑based lint, cyclomatic‑complexity, module‑size, doc‑string and type‑hint coverage.62  - **Track B – Compliance** – Checks against the 150 engineering standards defined in `ENGINEERING_STANDARDS.md`.63  - **Track C – Green‑Code** – Graphlet‑analysis + CPU/memory profiling to estimate energy‑efficiency and translate it into a CO₂‑saving score.64- **Training Pipeline (`training/train_grpo.py`)** – Uses **Unsloth** to load the base model with 4‑bit Quant‑LLM (QLoRA) and wraps it with LoRA adapters. Episodes are generated on‑the‑fly, the model produces several completions per prompt, and the custom `reward_function` scores each completion using the multiplicative formula (plus a formatting bonus). GRPO then performs a relative‑policy update.65- **Inference (`inference.py`)** – Loads the final LoRA adapter, receives the current episode state via `/infer`, and returns the best edit payload.66 67### Reward Components68 69| Component | Definition | Verification |70|-----------|------------|-------------|71| **Test Score (S_test)** | Does the refactored code still function correctly? | Binary gate: `1.0` if all files parse & tests pass, `0.0` for any failure. |72| **Compliance Score (C_i)** | Did the model follow the active engineering rules? | Per‑rule AST parsing to verify exact structural constraints (70% rule‑engine + 30% direct AST). |73| **Efficiency Penalty (P_efficiency)** | Did the model take too many steps? | Subtracts `0.01` per step/edit to encourage direct, minimal fixes. |74| **Hack Penalty (P_hack)** | Did the model try to cheat the environment? | Immediate `−1.0` reward and episode termination. |75 76### Anti‑Cheating Layers77 781. **Binary Execution Gate** – If ANY file in the codebase has a `SyntaxError`, the test multiplier drops to **zero**. The agent gets no points for “clean” code that doesn’t compile.792. **Protected File Lockdown** – Test infrastructure files (`conftest.py`, `test_*.py`, `pytest.ini`, `setup.cfg`) cannot be edited. Any attempt triggers `P_hack = −1.0`.803. **Test Stub Detection** – Creating functions like `def test_all(): return True` is flagged as a hack via AST inspection.814. **Forbidden Names** – Specific naming conventions (e.g., `varelunixo`, `xhackbypass`) trigger immediate penalties.825. **Assertion Guard** – Deleting all `assert` statements from a file that originally contained them is treated as cheating.83 84## 📚 API Endpoints85 86| Endpoint                               | Method | Description                               |87|----------------------------------------|--------|-------------------------------------------|88| `/`                                    | GET    | Project information                       |89| `/health`                              | GET    | Simple health check                       |90| `/health/green`                        | GET    | Status of the Green‑Code subsystem        |91| `/docs`                                | GET    | Swagger UI for the FastAPI server          |92| `/reset`                               | POST   | Initialise a new episode                  |93| `/step`                               | POST   | Submit an action (file edit)               |94| `/infer`                               | POST   | Run the trained agent (GPU required)      |95| `/dashboard/co2/{episode_id}`          | GET    | CO₂‑savings dashboard for an episode      |96 97## ⚙️ Setup98 991. **Clone the repository**100   ```bash101   git clone https://github.com/bcde123/Meta-Round2.git102   cd Meta-Round2103   ```1042. **Install dependencies**105   ```bash106   pip install -r requirements.txt107   ```1083. **Launch the environment server**109   ```bash110   uvicorn server:app --host 0.0.0.0 --port 7860111   ```1124. **(Optional) Train the model** – see the Training section below.113 114## 🚀 Training115 116```bash117# Verify the environment (CPU‑only quick check)118python training/verify_pipeline.py119 120# Full GRPO training (GPU, 200 episodes)121python training/train_grpo.py122```123The script:1241. Generates a synthetic dataset of corrupted episodes.1252. Loads the Qwen‑2.5‑Coder base model via Unsloth.1263. Attaches LoRA adapters (`r=32`).1274. Runs GRPO with a custom reward that combines Track A, B, C and a format‑bonus.1285. Saves the final adapter to `grpo_output/final_adapter/`.129 130## 📈 Inference & Evaluation131 132```bash133python inference.py   # loads the saved adapter and starts a demo loop134```135* The agent receives the current episode via the server, predicts the next edit, and the server applies it.136* After the episode finishes, the three tracks emit a detailed score breakdown and, for Track C, a CO₂‑savings estimate displayed at `/dashboard/co2/<episode_id>`.137 138## 🤝 Contributing139 140- Follow the **PEP‑8** style guide and keep docstrings.141- Add new corruptions to `EpisodeGenerator` as separate methods.142- Extend `ENGINEERING_STANDARDS.md` with additional rule definitions – the compliance checker will pick them up automatically.143- Open a PR with a clear description and update the changelog.144 145## 📜 License146 147This project is released under the **Apache‑2.0 License**. Feel free to fork, modify, and submit improvements.148 149---150*Created with ❤️ by the Meta‑Round 2 team.*151