Types

The egisai package exposes a small, frozen set of dataclasses for callers that want to use the policy engine outside the patched provider SDKs. They are all plain Python dataclasses — no I/O, no hidden state — so they are safe to log, diff, and pickle.

from egisai import (
    PolicyRule,
    PolicyContext,
    OutputPolicyContext,
    PolicyDecision,
    evaluate_policies,
    evaluate_output_policies,
)

# Sanitization helpers — `egisai.policy` re-exports them for use
# outside the patched call paths (custom audit pipelines, etc.).
from egisai.policy import Sanitization, label_redact

PolicyRule

@dataclass(frozen=True)
class PolicyRule:
    id: str | None
    name: str
    type: str
    tenant: str | None
    config: dict[str, Any]
    agent_ids: tuple[str, ...] = ()
    phase: str = "both"   # "request" | "response" | "both"
    applies_to: tuple[str, ...] = ()  # subset of {"model", "tool", "mcp"}

One active rule. The type field selects the evaluator inside the engine — common values include pii_scan, deny_regex, allow_model, max_prompt_chars, and semantic_guard. The config dict carries the type-specific options. agent_ids scopes the rule to specific agents — an empty tuple means “applies to every agent in the tenant”. phase selects which side of a call the rule fires on:

Phase	Behavior
`request`	The rule is evaluated only on the inbound payload, before the call is made. `evaluate_output_policies` ignores it.
`response`	The rule is evaluated only on the outbound payload, after the call returns. `evaluate_policies` ignores it.
`both` (default)	The rule is evaluated on each side independently.

The legacy wire spellings pre_model / post_model are still accepted and normalize to request / response when the rule is parsed. Every rule type accepts every phase. The engine evaluates each rule on whichever side it has meaningful signals for: text-content rules fire symmetrically on the prompt and the response; tool / shell / connector rules need response-side signals and silently no-op on request only. Older platform deployments that haven’t shipped the field yet behave as if every rule were both, preserving previous semantics. See Two-phase governance for the full phase × type matrix. applies_to scopes the rule to specific call surfaces ("model", "tool", "mcp"). An empty tuple means “all surfaces”. The evaluation functions accept a matching surfaces argument and skip rules whose scope doesn’t intersect it.

PolicyContext

@dataclass(frozen=True)
class PolicyContext:
    tenant: str
    model: str
    prompt_text: str
    prompt_chars: int
    stream: bool

Inputs for evaluating input-side policies — i.e. before the model call runs. Construct one when you want to evaluate rules against arbitrary text outside the patched call paths.

Field	Description
`tenant`	The tenant ID for which to apply the rules.
`model`	The model name your call targets (e.g. `"gpt-4.1"`). Used by `allow_model` rules.
`prompt_text`	The text the rules should evaluate.
`prompt_chars`	The character count of `prompt_text`. Used by `max_prompt_chars` rules.
`stream`	Whether the call is streaming. Reported on the audit event but does not affect evaluation.

OutputPolicyContext

@dataclass(frozen=True)
class OutputPolicyContext:
    tenant: str
    model: str
    text: str
    tool_names: list[str]
    tool_calls: list[dict[str, str]]
    mcp_targets: list[str]
    stream: bool
    allow_sanitize: bool = False

Inputs for evaluating output-side policies — i.e. after the model has responded. Captures the structured response so output-side rules can inspect both the assistant text and any tool / connector calls.

Field	Description
`tenant`	The tenant ID for which to apply the rules.
`model`	The model name that produced the output.
`text`	The assistant’s text reply, if any.
`tool_names`	List of tool names requested by the model.
`tool_calls`	Structured list of tool invocations.
`mcp_targets`	Connector targets requested by the model.
`stream`	Whether the call was streaming.
`allow_sanitize`	When `False` (default), `pii_scan` on the response side is coerced to `block` — there is no atomic mutation point on a streamed assistant response. Specific seams that DO have a mutation point (notably the Claude Agent SDK’s `PostToolUse` hook, which can substitute a tool’s result before the model is shown it) flip this to `True` so a `sanitize` verdict actually masks.

PolicyDecision

@dataclass(frozen=True)
class PolicyDecision:
    verdict: str                          # "allow" | "sanitize" | "block"
    reason_code: str | None
    message: str | None
    matched_policy: str | None
    matched_policies: tuple[MatchedPolicyRecord, ...] = ()
    sanitize_types: list[str]             # populated only on "sanitize"
    sanitize_mask_char: str = "#"

Outcome of evaluating a list of PolicyRule objects against one PolicyContext (input side) or OutputPolicyContext (output side).

