Model Lifecycle

Models progress through four states. Promotion is gated by regulatory evaluations — any failed evaluation blocks the promotion with HTTP 422.

text

State machine

registered → staging → production → archived
                    ↘ (regulatory gate blocks) → blocked

Registering a Model

Register a new model version with metadata. After registration succeeds, the CompliancePipelineAgent fires automatically as a Celery task — it selects the appropriate regulatory frameworks for the model's jurisdiction and industry, runs all evaluations in parallel, and either auto-promotes on pass or routes to a Legal HITL approval queue on failure. Requires Celery workers to be running.

bash

POST /api/v1/registry/models

1curl -X POST https://sovereign.yourcompany.com/api/v1/registry/models \
2  -H "Authorization: Bearer $TOKEN" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "name": "fraud-detector-v3",
6    "version": "3.1.0",
7    "framework": "scikit-learn",
8    "workspace_id": "ws-finance-prod",
9    "metadata": { "accuracy": 0.943, "auc_roc": 0.971 }
10  }'

Promotion & Gating

Promotion is an asynchronous Celery task. On success: the previous champion is archived, an audit event is written, and stakeholders are notified via webhook. If any RegulatoryEvaluation for the model is in failed status, promotion returns HTTP 422 with the blocking evaluation details.

bash

Promote a model

curl -X POST https://sovereign.yourcompany.com/api/v1/registry/models/{model_id}/promote \
  -H "Authorization: Bearer $TOKEN" \
  -d '{ "workspace_id": "ws-finance-prod", "notes": "Q4 re-train" }'

A/B Traffic Splitting

Run champion/challenger experiments before full promotion. The gateway routes challenger_weight% of requests to the challenger. The evaluate_challenger_split Celery Beat task compares metrics and raises an ApprovalRequest if the challenger shows sustained gains.

bash

Create A/B split

curl -X POST /api/v1/registry/models/{model_id}/split \
  -d '{ "challenger_id": "model-uuid-challenger", "challenger_weight": 10, "workspace_id": "ws-prod" }'

Data Sources & Column-Level Lineage

Register training and evaluation datasets with column-level lineage tracking. Columns marked is_pii: true are flagged in compliance reports and surfaced in the lineage DAG. The DATA_LINEAGE and PII_MASKING compliance rules use this data.

Source type	Description
`snowflake`	Snowflake data warehouse (account, warehouse, database, schema)
`bigquery`	Google BigQuery (project, dataset, table)
`s3`	AWS S3 bucket/prefix (with IRSA)
`gcs`	Google Cloud Storage (with Workload Identity)
`postgres`	PostgreSQL direct connection
`uri`	Arbitrary HTTPS/s3://gs:// URI

External Governance Integration

Import models from external ML platforms and link them for governance. Provider credentials are Fernet-encrypted before storage.

Provider	Description
`sagemaker`	AWS SageMaker model registry
`azure_ml`	Azure Machine Learning
`databricks`	Databricks MLflow registry
`vertex_ai`	Google Vertex AI