Metadata-Version: 2.4
Name: strict-semantic-mcp
Version: 0.1.1
Summary: Strict semantic-view linter and deterministic, FinOps-safe SQL compiler with an MCP server for AI data agents.
Author-email: Son Chau <46123450+noscn@users.noreply.github.com>
License-Expression: Apache-2.0
Project-URL: Repository, https://github.com/noscn/strict-semantic-mcp
Project-URL: Issues, https://github.com/noscn/strict-semantic-mcp/issues
Project-URL: Changelog, https://github.com/noscn/strict-semantic-mcp/blob/main/docs/REVISIONS.md
Keywords: semantic-layer,mcp,text-to-sql,sqlglot,bigquery,data-governance,finops
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: sqlglot>=26
Requires-Dist: pydantic>=2.5
Requires-Dist: pyyaml>=6
Provides-Extra: mcp
Requires-Dist: mcp>=2; extra == "mcp"
Provides-Extra: bigquery
Requires-Dist: google-cloud-bigquery>=3; extra == "bigquery"
Provides-Extra: duckdb
Requires-Dist: duckdb>=1; extra == "duckdb"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: duckdb>=1; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: mcp>=2; extra == "dev"
Dynamic: license-file

# strict-semantic-mcp

[![CI](https://github.com/noscn/strict-semantic-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/noscn/strict-semantic-mcp/actions/workflows/ci.yml)

**A CI linter for Snowflake-style semantic views, and a deterministic, FinOps-safe
semantic compiler + MCP server for AI data agents on BigQuery, DuckDB, Snowflake
and Postgres.**

Data warehouses like BigQuery have no native, strictly-enforced semantic views.
When text-to-SQL agents query them through loose YAML or flexible graph layers,
the failure modes are always the same: non-deterministic SQL, fan-out double
counting, ambiguous join paths, raw-row dumps, and runaway scan costs.

This project makes the semantic model a **blueprint, never a materialization**:

```
.sql DDL / .yaml spec ──parse──▶ canonical AST (Pydantic v2)
        ──lint (SV-R1..R10)──▶ valid blueprint
        ──compile(request)──▶ one deterministic SQL statement ──connector──▶ rows
```

- **Dual input, one AST.** Snowflake `CREATE SEMANTIC VIEW` DDL (human-authored)
  and a native YAML contract (automation-friendly) build byte-identical models.
- **Static ground rules (SV-R1..R10).** Primary keys and grain comments, a
  directed many-to-one join DAG with exactly one path between any two tables,
  no numeric dimensions, no `CURRENT_DATE`, snapshot metrics declared
  `NON ADDITIVE BY`, globally unique field names and synonyms, a security
  deny-list, comment templates. `strict-semantic lint` blocks CI on ERRORs.
- **Deterministic compilation.** Same request, same SQL, byte for byte. Joins
  only walk child→parent (zero fan-out, enforced); metrics of different grains
  drill across via `UNION ALL`; derived ratios divide NULL-safely; every
  expression is built as a sqlglot AST — no string concatenation anywhere.
- **FinOps guardrails.** At least one metric per query (no raw dumps),
  partition filters required and pushed into each table's subquery (the only
  placement BigQuery honors on joined tables), `LIMIT` injected and capped,
  BigQuery dry-run byte ceiling.
- **MCP server (mcp ≥ 2).** Five tools: `list_semantic_views`,
  `inspect_semantic_view`, `get_dimension_values`, `compile_semantic_query`,
  `execute_semantic_query`. The agent picks names from the catalog and never
  writes SQL; every refusal carries an error code and a repair hint.
- **Golden Questions eval.** `strict-semantic eval cases.yaml` grades
  answer/refuse/clarify cases against DuckDB deterministically — no LLM judge.
- **Open-core plugin hooks.** `on_model_loaded`, `before_compile` (RBAC filter
  injection), `after_compile` (cache/lineage), `on_query_executed` (audit).

## Quickstart

```bash
python -m venv .venv && .venv/bin/pip install -e '.[dev,mcp]'
.venv/bin/python -m pytest                                  # 64 tests
.venv/bin/strict-semantic lint tests/fixtures/ecommerce.sql
.venv/bin/strict-semantic eval tests/fixtures/golden_questions.yaml
.venv/bin/strict-semantic compile tests/fixtures/ecommerce.yaml \
    -m revenue -m aov -d region \
    -f '{"field":"order_date","op":">=","value":"2026-01-01"}' \
    -f '{"field":"order_date","op":"<","value":"2026-02-01"}' --dialect bigquery
```

Run the MCP server against the demo warehouse (in-memory DuckDB):

```bash
STRICT_SEMANTIC_CONFIG=$PWD/examples/config.duckdb.yml .venv/bin/strict-semantic-mcp
```

or register it with Claude Code:

```bash
claude mcp add strict-semantic -e STRICT_SEMANTIC_CONFIG=$PWD/examples/config.duckdb.yml -- $PWD/.venv/bin/strict-semantic-mcp
```

For BigQuery, copy `examples/config.bigquery.example.yml`, point `views:` at
your private spec folder, and set `max_bytes`.

## Writing a semantic view

Snowflake DDL (`.sql`) and the native YAML (`.yml`) are equivalent; metadata the
DDL has no slot for travels in structured comment directives (enforced by the
linter as SV-R8.1 templates):

```sql
CREATE SEMANTIC VIEW ecommerce
  TABLES (
    orders AS shop.orders PRIMARY KEY (order_id)
      COMMENT = 'One row per order. Primary date: order_date. Partition: order_date BY order_date. Source: shop.orders.',
    customers AS shop.customers PRIMARY KEY (customer_id)
      COMMENT = 'One row per customer. Primary date: signup_date. Source: shop.customers.'
  )
  RELATIONSHIPS ( orders_customers AS orders (customer_id) REFERENCES customers (customer_id) )
  DIMENSIONS (
    customers.region AS region WITH SYNONYMS ('market') COMMENT = 'Customer home region. Values: EU, US, APAC.',
    orders.order_date AS order_date COMMENT = 'Date the order was placed. Grains: day, week, month.'
  )
  METRICS (
    orders.order_count AS COUNT(order_id) COMMENT = 'Number of orders placed. Population: all orders. Additivity: additive.'
  )
  COMMENT = 'Retail sales.'
```

Directives: `One row per …` (grain), `Primary date: col.`,
`Point-in-time snapshot.`, `Partition: col BY dimension (lookback Nd, lookahead Nd).`,
`Grains: day, month.`, `Type: timestamp.`, `Values: a, b, c.`
See `tests/fixtures/ecommerce.{sql,yaml}` for the full twin fixtures.

## Querying

```json
{"metrics": ["revenue", "aov"], "dimensions": ["region", "order_date__month"],
 "filters": [{"field": "order_date", "op": "between", "value": ["2026-01-01", "2026-03-31"]},
             {"field": "aov", "op": ">", "value": 50}],
 "order_by": ["-revenue"], "limit": 100}
```

Time dimensions take a `__grain` suffix. Filters on dimensions apply before
aggregation, filters on metrics after. Dimension-only queries are refused
(`ERR_METRIC_REQUIRED`) — value discovery goes through `get_dimension_values`,
a bounded `SELECT DISTINCT … LIMIT ≤ 50`.

## Layout

```
src/strict_semantic/
├── models/        # canonical AST, error codes, request/response contracts
├── parsers/       # Snowflake DDL (token-stream) + native YAML -> one builder
├── linter/        # SV-R1..R10 engine: structure / logic / governance rules
├── compiler/      # join-graph resolver, FinOps guardrails, sqlglot SQL builder
├── connectors/    # DuckDB, BigQuery (dry-run + byte cap), protocol
├── plugins/       # open-core lifecycle hooks
├── eval/          # Golden Questions runner (deterministic, no LLM)
└── mcp_server/    # the five MCP tools over stdio
```

Design departures from the original blueprint, with reasons, are in
[docs/REVISIONS.md](docs/REVISIONS.md).

## Security & deployment responsibility

The server speaks **stdio** and is designed to run next to the agent, on your
machine, with your credentials. If you expose it over a network (HTTP/SSE,
a gateway, a shared host), authentication, transport security and tenant
isolation are yours to provide — nothing here does that for you.

Expect defense in depth from the warehouse side too: run the connector with a
**least-privilege, read-only** account scoped to the datasets the views name.
The compiler never concatenates SQL strings — filter values become typed
sqlglot literals, operators come from a fixed whitelist, and every identifier
must resolve against the linted model — but the SQL that reaches your warehouse
should still be gated by the warehouse's own permissions. Per the Apache 2.0
license, the software is provided as is, without warranty; securing the
deployment is the deployer's responsibility.

Report vulnerabilities privately via GitHub Security Advisories, not public
issues.

## Contributing

Scope is deliberately strict and minimal — read
[CONTRIBUTING.md](CONTRIBUTING.md) before proposing features. Short version:
determinism is non-negotiable, escape hatches get declined, and extensions
belong in plugins.

## License

Apache 2.0 (see [LICENSE](LICENSE) and [NOTICE](NOTICE)). Fixtures and examples
are a generic e-commerce schema; keep your company's semantic views in a
private repository and point the server at them via `STRICT_SEMANTIC_CONFIG`.
