Stack & Technology Choices¶

Python-first, Rust-optional¶

graph LR
    subgraph python["Python — Everything"]
        P1["Decorators & DX"]
        P2["CLI generators"]
        P3["LLM integrations"]
        P4["Async agent loops"]
        P5["pyoxigraph store"]
        P6["SHACL validation"]
        P7["PROV-O provenance"]
    end

    subgraph rust["Rust — Optional Accelerator"]
        R1["Panic boundary"]
        R2["Faster SPARQL"]
        R3["Native reasoning"]
    end

    python -.->|"pip install trails#91;rust#93;<br/>PyO3 abi3-py311"| rust

    style python fill:#7c4dff15,stroke:#7c4dff
    style rust fill:#00c85315,stroke:#00c853,stroke-dasharray:5

pip install trails gives you the full framework in pure Python. The default backend uses pyoxigraph — the same Oxigraph engine, accessed through Python bindings instead of a custom FFI.

pip install trails[rust] adds a compiled Rust extension (trails._core) for deployments where you want:

• Panic boundary — kernel panics become KernelError, never crash the interpreter
• Faster SPARQL — native Rust execution instead of Python-bridged pyoxigraph
• Native reasoning — Rust RDFS/OWL-RL materializer instead of Python SPARQL rules

The trails._bridge module auto-detects which backend is available. Your code never changes — Store, TrailsError, and all exceptions come from the bridge regardless of backend.

Why Oxigraph?¶

Embedded, zero-config, SPARQL 1.1 compliant. No external process to manage for development or small deployments. Both backends use Oxigraph under the hood — pyoxigraph for the Python backend, the Rust crate for the compiled backend. For production scale, swap to Fuseki or Qlever via config. See ADR-0007.

Why Cedar?¶

Cedar (by AWS) is a policy language purpose-built for authorization. It's declarative, auditable, and fast. Trails evaluates Cedar policies at invoke() time — every capability dispatch is policy-gated. See ADR-0006.

Why MCP?¶

Model Context Protocol is the emerging standard for exposing tools to AI clients (Claude, Cursor, etc.). Trails is MCP-first: trails server speaks MCP stdio by default, HTTP when launched explicitly. See ADR-0008.

Technology Table¶