First Login & Workspace Setup

When your administrator provisions your account you will receive an invitation email with a link to the platform. Click the link and sign in via your organisation's SSO provider (Azure AD, Okta, Google, etc.). On first login you are placed into your default workspace. A workspace is an isolated environment with its own models, LLM routing policies, compliance configuration, and audit log.

Persona	Default Role	What you can do
Data Scientist / ML Engineer	`dev`	Register models, view compliance reports, run evaluations, view audit log
MLOps / Platform Engineer	`ops`	All dev permissions + deploy models, approve HITL requests, manage clusters
Compliance Officer / Legal	`legal`	Approve or reject GitOps manifests and promotions, download audit packages, view all compliance reports
Platform Administrator	`admin`	All operations — user management, workspace creation, IdP configuration, key rotation

Workspace overview — The workspace landing page after sign-in — KPI cards, system health, and the model registry, all scoped to the selected workspace.

Inviting Your Team

Navigate to Settings → Team Members → Invite. Enter the email address and assign a role. The invitee receives a link valid for 48 hours. If your organisation uses SCIM provisioning (Okta, Azure AD), users are provisioned automatically — no manual invitations needed. Role assignments sync from your IdP's group mapping configuration.

bash

Invite a user via API (admin only)

1curl -X POST https://sovereign.yourcompany.com/api/v1/workspaces/WS_ID/invitations \
2  -H "Authorization: Bearer $ADMIN_TOKEN" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "email": "sarah.chen@yourcompany.com",
6    "role": "legal",
7    "expires_in_hours": 48
8  }'

Registering a Model

Go to Model Registry in the left navigation, then click Register New Model. Fill in the required fields and submit. The CompliancePipelineAgent starts automatically — you will see the model status change from registered → evaluating → passed or blocked within 5 minutes.

Field	Required	Notes
Model name	Yes	Lowercase, hyphens allowed. E.g. `fraud-detection`
Version	Yes	Semantic version. E.g. `v4.0.0`
Framework	Yes	scikit-learn, PyTorch, TensorFlow, XGBoost, Hugging Face, Custom
Task type	Yes	classification, regression, nlp, vision, recommendation, other
Artifact URI	Yes	S3/GCS/Azure Blob path to the serialised model file
Training dataset	Recommended	Name or URI — appears in the auto-generated model card
MLflow Run ID	Optional	Links training run metadata and params to the registry entry
Tags	Optional	Key-value pairs. E.g. `team: risk`, `env: staging`
Intended use	Recommended	Free text — included in model card for regulatory reviewers

Reviewing Compliance Evaluation Results

Once the CompliancePipelineAgent finishes (typically 3–5 minutes), navigate to Model Registry → select your model → Compliance tab. You will see a score for each active framework (0–100). Click any framework to expand the per-control breakdown. Controls marked ⚠️ have findings with specific remediation guidance generated by the RemediationSuggestionAgent.

Score range	Status	What happens next
90–100	Pass — Excellent	Model eligible for promotion immediately
75–89	Pass — Good	Model eligible for promotion; findings are informational
60–74	Warning — Review Required	HITL request created for Legal sign-off before promotion
0–59	Blocked	Promotion blocked; IncidentResponseAgent creates JIRA ticket with remediation plan

Compliance dashboard — Compliance posture by framework — overall health gauge, per-model compliant/non-compliant status, and remediation recommendations.

Reviewing and Completing the Model Card

The model card is auto-populated with data from your registration payload, MLflow run (if linked), and the completed compliance evaluation. Navigate to Model Registry → select your model → Model Card. Review the auto-filled fields, then complete any empty required sections (Intended Use, Known Limitations, Ethical Considerations). Model cards export as PDF (for regulatory submission) or JSON (for downstream tooling).

Reviewing Bias Evaluation Results

Navigate to Model Registry → select your model → Bias tab. The bias evaluation runs alongside the compliance evaluation. The primary metric is the Disparate Impact Ratio (DIR) — a value ≥ 0.80 per protected group is required to pass. Groups shown depend on which demographic features are present in your evaluation dataset. If a group shows DIR < 0.80, expand the row to see the outcome rate breakdown and the remediation recommendation (typically retraining data rebalancing).

Promoting a Model to Production

When all promotion gates pass (compliance score, bias DIR, robustness score, approval workflow), the Promote button becomes active on the model detail page. Click Promote → select the target environment → click Confirm. If your workspace has an approval workflow configured, the promotion enters Pending Approval state and Legal and CISO reviewers are notified by email and Slack. Reviewers can approve or reject directly from the platform UI or via the MCP Server in Claude Code.

bash

Check promotion gate status via API

