Metadata-Version: 2.4
Name: actra
Version: 0.5.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Security
Requires-Dist: pyyaml>=6.0.2
Summary: Actra - Deterministic admission control engine for automated system actions.
Keywords: policy,authorization,policy-engine,automation,admission-control
Author: Amit Saxena
License: Apache-2.0
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://github.com/getactra/actra
Project-URL: Homepage, https://github.com/getactra/actra
Project-URL: Repository, https://github.com/getactra/actra

# Actra Python SDK

**Action Admission Control for Automated Systems**

Deterministic policy engine that decides whether automated actions are **allowed before they execute**.

The **Actra Python SDK** provides a simple interface for loading policies and evaluating decisions using the Actra engine written in Rust.

---

## Runtime Admission Control

The SDK also provides a runtime layer for protecting functions using Actra policies.

If a policy blocks the operation, the function will not execute and a
PermissionError will be raised.

---

## Installation

Install from PyPI:

```bash
pip install actra
```

The package includes a compiled Rust engine, so no Rust toolchain is required during installation.

---

## Quick Start

```python
@actra.admit()
def refund(amount):
    ...
```

The rule lives in policy:

```yaml
rules:
  - id: block_large_refund
    when:
      subject:
        domain: action
        field: amount
      operator: greater_than
      value:
        literal: 1000
    effect: block
```

```markdown
Result:

refund(200)   > allowed  
refund(1500)  > blocked by policy
```

Actra evaluates the policy **before the function executes** and blocks refunds greater than 1000.

---


## Design Goals

The Python SDK focuses on:

* simple developer ergonomics
* deterministic policy evaluation
* minimal runtime overhead
* seamless integration with the Rust engine

The heavy lifting is performed by the core engine, ensuring fast and consistent evaluations.

---

## Architecture

```mermaid
flowchart LR
    subgraph User Code
        U[User Code]
    end
    
    subgraph SDK Layer
        S[Python SDK]
    end

    subgraph Native Bindings
        N[Rust bindings<br/>actra]
    end

    subgraph Core Engine
        C[Actra Engine]
    end

    U --> S --> N --> C
```

The SDK provides a Python-friendly interface while the core engine handles compilation and evaluation.

---

## License

Apache License 2.0

---

## Project

Actra is designed for systems requiring explicit, reproducible control over state-changing operations in automated environments.

