Policy Engine

What the Policy Engine Does

The Policy Engine is the deterministic decision layer of AI Governance Control Plane. It does not ask a model whether a change is acceptable. It evaluates explicit, versioned rules against evidence that the control plane has already captured, then produces a result that a reviewer can reproduce and inspect.

Policies can govern experiment candidates, prompt versions, and model versions. Typical evidence includes evaluation metrics, estimated cost, drift severity, prompt state, model provider, and model risk tier. The exact policy version, matching rule, condition trace, outcome, explanation, audit context, and evidence references remain attached to the resulting governance decision.

Studio makes the policy owner, category, tenant scope, active version, draft version, and version history visible together.

Policy and Rule Model

A policy has a stable identity, owner, category, tenant scope, and one or more versions. A version declares the target types it applies to and an ordered set of rules. Each rule has a stable ID, name, priority, effect, human-readable reason, optional severity, and one or more conditions. All conditions in a rule must match for that rule to match.

{
  "name": "Candidate quality gate",
  "category": "MODEL_RISK",
  "owner": "ml-governance",
  "target_types": ["Candidate"],
  "rules": [{
    "rule_id": "block-low-groundedness",
    "name": "Block low groundedness",
    "priority": 10,
    "effect": "BLOCK",
    "severity": "HIGH",
    "reason_template": "Groundedness is below the approved threshold.",
    "conditions": [{
      "field_path": "metrics.groundedness.score",
      "operator": "LESS_THAN",
      "expected_value": 0.8
    }]
  }]
}

Supported comparisons are GREATER_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL, EQUALS, NOT_EQUALS, IN, NOT_IN, EXISTS, and MISSING. The backend provides the authoring schema so clients use the supported fields and operators rather than duplicating policy semantics.

A version presents each ordered rule with its effect, priority, reason, condition field, operator, and expected value.

Deterministic Evaluation

Captured evidence
  → target-compatible active policy versions
  → rules sorted by ascending priority
  → first all-condition match per policy
  → policy outcomes + condition trace
  → persisted governance decision

Rules are evaluated in ascending numeric priority. The first rule whose conditions all match supplies that policy's effect and reason. If the target type is not covered, a field is absent, or no rule matches, the policy records a NO_DECISION outcome instead of inventing a result. The trace records the expected and actual values for every evaluated condition.

Version Lifecycle

New policy content begins as a DRAFT. Drafts can be edited and simulated. Activating a draft makes it the policy's active immutable version and deprecates the previous active version. Deprecated versions remain historical evidence, and archived versions cannot be activated.

DRAFT → ACTIVE → DEPRECATED
  │        │
  │        └── previous active version is deprecated
  └── ARCHIVED  (an archived version cannot be activated)

A decision references the exact policy ID and version that were considered. Changing a policy therefore creates a new version; it never rewrites the rule set used to support an earlier decision.

From Policy to Decision

A policy effect is a structured outcome, not merely a UI label. Across matching policies, BLOCK takes precedence, then REJECT, then APPROVE. A RECOMMEND, INVESTIGATE, or no matching rule produces a proposed decision for review. Missing Evidence is explicit and can lower confidence; it is never silently treated as a pass.

The final GovernanceDecision stores the outcome, confidence, policy references, evidence references, deterministic explanation, actor and request context, and audit record. Review it in Studio or through the governance decision review workflow.

Authoring and Simulation

Studio's Policy Engine lets governance teams search and filter policies, create definitions, inspect versions, edit drafts, activate or archive a version, and simulate a version against supplied evidence. Simulation returns the matched rule, effect, reason, matching and non-matching conditions, and evaluation trace. It is the safe way to test a change before activation.

The browser is deliberately not a policy evaluator: Studio sends the authoring request or simulation input to backend contracts and renders their response. This gives REST, MCP, and Studio users the same policy semantics.

Simulation accepts a target and evidence JSON, then shows the matched rule, effect, reason, matching conditions, and each trace entry.

REST API

• GET /api/v1/policy-schema — supported authoring schema
• GET, POST /api/v1/policies — list or create policies
• GET /api/v1/policies/{policy_id} — policy definition and version summary
• POST /api/v1/policies/{policy_id}/versions — create a draft version
• PUT /api/v1/policies/{policy_id}/versions/{version}/draft — replace draft content
• POST /api/v1/policies/{policy_id}/versions/{version}/activate — activate a draft
• POST /api/v1/policies/{policy_id}/versions/{version}/archive — archive a version
• POST /api/v1/policies/{policy_id}/versions/{version}/simulate — evaluate a version with a trace
• POST /api/v1/decisions/evaluate — evaluate and persist a governance decision

All protected policy and decision work resolves organization and project scope through the normal tenant context. See the REST API reference for the complete endpoint inventory.

Boundaries