1curl https://sovereign.yourcompany.com/api/v1/models/mdl_fraud_v4/promotion-gates \
2  -H "Authorization: Bearer $TOKEN"
3# → {
4#     "eligible": true,
5#     "gates": [
6#       { "gate": "compliance_score", "passed": true, "value": 91 },
7#       { "gate": "bias_dir",         "passed": true, "value": 0.94 },
8#       { "gate": "robustness",       "passed": true, "value": 0.78 },
9#       { "gate": "approval_workflow","passed": true, "approvals": 2 }
10#     ]
11#   }

Configuring the LLM Gateway

Navigate to LLM Gateway in the left navigation. The Gateway section has three tabs: Routing Policies, Route Simulator, and Usage Analytics.

Tab	What you can do
Routing Policies	Set classification tiers (PUBLIC / INTERNAL / CONFIDENTIAL / PII / PHI) and assign each to a provider endpoint. Toggle PII masking on or off per tier.
Route Simulator	Paste any prompt and see which tier it would receive, which endpoint it would route to, and which tokens would be masked — without sending it to any LLM.
Usage Analytics	View token usage by model, provider, and date range. Set monthly budget caps and download chargeback CSV reports for finance.

Monitoring for Drift

Navigate to Monitoring → Drift Dashboard. Production models are checked automatically every 60 minutes. The dashboard shows the latest PSI score for each model (colour-coded: green < 0.10, amber 0.10–0.24, red ≥ 0.25). Click any model to view the full drift report: per-feature PSI breakdown, historical trend chart, and the baseline captured at promotion time. To trigger an immediate check, click Run Drift Check on the model detail page.

Using the Audit Log

Navigate to Audit Log in the left navigation. Every action on the platform is recorded here — model registrations, compliance evaluations, promotions, demotions, LLM gateway blocks, and user login events. Use the filters to narrow by event type, date range, model, or user. Click Verify Chain to confirm the cryptographic hash chain is intact from the current entry back to genesis. For regulatory submissions, click Export CSV to download the full log for the selected date range.

Approval Workflows (Legal & CISO Reviewers)

If you have the legal role, navigate to Approvals in the left navigation to see all pending requests. Each request shows the model name, version, compliance scores, and the specific promotion being requested. Click Review to see the full compliance report and model card before making a decision. Click Approve to allow the promotion or Reject with a required comment (recorded in the audit chain). You can also approve via the MCP Server in Claude Code: type 'show me pending approvals' and 'approve model credit-risk-v2'.

Executive Dashboard

Navigate to Dashboard in the left navigation. The dashboard has three persona views selectable via the dropdown at the top right. The Legal view shows compliance pass rates by framework and overdue review requests. The Ops view shows model health, drift alerts, and LLM gateway cost by team. The Dev view shows recent model registrations, evaluation queue, and upcoming promotion deadlines. The GovernanceReportingAgent sends a formatted summary of this dashboard data to your configured Slack channel every Monday at 07:00 UTC.

Personal Access Tokens (PATs)

To use the REST API, TypeScript SDK, or MCP Server, you need a Personal Access Token. Navigate to Settings → Access Tokens → New Token. Give it a name, select the role scope (dev for read-only, ops for model management), and set an expiry. The token is shown once — copy it immediately. Store it in your password manager or secrets vault. Never commit a PAT to source control.

bash

Issue a PAT via API

1curl -X POST https://sovereign.yourcompany.com/api/v1/auth/tokens \
2  -H "Authorization: Bearer $OIDC_JWT" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "name": "my-laptop-dev",
6    "role": "dev",
7    "expires_in_days": 90
8  }'
9# → { "token": "sk-sovereign-xxxx", "expires_at": "2026-07-25T00:00:00Z" }

Notification Preferences

Navigate to Settings → Notifications to configure how you receive alerts from the IncidentResponseAgent. You can enable email, Slack DM, or browser notifications for: compliance evaluation completed, model blocked, drift alert, bias warning, promotion approval request, and weekly governance report. Workspace-level Slack channel and PagerDuty routing are configured by administrators under Settings → Integrations.

Role-Based Workflow Summary

Different team members interact with the platform differently. Here is a typical workflow for each persona.

Persona	Daily workflow	Key pages
Data Scientist	Register model → review compliance scores → address findings → submit for approval	Model Registry, Compliance, Bias, Model Card
MLOps Engineer	Monitor drift dashboard → respond to drift alerts → approve HITL requests → manage LLM Gateway budget	Drift Dashboard, Monitoring, LLM Gateway, Approvals
Compliance Officer	Review pending approvals → verify audit chain → download audit packages for regulators → review bias results	Approvals, Audit Log, Compliance, Bias
Legal Reviewer	Approve or reject model promotions → review model cards → sign off GitOps manifests	Approvals, Model Card, Audit Log
Platform Admin	Manage users and roles → configure OIDC providers → set workspace compliance frameworks → rotate encryption keys	Settings, Team Members, IdP Config, Security