SLayer — a semantic layer by Motley

A lightweight open-source semantic layer for AI agents and humans

Quick Start

# Install
pip install semantic-slayer[all]

# Start the HTTP server
slayer serve --models-dir ./my_models

# Or set up stdio MCP for an agent like Claude Code
# (the agent spawns slayer as a subprocess — you don't run this manually)
claude mcp add slayer -- slayer mcp --models-dir ./my_models

What is SLayer?

SLayer sits between your data and your apps or AI agents. Instead of writing raw SQL, agents describe what data they want — measures, dimensions, filters — and SLayer handles the rest.

Key features:

• Agent-first design — MCP, Python SDK, and REST API interfaces
• Datasource-agnostic — Postgres, MySQL, BigQuery, Snowflake, and more via sqlglot
• fields API — Describe derived metrics with formulas ("revenue / count", "cumsum(revenue)", "time_shift(revenue, -1, 'year')") in a single list
• Auto-ingestion with rollup joins — Connect to a DB, introspect schema, generate denormalized models with FK-based LEFT JOINs automatically
• Incremental model editing — Add/remove measures and dimensions without replacing the full model
• Lightweight — Minimal dependencies, easy to set up and extend

Interfaces

REST API

# Query
curl -X POST http://localhost:5143/query \
  -H "Content-Type: application/json" \
  -d '{"model": "orders", "fields": [{"formula": "count"}], "dimensions": [{"name": "status"}]}'

# List models (returns name + description)
curl http://localhost:5143/models

# Get a single datasource (credentials masked)
curl http://localhost:5143/datasources/my_postgres

# Health check
curl http://localhost:5143/health

MCP Server

SLayer supports two MCP transports:

Stdio — the agent spawns SLayer as a subprocess (for Claude Code, Cursor, etc.). You do not run slayer mcp manually; instead, register it with your agent:

# Register with Claude Code (the agent will spawn the process itself)
claude mcp add slayer -- slayer mcp --models-dir ./my_models

# If slayer is in a virtualenv, use the full path to the executable:
#   poetry env info -p   # prints e.g. /home/user/.venvs/slayer-xyz
#   claude mcp add slayer -- /home/user/.venvs/slayer-xyz/bin/slayer mcp --models-dir /path/to/my_models

SSE (Server-Sent Events) — MCP over HTTP, served alongside the REST API on /mcp. You run slayer serve yourself, then point the agent at the URL:

# 1. Start the server (REST API + MCP SSE)
slayer serve --models-dir ./my_models
# REST API at http://localhost:5143/query, /models, etc.
# MCP SSE at http://localhost:5143/mcp/sse

# 2. In a separate terminal, register the remote MCP endpoint with your agent
claude mcp add slayer-remote --transport sse --url http://localhost:5143/mcp/sse

Both transports expose the same tools — no duplication.

MCP tools:

Tool	Description
models_summary	List all models with their schemas (dimensions, measures)
inspect_model	Detailed model info with sample data
query	Execute semantic queries
create_model	Create a new model from table/SQL
add_measures	Add measures to an existing model
add_dimensions	Add dimensions to an existing model
delete_measures_dimensions	Remove measures or dimensions by name
update_model	Update model metadata (description, data source)
delete_model	Delete a model
create_datasource	Configure a database connection (with connection test and auto-ingestion; set auto_ingest=false to skip)
list_datasources	List configured datasources
describe_datasource	Show datasource details, test connection, list schemas
list_tables	Explore tables in a database
delete_datasource	Remove a datasource
ingest_datasource_models	Auto-generate models from DB schema

Typical agent workflow:

1. create_datasource (auto-ingests models by default) → models_summary → inspect_model → query
2. Or with auto_ingest=false: create_datasource → describe_datasource → ingest_datasource_models → models_summary → query

Python Client

from slayer.client.slayer_client import SlayerClient
from slayer.core.query import SlayerQuery, ColumnRef

# Remote mode (connects to running server)
client = SlayerClient(url="http://localhost:5143")

# Or local mode (no server needed)
from slayer.storage.yaml_storage import YAMLStorage
client = SlayerClient(storage=YAMLStorage(base_dir="./my_models"))

# Query data
query = SlayerQuery(
    model="orders",
    fields=[{"formula": "count"}, {"formula": "revenue_sum"}],
    dimensions=[ColumnRef(name="status")],
    limit=10,
)
df = client.query_df(query)
print(df)

CLI Query

# Run a query directly from the terminal
slayer query '{"model": "orders", "fields": [{"formula": "count"}], "dimensions": [{"name": "status"}]}'

# Or from a file
slayer query @query.json --format json

Models

Models are defined as YAML files. Add an optional description to help users and agents understand complex models:

name: orders
sql_table: public.orders
data_source: my_postgres
description: "Core orders table with revenue metrics"

dimensions:
  - name: id
    sql: id
    type: number
    primary_key: true
  - name: status
    sql: status
    type: string
  - name: created_at
    sql: created_at
    type: time

measures:
  - name: count
    type: count
  - name: revenue_sum
    sql: amount
    type: sum
  - name: revenue_avg
    sql: amount
    type: avg

Fields

The fields parameter specifies what data columns to return. Each field has a formula string and an optional name:

{
  "model": "orders",
  "dimensions": [{"name": "status"}],
  "time_dimensions": [{"dimension": {"name": "created_at"}, "granularity": "month"}],
  "fields": [
    {"formula": "count"},
    {"formula": "revenue_sum"},
    {"formula": "revenue_sum / count", "name": "aov"},
    {"formula": "cumsum(revenue_sum)"},
    {"formula": "change_pct(revenue_sum)"},
    {"formula": "last(revenue_sum)", "name": "latest_rev"},
    {"formula": "time_shift(revenue_sum, -1, 'year')", "name": "rev_last_year"},
    {"formula": "lag(revenue_sum, 2)", "name": "rev_2_periods_ago"},
    {"formula": "rank(revenue_sum)"}
  ]
}

