version:0.1
doc:index
updated:2026
Semantic Rails Documentation
This docs set mirrors the active runtime: an agent runtime built around the
capabilities → catalog → discover → inspect → build-options
→ validate → compile → execute loop, served over MCP and
/api/v1/*. capabilities and catalog are
orientation tools; plan, valid-values, and the
segment-* trio round out the 13-tool surface. The pages below cover
package authoring, the guided query APIs, planner semantics, explainability,
guardrails, and the agent-facing API path.
Recommended path:
Getting Started -> Agent Quickstart ->
Package Authoring ->
Architect MCP ->
Query Planner -> Agent Actions ->
Guardrails -> API Reference.
What this docs hub covers
- Quickstart commands based on
uv run semantic-rails .... - Agent setup paths for hosted MCP, local MCP, local HTTP, and supported-vs-experimental boundaries.
- The recommended
schema_version: 1authoring contract and the Jaffle reference package. - The preferred guided builder path:
capabilities -> catalog -> discover -> inspect -> build-options -> valid-values -> validate -> compile -> execute(the compile response carries the explain payload inline). - Planner semantics, explain output, and runtime boundaries.
- Agent quickstart, release benchmark, and comparison evidence for evaluation context.
Core runtime surfaces
| Surface | Role | Where to start |
|---|---|---|
semantic_rails/ |
Runtime package and planner | Query Planner |
configs/semantic_rails/jaffle_shop/ |
Active authored package | Package Authoring |
| Per-attribute YAML reference | Every authored field, type, default, and error code | Authoring Reference |
| Agent quickstart | Hosted MCP, local MCP, local HTTP, and supported surface boundaries | Agent Quickstart |
| Architect MCP | Developer workflow for creating and managing local semantic projects | Architect MCP |
| Agent action loop | Staged API path for apps and agents | Agent Actions |
/api/v1/* |
Public query and discovery API | API Reference |
Verification sources
- The comparison evidence under
comparisons/semantic_layers/. - Agent quickstart and benchmark evidence guide.
- The runtime docs in the main repo docs folder.
- The package examples and release-check commands used by maintainers.
quick.links
Quickstart: docs/getting-started.html Agent quickstart: docs/agent-quickstart.html Package authoring: docs/package-authoring.html Authoring reference: docs/authoring-reference.html Planner semantics: docs/query-planner.html Agent actions: docs/agent-actions.html Guardrails: docs/governance.html API surface: docs/api-reference.html
Continue to Getting Started for install, serve, and first-query flow.