> ## Documentation Index
> Fetch the complete documentation index at: https://ai.tharung.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Model Registry & Versioning

## 1. What is Model Registry?

A **Model Registry** is a centralized system used to store, manage, version, and track machine learning models.

Instead of keeping trained models as random files:

```text theme={null}
model.pkl
model_final.pkl
model_final_v2.pkl
model_latest.pkl
```

a registry provides an organized structure:

```text theme={null}
Model Registry
│
├── Model: DiabetesRegressor
│   ├── Version 1
│   ├── Version 2
│   └── Version 3
```

A registry can store information such as:

* Model name
* Model version
* Model artifacts
* Training metrics
* Model parameters
* Creation time
* Model stage/status
* Metadata

***

# 2. Why Model Versioning?

Model versioning makes it possible to keep multiple versions of a trained model.

Example:

```text theme={null}
DiabetesRegressor
│
├── v1.0.0 → Initial model
├── v1.1.0 → Improved preprocessing
└── v2.0.0 → New model architecture
```

If version 2 introduces a problem, version 1 can be restored.

***

# 3. Semantic Versioning

Semantic Versioning, commonly called **SemVer**, uses:

```text theme={null}
MAJOR.MINOR.PATCH
```

Example:

```text theme={null}
2.4.1
```

### MAJOR

Used when there are incompatible changes.

```text theme={null}
1.0.0 → 2.0.0
```

Example:

* Completely different model architecture
* Input format changed
* Prediction interface changed

### MINOR

Used when new functionality is added without breaking compatibility.

```text theme={null}
1.2.0 → 1.3.0
```

Example:

* Additional features
* Improved model
* New preprocessing capability

### PATCH

Used for small fixes.

```text theme={null}
1.3.0 → 1.3.1
```

Example:

* Bug fix
* Configuration correction
* Minor improvement

***

# 4. Model Registry Workflow

```text theme={null}
Train Model
     ↓
Evaluate Model
     ↓
Save Model
     ↓
Register Model
     ↓
Assign Version
     ↓
Store Metadata
     ↓
Load Specific Version
     ↓
Deploy
```

***

# 5. MLflow Model Registry

For the MLflow-based workflow, **MLflow Model Registry** can be used to manage model versions.

The basic architecture is:

```text theme={null}
Training Code
     │
     ▼
MLflow Run
     │
     ├── Parameters
     ├── Metrics
     └── Model
          │
          ▼
    Model Registry
          │
     ┌────┴────┐
     ▼         ▼
   v1.0.0    v2.0.0
```

***

# 6. Install MLflow

```bash theme={null}
pip install mlflow scikit-learn
```

***

# 7. Simple Model Registry Example

### `model_registry.py`

```python theme={null}
import mlflow
import mlflow.sklearn

from sklearn.datasets import load_diabetes
from sklearn.linear_model import LinearRegression
from sklearn.model_selection import train_test_split
from sklearn.metrics import mean_squared_error, r2_score


# 1. Set MLflow tracking database
mlflow.set_tracking_uri("sqlite:///mlflow.db")


# 2. Create or select experiment
mlflow.set_experiment("Model Registry Demo")


# 3. Load dataset
data = load_diabetes()

X = data.data
y = data.target


# 4. Split dataset
X_train, X_test, y_train, y_test = train_test_split(
    X,
    y,
    test_size=0.2,
    random_state=42
)


# 5. Start MLflow run
with mlflow.start_run() as run:

    # 6. Create model
    model = LinearRegression()

    # 7. Train model
    model.fit(X_train, y_train)

    # 8. Generate predictions
    predictions = model.predict(X_test)

    # 9. Calculate metrics
    mse = mean_squared_error(y_test, predictions)
    r2 = r2_score(y_test, predictions)

    # 10. Log parameters
    mlflow.log_param("model", "LinearRegression")
    mlflow.log_param("test_size", 0.2)
    mlflow.log_param("random_state", 42)

    # 11. Log metrics
    mlflow.log_metric("mse", mse)
    mlflow.log_metric("r2", r2)

    # 12. Register model
    model_info = mlflow.sklearn.log_model(
        sk_model=model,
        name="diabetes_model",
        registered_model_name="DiabetesRegression"
    )

    print("Model registered successfully")
    print(f"MSE: {mse:.4f}")
    print(f"R2 Score: {r2:.4f}")
    print(f"Run ID: {run.info.run_id}")
```

**version 2: changing the test size**

```python theme={null}
# 4. Split dataset
X_train, X_test, y_train, y_test = train_test_split(
    X, y, test_size=0.3, random_state=42
)

    # 10. Log parameters
    mlflow.log_param("model", "LinearRegression")
    mlflow.log_param("test_size", 0.3)
    mlflow.log_param("random_state", 42)
```

***

# 8. Important Part: Registering the Model

This section registers the trained model:

```python theme={null}
mlflow.sklearn.log_model(
    sk_model=model,
    name="diabetes_model",
    registered_model_name="DiabetesRegression"
)
```

The important parameter is:

```python theme={null}
registered_model_name="DiabetesRegression"
```

MLflow creates a registered model called:

```text theme={null}
DiabetesRegression
```

A new model version can be created when another run registers the same model name.

For example:

```text theme={null}
DiabetesRegression
│
├── Version 1
├── Version 2
└── Version 3
```

***

# 9. Start MLflow UI

Run:

