💀 CodeReaper: Autonomous Semantic Refactoring Engine

Enterprise Track Capstone | AI Agents Intensive 2025

1. The Problem: "The Silent Killer of Scale"

Every engineering team faces the nightmare of Technical Debt. As deadlines loom, functions become "God Objects," global variables bleed into logic, and dependencies tangle like spaghetti. Existing tools (linters) only find problems; they don't fix them.

The Failure of Standard AI: Standard coding agents suffer from "Graph Blindness." They refactor a file in isolation, often breaking external dependencies (changing a function signature that main.py relies on) or deleting global variables (breaking scope).

2. The Solution: Graph-Guided Safety

CodeReaper is not just a coding assistant; it is a Graph-Aware Architect. It constructs an Abstract Syntax Tree (AST) dependency graph of your repository before touching a single line of code.

🛡️ The Novelty: 3-Layer Safety Protocol

1. The Inquisitor: Scans code for Cyclomatic Complexity and "Smells" (e.g., Spaghetti Logic).
2. The Graph Shield: Detects external imports. If lib.py is used by main.py, the Shield locks the function signature, preventing the agent from breaking the build.
3. The Scope Guardian: A specialized research module that enforces Semantic Equivalency. It ensures that refactored code maintains access to global state (addressing the "Scope Shadowing" edge case).

3. Architecture & Tech Stack

CodeReaper uses a Hierarchical Multi-Agent System (HMAS) powered by Google Gemini 2.5 Pro:

• Frontend: Streamlit (Real-time Agent Visualization)
• Brain: Google Gemini API (Reasoning & Refactoring)
• Tools:
  • DependencyGraph: AST-based import mapping.
  • GlobalScopeGuardian: Semantic analysis for variable scope.
  • GoogleSearch: Fetches live context (e.g., "Python recursion best practices").

4. Implementation Highlights

This project demonstrates key course concepts:

• ✅ Multi-Agent Orchestration: Sequential workflow (Inquisitor -> Graph Agent -> Researcher -> Surgeon -> Guardian).
• ✅ Custom Tooling: We built ReaperTools for complexity analysis and ScopeGuardian for safety checks.
• ✅ Observability: The Streamlit dashboard visualizes the "Thought Process" of every agent in real-time.

5. Setup & Usage

Prerequisites: Python 3.9+, Google Gemini API Key.

# 1. Clone & Install
git clone [https://github.com/darksoul-nyx/codereaper.git](https://github.com/darksoul-nyx/codereaper.git)
pip install -r requirements.txt

# 2. Set API Key
export GOOGLE_API_KEY="your_key_here"

# 3. Run the Gauntlet
streamlit run src/app_v2.py