Update README.md

README.md

@@ -11,9 +11,286 @@ pinned: false
 short_description: Streamlit template space
 ---
 
-# Welcome to Streamlit!
+# 🤗 ML Tracker - Free W&B Alternative
 
-Edit `/src/streamlit_app.py` to customize this app to your heart's desire. :heart:
+A free, open-source experiment tracking platform hosted on HuggingFace Spaces. Track your ML experiments with beautiful dashboards, all powered by HuggingFace infrastructure.
 
-If you have any questions, checkout our [documentation](https://docs.streamlit.io) and [community
-forums](https://discuss.streamlit.io).
+## ✨ 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!** 🧪✨