Decision explainability

Every governance decision EgisAI makes is inspectable in four ways: programmatically in your code, structurally in the audit event, visually in the dashboard, and aggregately in the audit-evidence export. The four surfaces deliver progressively richer context for the same underlying decision — from a one-liner reason code to a full evidence package an auditor can review without your help. This page is the reference for procurement and compliance reviewers asking “how does EgisAI satisfy the explainability obligation in our regulatory framework?” The short answer: the SDK never returns a verdict without a matched policy and a reason. The detailed answer follows.

What the regulator usually requires

Different frameworks use different language but converge on the same expectation: an automated decision should carry a stable identifier of the rule that made it, a human-readable reason, and a path for an affected human to understand why.

Framework	Obligation	What EgisAI delivers
EU AI Act Article 13 (transparency)	Information about the system’s purpose and outcomes shall be provided in a clear and meaningful form.	Every audit row carries `verdict`, `matched_policy`, `reason_code`, and the post-redaction text that the model saw. The dashboard request-detail drawer renders these in plain English.
EU AI Act Article 14 (human oversight)	Natural persons must be able to interpret the system’s output and intervene.	Operators can pause an agent, edit a policy, and restore a prior policy version from the dashboard. Every action is captured in the operator-action audit trail.
EU AI Act Article 22 (records)	Logs shall enable monitoring of operation and detection of risks.	The audit log retains per-call decisions for the plan’s retention horizon and is exportable as evidence.
NIST AI RMF MEASURE 2.7	Document the methods and metrics used to evaluate AI system trustworthiness.	The compliance-coverage dashboard maps every enabled policy to the specific control it satisfies; the export’s manifest pre-stamps the controls.
SOC 2 CC7.2 (system operations — monitoring)	Logging and review of security events.	Per-call audit rows + operator-action audit rows, append-only by design.
GDPR Article 22(3) (human intervention)	Right to obtain human intervention on automated decisions.	A blocked call surfaces a `PermissionError` or a stub refusal with a structured reason code; operators can flag a request for review (see Contesting a block).

The remainder of this page describes the four surfaces that deliver on these obligations.

Surface 1 — programmatic, in your code

If your code wants to inspect a verdict directly, every patched provider call returns enough structured information to react to. The PolicyDecision object returned by the public policy primitives is the machine-readable contract:

from egisai import (
    evaluate_policies,
    PolicyContext,
    PolicyRule,
)

decision = evaluate_policies(
    policies=[...],
    context=PolicyContext(
        tenant="my-org",
        model="gpt-4.1",
        prompt_text="…",
        prompt_chars=128,
        stream=False,
    ),
)

print(decision.verdict)            # "allow" | "sanitize" | "block"
print(decision.reason_code)        # short stable code: "prompt_blocked", "output_pii", ...
print(decision.reason)             # human-readable string
print(decision.matched_policy)     # primary matching rule name
print(decision.sanitize_types)     # PII types masked when verdict == "sanitize"
for record in decision.matched_policies:
    print(record.name, record.verdict, record.reason_code)

The same fields appear on the audit event and on the dashboard, so a verdict your code observed will read identically to a reviewer reading the row a year later. When a call is blocked via the framework patch, your code sees either a PermissionError (default on_block="raise") carrying the same fields in its message, or a framework-shaped refusal object (on_block="stub") with the same reason code surfaced in the content. See Blocking behavior.

Surface 2 — structural, in the audit event

Every governed call writes a structured audit event with the decision embedded as nested objects. The full schema is in Audit-event schema; the explainability-relevant fields are:

{
  "verdict": "block",
  "risk_level": "high",
  "enforcement_status": "enforced",
  "prompt_decision": {
    "verdict": "allow",
    "matched_policies": []
  },
  "response_decision": {
    "verdict": "block",
    "reason_code": "tool_denied",
    "reason": "Tool 'shell.exec' is on the deny list for this agent.",
    "matched_policy": "no-shell-tools",
    "matched_policies": [
      {
        "name": "no-shell-tools",
        "type": "deny_tool_call",
        "verdict": "block",
        "reason_code": "tool_denied",
        "message": "Tool 'shell.exec' is on the deny list for this agent."
      }
    ]
  },
  "matched_policies": [
    {
      "name": "no-shell-tools",
      "type": "deny_tool_call",
      "verdict": "block",
      "reason_code": "tool_denied",
      "message": "Tool 'shell.exec' is on the deny list for this agent."
    }
  ]
}

The four invariants in this shape are important for review:

