AI Profiler CLI - Production Edition

Professional-grade AI-powered Python profiling tool with Claude AI insights and intelligent optimization recommendations.

✨ Features

• 🔍 Industrial-Strength Profiling - CPU and memory profiling with Scalene (5-10% overhead)
• 🤖 AI-Powered Analysis - Get actionable optimization suggestions from Claude AI
• 📊 Detailed Metrics - Per-function CPU breakdown, memory hotspots, and call counts
• 🎨 Beautiful Terminal Output - Rich formatting with tables, colors, and progress indicators
• ⚡ Zero Configuration - Works out of the box with sensible defaults
• 🌐 Web Integration - Upload results to the web platform for sharing and team collaboration

Quick Start

Installation

cd aiprofile-cli

# Install Poetry if needed
curl -sSL https://install.python-poetry.org | python3 -

# Install dependencies
poetry install

Setup API Key

export ANTHROPIC_API_KEY="your-api-key-here"

Run

# Profile a script
poetry run aiprofile run your_script.py

# With arguments
poetry run aiprofile run script.py --input data.csv

# Skip AI analysis (no API key needed)
poetry run aiprofile run script.py --no-analysis

Example

# Try with included examples
poetry run aiprofile run examples/simple_script.py
poetry run aiprofile run examples/slow_script.py

Project Structure

aiprofile-cli/
├── packages/cli/src/cli/
│   ├── profilers/           # Profiler implementations (Scalene)
│   ├── runner/              # Script execution (Python runner)
│   ├── ai/                  # Claude AI analyzer
│   ├── formatter/           # Rich terminal output
│   ├── models/              # Data models (generic + Python-specific)
│   ├── core/                # Core utilities (detector, logger, errors)
│   ├── commands.py          # CLI commands
│   └── main.py              # Typer CLI entry point
├── examples/python/         # Example Python scripts
├── tests/                   # Test suite
├── pyproject.toml           # Poetry configuration
├── pytest.ini               # Pytest configuration
└── README.md                # This file

Architecture Notes

The codebase is designed for extensibility:

• Generic Base Classes: Profiler, ScriptRunner, data models support multiple languages
• Language Detection: Automatic detection + override support in core/detector.py
• Future Support: Adding a new language requires:
  1. New profiler in profilers/<language>/
  2. New runner in runner/<language>_runner.py
  3. Updates to detector.py
  4. No changes to CLI or AI analysis logic needed

Development

Run Tests

poetry run pytest
# or
./scripts/test.sh

Code Quality

poetry run black .
poetry run ruff check .
poetry run mypy packages/*/src
# or
./scripts/lint.sh

Format Code

./scripts/format.sh

Usage

Basic Commands

# Get help
poetry run aiprofile --help

# Show version
poetry run aiprofile version

# Profile with custom duration
poetry run aiprofile run script.py --duration 60

Activate Poetry Shell

poetry shell
aiprofile run script.py  # No need for 'poetry run' prefix

How It Works

1. Profile - Runs Scalene on your Python script to collect CPU and memory metrics
2. Analyze (optional) - Sends profiling data to Claude for AI-powered analysis and recommendations
3. Display - Shows beautiful terminal output with tables, metrics, and actionable suggestions
4. Upload (optional) - Share results on the web platform for team collaboration

Sampling Rates & Accuracy

Uses carefully tuned sampling rates for production use [[memory:10987753]]:

• CPU: 1000 Hz (1ms sampling) for millisecond-level function breakdown
• Memory: 100 Hz (10ms sampling) for allocation tracking
• Overhead: ~5-10% - efficient enough for CI/CD pipelines

Requirements

• Python 3.9+ (tested on 3.9, 3.10, 3.11, 3.12)
• Poetry (for dependency management)
• Anthropic API key (optional, only needed for AI analysis feature)

Example Output

🔍 AI Profiler
━━━━━━━━━━━━━━━━━━━━

CPU Profile Results
Duration: 10.5s | Samples: 1050

╭─────────────── Top Functions by CPU Time ────────────────╮
│ Rank │ Function              │ CPU %    │ Time (s) │
├──────┼──────────────────────┼──────────┼──────────┤
│ 1    │ cpu_intensive_loop    │ 45.23%   │ 4.75     │
│ 2    │ nested_loops          │ 28.45%   │ 2.99     │
╰──────────────────────────────────────────────────────────╯

🤖 AI Analysis - Claude Insights
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🥇 Bottleneck #1: cpu_intensive_loop
   CPU: 45.2%
   
   Optimization Suggestions:
   1. Use list comprehension instead of loop
      Improvement: 30-40% faster | Difficulty: Low

Use Cases

• Performance Optimization - Identify bottlenecks in production code
• Debugging - Find memory leaks and unexpected CPU usage patterns
• Code Review - Share profiling data with your team
• Benchmarking - Compare performance before and after changes
• Education - Understand how your code executes at runtime
• CI/CD Integration - Profile tests and builds automatically

Production Status

✅ Production-Ready (v1.0.0)

• Thoroughly tested on Python 3.9-3.12
• Uses industry-standard Scalene profiler
• Minimal overhead (~5-10% CPU)
• Comprehensive error handling
• Type-safe with mypy checks
• Well-documented codebase

Open Source + Premium Model

This tool follows an open-source + web platform business model:

• aiprofile-cli (this repo) - Free, open-source profiler
• aiprofile-web - Premium web platform with:
  • Beautiful result visualizations
  • Team collaboration features
  • Historical trend tracking
  • Custom alerts and automation
  • API access for CI/CD integration
  • Shareable reports

Contributing

Contributions welcome! Areas for enhancement:

• Additional language support (Go, Rust, Node.js, Java)
• Performance optimizations
• Better error messages
• Documentation improvements
• Example scripts for various use cases

Future Roadmap

• Support for additional languages (Go, Rust, Node.js)
• GPU profiling support (PyTorch, TensorFlow metrics)
• Distributed tracing integration
• Custom metrics/annotations
• Export formats (Flamegraph, Speedscope, etc.)

License

MIT - See LICENSE file for details