Trails Guides¶
Learn how to build agentic-semantic-web applications with Trails.
Getting started¶
| Tutorial | Description |
|---|---|
| Getting Started | 10-minute path from zero to a running capability |
| Growing Your KG App | Start with one capability, add typed data, validation, reasoning, and policy — one feature at a time (ADR-0021) |
Guides¶
| Guide | Description |
|---|---|
| Shapes & Validation | Declare data shapes, validate inputs/outputs, export SHACL |
| Capabilities & Dispatch | Define capabilities, handle invocations, record provenance |
| ActiveGraph ORM | @node_type, ctx.kg.add, Model.where, Q combinators, deletes, escape hatches (ADR-0017) |
| Label-first Knowledge Graph | ctx.kg.node / edge / match / traverse, types= interop, trails kg CLI — untyped authoring under ADR-0021 |
| MCP Integration | Expose capabilities, resources, and prompts over Model Context Protocol — stdio + SSE (per-client sessions), subscribe + list_changed notifications |
| Policy & Authorization | Write Cedar policies, enforce access control with @policy |
| Capability Middleware | @before / @after / @on_error / @around — cross-cutting concerns (audit, metrics, arg/result transform) |
| Document Ingestion | trails.ingest — PDF/HTML/Markdown/DOCX/RTF/text extractors, paragraph chunker, Document + Chunk node types, content-hash dedup, PROV-O, chunk-to-vector handoff (ADR-0019) |
| RML Data Mapping | trails.rml — declarative CSV/JSON/XML-to-KG mapping via RML + Morph-KGC, @rml_source registry, PROV-O provenance, trails rml run/validate CLI (ADR-0024) |
| Federation | trails.federation — read-only SPARQL endpoint exposure, Cedar policy gating, cost tracking, W3C SPARQL Protocol HTTP routes (ADR-0023) |
| Auto-Ontology | trails.onto_infer — data-first schema discovery: deterministic schema inference from existing KG data, LLM-assisted generation (Phase 2), usage-driven refinement (Phase 3) (ADR-0025) |
| Schema Transformation | trails.onto_transform — declarative schema-to-schema transformation: auto-mapping, SPARQL CONSTRUCT generation, placeholder fields for enrichment (ADR-0026) |
| Enrichment Pipeline | trails.enrichment — fill placeholder fields with @enrichment functions: computed, API lookup, regex, or optional LLM; cost-tracked, PROV-O provenance (ADR-0026) |
| Baseline Configurations | trails.baselines — portable semantic contracts: built-in presets, custom TOML baselines, inheritance, trails doctor integration, federation negotiation (ADR-0027) |
Cutting Edge¶
| Guide | Description |
|---|---|
| Temporal KG | trails.temporal — bitemporal queries, as_of(), history(), temporal_diff() (ADR-0035) |
| Semantic Diff | trails.kg_diff — git-style change tracking for knowledge graphs (ADR-0036) |
| Hypothesis Agents | trails.agent.planners.hypothesis — scientific reasoning with grounded citations (ADR-0037) |
| Explainable Provenance | trails.explain — citation graphs, confidence propagation, counterfactuals (ADR-0038) |
| Live Schema Inference | trails.schema_watcher — streaming schema discovery from KG writes (ADR-0039) |
| Multi-Modal Nodes | trails.multimodal — binary attachments as first-class KG citizens (ADR-0040) |
| CRDT Editing | trails.crdt — conflict-free concurrent graph mutations (ADR-0041) |
| Agent Memory | trails.memory — persistent shared knowledge for AI agents: learn, recall, correct, forget, link, explain, diff across sessions and tools (ADR-0051) |
Runtime primitives¶
| Guide | Description |
|---|---|
| LLM Client & Session | trails.llm.LLMClient (Anthropic / Ollama / mock) + Session / TokenWindow with auto cost + PROV-O (ADR-0018) |
| Agent Runtime | trails.agent.planners.react — ReAct loop with tool discovery, retries, cost + PROV (ADR-0018) |
| Vector Retrieval | trails.vector — embedders, SqliteVecStore / QdrantStore, and hybrid SPARQL+vector retrieve() (ADR-0019) |
| Admin UI (MVP) | trails-admin — optional FastAPI + HTMX operator UI: auto-generated capability forms, PROV-O run inspector, ingestion dashboard (ADR-0019) |
| Testing | trails.testing — isolated_kernel, mock_llm, capture_events, fresh_context, pytest fixtures |
| Observability | Event hook (register_observer), capability + LLM + KG events, OpenTelemetry bridge, TrailsTracer / TrailsMetrics (ADR-0012, ADR-0018) |
Prerequisites¶
- Python 3.11+
- Rust 1.85+ (for building the kernel from source)
pip install trails(or development install from source)
Architecture at a glance¶
Trails apps follow a layered architecture:
Python surface (@shape, @capability, @policy)
│
trails-ffi (PyO3 bindings)
│
Rust kernel (trails-graph, trails-shapes, trails-caps, trails-prov, ...)
│
Graph store (Oxigraph, Fuseki, Qlever)
Your application code lives entirely in Python. The Rust kernel handles graph storage, SHACL validation, provenance recording, and capability dispatch. Communication happens transparently through PyO3 FFI.