Field	Description
`verdict`	`"allow"`, `"sanitize"`, or `"block"`. The most restrictive verdict across all matches wins; precedence is `block > sanitize > allow`.
`reason_code`	Short code identifying what fired (`None` on `allow`).
`message`	Human-readable explanation (`None` on `allow`).
`matched_policy`	Name of the primary rule that produced the verdict.
`matched_policies`	Ordered tuple of every rule that fired during evaluation, even when a more restrictive verdict dominates.
`sanitize_types`	Operator-facing PII type ids (e.g. `"ssn"`, `"credit_card"`, `"email"`) that were masked. Only meaningful when `verdict == "sanitize"`.
`sanitize_mask_char`	Mask character used for sanitization.

The field was previously named sanitize_kinds. The new canonical name is sanitize_types, and sanitize_kinds is exposed as a deprecated read-only alias for one release while consumers migrate. Prefer sanitize_types in new code.

PolicyDecision exposes three convenience constructors, mostly used internally:

Constructor	Returns
`PolicyDecision.allow()`	An `allow` verdict with no matched rules.
`PolicyDecision.deny(reason_code, message, matched_policy, ...)`	A `block` verdict.
`PolicyDecision.sanitize(types, reason_code, message, matched_policy, ...)`	A `sanitize` verdict.

MatchedPolicyRecord

Each entry in PolicyDecision.matched_policies:

@dataclass(frozen=True)
class MatchedPolicyRecord:
    name: str
    type: str
    verdict: str                          # what this single rule would have said
    reason_code: str
    message: str
    sanitize_types: tuple[str, ...] = ()
    sanitize_mask_char: str = "#"

This makes it possible to render an audit row that lists every rule that contributed to the final outcome — even rules whose individual verdicts were overridden by a more restrictive one.

Sanitization

@dataclass(frozen=True)
class Sanitization:
    type: str                # canonical PII type id
    count: int               # how many instances were masked
    mask: str                # the placeholder used in the masked text

Returned by egisai.policy.pii.sanitize() alongside the masked text. Records the shape of what was masked (type + count + mask) but never the raw value — auditable without leaking the value it was meant to protect.

label_redact

def label_redact(
    text: str,
    types: list[str] | None = None,
) -> str: ...

Replace every PII match in text with a typed label (<SSN>, <EMAIL>, <CREDIT_CARD>, …) instead of the mask-character shape used by sanitize(). Useful when you want to log a redacted preview of a payload to your own observability pipeline without sending the raw bytes.

from egisai.policy import label_redact

label_redact("Email me at jane.doe@example.com")
# 'Email me at <EMAIL>'

label_redact is local-only and runs the same detector pipeline as the policy engine, so the categories it knows about match what pii_scan policies enforce.

evaluate_policies

def evaluate_policies(
    policies: list[PolicyRule],
    context: PolicyContext,
) -> PolicyDecision: ...

Run the supplied input-side rules against context and return the resulting PolicyDecision. No I/O — purely deterministic for the local rule kinds.

evaluate_output_policies

def evaluate_output_policies(
    policies: list[PolicyRule],
    context: OutputPolicyContext,
) -> PolicyDecision: ...

Run the supplied output-side rules against context and return the resulting PolicyDecision. Use this when you have a structured response (text + tool calls) that you want to evaluate before forwarding it to a downstream consumer.

Example

from egisai import (
    PolicyContext,
    PolicyRule,
    evaluate_policies,
)

rule = PolicyRule(
    id="rule_demo",
    name="forbid-greetings",
    type="deny_regex",
    tenant="org_demo",
    config={"pattern": r"hello", "flags": ["IGNORECASE"]},
)

context = PolicyContext(
    tenant="org_demo",
    model="gpt-4.1",
    prompt_text="Hello world!",
    prompt_chars=12,
    stream=False,
)

decision = evaluate_policies([rule], context)
print(decision.verdict)        # "block"
print(decision.matched_policy) # "forbid-greetings"

Reference

PolicyRule

PolicyContext

OutputPolicyContext

PolicyDecision

MatchedPolicyRecord

Sanitization

label_redact

evaluate_policies

evaluate_output_policies

Example

What’s next

Verdicts

Policies

​PolicyRule

​PolicyContext

​OutputPolicyContext

​PolicyDecision

​MatchedPolicyRecord

​Sanitization

​label_redact

​evaluate_policies

​evaluate_output_policies

​Example

​What’s next

Verdicts

Policies

PolicyRule

PolicyContext

OutputPolicyContext

PolicyDecision

MatchedPolicyRecord

Sanitization

label_redact

evaluate_policies

evaluate_output_policies

Example

What’s next