Skip to main content

Compiler API

The Compiler API is the entry point that transforms YAML policy sources into a reusable compiled Policy artifact.

In the Python SDK, the compiler surface is exposed through the Actra class:

  • string-based compilation → from_strings()
  • file-system helpers → from_files() and from_directory()

This page documents the Python compiler APIs.

Mental Model​

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

This is the first stage of every Actra integration.

String-Based Compilation​

from_strings()​

Compile directly from YAML strings.

from actra import Actra

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

This is the most portable compiler API.

Best for:

  • generated config
  • remote policy fetch
  • test fixtures
  • notebooks
  • CI pipelines
  • dynamic policy generation

File-System APIs​

Python naturally supports local filesystem workflows, making file-based compilation a first-class production path.

from_files()​

Compile from explicit YAML file paths.

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

Best for:

  • Python services
  • scripts
  • CLI tools
  • local testing
  • CI jobs

from_directory()​

Compile from a policy directory.

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

This loads:

  • schema
  • policy
  • optional governance

from a standard directory layout.

This is the recommended production Python workflow.

Best for:

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

Compiler Version​

compiler_version()​

Retrieve the native compiler version.

version = Actra.compiler_version()

Useful for:

  • diagnostics
  • CI verification
  • artifact compatibility
  • support workflows
  • rollout validation

Failure Semantics​

Missing Files​

from_files() and from_directory() raise:

FileNotFoundError

for missing schema, policy, governance, or directory paths.

Invalid Schema YAML​

Invalid schema parsing raises:

ActraSchemaError

Native Compilation Failure​

Compiler validation failures surface from the Rust engine.

This includes:

  • schema errors
  • policy errors
  • governance violations
  • invalid operators
  • engine initialization issues

Production Recommendations​

Python services​

Prefer:

Actra.from_directory()

Dynamic / Test / Notebook workflows​

Prefer:

Actra.from_strings()

This keeps the compiler portable for REPLs, notebooks, CI, and generated policy systems.

Production Mental Model​

Python files -> from_directory() -> Policy
YAML strings -> from_strings() -> Policy

This keeps Python integrations simple and production-safe.

Next Steps​

  • Use Policy Artifact API
  • Integrate with Runtime API
  • Build Testing Policies
  • Use Explain & Debugging