codefix-env 0.2.1__tar.gz → 0.2.2__tar.gz

{codefix_env-0.2.1/src/codefix_env.egg-info → codefix_env-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codefix-env
-Version: 0.2.1
+Version: 0.2.2
 Summary: A high-performance PyTorch-based RL environment for automated code debugging and LLM agent evaluation
 Author-email: Shailendra Dhakad <dhakarshailendra829@gmail.com>
 License:                                  Apache License
@@ -267,244 +267,103 @@ Dynamic: license-file
 
 <div align="center">
 
-# CodeFix-Env
+<h1>CodeFix-Env</h1>
 
-**A reinforcement learning environment for training LLM-driven agents to autonomously debug, localize, and repair code through sandboxed execution and feedback-driven learning.**
+<p>A sandboxed reinforcement learning environment for training and evaluating LLM agents on automated code debugging, and the fast, verifiable feedback loop that kind of training requires.</p>
 
 <p align="center">
-  <strong>Built for scalable agent evaluation on real-world software debugging tasks.</strong>
+  <a href="https://github.com/dhakarshailendra829/codefix-env/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/dhakarshailendra829/codefix-env/ci.yml?branch=main&style=for-the-badge" alt="CI status"></a>
+  <a href="https://pypi.org/project/codefix-env/"><img src="https://img.shields.io/pypi/v/codefix-env?style=for-the-badge&color=blue" alt="PyPI version"></a>
+  <a href="https://github.com/dhakarshailendra829/codefix-env/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=for-the-badge" alt="Apache 2.0 License"></a>
+  <a href="tests/"><img src="https://img.shields.io/badge/tests-197%20passing-brightgreen?style=for-the-badge" alt="Tests passing"></a>
 </p>
 
 <p align="center">
-  <!-- Red -->
-  <a href="https://pytorch.org/">
-    <img src="https://img.shields.io/badge/PyTorch-EE4C2C?style=for-the-badge&logo=pytorch&logoColor=white" alt="PyTorch">
-  </a>
-
-  <!-- Orange -->
-  <a href="https://vllm.ai/">
-    <img src="https://img.shields.io/badge/vLLM-F97316?style=for-the-badge&logo=fastapi&logoColor=white" alt="vLLM">
-  </a>
-
-  <!-- Yellow -->
-  <a href="https://huggingface.co/">
-    <img src="https://img.shields.io/badge/HuggingFace-FFD21E?style=for-the-badge&logo=huggingface&logoColor=black" alt="HuggingFace">
-  </a>
-
-  <!-- Green -->
-  <a href="https://fastapi.tiangolo.com/">
-    <img src="https://img.shields.io/badge/FastAPI-009688?style=for-the-badge&logo=fastapi&logoColor=white" alt="FastAPI">
-  </a>
-
-  <!-- Blue -->
-  <a href="https://www.docker.com/">
-    <img src="https://img.shields.io/badge/Docker-2496ED?style=for-the-badge&logo=docker&logoColor=white" alt="Docker">
-  </a>
-
-  <!-- Indigo -->
-  <a href="https://github.com/">
-    <img src="https://img.shields.io/badge/CI/CD-181717?style=for-the-badge&logo=githubactions&logoColor=white" alt="CI/CD">
-  </a>
-
-  <!-- Violet -->
-  <a href="https://ollama.com/">
-    <img src="https://img.shields.io/badge/Ollama-7C3AED?style=for-the-badge&logo=llama&logoColor=white" alt="Ollama">
-  </a>
+  <strong>
+    <a href="#quick-start">Quick Start</a> ·
+    <a href="ARCHITECTURE.md">Architecture</a> ·
+    <a href="SECURITY.md">Security</a> ·
+    <a href="CONTRIBUTING.md">Contributing</a>
+  </strong>
 </p>
 
-
-<p align="center">
-  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/Python-3.10%2B-3776ab?style=flat-square&logo=python&logoColor=white"></a>
-  <a href="https://pytorch.org/"><img src="https://img.shields.io/badge/PyTorch-2.2%2B-ee4c2c?style=flat-square&logo=pytorch&logoColor=white"></a>
-  <a href="https://fastapi.tiangolo.com/"><img src="https://img.shields.io/badge/FastAPI-0.110%2B-009688?style=flat-square&logo=fastapi&logoColor=white"></a>
-  <a href="https://gymnasium.farama.org/"><img src="https://img.shields.io/badge/Gymnasium-Compatible-4B8BBE?style=flat-square"></a>
-  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-green?style=flat-square"></a>
-  <a href="tests/"><img src="https://img.shields.io/badge/Tests-197%2F197%20Passing-brightgreen?style=flat-square"></a>
-  <a href="https://github.com/dhakarshailendra829/codefix-env"><img src="https://img.shields.io/github/stars/dhakarshailendra829/codefix-env?style=flat-square"></a>
-</p>
+</div>
 
 ---
 
-### 📖 Overview
-
-CodeFix-Env is a **Gymnasium-compatible RL environment** that simulates real-world Python code debugging workflows. It enables researchers and engineers to:
+> **Status: active development.** The environment, sandbox, reward pipeline, and task registry are stable and tested. A trained-policy result and a larger, mined task set are in progress — see [Roadmap](#roadmap).
 
+---
 
-| Goal | Description |
-| :--- | :--- |
-| **Train** | Large language models (LLMs) on code repair tasks. |
-| **Evaluate** | AI agents on real debugging scenarios. |
-| **Benchmark** | Code generation and reasoning capabilities. |
-| **Build** | Automated debugging systems. |
-
-**Compatible with:** Qwen, Llama, CodeLlama, DeepSeek, and other leading LLMs.
+## Table of Contents
+
+- [Why CodeFix-Env?](#why-codefix-env)
+- [Install](#install)
+- [Quick Start](#quick-start)
+- [Deployment](#deployment)
+- [How It Works](#how-it-works)
+- [Benchmark](#benchmark)
+- [Capabilities](#capabilities)
+- [Roadmap](#roadmap)
+- [Contributing](#contributing)
+- [Security](#security)
+- [License](#license)
+- [Citations](#citations)
 
 ---
 
-</div>
+## Why CodeFix-Env?
 
----
+Training a coding agent to debug software requires more than static examples of correct code. It requires a tight loop: propose a fix, execute it against a real test suite, and receive a signal that reflects genuine progress rather than superficial activity.
 
-### 🔴 The Challenge
-Training Large Language Models (LLMs) for code generation and autonomous repair requires more than static data. Effective learning requires:
-
-*   **Authentic Scenarios:** Moving beyond synthetic examples to real-world debugging.
-*   **Tight Feedback Loops:** Providing immediate test results and error logs.
-*   **Measurable Progress:** Quantifiable metrics based on test pass rates.
-*   **Secure Execution:** Sandboxed environments to prevent unsafe code execution.
-
-### 🟢 The Solution: CodeFix-Env
-CodeFix-Env is a specialized environment designed for RL agents and LLMs to master code repair through:
-
-*   **Real-World Tasks:** 21 curated Python bugs ranging from logic errors to complex edge cases.
-*   **Test-Driven Feedback:** Agents receive granular execution data after every action.
-*   **Multi-Factor Rewards:** Reward signals based on test progress, code quality, and task completion.
-*   **Isolated Execution:** Built-in sandboxing with timeout protection for safe evaluations.
-*   **Structured Interaction:** Clean API for structured actions that LLMs can reliably generate.
-
-### Workflow
-```mermaid
-graph TD
-    A[Agent receives buggy code] --> B[Analyze code & test failures]
-    B --> C[Generate action: e.g., edit_line]
-    C --> D[Environment executes action]
-    D --> E[Environment provides feedback]
-    
-    subgraph Feedback Loop
-    E --> F[Test results & pass/fail counts]
-    E --> G[Code diff & change analysis]
-    E --> H[Shaped reward signals]
-    end
-    
-    F & G & H --> I{Solution found?}
-    I -- No --> B
-    I -- Yes --> J[Task Complete]
-```
----
+We do that because SWE-bench<sup>1</sup> gave coding agents a scalable, realistic evaluation standard, built on full repositories and real GitHub issues. What it does not give is a fast enough loop for on-policy reinforcement learning, where thousands of cheap episodes per training step are typically required.
 
-## Key Features
-
-** Task Library**
-- 21 carefully designed debugging tasks
-- 3 difficulty levels: Easy (8), Medium (8), Hard (5)
-- Each task includes buggy code, solution, test cases, and hints
-- Covers real Python patterns: loops, recursion, algorithms, decorators
-
-** LLM Integration**
-- Works with HuggingFace Transformers ecosystem
-- Compatible with training frameworks: SFT, DPO, GRPO, PPO
-- Pre-built support for Qwen, Llama, CodeLlama, DeepSeek models
-- Structured JSON action interface for LLM control
-
-** Performance**
-- Multiprocessing-based sandbox with timeout enforcement
-- Per-test execution isolation
-- 197 unit tests with 83% code coverage
-- Automated CI/CD pipeline (Python 3.10, 3.11, 3.12)
-
-** Developer Friendly**
-- Gymnasium standard interface
-- Async client for high-performance training
-- Sync wrapper for notebooks
-- FastAPI HTTP server for remote access
-- Complete type hints and documentation
+Most environments used for this today sit at one of two extremes: repository-scale benchmarks that are realistic but slow to sandbox, or ad-hoc code execution with no meaningful isolation at all. CodeFix-Env is built for the space between them.
 
----
+CodeFix-Env is building that middle layer:
 
-## Installation
+> a sandboxed, densely-rewarded reinforcement learning environment for single-function code repair, fast enough to serve as a rollout source, with a stated threat model rather than an assumed one
 
-### Step 1: Clone Repository
+We do that by:
 
-```bash
-git clone https://github.com/dhakarshailendra829/codefix-env.git
-cd codefix-env
-```
-### Step 2: Create virual Environment
-```bash
-python3.11 -m venv .venv
-source .venv/bin/activate (On mac)
-.venv/Scripts/activate (On Windows)
-```
-### Step 3: Intall Package
-#### For Basic Usage
-```bash
-pip install -e . 
-```
----
-#### For Developement
-```bash
-pip install -e ".[dev]"
-```
----
-#### For LLM training (includes transformers, TRL, datasets)
-```bash
-pip install -e ".[llm]"
-```
----
-#### For everything
-```bash
-pip install -e ".[dev,llm]"
-```
-### Step 4: Verify Installation
-```bash
-python -c "from codefix_env import CodeFixEnvironment; print(' Installation successful!')"
-```
----
-## Usage & Development Guide
+- executing every agent action inside a layered sandbox — static AST filtering, restricted builtins, and OS-level process isolation — documented in full in [SECURITY.md](SECURITY.md), including two hardening attempts that failed under load and were reverted rather than left unreported
+- computing a dense, per-step reward from hidden test-pass-rate deltas, rather than a single pass/fail signal at episode end
+- mining task candidates directly from real, merged bug-fix pull requests on GitHub, so tasks can be traced back to an actual historical defect (`scripts/mine_tasks.py`)
+- publishing the environment as an installable, continuously tested package rather than a static research repository
 
-### 1. Basic Environment Usage
-```python
-python << 'EOF'
-from codefix_env import CodeFixEnvironment, CodeFixAction, ActionType
+Our goal is to grow this into a task set and training result large enough to serve as a genuine benchmark and training ground for code-repair agents, in the same way SWE-bench did for repository-scale evaluation.
 
-# Create environment
-env = CodeFixEnvironment()
+<sup>1</sup> https://arxiv.org/abs/2310.06770
 
-# Start episode with random easy task
-obs = env.reset(difficulty="easy")
-print(f"Task: {obs.task_id}")
-print(f"Current Code:\n{obs.current_code}")
+---
 
-# Run tests to see failures
-action = CodeFixAction(action_type=ActionType.RUN_TESTS)
-result = env.step(action)
-print(f"\nTest Results: {result.observation.tests_passed}/{result.observation.tests_total} passing")
-print(f"Output:\n{result.observation.test_output}")
+## Install
 
-print(f"\nReward: {result.reward:.3f}")
-print(f"Episode Done: {result.done}")
-EOF
+```bash
+pip install codefix-env
 ```
 
-### 2. Testing & Quality Assurance
-To run the full suite:
+For development, or to use the training extras:
+
 ```bash
+git clone https://github.com/dhakarshailendra829/codefix-env.git
 cd codefix-env
-PYTHONPATH=src pytest tests/ -v --timeout=60
+python -m venv venv
+source venv/bin/activate      # Windows: venv\Scripts\activate
+pip install -e ".[dev]"       # add ",llm" for transformers/TRL/accelerate
 ```
 
-To run specific Test Suite
-```bash
-PYTHONPATH=src pytest tests/test_tasks.py::TestSolutionCorrectness -v
-```
+Verify:
 
-To check code standards:
 ```bash
-ruff check src/ tests/ examples/
-black --check src/ tests/ examples/
-mypy src/codefix_env/ --ignore-missing-imports
+codefix-server info
 ```
 
-### 3. API Server Deployment
-```bash
-cd codefix-env
-uvicorn src.codefix_env.server.app:app --reload --port 8000
-```
 ---
-## Usage Examples
 
-### 1. Core Debugging Workflow
-A complete cycle from task initialization to final submission.
+## Quick Start
+
+**Local environment** — run episodes directly in Python, no server required:
 
 ```python
 from codefix_env import CodeFixEnvironment, CodeFixAction, ActionType
@@ -512,152 +371,129 @@ from codefix_env import CodeFixEnvironment, CodeFixAction, ActionType
 env = CodeFixEnvironment()
 obs = env.reset(task_id="easy-001-missing-return")
 
-# 1. Run tests to identify failures
 result = env.step(CodeFixAction(action_type=ActionType.RUN_TESTS))
-print(f"Tests: {result.observation.tests_passed}/{result.observation.tests_total} passing")
+print(f"{result.observation.tests_passed}/{result.observation.tests_total} tests passing")
 
-# 2. Apply a targeted fix
 result = env.step(CodeFixAction(
     action_type=ActionType.EDIT_LINE,
     line_number=3,
-    new_content="    return result"
+    new_content="    return result",
 ))
 
-# 3. Final Verification & Submission
 result = env.step(CodeFixAction(action_type=ActionType.SUBMIT_FIX))
-print(f"Status: {'Solved' if result.observation.all_tests_pass else 'Failed'}")
-print(f"Final Reward: {result.reward:.3f}")
+print("solved" if result.observation.all_tests_pass else "not solved", result.reward)
 ```
 
-### 2. High-Level Task Management
-Programmatically interact with the task database.
+**Server mode** — expose the environment over HTTP for remote or multi-language clients:
 
-```python
-from codefix_env import list_tasks, Difficulty, task_count
+```bash
+codefix-server serve --port 8000
+```
 
-# Get environment stats
-print(f"Total tasks by difficulty: {task_count()}")
+**Task inspection** — list and filter the task registry:
 
-# Bulk process specific difficulty levels
-easy_tasks = list_tasks(difficulty=Difficulty.EASY)
-for task in easy_tasks[:5]:
-    print(f"Loading {task.id}: {task.title}")
+```bash
+codefix-server tasks
+```
+
+**Baseline evaluation** — run oracle and random policies across the full task set:
+
+```bash
+python scripts/run_baseline_eval.py --episodes 3
 ```
 
 ---
 
-## LLM Training & Integration
+## Deployment
 
-### Server-Client Architecture
-Deploy the environment as a service to scale LLM evaluations across multiple agents.
+The repository includes a `Dockerfile` for running the environment as a standalone service:
 
 ```bash
-# Start the API server
-uvicorn src.codefix_env.server.app:app --port 8000
+docker build -t codefix-env .
+docker run -p 8000:8000 codefix-env
 ```
 
-### Building Training Datasets
-Export environment states into `.jsonl` formats for fine-tuning models like Llama or Qwen.
-
-```python
-import json
-from codefix_env import CodeFixClient
-
-async def collect_trajectories():
-    async with CodeFixClient("http://localhost:8000") as client:
-        obs = await client.reset(difficulty="medium")
-        dataset_entry = {
-            "instruction": f"Fix the following code: {obs.current_code}",
-            "context": obs.test_output,
-            "metadata": {"task_id": obs.task_id}
-        }
-        # Append to training_data.jsonl....
-```
+Set `CODEFIX_REWARD_MODEL_PATH` if using a trained neural reward checkpoint (see [ARCHITECTURE.md](ARCHITECTURE.md)). No other environment variables are required for the default, rule-based reward configuration.
 
-### Zero-Shot Inference (HuggingFace)
-Connect an LLM directly to the environment loop.
+---
 
-```python
-from transformers import pipeline
-from codefix_env import CodeFixEnvironment
+## How It Works
 
-# Load a coding model
-fixer = pipeline("text-generation", model="Qwen/Qwen2.5-Coder-7B")
+When an episode runs, CodeFix-Env:
 
-env = CodeFixEnvironment()
-obs = env.reset(difficulty="easy")
+1. **Loads** a task — a buggy function, a hidden test suite, and graduated hints
+2. **Receives** a structured action from the agent: run tests, edit a line, insert, delete, request a hint, view the code, or submit
+3. **Executes** any code-mutating action inside the sandbox, isolated from the host process
+4. **Computes** a unified diff against the original code and a dense, shaped reward from the test-pass-rate change
+5. **Returns** the updated observation, including test output and the diff, so the agent can decide its next action
+6. **Terminates** the episode on a full solve, an explicit submission, or the step budget running out
 
-# Generate a fix based on environment observation
-prompt = f"Fix this Python code based on these errors: {obs.test_output}\nCode:\n{obs.current_code}"
-suggestion = fixer(prompt)
-```
+Full design detail, including the reward formula and the sandbox's layered isolation model, is in [ARCHITECTURE.md](ARCHITECTURE.md).
 
 ---
 
-## API Quick Reference
+## Benchmark
 
+Regenerate these numbers with `python scripts/run_baseline_eval.py --episodes 3`.
 
-| Class / Method | Description |
-| :--- | :--- |
-| `CodeFixEnvironment` | Local execution engine for debugging tasks. |
-| `CodeFixClient` | Async client for interacting with a remote server. |
-| `env.step(action)` | Executes an `ActionType` (EDIT, RUN_TESTS, SUBMIT). |
-| `Difficulty` | Enum: `EASY`, `MEDIUM`, `HARD`. |
-| `BugCategory` | Categories: `SYNTAX`, `LOGIC`, `DATA_STRUCTURE`, `ALGORITHM`. |
+<!-- BENCHMARK-START -->
 
----
+Oracle policy (applies the known-correct fix) versus a random policy, across all 21 tasks:
 
-## Development & CI/CD
-Standard commands for maintaining the environment.
+| Policy | Easy | Medium | Hard |
+|---|---|---|---|
+| Oracle | 100% | 87.5% | 60% |
+| Random | 0% | 0% | 20% |
 
-```bash
-# Run full test suite with coverage
-pytest tests/ -v --cov=src/codefix_env
+No trained-policy result yet — this compares two fixed baselines to confirm the reward signal discriminates genuine problem-solving from undirected action. A GRPO training result is in progress; see [Roadmap](#roadmap).
+
+<!-- BENCHMARK-END -->
 
-# Static Analysis
-ruff check src/   # Linting
-black --check src/ # Formatting
-mypy src/         # Type Checking
-```
 ---
 
-<div align="center">
+## Capabilities
 
-# LLM Ecosystem & Infrastructure
+| | |
+|---|---|
+| **Sandboxed execution** | Static AST filtering, restricted builtins, and OS-level process isolation, with a documented threat model |
+| **Dense reward shaping** | Per-step reward from test-pass-rate deltas, hint-usage and step-count penalties, and a solve bonus |
+| **Graded task registry** | 21 tasks across easy, medium, and hard tiers, each with hidden tests and progressive hints |
+| **Task mining pipeline** | Extracts candidate tasks from real, merged GitHub bug-fix pull requests for human review |
+| **Server and async client** | FastAPI HTTP server with a session-scoped API, plus an async client for training loops |
+| **Framework-compatible** | Gymnasium-style `reset()`/`step()`/`state()` interface; usable with SFT, DPO, GRPO, and PPO training code |
+| **CI-gated** | 197 tests, linting, and type checking on every change, across Python 3.10 through 3.12 |
 
-### LLM Models
+---
 
-| Model | Description |
-| :--- | :--- |
-| 🟢 **Qwen 1.5B, 7B, 14B** | Alibaba's instruction models |
-| 🟢 **Llama 2-7B-Chat** | Meta's foundation model |
-| 🟢 **CodeLlama 7B, 13B, 34B** | Specialized for code |
-| 🟢 **DeepSeek Coder 1.3B, 6.7B** | Chinese LLM for code |
-| 🟢 **Mistral 7B** | Open-source efficient model |
+## Roadmap
 
-<br/>
+- Closed-loop RL training result: fine-tune a small open-weight code model against the environment and publish a measured pass-rate curve
+- A trained checkpoint for the optional learned reward model, calibrated against oracle judgment
+- Task registry expansion from 21 to several hundred tasks, mined and reviewed from real repositories
+- Multi-file task support, extending beyond single-function scope
+- Container-level sandbox isolation (namespace and capability restrictions, seccomp filtering)
+- Support for a second programming language
+- Horizontally scalable session handling for distributed rollout collection
+- Listing on the OpenEnv Hub
 
-### ⚙️ Training Frameworks
+---
 
-| Framework | Method |
-| :--- | :--- |
-| 🟢 **SFT** | Supervised fine-tuning |
-| 🟢 **DPO** | Direct preference optimization |
-| 🟢 **GRPO** | Group relative policy optimization |
-| 🟢 **PPO** | Proximal policy optimization |
+## Contributing
 
-<br/>
+Issues and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for local setup, the task-authoring template, and the pull request workflow.
 
-### 🏗️ Infrastructure
+---
 
-| Tool | Purpose |
-| :--- | :--- |
-| 🟢 **HuggingFace** | Model hub & training |
-| 🟢 **vLLM** | Fast LLM serving |
-| 🟢 **Ollama** | Local model deployment |
-| 🟢 **Docker** | Containerization |
-| 🟢 **GitHub Actions** | CI/CD |
+## Security
+
+Execution isolation is treated as a first-class design concern, not an afterthought — including reporting what the current sandbox does not protect against. See [SECURITY.md](SECURITY.md) for the full threat model and for responsible disclosure of any suspected sandbox escape.
 
-</div>
 ---
-## Note:- This is pure backend system not frontend, we are working on frontent very soon we will update.
+
+## License
+
+Apache License 2.0 — see [LICENSE](LICENSE).
+
+## Citations
+<sup>2</sup> Dhakad, S. CodeFix-Env: A Sandboxed Reinforcement Learning Environment for Automated Code Debugging. arXiv:2607.XXXXX, 2026.
+