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.

Cloud docs

Connect a warehouse, get a project into Cloud, and connect an assistant to the Cloud MCP.

What this docs hub covers

Quickstart commands: a one-command uvx try, your own package with --path, installing with uv tool install or a pinned uv venv --python 3.12, the semantic-rails setup --interactive wizard, and local profiles.
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 agent loop, discover -> plan -> execute, and the guided builder helpers build-options and valid-values.
Planner semantics, explain output, and runtime boundaries.
Agent quickstart, release benchmark, and comparison evidence for evaluation context.

Runtime and Cloud 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
Cloud connections	Warehouse credentials, network access and testing	Connect a warehouse
Cloud projects	Package authoring, upload, validation and promotion	Get a project into Cloud
Cloud MCP	Assistant connection and authentication	Connect assistants

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.