Semantic Rails is an open-source semantic layer for AI agents. You define metrics, dimensions and join paths once, in YAML. Agents then find those definitions, validate a query and compile SQL through an MCP server, a CLI or an HTTP API, instead of writing joins and metric formulas by hand.
uvx semantic-rails ask --package jaffle_shop "revenue by store" --run
An agent writing SQL against raw tables has to guess join paths and metric formulas, and a wrong join returns a plausible number, not an error. With Semantic Rails, the definitions live in a versioned package, and the agent works through separate tools: it finds governed IDs, drafts Query IR, validates it and compiles SQL whose join paths it can inspect. The plain-English planner is rule-based and can miss part of a question, so every draft comes back as Query IR you can check before it runs.
Scope classification runs
inline on discover and plan -
out-of-scope intents come back as structured blocks before
the planner touches the warehouse. The sixth tool,
segment, validates, explains and previews
package-authored segments.
The compiler walks the entity graph, checks direction and cardinality
at every hop, and reports the route it chose in a
hop_profile next to the SQL. A shape it can't rewrite
safely stops with a typed error and a hint instead of SQL. These are
compile responses from semantic-rails 0.3.0 for hand-built Query IR on
the bundled jaffle_shop package.
Every command uses the published package from PyPI. You need
uv;
it fetches Python 3.11 or newer if your system Python is older. Run the
Terminal commands first, in the directory you'll use: the Claude Code,
Cursor, Claude Desktop and Codex tabs connect the my_package
they create. The commands are for macOS and Linux shells; Windows isn't
covered by our checks yet.
uvx semantic-rails init my_package --yes uvx semantic-rails project validate --path ./my_package uvx semantic-rails ask --path ./my_package "total amount by event type" --run
init writes a runnable starter package:
YAML models, metrics, examples, tests and CSV data. Pass
--path, or run commands inside the package directory;
without either, and without a saved profile, commands stop with
no_package_selected.
claude mcp add semantic-rails -- uvx semantic-rails mcp stdio --path "$PWD/my_package"
Install the command and print the two absolute paths the
config needs, then add the server to .cursor/mcp.json.
uv tool install semantic-rails echo "$(uv tool dir --bin)/semantic-rails" echo "$PWD/my_package"
{
"mcpServers": {
"semantic-rails": {
"command": "/absolute/path/to/semantic-rails",
"args": ["mcp", "stdio", "--path", "/absolute/path/to/my_package"]
}
}
}
uv tool install semantic-rails "$(uv tool dir --bin)/semantic-rails" mcp setup --path "$PWD/my_package" --client claude --mcp query --install --yes
Run mcp setup without --install
--yes first to preview the change. uv tool dir --bin
finds the command even when uv's tool directory isn't on your
PATH yet; uv tool update-shell adds it for new
terminals.
codex mcp add semantic-rails -- uvx semantic-rails mcp stdio --path "$PWD/my_package"
claude mcp add --transport http semantic-rails-demo https://semantic-rails.com/mcp codex mcp add semantic-rails-demo --url https://semantic-rails.com/mcp
The hosted endpoint serves synthetic Jaffle Shop data only. It is anonymous and rate-limited, and it can't load your package. See the demo policy.
They may be the better choice for you. They're more mature and connect to far more BI tools. Semantic Rails is narrower: an engine built around the agent loop, which you can run locally or embed.
explain payload on compile (over MCP,
execute in sql mode; at compact or
full verbosity) that shows the join
route it chose and the other candidates it considered.The comparison pack shows how each layer expresses the same questions. It doesn't show that Semantic Rails is better at them.
The comparison pack asks the same 16 questions of six semantic layers and records how each one expresses them. It measures capability, not speed. One published rubric labels all six; the page explains its modeling limits.
Semantic Rails is beta software. This is what works today, what doesn't yet, and what is being built.
The open-source runtime, the CLI, MCP over stdio and HTTP, the
/api/v1/* HTTP API, DuckDB and Snowflake execution,
package authoring, validation, compile and explain. Postgres, BigQuery,
Databricks, Athena, ClickHouse, MotherDuck and DuckLake are supported
with guardrails; they're tested against live warehouses on demand, not
in every CI run.
The engine, CLI, MCP servers and HTTP API are Apache-2.0, with no gated features and no telemetry, and you don't need anything else to use them. SR Cloud is a separate hosted product in early access: connect your warehouse, build shared semantic models, and invite teammates. Explore metrics together and serve governed answers through API and MCP.
If Semantic Rails doesn't fit the way your agent works, tell us why.