semantic-risk-engine 0.1.0

Detect semantic SQL changes and estimate deterministic risk.

Semantic Risk Engine

Detect semantic SQL changes and compute deterministic risk classifications.

Installation

pip install semantic-risk-engine
# or with uv
uv add semantic-risk-engine

Python API quickstart

from semantic_engine import DiffEngine, RiskEngine

old_sql = "SELECT id, name FROM users WHERE active = 1"
new_sql = "SELECT id FROM users"

diff = DiffEngine().diff(old_sql, new_sql, dialect="snowflake")
report = RiskEngine().compute_risk(diff)

for item in report.high:
    print(f"HIGH: {item.change.identifier}")
    print(f"  {item.reason}")

For type annotations, import from semantic_engine.models:

from semantic_engine.models import SemanticDiff, RiskReport, RiskItem, Change

How it works

SQL is parsed into a sqlglot AST and extracted into a normalized SemanticModel (tables, joins, columns, filters, aggregations, window functions, CTEs, subqueries). Two SemanticModels are diffed to produce a SemanticDiff — a structured list of semantic changes. Each change is classified into HIGH / MEDIUM / LOW / INFO risk based on data-contract impact rules. No query execution, no database connections — pure static analysis.

CLI

semantic-risk-engine diff old.sql new.sql
semantic-risk-engine diff old.sql new.sql --dialect bigquery

Options:

• --dialect — sqlglot dialect name (default: snowflake)

Dialect support

The dialect parameter defaults to "snowflake" and accepts any sqlglot dialect string, for example "bigquery", "spark", "duckdb", "postgres". Output expressions are rendered in the specified dialect.

Development

Run tests:

uv run pytest

Run one test file:

uv run pytest tests/test_diff_engine.py

Lint:

uv run ruff check .
uv run ruff format --check .

See CONTRIBUTING.md for contribution guidelines.