Agentic knowledge-graph framework.
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. Every feature is additive — code you write on day one keeps working on day 365.
Status: pre-alpha (
v0.1.0a0). The API is stabilizing but may change before v1.0. See the roadmap.
pip install -e ./python # local install (no PyPI release yet)
trails new blog && cd blog
trails serverWrite your first app:
from trails import App
app = App("blog")
@app.model("Post", fields={"title": str, "body": str})
class Post: pass
@app.capability("create_post")
def create_post(ctx, title: str, body: str) -> dict:
post = Post(title=title, body=body)
post.save(ctx)
return {"id": str(post.iri)}
app.run() # http://localhost:8000app.run() discovers capabilities automatically, exposes them over MCP
and HTTP, and records provenance. No config files, no boilerplate.
| Feature | Description |
|---|---|
| ActiveGraph ORM | Django-parity ORM for knowledge graphs — @node_type, Model.where(), Q combinators, property-path traversal |
| Agent Runtime | ReAct, Plan-and-Execute, and Reflexion planners with PROV-O trails and cost envelopes |
| 4 LLM Providers | Anthropic, OpenAI, Ollama, and Mock — same .complete() API, one-line swap |
| Trust Stack | Cedar policies (evaluation; invoke-boundary enforcement WIP), DIDs, verifiable credentials, provenance, cost tracking, consent receipts — all opt-in |
| Data Integration | PDF/HTML/Markdown ingestion, RML mapping via Morph-KGC (trails[rml]), auto-ontology, enrichment pipelines |
| Federation | SPARQL endpoint, SERVICE queries, MCP relay, ontology exchange with schema fingerprints and gossip discovery |
| Design Patterns | FSM, Pipeline, Unit of Work (client-side batching, not ACID isolation), Facade (App), Proxy (FederationPeer) |
| Security | SSRF protection, auth on HTTP endpoints, SPARQL injection prevention, path traversal guards, configurable endpoint groups |
| MCP Native | Tools, Resources, Prompts over Model Context Protocol — works with Claude, Cursor, and any MCP client |
| Vector Search | Hybrid SPARQL + vector retrieval with pluggable embedders and stores |
| Temporal KG | Bitemporal queries — as_of(), history(), temporal_diff(). Track how knowledge changes over time |
| Hypothesis Agents | Scientific reasoning: observe, hypothesize, test, report — with grounded citations |
| Explainable Provenance | Citation graphs, confidence propagation |
| Semantic Diff | trails kg diff — git-style change tracking for knowledge graphs |
| Multi-Modal Nodes | Binary attachments (images, PDFs) as first-class KG citizens |
| CRDT Editing | LWW-Element-Set for concurrent graph mutations — event-based tracking (not SPARQL-level interception) |
| Live Schema Inference | Real-time schema discovery from KG writes — detects drift, suggests types |
| Selective Disclosure | Reveal only specific VC claims — salted-hash redaction |
| Config System | trails.toml with 12 sections, env var overrides, trails config show/validate |
trails next |
Contextual advisor — suggests the next step based on your project's current state |
| Admin UI | Optional FastAPI + HTMX dashboard for browsing the graph, capabilities, and provenance |
┌─────────────────────────────────────────────────┐
│ Python Surface │
│ @capability · @node_type · @shape · @policy │
│ ORM · Agents · Federation · 15+ more features │
├─────────────────────────────────────────────────┤
│ trails._bridge (auto-detect backend) │
├──────────────────────┬──────────────────────────┤
│ Python backend │ Rust kernel (optional) │
│ pyoxigraph │ trails._core via PyO3 │
└──────────────────────┴──────────────────────────┘
Python-first, Rust-optional. pip install trails works without a
Rust toolchain — the pure-Python backend uses pyoxigraph. Install the
optional Rust kernel (trails[rust]) for lower latency and stricter
panic boundaries. The bridge layer auto-detects which backend is
available.
trails new <name> # Scaffold a project (--template minimal|agent|kg|full)
trails server [--watch] # MCP or HTTP server with hot reload
trails console # REPL with Q, planners, LLMClient, ctx
trails g cap|sh|res <name> # Rails-style generators
trails kg query|dump|count # Ad-hoc graph debugging
trails doctor # Health checks (store, LLM, federation, schemas)
trails onto infer|generate # Auto-ontology from data or natural language
trails rml run|validate # RML data mapping
trails enrich run|status # Enrichment pipeline execution
trails federation status # Federation peer management
trails baseline validate # Config contract validation
trails next # Contextual next-step advisor
trails config show|validate|init # Configuration management
trails kg history|diff|snapshot # Temporal + semantic diff
trails explain show|citations # Explainable provenance
trails routes --all # All HTTP + MCP + capability routes
trails cred issue|verify|derive # Verifiable credentials
trails vocab list|diff # Vocabulary management
trails test --discover # Test discovery + snapshotsSee examples/README.md for the full learning path — from hello world to production apps, organized by difficulty level.
| Resource | Description |
|---|---|
| Guides Website | MkDocs site at /docs when served; deployable via Gitea Pages |
| Handbook | 11-chapter learning path from zero to production |
| Guides | 22 feature-focused reference guides |
| Tutorial | Walk the progressive enhancement ladder |
| ADRs | 41+ architecture decision records |
| API Reference | Auto-generated from source |
- One surface, additive features — no tiers, no module splits (ADR-0021)
- MCP-first transport — stdio by default, HTTP on demand (ADR-0008)
- Cedar for authorization — policy evaluation available; invoke-boundary enforcement in progress (ADR-0006)
- Provenance always on — PROV-O on every write (ADR-0009)
- Cost as a primitive — nested envelopes with dedup (ADR-0012)
- Python-first, Rust-optional —
pip install trailsworks without Rust - Temporal by default — PROV-O on every write, bitemporal queries opt-in
- Explainable AI — every agent answer links to its evidence
# Python surface (no Rust needed)
cd python && pip install -e ".[dev]" && pytest tests/
# Rust kernel (optional)
cd rust && cargo test --workspace
# Docker (pure Python — no Rust needed)
docker build -t trails .
docker run -p 8080:8080 -v ./myapp:/app trails
# Docker with Rust kernel (requires Dockerfile with multi-stage build)
# docker build -t trails:rust --target rust .
# Documentation site
./scripts/docs-serve # live reload at localhost:8000
./scripts/docs-build # build to _site/3600+ Python test functions across 130+ test files. ~98 Rust unit tests across 7 active crates (5 archived).
Apache License 2.0. Free and open source — use, modify, and distribute, including commercially, with an explicit patent grant.