Skip to main content

Runtime API Deep Dive

The ActraRuntime is the primary execution layer for Python applications.

It transforms a compiled Policy artifact into deterministic runtime enforcement before your functions execute.

Creating a Runtime​

Create a runtime from a compiled Policy.

from actra import Actra, ActraRuntime

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

The runtime instance is reusable across requests, workers, notebooks, and job executions.

Resolver APIs​

Resolvers dynamically provide runtime context.

Actor Resolver​

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

Use this for:

  • request identity
  • service-to-service auth
  • AI agent identity
  • queue worker ownership
  • notebook session identity

Snapshot Resolver​

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

Use this for:

  • DB lookups
  • Redis flags
  • fraud systems
  • deployment state
  • approval workflows

Context Resolver​

runtime.set_context_resolver(lambda: request)

This Python-specific hook lets the runtime lazily resolve framework context.

Excellent for:

  • FastAPI request context
  • Celery task metadata
  • notebooks
  • agent session state
  • background workers

Decision Observer​

runtime.set_decision_observer(lambda event: print(event["decision"]["effect"]))

Observers receive:

  • action
  • decision
  • resolved actor
  • resolved snapshot
  • timestamp
  • duration_ms

Observer failures never break execution.

Decision Helper APIs​

These methods are ideal for lightweight checks.

allow()​

ok = runtime.allow("refund", amount=100)

Returns True if decision effect is allow.

block()​

denied = runtime.block("delete_user", target="user_123")

Returns True if decision effect is block.

requires_approval()​

approval = runtime.requires_approval(
    "deploy",
    environment="production",
)

Returns True for require_approval decisions.

Full Decision Access​

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

Returns the full Decision dictionary.

Function Protection APIs​

These are the most commonly used production APIs.

admit()​

Protect a function before execution.

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

When called:

  1. action payload is built
  2. actor resolver runs
  3. snapshot resolver runs
  4. policy evaluates
  5. function executes only if allowed

Failure Behavior​

  • block → raises ActraPolicyError
  • require_approval → raises ActraPolicyError
  • allow → executes function

The error includes decision metadata including matched_rule.

audit()​

Non-blocking shadow mode.

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

Always executes the function while still evaluating policy.

Ideal for:

  • migrations
  • shadow rollout
  • policy tuning
  • observability-only mode

Argument Mapping Model​

The runtime supports multiple action payload construction strategies.

kwargs-first Mapping​

runtime.evaluate(
    runtime.action("refund", amount=100, currency="USD")
)

Keyword arguments are the most ergonomic Python mapping model.

Signature-driven Mapping​

Decorator wrappers can infer action payloads from function signatures.

This keeps existing Python codebases highly ergonomic.

Schema-driven Mapping​

If explicit fields are omitted, runtime can fall back to schema-defined action fields.

Action Builder APIs​

build_action()​

Build an action payload manually.

action = runtime.build_action("refund", amount=1000)

Supports:

  • field filtering
  • schema filtering
  • custom builder override

action()​

Ergonomic helper using runtime schema.

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

Best for:

  • FastAPI middleware
  • Celery workers
  • agent tools
  • notebooks
  • MCP

Action Type Resolution​

A Python-specific advanced feature.

runtime.set_action_type_resolver(lambda fn: fn.__name__)

This is extremely useful for framework integrations and decorator-heavy systems.

Explain APIs​

explain()​

Explain a concrete action.

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

Prints:

  • action
  • actor
  • snapshot
  • final decision

explain_call()​

Explain an upcoming function call.

runtime.explain_call(
    refund,
    order_id="order_123",
    action_type="refund",
)

This uses function signature and schema-driven normalization.

Error Semantics​

Resolver Failures​

Actor or snapshot resolver failures raise:

ActraError

Policy Failures​

Evaluation failures raise:

ActraPolicyError

Builder Failures​

Custom builder failures raise:

ActraError

Production Mental Model​

Function Call
 -> Build Action
 -> Resolve Actor
 -> Resolve Snapshot
 -> Evaluate Policy
 -> Execute or Raise

This is the core runtime execution pipeline.

Next Steps​

  • Explore Policy Artifact API
  • Learn Compiler API
  • Build Actor Resolvers
  • Build Snapshot Resolvers
  • Add Observability & Audit
  • Use Explain & Debugging