model-registry

# Model Registry

## Overview

Centralized system for managing ML model lifecycle: versioning, staging (dev/staging/prod), metadata tracking, lineage, and rollback. Ensures production models are tracked, reproducible, and can be safely deployed or rolled back—all integrated with SpecWeave's increment workflow.

## Why Model Registry Matters

**Without Model Registry**:
- ❌ "Which model is in production?"
- ❌ "Can't reproduce model from 3 months ago"
- ❌ "Breaking change deployed, how to rollback?"
- ❌ "Model metadata scattered across notebooks"
- ❌ "No audit trail for model changes"

**With Model Registry**:
- ✅ Single source of truth for all models
- ✅ Full version history with metadata
- ✅ Safe staging pipeline (dev → staging → prod)
- ✅ One-command rollback
- ✅ Complete model lineage
- ✅ Audit trail for compliance

## Model Registry Structure

### Model Lifecycle Stages

```
Development → Staging → Production → Archived

Dev:      Training, experimentation
Staging:  Validation, A/B testing (10% traffic)
Prod:     Production deployment (100% traffic)
Archived: Decommissioned, kept for audit
```

## Core Operations

### 1. Model Registration

```python
from specweave import ModelRegistry

registry = ModelRegistry(increment="0042")

# Register new model version
model_version = registry.register_model(
    name="fraud-detection-model",
    model=trained_model,
    version="v3",
    metadata={
        "algorithm": "XGBoost",
        "accuracy": 0.87,
        "precision": 0.85,
        "recall": 0.62,
        "training_date": "2024-01-15",
        "training_data_version": "v2024-01",
        "hyperparameters": {
            "n_estimators": 673,
            "max_depth": 6,
            "learning_rate": 0.094
        },
        "features": feature_names,
        "framework": "xgboost==1.7.0",
        "python_version": "3.10",
        "increment": "0042"
    },
    stage="dev",  # Initial stage
    tags=["fraud", "production-candidate"]
)

# Creates:
# - Model artifact (mo