Depyler

Energy-efficient Python-to-Rust transpiler with progressive verification capabilities. Transform Python code into safe, performant Rust while reducing energy consumption by 75-85%. Built with zero tolerance for technical debt and extreme quality standards following the Toyota Way.

Enterprise Testing Excellence: v2.2.2 delivers enterprise-grade testing infrastructure with 350+ tests across property-based, mutation, fuzzing, and coverage testing frameworks. Features comprehensive CI/CD integration, automated quality gates, and cross-platform testing matrix. Maintains zero defects policy with formal verification readiness and ownership inference. Line coverage: 70% | Function coverage: 74%

🚀 Installation

Install depyler using one of the following methods:

• From Crates.io (Recommended):

  cargo install depyler
  

• From Source:

  git clone https://github.com/paiml/depyler
  cd depyler
  cargo build --release
  cargo install --path crates/depyler
  

• From GitHub Releases: Pre-built binaries are available on the releases page.

Requirements

• Rust: 1.83.0 or later
• Python: 3.8+ (for test validation)

🎯 New in v3.1.0: Background Agent Mode

Continuous transpilation with Claude Code integration! Depyler now includes a background agent that provides real-time Python-to-Rust transpilation through the Model Context Protocol (MCP).

# Start the agent for Claude Code
depyler agent start --foreground

# Monitor a Python project
depyler agent add-project /path/to/project

# Check agent status
depyler agent status

See AGENT.md for complete agent documentation and Claude Code setup instructions.

🚀 Getting Started

Quick Start

# Transpile a Python file to Rust (default)
depyler transpile example.py

# Transpile to Ruchy script format (v3.0.0+)
depyler transpile example.py --target=ruchy

# Transpile with verification
depyler transpile example.py --verify

# Analyze code complexity before transpilation
depyler analyze example.py

# Interactive mode with AI suggestions
depyler interactive example.py --suggest

# Check transpilation compatibility
depyler check example.py

# Inspect AST/HIR representations
depyler inspect example.py --repr hir

# Start Language Server for IDE integration
depyler lsp

# Profile Python code for performance analysis
depyler profile example.py --flamegraph

# Generate documentation from Python code
depyler docs example.py --output ./docs

Using as a Library

Add to your Cargo.toml:

[dependencies]
depyler = "3.0.0"

Basic usage:

use depyler::{transpile_file, TranspileOptions};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let options = TranspileOptions::default()
        .with_verification(true)
        .with_optimization_level(2);
    
    let rust_code = transpile_file("example.py", options)?;
    println!("{}", rust_code);
    
    Ok(())
}

🆕 Multi-Target Support (v3.0.0+)

Ruchy Script Format

Depyler now supports transpiling Python to Ruchy script format, a functional programming language with pipeline operators and actor-based concurrency:

# Transpile to Ruchy format
depyler transpile example.py --target=ruchy

# Output will have .ruchy extension
depyler transpile example.py --target=ruchy -o example.ruchy

Ruchy Features:

• Pipeline Operators - List comprehensions → functional pipelines (|>)
• String Interpolation - f-strings → native interpolation
• Pattern Matching - isinstance() → match expressions
• Actor Concurrency - async/await → actor-based model
• DataFrame Support - NumPy/Pandas → native DataFrame API

Example Transformation:

# Python
result = [x * 2 for x in range(10) if x > 5]

# Ruchy
result = range(10) |> filter(x => x > 5) |> map(x => x * 2)

Key Features

🔄 Core Transpilation

• Python AST to HIR - High-level intermediate representation for safe transformations
• Type Inference - Smart type analysis with annotation support
• Memory Safety - Automatic ownership and borrowing inference
• Direct Rules Engine - Pattern-based Python-to-Rust transformations
• String Optimization - Interning for frequently used literals, Cow for flexible ownership

⚡ Performance & Efficiency

• Energy Reduction - 75-85% lower energy consumption vs Python
• Binary Optimization - Compile with LTO, strip, and panic=abort
• Zero-Copy Strings - Smart string allocation strategies with Cow
• LLVM Backend - Leverages Rust's optimizing compiler
• String Interning - Automatic interning for strings used >3 times

🛡️ Safety & Verification

• Property-Based Testing - QuickCheck for semantic equivalence
• Memory Safety Analysis - Prevents use-after-free and data races
• Bounds Checking - Automatic insertion where needed
• Contract Verification - Pre/post condition checking
• Formal Verification Ready - Structured for future SMT integration

🤖 AI Integration

• Model Context Protocol - Full MCP v1.0 support
• Interactive Mode - AI-powered transpilation assistance
• Annotation Suggestions - Smart optimization hints
• Complexity Analysis - Migration difficulty assessment

