Metadata-Version: 2.4
Name: tracelet
Version: 0.0.8
Summary: Tracelet is an automagic pytorch metric exporter
Author-email: Prassanna Ravishankar <me@prassanna.io>
Project-URL: Homepage, https://prassanna.io/tracelet/
Project-URL: Repository, https://github.com/prassanna-ravishankar/tracelet
Project-URL: Documentation, https://prassanna.io/tracelet/
Project-URL: Changelog, https://github.com/prassanna-ravishankar/tracelet/releases
Keywords: python,pytorch,machine-learning,experiment-tracking,mlops
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <4.0,>=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: gitpython
Requires-Dist: psutil
Requires-Dist: pydantic
Requires-Dist: pydantic-settings
Provides-Extra: mlflow
Requires-Dist: mlflow>=3.1.1; extra == "mlflow"
Provides-Extra: clearml
Requires-Dist: clearml>=1.15.0; extra == "clearml"
Provides-Extra: wandb
Requires-Dist: wandb>=0.16.0; extra == "wandb"
Provides-Extra: aim
Requires-Dist: aim>=3.17.0; python_version < "3.13" and extra == "aim"
Provides-Extra: pytorch
Requires-Dist: torch>=1.13.0; extra == "pytorch"
Requires-Dist: tensorboard>=2.15.0; extra == "pytorch"
Provides-Extra: lightning
Requires-Dist: pytorch-lightning>=2.0.0; extra == "lightning"
Provides-Extra: tensorboard
Requires-Dist: tensorboard>=2.15.0; extra == "tensorboard"
Provides-Extra: backends
Requires-Dist: mlflow>=3.1.1; extra == "backends"
Requires-Dist: clearml>=1.15.0; extra == "backends"
Requires-Dist: wandb>=0.16.0; extra == "backends"
Requires-Dist: aim>=3.17.0; python_version < "3.13" and extra == "backends"
Provides-Extra: frameworks
Requires-Dist: torch>=1.13.0; extra == "frameworks"
Requires-Dist: tensorboard>=2.15.0; extra == "frameworks"
Requires-Dist: pytorch-lightning>=2.0.0; extra == "frameworks"
Provides-Extra: all
Requires-Dist: mlflow>=3.1.1; extra == "all"
Requires-Dist: clearml>=1.15.0; extra == "all"
Requires-Dist: wandb>=0.16.0; extra == "all"
Requires-Dist: aim>=3.17.0; python_version < "3.13" and extra == "all"
Requires-Dist: torch>=1.13.0; extra == "all"
Requires-Dist: tensorboard>=2.15.0; extra == "all"
Requires-Dist: pytorch-lightning>=2.0.0; extra == "all"
Dynamic: license-file

# Tracelet

<p align="center">
  <img src="https://raw.githubusercontent.com/prassanna-ravishankar/tracelet/main/docs/tracelet.webp" alt="Tracelet Logo" width="200">
</p>

<p align="center">
  <a href="https://github.com/prassanna-ravishankar/tracelet/releases">
    <img src="https://img.shields.io/github/v/release/prassanna-ravishankar/tracelet" alt="Release">
  </a>
  <a href="https://github.com/prassanna-ravishankar/tracelet/actions">
    <img src="https://img.shields.io/github/actions/workflow/status/prassanna-ravishankar/tracelet/main.yml?branch=main" alt="Build">
  </a>
  <a href="https://github.com/prassanna-ravishankar/tracelet/blob/main/LICENSE">
    <img src="https://img.shields.io/github/license/prassanna-ravishankar/tracelet" alt="License">
  </a>
</p>

Tracelet is a Python library for tracking machine learning experiments. It works with popular backends like MLflow, Weights & Biases, ClearML, and AIM, and can automatically detect hyperparameters from your code.

## What it does

- Tracks metrics, parameters, and artifacts across ML backends
- Automatically captures hyperparameters without manual logging
- Integrates with PyTorch, PyTorch Lightning, and TensorBoard
- Handles models, checkpoints, images, and other ML artifacts
- Monitors system resources during training

## Installation

```bash
pip install tracelet
```

Install backend support as needed:

```bash
pip install tracelet[mlflow]     # For MLflow
pip install tracelet[wandb]      # For Weights & Biases
pip install tracelet[clearml]    # For ClearML
pip install tracelet[aim]        # For AIM
pip install tracelet[all]        # Everything
```

## Usage

### Basic Example

```python
from tracelet import Experiment

# Start tracking
exp = Experiment(name="my_experiment", backend=["mlflow"])
exp.start()

# Train your model
for epoch in range(10):
    loss = train_model()
    exp.log_metric("loss", loss, epoch)

exp.stop()
```

### Automatic Detection

```python
from tracelet import Experiment

# Enable automagic to detect hyperparameters automatically
exp = Experiment(name="auto_experiment", backend=["wandb"], automagic=True)
exp.start()

# Define hyperparameters normally - they're captured automatically
learning_rate = 0.001
batch_size = 32

# Your training code here
for epoch in range(epochs):
    loss = train_model()
    # Metrics logged automatically if using TensorBoard

exp.stop()
```

### PyTorch Lightning

```python
from tracelet import Experiment
import pytorch_lightning as pl

# Add to existing Lightning code
exp = Experiment(name="lightning_model", backend=["clearml"], automagic=True)
exp.start()

# Your existing code - all self.log() calls tracked automatically
trainer = pl.Trainer(max_epochs=10)
trainer.fit(model, datamodule)

exp.stop()
```

### Multiple Backends

```python
# Log to multiple backends simultaneously
exp = Experiment(
    name="comparison",
    backend=["mlflow", "wandb", "clearml"]
)
```

## Configuration

Set defaults with environment variables:

```bash
export TRACELET_PROJECT="my_project"
export TRACELET_BACKEND="mlflow"
export TRACELET_ENABLE_AUTOMAGIC="true"
```

Or programmatically:

```python
from tracelet.settings import TraceletSettings

settings = TraceletSettings(
    project="my_project",
    backend=["mlflow"],
    enable_automagic=True,
    track_system=True
)
```

## Examples

The `examples/` directory contains runnable examples:

- `01_manual_tracking/` - Basic usage examples
- `02_automagic_tracking/` - Automatic hyperparameter detection
- `03_backend_integrations/` - Backend-specific features
- `05_lightning_automagic/` - PyTorch Lightning integration

```bash
cd examples
python 01_manual_tracking/01_basic_manual.py
```

## Documentation

- [Documentation](https://prassanna-ravishankar.github.io/tracelet/)
- [API Reference](https://prassanna-ravishankar.github.io/tracelet/api/)
- [Configuration Guide](https://prassanna-ravishankar.github.io/tracelet/settings/)

## Development

```bash
git clone https://github.com/prassanna-ravishankar/tracelet.git
cd tracelet
uv sync
uv run pytest
```

## License

Apache License 2.0 - see [LICENSE](LICENSE) file.

## Support

- [Issues](https://github.com/prassanna-ravishankar/tracelet/issues) for bug reports
- [Discussions](https://github.com/prassanna-ravishankar/tracelet/discussions) for questions