Formulas are parsed using Python's ast module (see slayer/core/formula.py). Available functions: cumsum, lag, lead, change, change_pct, rank, last (most recent value via FIRST_VALUE), time_shift (year-over-year etc. via self-join CTE).

Functions that need ordering over time resolve the time dimension via: query time_dimensions (if exactly one) -> model default_time_dimension -> error. The time_shift function also uses a granularity argument (year, month, quarter, etc.) and generates a self-join CTE.

Filter Templates

Use variables to parameterize queries with {var_name} placeholders in filter values:

{
  "model": "orders",
  "fields": [{"formula": "count"}, {"formula": "revenue_sum"}],
  "filters": [
    {"member": {"name": "status"}, "operator": "equals", "values": ["{status}"]},
    {"member": {"name": "customer_id"}, "operator": "equals", "values": ["{cid}"]}
  ],
  "variables": {"status": "completed", "cid": 42}
}

If the entire value is a single {var}, the variable's native type is preserved (int, date, etc.). Mixed strings like "prefix_{var}" do string substitution. Missing variables are left as-is.

Auto-Ingestion

Connect to a database and generate models automatically. SLayer introspects the schema, detects foreign key relationships, and creates denormalized models with rollup-style LEFT JOINs.

For example, given tables orders → customers → regions (via FKs), the orders model will automatically include:

• Rolled-up dimensions: customers__name, regions__name, etc.
• Count-distinct measures: customers__count, regions__count
• A SQL query with transitive LEFT JOINs baked in

# Via CLI
slayer ingest --datasource my_postgres --schema public

# Via API
curl -X POST http://localhost:5143/ingest \
  -d '{"datasource": "my_postgres", "schema_name": "public"}'

Via MCP, agents can do this conversationally:

1. create_datasource(name="mydb", type="postgres", host="localhost", database="app", username="user", password="pass")
2. ingest_datasource_models(datasource_name="mydb", schema_name="public")
3. models_summary() → inspect_model(model_name="orders") → query(...)

Configuration

Datasources are configured as individual YAML files in the datasources/ directory:

# datasources/my_postgres.yaml
name: my_postgres
type: postgres
host: ${DB_HOST}
port: 5432
database: ${DB_NAME}
username: ${DB_USER}
password: ${DB_PASSWORD}

Environment variable references (${VAR}) are resolved at read time. Both username and user field names are accepted.

Storage Backends

SLayer ships with two storage backends:

• YAMLStorage (default) — models and datasources as YAML files on disk. Great for version control.
• SQLiteStorage — everything in a single SQLite file. Good for embedded use or when you don't want to manage files.

from slayer.storage.yaml_storage import YAMLStorage
from slayer.storage.sqlite_storage import SQLiteStorage

# YAML files in a directory
storage = YAMLStorage(base_dir="./slayer_data")

# Single SQLite file
storage = SQLiteStorage(db_path="./slayer.db")

Both implement the StorageBackend protocol, so you can swap them freely or write your own:

from slayer.storage.base import StorageBackend

class MyCustomStorage(StorageBackend):
    def save_model(self, model): ...
    def get_model(self, name): ...
    def list_models(self): ...
    def delete_model(self, name): ...
    # same for datasources

Pass any backend to create_app(), create_mcp_server(), or SlayerClient(storage=...).

Examples

The examples/ directory contains runnable examples that also serve as integration tests:

Example	Description	How to run
embedded	SQLite, no server needed	python examples/embedded/run.py
postgres	Docker Compose with Postgres + REST API	cd examples/postgres && docker compose up -d

Each example includes a verify.py script that runs assertions against the seeded data.

Both examples use a shared seed dataset (examples/seed.py) with a small e-commerce schema: regions, customers, products, and orders (68 orders across 12 months). The embedded example includes derived column demo queries using fields.

Claude Code Skills

SLayer includes Claude Code skills in .claude/skills/ to help Claude understand the codebase:

• slayer-overview — architecture, package structure, MCP tools list
• slayer-query — how to construct queries with fields, dimensions, filters, time dimensions
• slayer-models — model definitions, datasource configs, auto-ingestion, incremental editing

Development

# Install with all extras
poetry install -E all

# Run tests
poetry run pytest

# Lint
poetry run ruff check slayer/ tests/

# Start dev server
poetry run slayer serve

Why SLayer?

SLayer is embeddable

Besides being a standalone service, SLayer is also a Python module. That's why it can also be directly imported and used in Python applications with no network communication involved.

For example, using it in a multi-tenant application could be as simple as:

client = SlayerClient(storage=MyStorage(tenant_id=...))

No need for setting up network and auth at all.

SLayer models can be updated on the fly

In SLayer, models are treated as a dynamic part of the process, rather than something that is preconfigured and frozen. Models can be created or edited at any time and immediately queried. We expose tools for interacting with the models via API, CLI and MCP.

SLayer is flexible

Slayer is agnostic to the datasource type: it can be an SQL database, a BI tool or even a REST API. Adapters for popular databases are included, but adding a new one just takes implementing 3 straightforward methods: a query-to-datasource-input translator and a result-to-dataframe parser. Please open a pull request if you write one!

Known limitations

SLayer currently has no caching or pre-aggregation engine. If you need to process lots of requests to large databases at sub-second latency, consider specialized tools like CubeJS, dbt, AtScale, Looker, etc.

License

MIT — see LICENSE.