🚀 Python2CPP-Agent

An LLM-powered developer agent that translates Python code into standard, optimized C++17, compiles it with g++ -O3, runs both versions side-by-side, and generates a detailed performance and correctness benchmark report.

---

🎯 Core Features

• Robust Code Extraction: Extracts raw Python scripts even when wrapped inside markdown code blocks.
• LLM-Powered Translation: Translates complete logic structures (variables, arrays, functions, loops) to idiomatic, standard C++17.
• Auto-Compilation: Uses g++ -O3 -std=c++17 to compile translated source files into static executables.
• Performance Evaluation: Runs both implementations concurrently with customized timeout caps and measures runtime using high-precision timers.
• Correctness Normalization: Normalizes terminal outputs (collapsing spaces, ignoring execution duration outputs) to verify algorithmic correctness without false alarms.
• Interactive Workbench: Comes with both a rich command-line tool (cli.py) and an elegant Gradio browser UI (app.py).

---

📂 Project Directory Structure

Python2CPP-Agent/
├── README.md               # Detailed introduction and user manual
├── LICENSE                 # MIT License
├── CONTRIBUTING.md         # Open-source contributions guidelines
├── CODE_OF_CONDUCT.md      # Community behavioral expectations
├── requirements.txt        # PIP dependencies manifest
├── pyproject.toml          # Packaging metadata and CLI commands
├── .gitignore              # Ignored cache/output files config
├── app.py                  # Gradio Web Workbench app
├── cli.py                  # CLI command line application
├── agent/                  # Core Modular Package
│   ├── __init__.py         # Package initializer
│   ├── translator.py       # OpenAI-compatible translator client
│   ├── compiler.py         # Subprocess compiler manager
│   ├── benchmark.py        # Normalizer and speedup metric computer
│   ├── executor.py         # Safe, timed python/C++ execution wrapper
│   ├── report.py           # Markdown/JSON formatting engine
│   ├── utils.py            # Text parsing and file helpers
│   └── prompts.py          # Translation prompts and LLM constraints
├── examples/               # Demonstration Scripts
│   ├── fibonacci.py        # Iterative Fibonacci checks
│   ├── matrix.py           # Dense 3D matrix multiplication
│   ├── sorting.py          # Vector Bubble Sort swaps
│   └── prime.py            # Prime number check loops
├── tests/                  # Lightweight Unit Tests
│   ├── test_extract.py     # Code extraction parser test
│   ├── test_compare.py     # Whitespace and timing filters test
│   ├── test_executor.py    # Process execution constraints test
│   └── test_report.py      # Markdown formatting validation test
├── docs/                   # Architectural Guides
│   ├── architecture.md     # Pipeline design overview
│   ├── benchmark.md        # Correctness and performance details
│   └── api.md              # Library API specifications
└── benchmark/              # Past Run Logs
    ├── results.json        # Performance history database
    └── report.md           # Pre-compiled results summary

---

⚙️ Quick Start

1. Prerequisites

• Python: 3.10 or newer.
• C++ Compiler: A C++17 compatible g++ compiler on your system path.
  • Linux (Ubuntu/Debian):

    sudo apt install g++

  • macOS: Install Xcode Command Line Tools by running:

    xcode-select --install

  • Windows: Install MinGW-w64 (e.g., via MSYS2 or WinLibs) or Visual Studio Build Tools.

2. Installation

Clone this repository and install dependencies:

git clone https://github.com/BenyaminMahdavifar/Python2CPP-Agent.git
cd Python2CPP-Agent
pip install -r requirements.txt

3. API Environment Variables

Set up one of the following environment variables depending on your chosen API provider:

Using Google Gemini API (Recommended & Free options):

export GEMINI_API_KEY="your-gemini-key"

Using OpenRouter:

export OR_API_KEY="your-openrouter-key"

Using OpenAI:

export OPENAI_API_KEY="your-openai-key"

---

🛠️ Usage

Command Line Interface (CLI)

Run translation and performance evaluations directly from your terminal:

# Run on an existing file
python cli.py -f examples/fibonacci.py

# Run on a raw code string
python cli.py -c "print(sum(i for i in range(100000)))"

# Change output directory and save as JSON
python cli.py -f examples/prime.py -o custom_workspace/ --json

Gradio Web Interface

Launch a local visual workspace directly in your web browser:

python app.py

Open http://localhost:3000 in your browser to start.

---

🧪 Testing

We use pytest for unit testing. Install the dev dependencies and run tests:

pip install -e .[dev]
pytest

---

👥 Author

Benyamin Mahdavifar

• GitHub Profile: @BenyaminMahdavifar
• Email: benjamincrayan@gmail.com
• Repository: Python2CPP-Agent
• Bug Tracker: Issues

---

📄 License

This project is licensed under the terms of the MIT License. See LICENSE for details.