README.md

---
title: OpenWB
emoji: 🚀
colorFrom: red
colorTo: red
sdk: docker
app_port: 8501
tags:
- streamlit
pinned: false
short_description: Streamlit template space
---

# 🤗 OpenWB - Free W&B Alternative

A free, open-source experiment tracking platform hosted on HuggingFace Spaces. Track your ML experiments with beautiful dashboards, all powered by HuggingFace infrastructure.

## ✨ Features

- 🔐 **HuggingFace Authentication** - Connect with your HF token
- 📊 **Interactive Dashboards** - Beautiful charts powered by Plotly
- 🚀 **Easy API** - Simple Python client for logging metrics
- 💾 **Free Storage** - Uses HuggingFace Hub for data persistence
- 🔄 **Real-time Updates** - Live dashboard updates
- 📈 **Multiple Chart Types** - Line plots, scatter plots, histograms
- 🎯 **Experiment Comparison** - Compare multiple runs
- 📋 **Configuration Tracking** - Store and view experiment configs

## 🚀 Quick Start

### 1. Deploy on HuggingFace Spaces

1. Go to [HuggingFace Spaces](https://huggingface.co/new-space)
2. Choose **Docker** as SDK
3. Select **Streamlit** template
4. Copy all the files from this repository
5. Deploy your space

### 2. Get Your API Key

1. Visit your deployed space
2. Connect with your HuggingFace token
3. Copy your generated API key from the dashboard

### 3. Install Client Library

```bash
pip install requests
```

### 4. Start Tracking

```python
from client import MLTracker

# Initialize tracker
tracker = MLTracker(
    api_key="your-api-key-here",
    base_url="https://your-space-name.hf.space"
)

# Start experiment
tracker.init("my_first_experiment", config={
    "model": "ResNet50",
    "dataset": "CIFAR-10",
    "learning_rate": 0.001,
    "batch_size": 32
})

# Log metrics during training
for epoch in range(100):
    # Your training code here
    loss = train_one_epoch()
    accuracy = evaluate_model()
    
    # Log to ML Tracker
    tracker.log({
        "loss": loss,
        "accuracy": accuracy,
        "epoch": epoch
    })

# Finish experiment
tracker.finish()
```

## 📁 Project Structure

```
ml-tracker/
├── Dockerfile              # HuggingFace Spaces Docker config
├── requirements.txt         # Python dependencies
├── app.py                  # Main Streamlit dashboard
├── api.py                  # FastAPI backend (optional)
├── client.py               # Python client library
└── README.md               # This file
```

## 🔧 Configuration

### Environment Variables

You can set these environment variables for easier usage:

```bash
export ML_TRACKER_API_KEY="your-api-key"
export ML_TRACKER_BASE_URL="https://your-space-name.hf.space"
```

### HuggingFace Space Settings

In your Space settings, you can:
- Enable/disable public access
- Set custom domain
- Configure hardware (upgrade for better performance)

## 💡 Usage Examples

### Basic Usage

```python
import mltracker

# Initialize with environment variables
mltracker.init("experiment_name", config={
    "model": "BERT",
    "dataset": "IMDB"
})

# Log metrics
mltracker.log({"loss": 0.5, "accuracy": 0.85})
mltracker.log({"loss": 0.3, "accuracy": 0.90})

# Finish
mltracker.finish()
```

### Advanced Usage

```python
from client import MLTracker

tracker = MLTracker(api_key="...", base_url="...")

# Multiple experiments
for lr in [0.001, 0.01, 0.1]:
    tracker.init(f"lr_{lr}", config={"learning_rate": lr})
    
    for epoch in range(10):
        # Training code
        loss = train_with_lr(lr)
        tracker.log({"loss": loss})
    
    tracker.finish()

# Get experiment data
experiments = tracker.get_experiments()
for exp in experiments:
    print(f"Experiment: {exp['experiment']}")
    print(f"Steps: {exp['total_steps']}")
```

### PyTorch Integration

```python
import torch
import torch.nn as nn
from client import MLTracker

# Initialize tracker
tracker = MLTracker(api_key="...", base_url="...")
tracker.init("pytorch_experiment", config={
    "model": "ResNet18",
    "optimizer": "Adam",
    "learning_rate": 0.001
})

# Training loop
model = resnet18()
optimizer = torch.optim.Adam(model.parameters(), lr=0.001)
criterion = nn.CrossEntropyLoss()

for epoch in range(100):
    for batch_idx, (data, target) in enumerate(train_loader):
        # Forward pass
        output = model(data)
        loss = criterion(output, target)
        
        # Backward pass
        optimizer.zero_grad()
        loss.backward()
        optimizer.step()
        
        # Log metrics
        if batch_idx % 100 == 0:
            tracker.log({
                "loss": loss.item(),
                "epoch": epoch,
                "batch": batch_idx
            })
    
    # Validation
    val_accuracy = evaluate(model, val_loader)
    tracker.log({"val_accuracy": val_accuracy})
```

## 🎨 Dashboard Features

### Metrics Visualization
- **Line Charts** - Track metrics over time
- **Multi-metric Plots** - Compare different metrics
- **Real-time Updates** - Live dashboard refresh

### Experiment Management
- **Experiment List** - View all your experiments
- **Configuration Viewer** - See experiment settings
- **Data Export** - Download raw data

### Comparison Tools
- **Multi-experiment View** - Compare different runs
- **Metric Filtering** - Focus on specific metrics
- **Time Range Selection** - Zoom into specific periods

## 🔒 Security

- **Token-based Auth** - Secure HuggingFace token authentication
- **API Key Management** - Unique API keys per user
- **Data Isolation** - Each user's data is separate
- **HTTPS Only** - All communication encrypted

## 🛠️ Development

### Local Development

```bash
# Clone repository
git clone https://github.com/yourusername/ml-tracker
cd ml-tracker

# Install dependencies
pip install -r requirements.txt

# Run locally
streamlit run app.py
```

### Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

## 📚 API Reference

### MLTracker Class

```python
class MLTracker:
    def __init__(self, api_key: str, base_url: str)
    def init(self, experiment_name: str, config: dict = None)
    def log(self, metrics: dict, step: int = None)
    def get_experiments(self) -> list
    def get_experiment(self, name: str) -> dict
    def delete_experiment(self, name: str)
    def finish(self)
```

### Global Functions

```python
def init(experiment_name: str, config: dict = None, api_key: str = None, base_url: str = None)
def log(metrics: dict, step: int = None)
def finish()
```

## 🤝 Support

- **Issues** - Report bugs on GitHub
- **Discussions** - Ask questions in GitHub Discussions
- **Documentation** - Check the wiki for detailed guides

## 📄 License

MIT License - See LICENSE file for details

## 🙏 Acknowledgments

- HuggingFace for providing free hosting
- Plotly for beautiful charts
- Streamlit for easy web apps
- The ML community for inspiration

---

**Happy Experimenting!** 🧪✨