Log in Explore Cloud
version:0.2 doc:index updated:2026

Build a semantic layer for AI agents

Semantic Rails is a Python semantic layer for AI agents. Define business metrics, relationships, and policies in YAML, then let agents discover those definitions, validate semantic queries, and compile governed SQL. Connect through the Model Context Protocol (MCP), HTTP API, or command line.

Start with a local semantic layer and your first query, or follow the MCP setup guide for AI assistants. The runtime guides agents through discovery, inspection, validation, compilation, and execution, with query plans and policy checks available along the way.

Define your data with the package authoring guide and YAML field reference. Use Architect MCP to author packages with an assistant, then explore query planning, governance and guardrails, and the SQL query API and CLI reference.

What this docs hub covers

  • Quickstart commands based on uv venv, uv pip install 'semantic-rails>=0.2.0', semantic-rails setup --interactive, local profiles, and explicit --path usage for automation.
  • Agent setup paths for hosted MCP, local MCP, local HTTP, MCP doctor checks, and supported-vs-experimental boundaries.
  • The recommended schema_version: 1 authoring contract, plus the bundled Jaffle fixture for smoke tests.
  • 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.