Skip to content

The Trails Handbook

Welcome to the Trails Handbook -- the official learning resource for building agentic knowledge-graph applications with Trails.

If you know Python but have never touched RDF, SPARQL, or knowledge graphs, you are in the right place. If you already know semantic web tech and want a framework that makes it productive, you are also in the right place. The handbook meets you where you are and walks you forward.

Start Here

New to Trails? Follow this path:

  1. Getting Started -- Install Trails, scaffold a project, write your first capability and node type. Takes about 15 minutes.

  2. Core Concepts -- Understand the mental model: knowledge graphs, capabilities, node types, shapes, the context object, and progressive enhancement. The chapter that makes everything else click.

  3. Working with Data -- Create, query, filter, and aggregate data using the ORM. Learn the query builder, Q combinators, property paths, and when to drop to raw SPARQL.

  4. Trust, Policy, and Identity -- Add Cedar policies, DID identity, cost envelopes, and provenance. The trust stack that makes Trails apps auditable and regulation-ready.

Once you have the basics, explore specialised topics:

  1. The Auto-Ontology Paradigm -- Load data first, let the framework discover your schema. Inference, generation, and refinement.

  2. Transformation, Enrichment, and Baselines -- Migrate schemas, fill gaps with enrichment functions, and validate projects against portable configuration contracts.

  3. WoT Integration and Memory Security -- Publish your agent as a WoT Thing, enforce identity and confidence on shared memory, and control what facts cross trust boundaries.

Learning Paths

Beginner (start here)

Chapter Time What you learn
Getting Started 15 min Install, scaffold, first capability
Core Concepts 30 min Mental model, decorators, context
Working with Data 30 min ORM queries, filters, SPARQL

Intermediate

Resource Time What you learn
Trust and Policy 30 min Cedar, DIDs, provenance, cost
Tutorial: Growing your KG app 45 min Full progressive-enhancement walk
Middleware guide 20 min @before, @after, @around
MCP guide 20 min Exposing capabilities to AI clients

Advanced

Resource Time What you learn
Agent runtime guide 30 min Sessions, planners, budgets
Federation guide 20 min Multi-instance SPARQL + MCP mesh
RML data mapping guide 20 min Declarative CSV/JSON/XML ingest
Auto-ontology guide 20 min Infer, generate, refine schemas
Transformation and Baselines 30 min Schema migration, enrichment, config contracts
WoT and Memory Security 30 min WoT discovery, memory gateway, trust boundaries
Architecture 30 min Kernel, FFI, request lifecycle

Reference Guides

The handbook teaches concepts and patterns. For exhaustive API reference, see the 19 deep-dive guides:

Full guide index: docs/guides/index.md

How to Read This Handbook

Each chapter follows the same structure:

  • Overview -- what the chapter covers and why it matters
  • Learning objectives -- what you will be able to do after reading
  • Worked examples -- runnable code you can copy into a project
  • What's next -- pointer to the next chapter and related guides

Code examples are written to be complete. If a block starts with from trails import ..., you can paste it into a file inside a Trails project and it will work. When a snippet builds on earlier code, the chapter says so explicitly.

Prerequisites

  • Python 3.11+ -- Trails uses PyO3 with the abi3-py311 stable ABI
  • A terminal -- all examples use the trails CLI
  • No RDF knowledge required -- the handbook introduces concepts as they become relevant, not before