Skip to main content

Policy Artifact API

The Policy class is the compiled policy artifact used by the Python SDK.

It wraps the validated native engine instance and provides a safe, ergonomic API for:

  • deterministic evaluation
  • schema-aware runtime integration
  • testing and assertions
  • policy hashing
  • debugging and explain flows
  • notebook-friendly rich representations

This page documents the Policy APIs exposed by the Python SDK.

Creating a Policy​

Most applications do not construct Policy directly.

Instead, create it through the compiler layer:

from actra import Actra

policy = Actra.from_directory("./policy")

This returns a compiled Policy artifact ready for runtime use.

Artifact Mental Model​

YAML -> Compiler -> Native Policy -> Policy Artifact

The Policy instance is:

  • immutable after compilation
  • reusable across requests
  • safe for repeated evaluation
  • compatible with ActraRuntime

Evaluation APIs​

evaluate()​

Primary decision API.

decision = policy.evaluate({
    "action": {"type": "refund", "amount": 1000},
    "actor": {"role": "support"},
    "snapshot": {"is_locked": False},
})

This delegates directly to the native engine.

Returns a Decision dictionary.

evaluate_action()​

Ergonomic helper for direct domain inputs.

decision = policy.evaluate_action(
    {"type": "refund", "amount": 1000},
    {"role": "support"},
    {"is_locked": False},
)

This is equivalent to evaluate() with explicit action, actor, and snapshot sections.

Best for:

  • tests
  • scripts
  • CI validation
  • framework adapters

Testing & Assertions​

assert_effect()​

The strongest testing API in the Policy class.

policy.assert_effect(
    {
        "action": {"type": "deploy", "environment": "production"},
        "actor": {"role": "developer"},
        "snapshot": {},
    },
    "require_approval",
)

If the actual effect does not match, it raises AssertionError with:

  • expected effect
  • actual effect
  • full evaluation context

This is ideal for:

  • unit tests
  • pytest suites
  • CI regression suites
  • governance contract checks
  • rollout verification

Policy Hashing​

policy_hash()​

Returns a stable hash of the compiled policy artifact.

hash_value = policy.policy_hash()

Excellent for:

  • cache keys
  • artifact integrity
  • CI drift checks
  • deployment verification
  • rollout safety

Explain & Debugging​

explain()​

Evaluates the policy and prints a structured explanation.

policy.explain({
    "action": {"type": "refund", "amount": 5000},
    "actor": {"role": "finance"},
    "snapshot": {"is_locked": False},
})

Printed sections include:

  • action
  • actor
  • snapshot
  • final result

This is excellent for:

  • local debugging
  • notebook exploration
  • CI logs
  • policy support workflows
  • rollout validation

The method also returns the Decision dictionary.

Notebook & REPL Experience​

The Python Policy object provides rich interactive representations.

__repr__() / __str__()​

print(policy)

Displays a compact representation including the policy hash.

_repr_html_()​

In Jupyter notebooks, the policy renders with a rich HTML summary.

This is excellent for:

  • notebooks
  • demos
  • governance reviews
  • interactive debugging

Error Semantics​

Invalid Schema YAML​

Invalid schema loading raises:

ActraSchemaError

Assertion Failure​

assert_effect() mismatches raise:

AssertionError

with expected vs actual decision details.

Native Evaluation Failure​

Evaluation errors surface from the Rust engine.

Production Use Cases​

The Policy artifact is ideal for:

  • direct service-side checks
  • CI policy verification
  • notebook experimentation
  • snapshot tests
  • contract tests
  • approval gate validation
  • deployment drift detection

Production Mental Model​

Compiled Policy
 -> evaluate()
 -> Decision
 -> assert / explain / hash

This is the safest low-level policy interface in the Python SDK.

Next Steps​

  • Explore Compiler API
  • Build Testing Policies
  • Use Explain & Debugging
  • Integrate with Runtime API