Hyperpilot 🧑‍🚀

Intelligent ML Research Assistant Powered by Claude.

What is Hyperpilot?

Hyperpilot helps ML practitioners and researchers track experiments and get intelligent suggestions for improvements. It automatically captures:

• Model architectures (layer counts, parameters)
• Dataset information (size, augmentations, preprocessing)
• Training configurations (optimizers, loss functions, schedulers)
• Code changes (what changed and why it matters)
• Metrics over time (training curves, validation scores)

Then uses Claude AI to analyze your complete experiment history and suggest what to try next.

Installation

pip install hyperpilot

Or install from source:

git clone https://github.com/nglguarino/hyperpilot.git
cd hyperpilot
pip install -e .

Quick Start

from hyperpilot import quick_start

# One-line setup
tracker, auto = quick_start(project="my_project")

# Your model
model = YourModel()
model = auto.wrap_model(model)  # Auto-captures architecture

# Start experiment
exp_id = tracker.start_experiment("baseline", config={"lr": 0.001})
auto.set_experiment(exp_id)

# Training loop
for epoch in range(epochs):
    # Your training code
    tracker.log_metrics(exp_id, {"loss": loss, "acc": acc}, step=epoch)

# End and get suggestions
tracker.end_experiment(exp_id, final_metrics={"test_acc": 0.89})
tracker.suggest_improvements(exp_id)

Features

🎯 Automatic Context Capture

from hyperpilot import AutoTracker

auto = AutoTracker(tracker)

# Automatically captures everything
model = auto.wrap_model(model)
train_loader = auto.wrap_dataloader(train_loader)
auto.capture_training_config(optimizer, loss_fn, scheduler)

🔍 Code Change Detection

# Analyze what changed in your code
tracker.analyze_code("train_v2.py")

# Compare experiments
tracker.compare_with_previous(exp_id)

🤖 AI-Powered Suggestions

# Get intelligent suggestions based on full history
tracker.suggest_improvements(exp_id, max_suggestions=5)

💾 Session Management

# Export your project state
tracker.export_project_state("./backup.json.gz")

# Resume later
tracker.import_project_state("./backup.json.gz")

# Generate context for Claude chat
context = tracker.get_claude_context()

📓 Jupyter Integration

# In notebook
%load_ext hyperpilot.notebook_magic
%hyperpilot_init my_project

# Start experiment
%hyperpilot_start baseline lr=0.001 batch_size=32

# Auto-track cell
%%hyperpilot_track
model = ResNet18()
optimizer = torch.optim.Adam(model.parameters())

# Log metrics
%hyperpilot_log loss=0.5 acc=0.89 step=10

# Get suggestions
%hyperpilot_suggest

🖥️ Command Line Interface

# List experiments
hyperpilot list --project my_project

# Analyze code
hyperpilot analyze train.py --project my_project

# Compare experiments
hyperpilot compare 41 42 --detailed

# Get suggestions
hyperpilot suggest 42

# Export/import
hyperpilot export ./backup.json.gz
hyperpilot import ./backup.json.gz

# Generate Claude context
hyperpilot context --output context.md

How It Works

1. Track: Hyperpilot captures your experiments, code changes, and context
2. Analyze: Code analyzer detects meaningful changes between experiments
3. Compress: Context manager intelligently summarizes long histories
4. Suggest: Claude analyzes patterns and suggests what to try next

Smart Context Compression

For projects with 100+ experiments, Hyperpilot:

• Shows recent experiments in full detail
• Summarizes older experiments
• Extracts key learnings and patterns
• Keeps everything within Claude's context window

Examples

See hyperpilot/examples.py for comprehensive examples:

• Basic tracking
• Auto-tracking
• Code analysis
• Session management
• Full workflow

Framework Support

Framework-agnostic. Works with any Python ML framework:

• ✅ PyTorch
• ✅ TensorFlow / Keras
• ✅ JAX
• ✅ scikit-learn

Configuration

Set your Anthropic API key:

export ANTHROPIC_API_KEY="your-key-here"

Or pass it directly:

tracker = ExperimentTracker(project="my_project", api_key="your-key")

Architecture

hyperpilot/
├── tracker.py          # Main interface
├── storage.py          # SQLite database
├── advisor.py          # AI suggestions
├── code_analyzer.py    # Code change detection
├── context_manager.py  # Smart context compression
├── auto_tracker.py     # Automatic instrumentation
├── session_manager.py  # Export/import
├── notebook_magic.py   # Jupyter integration
└── cli.py              # Command line interface

Why Hyperpilot?

vs MLflow/Weights & Biases:

• Lightweight, local-first
• No server setup required
• AI-powered suggestions (not just tracking)
• Smart context compression

vs Manual tracking:

• Automatic code change detection
• Structured storage
• AI analysis of patterns
• Easy to resume sessions

Use Cases

Iterative Model Development

# Day 1: Baseline
tracker, auto = quick_start(project="image_classifier")
exp_id = tracker.start_experiment("baseline", config={"lr": 0.001})
# ... training ...
tracker.suggest_improvements(exp_id)

# Day 2: Resume and improve
tracker.import_project_state("./backup.json.gz")
# Try Claude's suggestions
exp_id = tracker.start_experiment("improved", config={"lr": 0.0005})

Hyperparameter Search with Intelligence

# Instead of random search, let Claude guide you
for i in range(10):
    suggestions = tracker.suggest_improvements(last_exp_id)
    # Parse suggestions and try them
    config = extract_config_from_suggestions(suggestions)
    exp_id = tracker.start_experiment(f"guided_{i}", config)
    # ... training ...

Team Collaboration

# Team member 1
hyperpilot export ./team_experiments.json.gz

# Team member 2
hyperpilot import ./team_experiments.json.gz
hyperpilot list --best --limit 10
hyperpilot suggest 42  # Get suggestions based on team's history

Research Paper Experiments

# Track all experiments for paper
tracker = ExperimentTracker(project="paper_experiments")

# Ablation studies
for component in ["dropout", "batch_norm", "augmentation"]:
    exp_id = tracker.start_experiment(f"ablation_{component}", config={...})
    # ... training ...
    
# Generate summary for paper
context = tracker.get_claude_context()
# Upload to Claude: "Help me write the experiments section"

Best Practices

1. Start experiments early: Call start_experiment() before training
2. Log frequently: Log metrics at each epoch/step
3. Use auto-tracking: Wrap models and dataloaders for automatic capture
4. Analyze code changes: Call analyze_code() when you modify training code
5. Export regularly: Save project state at end of each session
6. Review suggestions: Let Claude guide your next experiments

Troubleshooting

API Key Issues

# Set via environment variable
export ANTHROPIC_API_KEY="your-key"

# Or pass directly
tracker = ExperimentTracker(project="test", api_key="your-key")

Database Locks

If you get database lock errors, ensure only one process accesses the database at a time.

Notebook Path Detection

If notebook analysis fails, manually specify the path:

tracker.analyze_code("/path/to/notebook.ipynb")

Roadmap

• Visualization dashboard
• Multi-project comparison
• Integration with popular ML frameworks (Hugging Face, Lightning)
• Cloud backup support
• Team collaboration features

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see LICENSE file for details.

Citation

If you use Hyperpilot in your research, please cite:

@software{hyperpilot2025,
  author = {Angelo Guarino},
  title = {Hyperpilot: AI Research Companion},
  year = {2025},
  url = {https://github.com/nglguarino/hyperpilot}
}

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

Acknowledgments

Built with:

• Anthropic Claude for AI suggestions
• Rich for beautiful terminal output
• SQLite for data storage

---

Made with 💔 using Claude