Skip to content

Architecture

Trails is a Python-first framework. pip install trails gives you the full feature set backed by pyoxigraph — no Rust toolchain required. An optional compiled extension (pip install trails[rust]) adds a Rust kernel for performance-critical deployments.

All code — your app, the ORM, agents, ingestion — talks to the store through trails._bridge, which auto-detects the backend at import time.

Layers

graph TB
    subgraph surface["Python Surface (~24K LLOC)"]
        direction LR
        DEC["Decorators<br/>@capability @node_type<br/>@shape @policy"]
        ORM["ActiveGraph ORM<br/>QueryBuilder"]
        AGT["Agent Planners<br/>ReAct / PlanExec / Reflexion"]
        ING["Ingest + Vector<br/>+ RML + Enrichment"]
    end

    subgraph bridge["trails._bridge"]
        BR["Auto-detect backend<br/>BACKEND = 'python' | 'rust'"]
    end

    subgraph backends["Backends (one active at runtime)"]
        direction LR
        PY["Pure Python<br/>pyoxigraph + _exceptions<br/><i>default — no Rust needed</i>"]
        RS["Rust Kernel<br/>trails._core (PyO3 FFI)<br/><i>optional — pip install trails#91;rust#93;</i>"]
    end

    subgraph store["Graph Store"]
        OX["Oxigraph<br/>(embedded, in-memory or RocksDB)"]
        AD["Adapters: Fuseki | Qlever"]
    end

    DEC --> BR
    ORM --> BR
    AGT --> BR
    ING --> BR
    BR --> PY
    BR --> RS
    PY --> OX
    RS --> OX
    OX --> AD

    style surface fill:#7c4dff15,stroke:#7c4dff
    style bridge fill:#ffd74015,stroke:#ffd740
    style PY fill:#448aff15,stroke:#448aff
    style RS fill:#00c85315,stroke:#00c853
    style store fill:#78909c15,stroke:#78909c

Two Backends, One API

Python backend (default) Rust backend (optional)
Install pip install trails pip install trails[rust]
Store pyoxigraph (Python bindings) Oxigraph via PyO3 FFI
Exceptions trails._exceptions (pure Python) trails._core (Rust-defined)
Panic boundary No (Python exceptions propagate normally) Yes (kernel panics become KernelError)
SHACL validation Python-side Rust-side (faster)
Reasoning Python SPARQL rules Rust reasoner (faster)
PROV-O Python provenance writer Rust provenance writer
Performance Good for development and moderate workloads Better for production scale

The bridge (trails._bridge) exports BACKEND — "python" or "rust" — so trails doctor and tests can report which is active.

Key Principles

  1. One surface, additive features — ADR-0021. No tiers, no module splits. You grow into the stack.

  2. Brain / Hand separation — every subsystem separates planning (reasoning, LLM calls, query building) from execution (dispatch, store operations, API calls). See the Brain and Hand deep dive.

  3. Trust is opt-in but first-class — Cedar policy, PROV-O, DIDs, cost envelopes, consent receipts. You don't pay for them until you reach for them.

  4. Python-first, Rust-optional — the full framework works in pure Python. The Rust kernel is an accelerator for production deployments, not a requirement.

Pages in This Section