Rust Engine

Admina ships a Rust core engine (admina_core) compiled via PyO3 as a Python extension. The engine provides up to 434× faster governance processing compared to the pure Python implementation for the full 4-domain pipeline. Admina auto-detects which engine to use at startup.

Performance

Component Rust (median) P95 P99
Firewall (regex) 2.08µs 2.33µs 2.50µs
PII Scanner 0.62µs 0.67µs 0.71µs
Loop Breaker 2.38µs 2.67µs 2.75µs
Hash Chain 1.00µs 1.12µs 1.25µs
4-Domain pipeline 6.25µs 7.04µs 7.29µs

Verified Docker run: Linux aarch64, Python 3.11, single-threaded, 10,000 iterations after 1,000 warmup. Reproduce with docker build -f Dockerfile.benchmark -t admina-bench . && docker run --rm admina-bench.

Rust vs Python comparison
Component Python (median) Rust (median) Speedup
Firewall 7.79µs 2.08µs 3.7×
PII (regex-only) 8.21µs 0.62µs 13.2×
PII (with spaCy NER) 1,992µs 0.62µs 3,213×
Loop Breaker (sklearn) 505µs 2.38µs 212×
Full pipeline 2,261µs 5.21µs 434×

Python column includes spaCy NER and sklearn TF-IDF — the production-equivalent path. The large speedup in PII and Loop Breaker reflects replacing ML libraries with compiled Rust.

The real advantage is under concurrent load. Python's GIL serialises governance calls under concurrent agent traffic — throughput plateaus even as more cores are available. The Rust engine has no GIL: all regex, PII, and hash-chain operations run truly in parallel across threads, with p99 latency staying flat at typical production concurrency levels (10–50 simultaneous agent sessions).

Selecting the engine

Since v0.10.0 a single switch — ADMINA_ENGINE — selects the governance-engine backend uniformly across the proxy, the SDK, and the LangChain/CrewAI callbacks (engines are acquired through one admina.engines package). This means Admina works identically without Rust — just slower.

  • ADMINA_ENGINE=auto — default. Use Rust for the firewall + loop breaker when admina-core is installed, else Python. PII redaction stays on the Python engine for full recall.
  • ADMINA_ENGINE=python — force the pure-Python engines everywhere (broadest detection coverage).
  • ADMINA_ENGINE=rust — force Rust everywhere, including PII (faster, narrower coverage). An unrecognized value raises at startup.
# Check which engine is active
make status
# → {"engine": "rust", "rust_available": true, "version": "0.10.1"}

# Or via the health endpoint
curl http://localhost:8080/health
# → {"engine": "rust", "rust_available": true, ...}

Install — prebuilt wheel

Since v0.9.4 the Rust engine is opt-in via the [rust] extra. The extra pulls the admina-core wheel from PyPI and the engine bridge auto-detects it at startup. 

pip install "admina-framework[rust]"
python -c "import admina_core; print(admina_core.__version__)"
# → 0.10.1

The project ships as a single Stable-ABI (abi3-py311) wheel — one artefact works on Python 3.11+ without per-interpreter wheels.

Detection-coverage trade-off

The Rust and Python firewall/PII engines are not equivalent — this is measured, not assumed. The Rust firewall uses per-pattern severity (matching the Python InjectionFirewall reporting model) but its pattern coverage is still narrower: on the internal evasion corpus it blocks 7/14 attacks at HIGH+, and the Rust PII scanner does not cover EU national IDs or NER person/org names. So under ADMINA_ENGINE=auto the firewall and loop breaker run on Rust while PII redaction stays on Python for full recall; ADMINA_ENGINE=rust opts the PII scanner into Rust too. Full Rust↔Python detection parity (evasion normalisation, multilingual patterns) is on the roadmap — until then the pure-Python install has the broadest coverage, and the Rust engine wins on raw throughput (≈6.25µs full-pipeline median).

Note (v0.9.1 hotfix). admina-core 0.9.0 was yanked from PyPI due to a PyO3 framework-linking bug that aborted at import on Python versions other than the build host. Always use admina-core ≥ 0.9.1. Mac Intel (x86_64-apple-darwin) wheels are not published; Intel users build from sdist via the steps below.

Building the Rust engine from source

Prerequisites

  • Rust toolchain 1.75+ (rustup.rs)
  • Python 3.11+ with development headers
  • maturin (pip install maturin)

Build

# Full build: Rust engine + Python install
make all

# Or manually
cd core-rust
maturin develop --release    # builds + installs into current venv

# Python-only mode (no Rust required)
make python

Verify the build

python -c "import admina_core; print(admina_core.__version__)"
# → 0.10.1

python -c "from admina_core import Firewall; f = Firewall(); print(f.check('test'))"
# → {"risk_level": "LOW", "matched_patterns": []}

Rust modules

core-rust/src/firewall.rs

RegexSet single-pass injection pattern matching. Compiles all 15 patterns at build time for zero runtime regex compilation overhead.

core-rust/src/pii.rs

Compiled PII regex scanner. Email, phone, credit card, SSN, IBAN, IP — all patterns pre-compiled into a single pass.

core-rust/src/loop_breaker.rs

TF-IDF vectorization and cosine similarity for loop detection. Uses nalgebra for fast vector operations.

core-rust/src/forensic.rs

SHA-256 hash chain for the forensic black box. Uses the sha2 crate for zero-dependency hashing.

Running benchmarks

# Full benchmark suite (requires both engines)
make bench

# Or directly
python benchmark.py --output report.html

# Stress test with 10k requests
python benchmark.py --requests 10000 --report json

The benchmark generates an HTML report with latency percentiles, throughput curves, and a Python vs Rust comparison. Reports are saved to benchmark-reports/.

Dockerfile notes

The included proxy/Dockerfile compiles the Rust engine during the Docker build. If the Rust toolchain is unavailable in the build environment, the build falls back to Python-only mode automatically (see Makefile targets).

The benchmark.Dockerfile is a separate image for running benchmarks in isolation without polluting the proxy image.