onlycoding135/constrained-refactor-gauntlet

Constrained Refactor Gauntlet

An OpenEnv RL environment where an agent refactors a legacy Python codebase while obeying 150 cascading engineering rules.

$$R{total} = (W{test} \cdot S{test}) \times \left( \frac{1}{N} \sum{i=1}^{N} Ci \right) - P{efficiency} - P_{hack}$$

🎯 Hackathon

Meta PyTorch OpenEnv Hackathon — Long‑Horizon Planning & Instruction Following

🏗️ Architecture Overview

flowchart TD
    subgraph Env[Environment Server]
        Reset["/reset"] --> EpisodeGen[Episode Generator]
        EpisodeGen --> Corrupt[Corruption Pipeline]
        Corrupt --> State[Initial State]
        State --> Step[/step]
        Step --> Eval[Evaluation Engine]
        Eval --> Reward[Reward Function]
        Reward --> Step
    end
    subgraph Train[Training Pipeline]
        Model[(Base Model\nQwen/Qwen2.5‑Coder‑7B‑Instruct)] --> LoRA[LoRA Adapters]
        LoRA --> GRPO[GRPO Trainer]
        GRPO --> Dataset[Generated Episodes]
        Dataset --> GRPO
    end
    subgraph Eval[Evaluation Tracks]
        TrackA[Track A – Code Quality]
        TrackB[Track B – Compliance]
        TrackC[Track C – Green‑Code]
        Reward --> TrackA & TrackB & TrackC
    end
    Env --> Train
    Train --> Infer[/infer]

Core Components

• —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.
• —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.
• —FastAPI Server (`server.py`) – Exposes a standard RL interface:
• —GET / – Project info
• —GET /health – Health check
• —POST /reset – Start a new episode
• —POST /step – Submit an action (XML‑formatted file edits)
• —POST /infer – Run the trained agent on the current state (GPU required)
• —GET /dashboard/co2/{episode_id} – Visualise CO₂‑savings from Track C
• —Evaluation Engine – Implements three orthogonal tracks that feed the final reward:
• —Track A – Code Quality – Fast AST‑based lint, cyclomatic‑complexity, module‑size, doc‑string and type‑hint coverage.
• —Track B – Compliance – Checks against the 150 engineering standards defined in ENGINEERING_STANDARDS.md.
• —Track C – Green‑Code – Graphlet‑analysis + CPU/memory profiling to estimate energy‑efficiency and translate it into a CO₂‑saving score.
• —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.
• —Inference (`inference.py`) – Loads the final LoRA adapter, receives the current episode state via /infer, and returns the best edit payload.

Reward Components

Anti‑Cheating Layers

1. 1.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.
2. 2.Protected File Lockdown – Test infrastructure files (conftest.py, test_*.py, pytest.ini, setup.cfg) cannot be edited. Any attempt triggers P_hack = −1.0.
3. 3.Test Stub Detection – Creating functions like def test_all(): return True is flagged as a hack via AST inspection.
4. 4.Forbidden Names – Specific naming conventions (e.g., varelunixo, xhackbypass) trigger immediate penalties.
5. 5.Assertion Guard – Deleting all assert statements from a file that originally contained them is treated as cheating.

📚 API Endpoints

⚙️ Setup

1. 1.Clone the repository

   git clone https://github.com/bcde123/Meta-Round2.git
   cd Meta-Round2

1. 1.Install dependencies

   pip install -r requirements.txt

1. 1.Launch the environment server

   uvicorn server:app --host 0.0.0.0 --port 7860

1. 1.(Optional) Train the model – see the Training section below.

🚀 Training

# Verify the environment (CPU‑only quick check)
python training/verify_pipeline.py

# Full GRPO training (GPU, 200 episodes)
python training/train_grpo.py

The script:

1. 1.Generates a synthetic dataset of corrupted episodes.
2. 2.Loads the Qwen‑2.5‑Coder base model via Unsloth.
3. 3.Attaches LoRA adapters (r=32).
4. 4.Runs GRPO with a custom reward that combines Track A, B, C and a format‑bonus.
5. 5.Saves the final adapter to grpo_output/final_adapter/.

📈 Inference & Evaluation

python inference.py   # loads the saved adapter and starts a demo loop

• —The agent receives the current episode via the server, predicts the next edit, and the server applies it.
• —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>.

🤝 Contributing

• —Follow the PEP‑8 style guide and keep docstrings.
• —Add new corruptions to EpisodeGenerator as separate methods.
• —Extend ENGINEERING_STANDARDS.md with additional rule definitions – the compliance checker will pick them up automatically.
• —Open a PR with a clear description and update the changelog.

📜 License

This project is released under the Apache‑2.0 License. Feel free to fork, modify, and submit improvements.

Created with ❤️ by the Meta‑Round 2 team.