Autonomous Python-to-C++ Transpiler, Pybind11 Extension Generator & Self-Healing Benchmark Pipeline
PolyCode AI is an end-to-end AI engineering tool that transpiles bottleneck Python functions into optimized C++17 code and native Pybind11 C extensions. It automatically compiles binaries via subprocesses, self-heals compilation errors using terminal stderr feedback, and benchmarks execution speedup side-by-side.
- Overview
- Key Features
- Architecture & Workflow
- Demo
- System Requirements
- Installation & Quickstart
- Project Directory Structure
- Usage Guide
- Running Tests
- Troubleshooting & Configuration
- License
Python is the leading language for rapid prototyping and AI development, but its interpreted nature and Global Interpreter Lock (GIL) make it slow for CPU-heavy mathematical computations. PolyCode AI bridges this gap by automatically converting Python bottlenecks into compiled, bare-metal C++ executables and native Pybind11 Python C-extensions (.pyd / .so).
PolyCode AI combines three core software capabilities into a single seamless pipeline:
- Multi-Language LLM Polyglot Transpiler: Prompts frontier models via LiteLLM to convert Python algorithms into C++17 and Pybind11 module formats.
- Native Python Extension Generator: Invokes local C++ compilers (
g++) via subprocesses to produce compiled shared libraries on the fly. - Self-Healing LLM Code Optimization Agent: Captures compiler output (
stderr) upon compilation failures, automatically sending stack traces back to the LLM to patch and recompile code without human intervention.
- Multi-Target Transpilation: Supports C++17 standalone executables and Pybind11 dynamic modules.
- Autonomous Error Recovery: Captures raw
g++compilation errors and iterates with reflection loops until valid binaries are built. - Automated Toolchain Integration: Resolves Pybind11 include headers, Python C API libraries, and
g++flags automatically. - Side-by-Side Micro-Benchmarking: Executes and measures execution time for Pure Python, Compiled C++ Executables, and Native Pybind11 Extensions to compute exact speedup factors.
- Interactive Dashboard: Built with Gradio for clean side-by-side code visualizers, execution time metrics, and real-time build logs.
┌─────────────────────────────────────────┐
│ User Input (Python) │
└────────────────────┬────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────────────────────┐
│ 1. LLM Transpilation Engine │
│ • Converts Python code to C++17 & Pybind11 native modules via LiteLLM │
└─────────────────────────────────────────┬────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────────────────────┐
│ 2. Native Extension Compiler │
│ • Spawns g++ via subprocess │
│ • Links Pybind11 header files and produces dynamic library (.pyd / .so) │
└─────────────────────────────────────────┬────────────────────────────────────────┘
│
Compilation?
┌─────┴─────┐
FAILED PASSED
│ │
▼ │
┌────────────────────────────────────────┐ │
│ 3. Self-Healing Agent │ │
│ • Captures g++ stderr compiler error │ │
│ • Refines prompt with error context │ │
│ • Re-prompts LLM for corrected code │ │
└──────────────────┬─────────────────────┘ │
└───────────────────┐ │
▼ ▼
┌──────────────────────────────────────────────────────────────────────────────────┐
│ 4. Execution & Benchmarking Suite │
│ • Runs Pure Python, C++ Executable, and Pybind11 Extension │
│ • Measures execution timing and calculates performance speedup │
└──────────────────────────────────────────────────────────────────────────────────┘
This project demonstrates an end-to-end code optimization workflow:
- Converts Python code into C++17 and Pybind11 targets using LLMs
- Compiles generated code with
g++ - Uses compiler
stderrto drive an automated self-healing loop - Benchmarks Python, C++, and Pybind11 execution
- Presents code, build logs, and performance results in a Gradio dashboard
- Operating System: Windows 11 / Linux / macOS
- Python Environment: Python 3.12+ (managed via
uv) - C++ Compiler:
g++with C++17 support (MinGW-w64 on Windows, GCC, or Clang) - API Credentials: API key for OpenAI, Gemini, Groq, or OpenRouter (managed via LiteLLM)
# Clone the repository
git clone https://github.com/FMangiwa/polycode-ai.git
cd polycode-ai
Create and activate a isolated environment using uv:
# Create virtual environment
uv venv
# Install dependencies from requirements.txt
uv pip install -r requirements.txt
Create a .env file in 4\_polycode\_ai/:
OPENAI\_API\_KEY=your\_openai\_api\_key
GROQ\_API\_KEY=your\_groq\_api\_key
# Additional keys supported by LiteLLM (GEMINI\_API\_KEY, OPENROUTER\_API\_KEY, etc.)
uv run python app.py
Open http://127.0.0.1:7860 in your web browser.
4\_polycode\_ai/
├── .env # Environment variables & API credentials (API keys)
├── app.py # Main Gradio application launcher & entrypoint
├── config.py # Global constants, paths, and build environment settings
├── pytest.ini # Pytest configuration and warning suppression rules
├── Readme.md # Project documentation & architecture overview
├── requirements.txt # Python project dependencies
├── engine/
│ ├── \_\_init\_\_.py # Engine package initializer
│ ├── compiler.py # Low-level g++ compiler & subprocess management
│ ├── llm.py # LiteLLM client wrapper & C++/Pybind11 system prompts
│ ├── orchestrator.py # Core pipeline coordinator & benchmark runner
│ ├── pybind\_loader.py # Native C++ extension builder & module importer
│ └── self\_healing.py # Iterative LLM reflection & error-correction loops
├── tests/
│ ├── test\_app.py # Gradio API integration tests
│ ├── test\_config.py # Configuration assertion tests
│ └── test\_engine.py # Code block extraction & LLM parser tests
└── ui/
├── \_\_init\_\_.py # UI package initializer
└── dashboard.py # Gradio dashboard interface layout & event handlers
- Paste Code: Enter a CPU-bound Python function into the PolyCode AI dashboard.
- Run Pipeline: Click Transpile & Benchmark.
- Monitor Build: View compilation terminal output in real time. If
g++yields an error, watch the self-healing loop patch the code automatically. - Select Target: Choose between C++ Standalone Executable or Pybind11 Native Extension.
- Analyze Speedup: Compare execution runtime and performance gain metrics side-by-side.
PolyCode AI uses pytest for unit and integration testing. Run tests via uv:
uv run pytest -v
tests/test\_app.py::test\_gradio\_client\_predict\_integration PASSED [ 25%]
tests/test\_config.py::test\_config\_constants PASSED [ 50%]
tests/test\_engine.py::test\_engine\_response PASSED [ 75%]
tests/test\_engine.py::test\_extract\_code\_block PASSED [100%]
============================== 4 passed in 9.27s ==============================
If g++ is not recognized, ensure MinGW-w64 or GCC is added to your system PATH:
# Verify g++ availability
g++ --version
When compiling Pybind11 modules manually, ensure header locations match your active environment:
python -c "import pybind11; print(pybind11.get\_include())"
See LICENSE.