Skip to main content

Python SDK Overview

The Python SDK is the primary integration layer for Python applications using Actra.

It provides a clean three-layer architecture:

Actra         -> load & compile policies
Policy        -> compiled policy artifact
ActraRuntime  -> runtime enforcement

This gives Python teams a deterministic path from YAML policy files to protected function execution.

Installation​

pip install actra

Fastest Happy Path​

The fastest way to get started is loading a policy directory.

from actra import Actra, ActraRuntime

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

This flow:

  1. loads schema, policy, and optional governance files
  2. compiles them into a native policy artifact
  3. creates a reusable runtime instance

SDK Architecture​

1) Compiler Layer​

The compiler layer converts YAML into a reusable Policy artifact.

From YAML Strings​

policy = Actra.from_strings(
    schema_yaml,
    policy_yaml,
    governance_yaml,
)

From Individual Files​

policy = Actra.from_files(
    "./policy/schema.yaml",
    "./policy/policy.yaml",
    "./policy/governance.yaml",
)

From Policy Directory​

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

This is the recommended production setup for:

  • monorepos
  • governed policy repos
  • CI validation
  • multi-team ownership

2) Policy Artifact Layer​

The compiled Policy is a reusable runtime-safe artifact.

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

The policy layer supports:

  • deterministic evaluation
  • policy hashing
  • explain debugging
  • assertion helpers
  • schema access
  • notebook-friendly rich representation

3) Runtime Enforcement Layer​

The runtime protects functions before execution.

@runtime.admit(action_type="refund")
def refund(payment_id: str):
    return "ok"

When called, the runtime:

  1. builds action payload
  2. resolves actor context
  3. resolves snapshot state
  4. evaluates matching rules
  5. executes or blocks

Resolver Model​

Actor Resolver​

runtime.set_actor_resolver(lambda ctx: {
    "role": ctx.user.role,
})

Use actor resolvers for:

  • request identity
  • service identity
  • workflow caller
  • AI agent identity

Snapshot Resolver​

runtime.set_snapshot_resolver(lambda ctx: {
    "is_locked": ctx.account.locked,
})

Use snapshot resolvers for:

  • database state
  • Redis flags
  • fraud checks
  • deployment safety
  • workflow approvals

Runtime Decision Helpers​

For lightweight checks:

runtime.allow("refund", amount=100)
runtime.block("refund", amount=100)
runtime.requires_approval("refund", amount=100000)

For full decision access:

decision = runtime.evaluate(
    runtime.action("refund", amount=1000)
)

Protecting Functions​

The most common production pattern is decorator-based function protection.

@runtime.admit(action_type="refund")
async def guarded_refund(order_id: str):
    return {"ok": True}

If blocked, the runtime raises ActraPolicyError.

If approval is required, the same error contains the decision payload.

Non-Blocking Audit Mode​

For observability-only workflows:

@runtime.audit(action_type="refund")
def audited_refund(order_id: str):
    return {"ok": True}

This always executes the function while still producing policy decisions.

Ideal for:

  • shadow rollout
  • dry runs
  • migration safety
  • policy tuning

Explain & Debugging​

Use explain APIs for debugging live decisions.

runtime.explain(
    runtime.action("refund", amount=5000)
)

Or explain an upcoming function call:

runtime.explain_call(
    refund,
    amount=5000,
    action_type="refund",
)

Production Mental Model​

YAML files -> Actra -> Policy -> Runtime -> @admit

This is the core Python integration pipeline.

Common Use Cases​

  • FastAPI route protection
  • background workers
  • Celery tasks
  • cron jobs
  • deployment automation
  • AI tool execution
  • workflow steps
  • notebooks and REPL debugging

Next Steps​

  • Learn Compiler API
  • Explore Policy Artifact API
  • Deep dive into Runtime API
  • Build Actor Resolvers
  • Add Snapshot Resolvers
  • Use Explain & Debugging