```bash theme={null}
mlflow ui --backend-store-uri sqlite:///mlflow.db
```

Open:

```text theme={null}
http://127.0.0.1:5000
```

The MLflow UI can be used to inspect:

```text theme={null}
Experiments
   ↓
Runs
   ↓
Parameters
Metrics
Artifacts
Models
```

The registered model can be viewed from the **Models** section.

***

# 10. Load a Specific Model Version

A registered model can be loaded using its name and version.

```python theme={null}
import mlflow.sklearn

model = mlflow.sklearn.load_model(
    "models:/DiabetesRegression/1"
)
```

Here:

```text theme={null}
DiabetesRegression
```

is the model name.

```text theme={null}
1
```

is the model version.

***

# 11. Make Predictions Using the Loaded Model

```python theme={null}
import mlflow.sklearn

from sklearn.datasets import load_diabetes


# Load version 1
model = mlflow.sklearn.load_model(
    "models:/DiabetesRegression/1"
)


# Load data
data = load_diabetes()

X = data.data


# Generate predictions
predictions = model.predict(X[:5])

print("Predictions:")
print(predictions)
```

***

# 12. Load Different Versions

Version 1:

```python theme={null}
model = mlflow.sklearn.load_model(
    "models:/DiabetesRegression/1"
)
```

Version 2:

```python theme={null}
model = mlflow.sklearn.load_model(
    "models:/DiabetesRegression/2"
)
```

Version 3:

```python theme={null}
model = mlflow.sklearn.load_model(
    "models:/DiabetesRegression/3"
)
```

This allows a specific model version to be selected.

***

# 13. Model Version Example

Suppose three training runs are performed.

```text theme={null}
Run 1
MSE = 3200
R²  = 0.40
      ↓
DiabetesRegression v1
```

Then an improved model:

```text theme={null}
Run 2
MSE = 2800
R²  = 0.52
      ↓
DiabetesRegression v2
```

Another improvement:

```text theme={null}
Run 3
MSE = 2500
R²  = 0.60
      ↓
DiabetesRegression v3
```

The registry now contains:

```text theme={null}
DiabetesRegression
│
├── v1 → R² 0.40
├── v2 → R² 0.52
└── v3 → R² 0.60
```

***

# 14. Model Lifecycle

A model can move through different lifecycle states depending on the registry workflow.

Typical workflow:

```text theme={null}
Development
     ↓
Validation
     ↓
Staging
     ↓
Production
     ↓
Archived
```

For example:

```text theme={null}
DiabetesRegression v3
        ↓
     Staging
        ↓
     Testing
        ↓
   Production
```

***

# 15. Model Registry vs Experiment Tracking

These concepts are related but different.

| Feature                     | Experiment Tracking | Model Registry            |
| --------------------------- | ------------------- | ------------------------- |
| Parameters                  | Yes                 | Metadata                  |
| Metrics                     | Yes                 | Metadata                  |
| Artifacts                   | Yes                 | Model artifacts           |
| Training runs               | Yes                 | Related to model versions |
| Model versions              | Limited             | Yes                       |
| Model lifecycle             | No/limited          | Yes                       |
| Production model management | No                  | Yes                       |

### Experiment Tracking

Answers:

> How was this model trained?

Example:

```text theme={null}
Learning rate = 0.01
Epochs = 20
R² = 0.91
```

### Model Registry

Answers:

> Which model version should be used?

Example:

```text theme={null}
FraudModel v3
```

***

# 16. Recommended Model Naming

Use descriptive names:

```text theme={null}
DiabetesRegression
CustomerChurnModel
FraudDetectionModel
RecommendationModel
SentimentClassifier
```

Avoid names such as:

```text theme={null}
model1
finalmodel
newmodel
bestmodel
testmodel
```

***

# 17. Important Model Metadata

A production model registry should ideally track:

```text theme={null}
Model Name
Version
Framework
Training Dataset
Features
Parameters
Metrics
Training Run
Model Artifact
Created Time
Author
Model Status
```

Example:

```text theme={null}
Model: DiabetesRegression
Version: 2
Framework: Scikit-learn
Algorithm: LinearRegression
MSE: 2800
R²: 0.52
Status: Production
```

***

# 18. Complete Model Lifecycle

```text theme={null}
             Dataset
                │
                ▼
          Train Model
                │
                ▼
        Evaluate Model
                │
          ┌─────┴─────┐
          │           │
       Poor Model   Good Model
          │           │
       Retrain       ▼
                Log to MLflow
                      │
                      ▼
                Model Registry
                      │
               ┌──────┴──────┐
               ▼             ▼
             v1.0.0        v1.1.0
               │             │
               └──────┬──────┘
                      ▼
                   Staging
                      │
                      ▼
                 Production
```

***

## Key Concepts

* **Model Registry** - centralized management of trained model versions.
* **Model Version** - a specific registered instance of a model.
* **Semantic Versioning** - `MAJOR.MINOR.PATCH` version format.
* **Experiment Tracking** - records parameters, metrics, artifacts, and training runs.
* **Model Registry** - manages model versions and lifecycle.
* **Model Artifact** - saved trained model that can be loaded later.
* **Rollback** - switching back to an earlier model version.
* **Staging** - model validation environment before production.
* **Production** - model version currently used by an application.
* **Archived** - old model version retained for historical purposes.

### File

```text theme={null}
Day 48 - Model Registry/
│
├── model_registry.py
└── mlflow.db
```