aiprofile 1.0.2
AI-powered Python profiling tool with Claude AI insights and intelligent optimization recommendations
License: MIT
Requires Python: !=2.7.*,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,!=3.6.*,!=3.7.*,!=3.8.*,>=3.9
Keywords: profiling, performance, ai, claude, python, optimization, bottleneck-detection

# 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

```bash
cd aiprofile-cli

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

# Install dependencies
poetry install
```

### Setup API Key

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

### Run

```bash
# 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

```bash
# 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

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

### Code Quality

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

### Format Code

```bash
./scripts/format.sh
```

## Usage

### Basic Commands

```bash
# 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

```bash
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