Verdict precedence is explicit. The top-level verdict is the dominant outcome; the per-phase decisions show what each side decided independently.
Every rule that fired is preserved. A rule whose individual verdict was sanitize is still in matched_policies even if a later rule’s block dominated. Review is accurate without inference.
Reason codes are stable. Codes like prompt_blocked, output_pii, tool_denied, output_too_large are designed for switch-statement consumption and do not change across releases.
Enforcement honesty. enforcement_status distinguishes enforced (the policy physically prevented the action) from advisory (the policy decided block but the framework had already executed the call). Auditors can find the latter via a WHERE verdict='block' AND enforcement_status='advisory' query — see Enforcement matrix.

Surface 3 — visual, on the dashboard

The Requests page renders every audit row in a list. Clicking a row opens a request-detail drawer with five panels designed for review:

Decision summary card — verdict pill, matched policy name, reason, risk badge, enforcement badge.
Two-phase decision strip — separate request and response cards showing what each side decided and which rules matched.
Decision narrative — a one-line natural-language story (“the agent tried to draft an HR letter; EgisAI redacted 2 SSNs before the model saw them”).
Matched policies list — every rule that fired, in evaluation order, with its individual verdict and reason.
Post-redaction text preview — request_text / request_text_before_redaction / response_preview, all post-redaction, with a diff view when sanitize fired.

Reviewers who don’t write SQL get an audit-grade understanding of a single decision in 30 seconds.

Surface 4 — aggregate, in the evidence export

For audit-cycle review, the Audit-evidence export ZIP carries the same decisions at scale. The export’s manifest pre-stamps each CSV with the framework controls it satisfies, so an auditor can review by control id without back-mapping the rows. The aggregate view answers the regulator-style questions the per-row view can’t:

“Show me every call this quarter where a fairness policy fired.”
“Show me the policy inventory the day the system rejected this decision, with versions.”
“Show me every operator action that touched the PII policies in the last six months.”

All three are CSV joins on the export.

How this maps to a customer obligation

When an operator’s downstream regulator asks “how do you explain decisions made by your AI?”, the answer threads through the four surfaces above:

Customer obligation	EgisAI artefact
Disclose decision rationale to an affected human.	`reason_code` + `reason` on the verdict; rendered on the dashboard request-detail drawer. The operator delivers the explanation; EgisAI provides the structured signal.
Allow human review of a decision.	The dashboard request-review workflow (see Contesting a block).
Preserve evidence for a future audit.	The audit-evidence export — append-only, plan-driven retention, framework-mapped manifest.
Demonstrate which rules governed which calls.	`matched_policies` per row + `policies.csv` inventory snapshot at export time.

A worked example

A customer-service agent at a financial-services company is blocked from returning a wire-instruction format. The audit row reads:

verdict: block
enforcement_status: enforced
response_decision.reason_code: output_blocked
response_decision.matched_policy: wire-instruction-output-block
matched_policies[0].message: “Response matched deny regex wire-instruction-format; refused before delivery to caller.”

The end customer asks for a reason. The operator opens the dashboard request-detail drawer, copies the structured reason and the post-redaction preview, and replies through their support channel. The auditor, six months later, reads the same row in the evidence export and sees the same information — no back-translation, no missing context. That is the explainability contract.

What EgisAI does not explain

To be unambiguous:

We do not explain the business reason the operator authored the policy. That’s authoring intent that lives in the operator’s policy authoring notes.
We do not explain why a model produced a particular response. The audit shows the response and the policies that fired on it; the causal explanation of the model’s behavior belongs to the model vendor.
We do not run causal counterfactuals. The decision_narrative field may include an optional counterfactual when the dashboard’s enrichment thinks one is helpful, but it is best-effort narrative, not a guaranteed causal claim.

What’s next

Verdicts

The three verdicts and the reason-code vocabulary.

Audit-event schema

Every field, every type, every privacy invariant.

Contesting a block

What an operator can do when a decision was wrong.

Enforcement matrix

Where the advisory rather than enforced distinction matters.

Get started

Core concepts

Integrations

Gateway

Coverage

Guides

Operations

Decision explainability

What the regulator usually requires

Surface 1 — programmatic, in your code

Surface 2 — structural, in the audit event

Surface 3 — visual, on the dashboard

Surface 4 — aggregate, in the evidence export

How this maps to a customer obligation

A worked example

What EgisAI does not explain

What’s next

Verdicts

Audit-event schema

Contesting a block

Enforcement matrix

​What the regulator usually requires

​Surface 1 — programmatic, in your code

​Surface 2 — structural, in the audit event

​Surface 3 — visual, on the dashboard

​Surface 4 — aggregate, in the evidence export

​How this maps to a customer obligation

​A worked example

​What EgisAI does not explain

​What’s next

Verdicts

Audit-event schema

Contesting a block

Enforcement matrix

What the regulator usually requires

Surface 1 — programmatic, in your code

Surface 2 — structural, in the audit event

Surface 3 — visual, on the dashboard

Surface 4 — aggregate, in the evidence export

How this maps to a customer obligation

A worked example

What EgisAI does not explain

What’s next