🛠️ Developer Tools

• Language Server Protocol - VSCode, Neovim, and other IDE support
• Debugging Support - Source mapping and debugger integration
• Performance Profiling - Hot path detection and optimization
• Documentation Generation - Auto-generate API docs from Python

🎯 Supported Python Features

✅ Production Ready

• Functions with type annotations
• Basic types (int, float, str, bool)
• Collections (List, Dict, Tuple, Set, FrozenSet)
• Control flow (if, while, for, break, continue)
• List, dict, and set comprehensions
• Exception handling → Result<T, E>
• Classes with methods, properties, dataclasses
• Static methods and class methods
• Basic async/await support
• Lambda functions
• Power operator (**) and floor division (//)
• String optimization (interning, Cow support)
• Protocol to Trait mapping
• Const generic array inference
• With statements (context managers)
• Iterator protocol (iter, next)

🚧 In Development

• Full async/await (async iterators, generators)
• Generator expressions with yield
• Advanced decorators
• Class inheritance
• Match/case statements (Python 3.10+)
• Package imports and relative imports

❌ Not Supported

• Dynamic features (eval, exec)
• Runtime reflection
• Monkey patching
• Multiple inheritance

📋 Tool Usage

CLI Interface

# Basic transpilation
depyler transpile input.py              # Creates input.rs
depyler transpile input.py -o output.rs # Custom output
depyler transpile src/ -o rust/         # Directory mode

# Analysis and verification
depyler check input.py                  # Compatibility check
depyler analyze input.py                # Complexity metrics
depyler verify output.rs                # Verify generated code
depyler inspect input.py --repr ast     # View AST/HIR

# Interactive features
depyler interactive input.py            # Interactive session
depyler interactive input.py --suggest  # With AI suggestions

# Quality enforcement
depyler transpile input.py --verify          # With verification
depyler quality-check input.py               # Toyota Way scoring

# Developer tools
depyler lsp                                  # Start Language Server
depyler debug --tips                         # Debugging guide
depyler profile input.py                     # Performance profiling
depyler docs input.py                        # Generate documentation

MCP Integration

Using with Claude Code

# Add to Claude Code
claude mcp add depyler ~/.local/bin/depyler

MCP Server Mode

# Start MCP server
depyler serve --mcp

# Available MCP tools:
# - transpile_python: Convert Python to Rust
# - analyze_complexity: Code complexity analysis
# - verify_transpilation: Verify semantic equivalence
# - suggest_annotations: Optimization hints

HTTP API

# Start HTTP server
depyler serve --port 8080 --cors

# API endpoints
curl "http://localhost:8080/health"
curl "http://localhost:8080/api/v1/transpile" \
  -H "Content-Type: application/json" \
  -d '{"code":"def add(a: int, b: int) -> int: return a + b"}'

🏗️ Architecture

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Python AST    │────▶│      HIR        │────▶│   Rust AST      │
│  (rustpython)   │     │  (Intermediate) │     │     (syn)       │
└─────────────────┘     └─────────────────┘     └─────────────────┘
         │                       │                        │
         ▼                       ▼                        ▼
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│ Type Inference  │     │  Optimizations  │     │ Code Generation │
└─────────────────┘     └─────────────────┘     └─────────────────┘

🚦 CI/CD Integration

GitHub Actions Example

name: Transpile and Verify
on: [push, pull_request]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: dtolnay/rust-toolchain@stable

      - name: Install depyler
        run: cargo install depyler

      - name: Check Python compatibility
        run: depyler check src/**/*.py

      - name: Transpile to Rust
        run: depyler transpile src/ -o rust/ --verify

      - name: Run quality checks
        run: depyler quality-check src/**/*.py --strict

Toyota Way Quality Standards

This project exemplifies the Toyota Way philosophy through disciplined quality practices:

自働化 (Jidoka) - Build Quality In

• ZERO SATD: No TODO, FIXME, HACK, or placeholder implementations
• ZERO Incomplete: All features fully implemented with unreachable!() removed
• ZERO High Complexity: No function exceeds cyclomatic complexity of 20
• 100% Verification: All generated code must compile and pass tests

現地現物 (Genchi Genbutsu) - Go and See

• Real-World Testing: Validated against actual Python codebases
• Performance Profiling: Energy consumption measured on real hardware
• Direct Debugging: Debug at the generated Rust level, not just HIR

改善 (Kaizen) - Continuous Improvement

• v1.0.1: Fixed all SATD markers and incomplete implementations
• v1.0.2: Enhanced string optimization with interning and Cow
• Next: Lifetime analysis enhancements for better borrowing inference

🧪 Testing

# Run all tests
cargo test --workspace

# Run with coverage
cargo tarpaulin --out Html

# Run property tests
cargo test --features quickcheck

# Run benchmarks
cargo bench

# Run specific test suites
cargo test -p depyler-core        # Core transpilation
cargo test -p depyler-verify      # Verification
cargo test -p depyler-mcp         # MCP integration

Recent Updates

🚀 v2.3.0 - MCP and Quality Enhancements

• Updated MCP Integration: Upgraded pmcp SDK from 0.6.3 to 1.2.1
• PMAT Quality Integration: Added automatic quality validation for transpiled code
  • Quality scoring system (0-100) with pass/fail thresholds
  • Automated suggestions for improving code quality
  • Todo task management for multi-file projects
• New MCP Tools: Added pmat_quality_check tool for validating Rust code quality

🧪 v2.2.2 - Enhanced Test Coverage & Quality

• Improved Test Coverage: Achieved 70% line coverage with 350+ tests
  • Added comprehensive property-based tests for core modules
  • Added unit tests for migration_suggestions, direct_rules, lsp, module_mapper
  • Added doctests for all public APIs
  • Fixed interactive tests to be non-blocking in CI
• Advanced Testing Frameworks: Multiple testing paradigms
  • Property-based testing with custom generators
  • Mutation testing for code robustness
  • Multi-strategy fuzzing (security, unicode, performance)
  • Specialized coverage testing with error path analysis
• Quality Automation: Continuous monitoring and metrics
  • PMAT metrics dashboard with TDG scoring
  • Automated quality gates and thresholds
  • Performance regression detection
• CI/CD Integration: Comprehensive GitHub Actions workflows
  • Cross-platform testing matrix (Linux, macOS, Windows)
  • Automated release workflows
  • Quality gate enforcement

🛠️ v2.1.0 - Developer Tooling Suite

• IDE Integration (LSP): Full Language Server Protocol support
  • Symbol navigation, hover info, completions, diagnostics
  • Go-to-definition and find-references
• Debugging Support: Source mapping and debugger integration
  • Debug levels: None, Basic (line mapping), Full (variable state)
  • GDB/LLDB script generation
• Performance Profiling: Analyze transpiled code performance
  • Hot path detection and flamegraph generation
  • Performance predictions and optimization hints
• Documentation Generation: Auto-generate docs from Python
  • API references, usage guides, migration notes
  • Markdown and HTML output formats

🚀 v2.0.0 - Production Ready

• Optimization Framework: Dead code elimination, constant propagation
• Enhanced Diagnostics: Context-aware errors with suggestions
• Migration Analysis: Python-to-Rust idiom recommendations
• Performance Warnings: Detect O(n²) algorithms and inefficiencies
• Type Inference: Intelligent parameter and return type suggestions
• Function Inlining: Smart inlining with cost-benefit analysis

🎯 v1.x Series - Core Features

• v1.6.0: Extended standard library mappings (20+ modules)
• v1.5.0: Basic module system and imports
• v1.4.0: Async/await support
• v1.3.0: Advanced type features (with statements, iterators)
• v1.2.0: Full OOP support (classes, methods, properties)
• v1.1.0: Core language completeness (operators, collections)

🤝 Contributing

We welcome contributions! Please follow our quality standards:

1. Write tests first - TDD is mandatory
2. Maintain coverage - 85%+ for all new code
3. Zero warnings - cargo clippy -- -D warnings
4. Format code - cargo fmt
5. Document changes - Update relevant docs

See CONTRIBUTING.md for detailed guidelines.

📚 Documentation

• Agent Mode Guide - Background agent with MCP integration ✨
• API Documentation - Complete API reference
• Docker Guide - Container deployment
• Troubleshooting - Common issues and solutions
• Release Checklist - Release process guide
• Architecture - System architecture
• Changelog - Version history
• Contributing - Development guide

🚦 Roadmap

✅ v2.2 - Enterprise Testing (Released)

• Property-based testing framework
• Mutation testing infrastructure
• Security-focused fuzzing
• CI/CD integration with quality gates

✅ v2.1 - Developer Experience (Released)

• Complete IDE integration with LSP
• Comprehensive debugging support
• Performance profiling tools
• Documentation generation

✅ v2.0 - Production Ready (Released)

• Advanced optimization passes
• Enhanced error reporting
• Migration suggestions
• Performance analysis

✅ v1.x - Feature Complete (Released)

• Core language support
• Object-oriented programming
• Type system enhancements
• Async/await basics
• Module system
• Standard library mappings

🔮 v3.0 - Advanced Features (Future)

• Full generator support with yield
• Advanced decorator patterns
• Complete async ecosystem
• Package management integration

See ROADMAP.md for detailed plans.

📄 License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option.

Built with extreme quality standards by the Depyler team