00 — Vision¶

Trails in one paragraph¶

Trails is Rails for agentic knowledge-graph apps. One surface: start with nodes and edges, add types when you want validation, add SHACL when you want closed-world checks, add OWL when you want reasoning or interop. Every feature is additive. Code you write on day one keeps working on day 365 — new features never force rewrites. See concepts/progressive-enhancement.md for the conceptual overview of this ladder, and ADR-0021 for the normative decision.

The 15-second demo¶

trails new blog && cd blog && trails server

That scaffolds one app.py, starts the server, auto-detects transport (stdio when piped to an MCP client, HTTP otherwise), and serves this:

@capability
def hello(name: str) -> str:
    return f"Hello, {name}"

No IRI, no predicate, no shape, no SPARQL in sight. The capability is auto-exposed over MCP and HTTP, with provenance recorded on every call. This is the Sprint-1 target surface¹ — positional @capability, bare decorator, a one-file scaffold.

Growing into the stack¶

The same hello above is valid Trails code. When you need more, you add one line at a time — never rewrite.

Step 1. Nodes and edges. Store data without declaring a type:

ctx.kg.add({"name": "Alice", "role": "admin"})

Step 2. Add a node type when you want input validation:

@node_type("User", fields={"name": str, "role": str})

Existing hello unchanged. The added type gives you JSON-Schema validation on writes to User-labelled nodes.

Step 3. Add a shape when you want closed-world validation:

@shape  # IRI auto-minted from trails.toml base_iri[^1]
class User:
    name: str
    role: str

Step 4. Add OWL when you want reasoning or cross-system interop:

:Admin rdfs:subClassOf :User .

Query with SPARQL, reason with the embedded reasoner, publish your ontology for other systems to consume. The hello capability from Step 1 still works unchanged.

Cedar, PROV-O, and SHACL all use the strongest available typing present on each entity — label only, JSON-Schema type, or RDF class. One code path, feature-detected at dispatch time.

Trust stack is a ceiling, not a floor¶

The primitives for trustworthy agent apps — Cedar policy with a typed decision log, DIDs and verifiable credentials, PROV-O provenance on every write, SHACL validation of inputs and outputs, OWL reasoning, consent receipts emitted to the principal's wallet, capability tokens, replayable traces, content-addressed caching on idempotent capabilities, per-capability cost envelopes with token and USD budgets — are all present and first-class. You opt into them by adding the feature.

That matters because the constraints are real. LLMs finally made RDF cheap to produce and consume: the bottleneck of Semantic Web 1.0 — human-authored ontologies and triples — is gone. Agents prefer semantically-typed, self-describing, discoverable capabilities over REST shaped for human-written clients. MCP is the first broadly adopted protocol in this shape but under-specifies preconditions, provenance, cost, and consent. EU AI Act Article 12 logging, GDPR on agent-mediated data flows, and emerging FTC guidance all require traceability, consent, and purpose-binding that Rails-era frameworks cannot produce. DIDs, consent receipts, biscuit-style capabilities, and embedded triple stores like Oxigraph have matured from drafts into shipping infrastructure.

Trails wires these into one coherent default. You do not pay for them until you need them, and you do not re-architect when you do.

Who this is for¶

A developer evaluating Trails probably comes from one of three shapes:

• Evidence graphs. Research and analysis tools where every claim needs a provenance chain — compliance-style assistants, compliance research, audit-ready literature review. You get PROV-O for free and grow into SHACL when reviewers push back on claim quality.
• Entity graphs. Teams coming from Neo4j who want ACID storage, label-first modelling, and room to grow into semantics without re-platforming. Start with ctx.kg.add(...); add OWL the week someone asks for cross-system interop.
• Regulated-industry agent apps. Healthtech, legaltech, govtech shipping under EU AI Act with auditable decision logs, typed policies, and consent receipts built into the request path from day one.

Who this is not for¶

Not a Neo4j drop-in; storage is Oxigraph RDF, not labelled property graphs. Not a LangChain replacement; Trails is the app framework below your agent orchestrator. Not a CMS. Not a general-purpose ML platform. Not a better REST framework — use Rails, Django, or FastAPI for that.