Trails¶

Hello, Trails¶

from trails import capability, node_type

@node_type("Note", fields={"title": str, "body": str})
class Note: pass

@capability
def create_note(ctx, title: str, body: str) -> dict:
    n = Note(title=title, body=body)
    ctx.kg.add(n)
    return {"id": n.id}

That's a working app. trails server discovers it, exposes it over MCP and HTTP, and records provenance. No config files, no boilerplate.

The Progressive Enhancement Ladder¶

graph LR
    A["<b>Labels</b><br/>ctx.kg.node / edge"] --> B["<b>Types</b><br/>@node_type + fields"]
    B --> C["<b>Validation</b><br/>@shape + SHACL"]
    C --> D["<b>Reasoning</b><br/>OWL-RL inference"]

    style A fill:#e8def8,color:#1b1b1f,stroke:#7c4dff,stroke-width:2px
    style B fill:#d0bcff,color:#1b1b1f,stroke:#651fff,stroke-width:2px
    style C fill:#bbd0ff,color:#1b1b1f,stroke:#536dfe,stroke-width:2px
    style D fill:#c2e7ff,color:#1b1b1f,stroke:#448aff,stroke-width:2px

Each step is opt-in. You never re-architect — you just add a decorator. See ADR-0021 for the full rationale.

What You Get¶

Architecture at a Glance¶

graph TB
    subgraph Python["Python Surface (~24K LLOC)"]
        direction TB
        APP["Your App<br/>@capability @node_type @shape @policy"]
        ORM["ORM &bull; Agents &bull; Ingest &bull; Vector"]
        RT["Runtime: invoke() &bull; ctx.kg &bull; ctx.llm"]
        TR["MCP (stdio + SSE) &bull; HTTP (FastAPI) &bull; CLI"]
    end

    subgraph Bridge["trails._bridge"]
        BR["Auto-detect backend"]
    end

    subgraph Backends["Backends"]
        direction LR
        PY["Python backend<br/>pyoxigraph<br/><i>default</i>"]
        RS["Rust kernel<br/>trails._core<br/><i>optional</i>"]
    end

    subgraph Store["Oxigraph"]
        AD["Adapters: Oxigraph | Fuseki | Qlever"]
    end

    APP --> ORM --> RT --> TR
    TR --> BR
    BR --> PY
    BR --> RS
    PY --> AD
    RS --> AD

    style Python fill:#7c4dff15,stroke:#7c4dff
    style Bridge fill:#ffd74015,stroke:#ffd740
    style PY fill:#448aff15,stroke:#448aff
    style RS fill:#00c85315,stroke:#00c853

The Brain and Hand Pattern¶

Trails separates reasoning from execution throughout its architecture. Look for these markers in the guides:

Marker	Role	What it does
Brain	Planning / reasoning	Decides what to do — query planning, strategy selection, LLM calls
Hand	Execution / action	Does the thing — runs queries, transforms data, calls APIs

This separation makes every subsystem testable (mock the hand, unit-test the brain), pluggable (swap the hand without touching the brain), and observable (track planning cost separately from execution cost).

Deep dive: Brain and Hand in Trails

Quick Links¶