Hyperpilot
nglguarino/hyperpilot
Assistente IA para rastreamento e otimização de experimentos de ML
Ver no GitHubAssistente de pesquisa ML alimentado por Claude que rastreia experimentos, captura automaticamente arquiteturas de modelos, configurações de treinamento e métricas, então sugere melhorias baseado em análise inteligente do histórico completo. Integra-se nativamente com Jupyter e CLI.
Instalação
npx convez-ai nglguarino/hyperpilot1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Rastreamento automatizado de experimentos de deep learning
- Análise de padrões entre múltiplas rodadas de treinamento
- Geração de sugestões de melhoria baseadas em histórico completo
- Detecção e documentação de mudanças de código entre experimentos
Veredito

Ferramenta prática e bem arquitetada para pesquisadores ML que reduz overhead manual de rastreamento experimental. A integração com Claude para sugestões inteligentes é o diferencial real, embora exija ainda curva de aprendizado razoável para máximo proveito.
README
A tradução para o português deste README ainda está na fila.
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
- Track: Hyperpilot captures your experiments, code changes, and context
- Analyze: Code analyzer detects meaningful changes between experiments
- Compress: Context manager intelligently summarizes long histories
- 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
- Start experiments early: Call
start_experiment()before training - Log frequently: Log metrics at each epoch/step
- Use auto-tracking: Wrap models and dataloaders for automatic capture
- Analyze code changes: Call
analyze_code()when you modify training code - Export regularly: Save project state at end of each session
- 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:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - 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
Acknowledgments
Built with:
- Anthropic Claude for AI suggestions
- Rich for beautiful terminal output
- SQLite for data storage
Made with 💔 using Claude