Domino Governance Skill

This skill provides knowledge for managing model risk governance in Domino Data Lab using the Governance API.

Configuration

TOKEN=$(curl -s http://localhost:8899/access-token)
# Governance is NOT routed through $DOMINO_API_HOST (internal Kubernetes).
# Derive the external cluster URL from the JWT iss claim — works in any workspace type.
CLUSTER_URL=$(echo $TOKEN | cut -d'.' -f2 | python3 -c "
import sys, base64, json, re
p = sys.stdin.read().strip()
p += '=' * (-len(p) % 4)
print(re.sub(r'/auth/realms/.*', '', json.loads(base64.b64decode(p))['iss']))
")
BASE="$CLUSTER_URL/api/governance/v1"

Key Concepts

Policy (Template)

A policy is a reusable governance template that defines the stages, evidence requirements, and approval gates a model must pass through. Examples: SR 11-7, NIST AI RMF, internal model risk frameworks. Policies are created by administrators in the Domino UI.

Bundle (Living Document)

A bundle is the compliance document for a specific model in a specific project. It follows a policy and accumulates evidence as the model progresses through development, validation, and approval. One project can have multiple bundles (e.g., one per model version).

Evidence (Proof)

Evidence comes in two forms:

1. Attachments — Files, model versions, and reports attached to the bundle (visible in the "Attachments" tab)
2. EvidenceSet answers — Responses to policy-defined form questions (visible in the "Evidence" tab for each stage)

Finding (Issue)

A finding documents a problem, risk, or concern discovered during review. Findings have severity levels and are tracked as part of the audit trail.

Related Documentation

• BUNDLE-LIFECYCLE.md - Stage sequences, creating bundles, progressing stages
• EVIDENCE-WORKFLOW.md - Attachment types, evidence submission, findings

Governance API Reference

All endpoints are under $BASE (/api/governance/v1). Authenticate with Authorization: Bearer $TOKEN.

Standard 8-Step Governance Workflow

Follow these steps when setting up governance for a model:

Step 1: Discover Policies

curl -s "$BASE/policy-overviews" \
  -H "Authorization: Bearer $TOKEN"

Review available templates. Note the id of the policy you want to use.

Step 2: Get the Project ID

The project ID is needed to create a bundle. Use the DOMINO_PROJECT_ID environment variable (available inside Domino) or look it up via the gateway API.

Step 3: Create a Bundle

curl -X POST "$BASE/bundles" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "your-project-id",
    "name": "My Model v1.0",
    "description": "Description of the model being governed",
    "policyId": "policy-uuid"
  }'

Save the returned id as your BUNDLE_ID.

Step 4: Inspect the Bundle

curl -s "$BASE/bundles/$BUNDLE_ID" \
  -H "Authorization: Bearer $TOKEN"

This reveals the policy's stage structure, attachments, and approval status. Note: This does NOT return evidenceSet IDs — see Step 6 for how to discover those.

Step 5: Attach Evidence

See EVIDENCE-WORKFLOW.md for full details. Two attachment types are supported:

# Attach a registered model version
curl -X POST "$BASE/bundles/$BUNDLE_ID/attachments" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"type":"ModelVersion","identifier":{"name":"model-name","version":5},"name":"Display Name"}'

# Attach a project file (notebook, report, etc.)
curl -X POST "$BASE/bundles/$BUNDLE_ID/attachments" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"type":"Report","identifier":{"branch":"main","commit":"abc...","source":"git","filename":"path/to/file"},"name":"Display Name"}'

Step 6: Answer Evidence Questions (EvidenceSet)

Evidence questions are the interactive forms shown in the Domino UI under each stage's "Evidence" tab. They are defined in the policy YAML as evidenceSet items.

6a. Discover EvidenceSet IDs

EvidenceSet IDs are NOT in the bundle response. Fetch them from the policy endpoint:

curl -s "$BASE/policies/$POLICY_ID" \
  -H "Authorization: Bearer $TOKEN"

The response contains stages[] → evidenceSet[] → artifacts[] with full UUIDs for each evidence item and artifact.

6b. Submit Answers

curl -X POST "$BASE/rpc/submit-result-to-policy" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "bundleId": "bundle-uuid",
    "policyId": "policy-uuid",
    "evidenceId": "evidence-uuid",
    "content": {
      "artifact-uuid": "value"
    }
  }'

Key details:

• Use policyId (NOT policyVersionId)
• evidenceId is the evidence set item UUID (from policy response)
• content is a map of {artifactId: value}
• For radio/textinput/textarea/select: value is a string
• For checkbox/multiSelect: value is an array of strings
• Submit one artifact at a time per call, or multiple artifacts in the same evidence item together

Step 7: Progress Stages

As evidence is collected and approvals obtained:

curl -X PATCH "$BASE/bundles/$BUNDLE_ID/stages/$STAGE_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "Complete"}'

Step 8: Document Findings (if any)

curl -X POST "$BASE/findings" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "bundleId": "bundle-uuid",
    "policyVersionId": "policy-version-uuid",
    "name": "Finding title",
    "title": "Finding title",
    "description": "Detailed description...",
    "severity": "High",
    "approver": {"id": "org-uuid", "name": "model-gov-org"},
    "assignee": {"id": "user-uuid", "name": "username"}
  }'

Get the policyVersionId and user/org IDs from the bundle response (Step 4).

Viewing in Domino UI

After creating a bundle and attaching evidence, the bundle is visible in the Domino UI: Project > Govern > Bundles > click the bundle name

The UI shows:

• Overview — Stage progression and classification
• Evidence tab (per stage) — Interactive forms for evidenceSet questions
• Attachments tab — Files, model versions, and reports
• Findings tab — Documented issues with severity

Documentation Reference

Before writing or verifying any API call, use the cluster swagger to confirm current endpoint paths and field names. Use public docs for workflow context and field explanations.

Governance API base: External cluster URL only — $DOMINO_API_HOST (internal Kubernetes) does not route to this service. Derive the URL from the JWT iss claim (works in any workspace type).

Fetch the governance swagger spec (requires bearer token):

TOKEN=$(curl -s http://localhost:8899/access-token)
CLUSTER_URL=$(echo $TOKEN | cut -d'.' -f2 | python3 -c "
import sys, base64, json, re
p = sys.stdin.read().strip()
p += '=' * (-len(p) % 4)
print(re.sub(r'/auth/realms/.*', '', json.loads(base64.b64decode(p))['iss']))
")
curl -H "Authorization: Bearer $TOKEN" "$CLUSTER_URL/api/governance/swagger/doc.json"
# Browser UI (must be logged in): $CLUSTER_URL/api/governance/swagger/index.html

Public docs (workflow context and field explanations):

• API Guide