Semantic Runtime

CI License: MIT Python

Semantic infrastructure layer for AI Agents: semantic understanding, context resolution, evidence, and safe execution between models and tools.

Models provide intelligence. Tools provide capability. Semantic Runtime provides understanding.

Status

• Shipped: core data models (Entity / Relation / Metric / Evidence / Policy), YAML model loader, registry, graph engine, deterministic context resolver, metric dependency resolution, schema connectors (SQLite, PostgreSQL, MySQL, Snowflake), SQL guardrails, model integrity validation, policy-based operation validation, SafetyProvider extension point, MCP server (stdio + streamable HTTP), five built-in domain packs, the v0.2 benchmark framework (six question types, SRB score), docker compose quick start, and the killer demo.
• Planned: JoinLint adapter integration, plugin system, third-party community packs, Snowflake-verified integration, Mode B agent evaluation, and scripts tooling.

Design Documents

Specifications live in docs/; the Obsidian index is Semantic Runtime.md.

• PRD — positioning, problem, vision, scope
• Protocol Specification — MCP tools, core objects, protocol principles
• Reference Architecture — core modules and integrations
• Data Model Specification — Entity / Relation / Metric / Evidence / Policy
• API & MCP Specification — Python SDK, MCP tools, error model
• Implementation Blueprint — repository layout, milestones
• MVP Demo Design — e-commerce revenue demo
• Open Source Strategy — adoption and ecosystem
• Future Roadmap — Phase 1-5 roadmap
• Post v0.1 Roadmap — Phase 6-10 execution plan, v0.2-v1.0 evolution
• Benchmark Plan v0.2 — six question types, SRB scoring, Mode A/B split
• Validation and Adoption Plan — real-world validation framework, adoption stages

Superseded v0.1 drafts are archived in docs/archive/.

Repository Layout

docs/                  design specifications (source of truth)
src/semantic_runtime/  core runtime packages
  core/  models/  loaders/  context/  safety/  evidence/  mcp/  connectors/
tests/unit/            unit tests
tests/integration/     integration tests (MCP server, connectors, benchmarks)
benchmarks/            v0.2 framework: runner, scorer, per-domain datasets
examples/              demo semantic models and scripts
scripts/               development tooling (planned)

Development

python -m pip install -e '.[dev]'
python -m pytest -q
python -m ruff check src tests

The repository is uv-managed for reproducible environments:

uv sync --extra dev
uv run pytest -q

MCP Server

Serve any semantic model to MCP clients over stdio:

python -m semantic_runtime.mcp                                   # e-commerce pack
python -m semantic_runtime.mcp path/to/semantic_model.yaml       # your model

Exposes five tools: list_entities, describe_entity, get_metric, resolve_context, and validate_operation. Try it with any MCP client (e.g. Claude Desktop) pointed at the command above, or connect with the SDK:

from semantic_runtime.core import SemanticRuntime
from semantic_runtime.packs import load_pack

runtime = SemanticRuntime(load_pack("ecommerce"))
context = runtime.resolve_context("Why did revenue drop?")
print(context.matched_terms)  # ["revenue"]

Benchmarks

The v0.2 framework (see the Benchmark Plan) evaluates runtime capability with six question types — semantic understanding, entity discovery, relationship reasoning, metric dependency, evidence grounding, and safety validation — and reports a weighted SRB score with a hard safety gate:

python benchmarks/runner.py --domain ecommerce                 # full run
python benchmarks/runner.py --domain ecommerce --type metric_dependency
python benchmarks/runner.py --domain ecommerce --safety
python benchmarks/runner.py --domain ecommerce --output report.json

Legacy entry points remain available: benchmarks/run_benchmark.py and benchmarks/run_safety_eval.py.

Docker

docker compose up              # serves the e-commerce pack over streamable HTTP on :8000

docker build -t semantic-runtime .
docker run --rm -i semantic-runtime            # MCP over stdio, e-commerce pack

For an HTTP endpoint instead of stdio:

python -m semantic_runtime.mcp --http --port 8000

Quick Start (five minutes)

1. Install: pip install 'semantic-runtime[dev]' (or uv sync --extra dev)
2. Run the MCP server: python -m semantic_runtime.mcp (stdio, e-commerce pack)
3. Wire it into Claude Desktop with examples/claude_desktop_config.example.json (copy the mcpServers block into your claude_desktop_config.json); Cursor users add the same block to .cursor/mcp.json
4. Ask: "Why did revenue decrease last month?"
5. Generate the demo database for connector experiments:

python examples/ecommerce/seed_db.py        # creates examples/ecommerce/shop.db

Safety

Deterministic safety checks run before any operation; nothing executes side-effectful SQL. validate defaults to deny: policies must explicitly allow an action, and SQL guardrails reject multi-statements and UPDATE/DELETE without WHERE:

runtime.validate("execute.query")                       # allow=True (policy)
runtime.validate("execute.query", sql="DELETE FROM orders")  # allow=False, UNSAFE_DELETE_NO_WHERE
runtime.validate_model()                                 # integrity: relations/metrics resolve

Operation safety runs through a SafetyProvider — inject your own to plug in external engines (JoinLint adapters implement check_operation):

from semantic_runtime.core import SemanticRuntime
from semantic_runtime.safety import SafetyReport

class MyProvider:
    def check_operation(self, action, sql):
        return SafetyReport()  # safe

runtime = SemanticRuntime.load("model.yaml", safety_provider=MyProvider())

Semantic Packs

Built-in domain semantic models ship with the package:

from semantic_runtime.core import SemanticRuntime
from semantic_runtime.packs import load_pack

runtime = SemanticRuntime(load_pack("ecommerce"))  # ecommerce, saas, finance, game, healthcare

Each pack provides entities, relations, metrics, evidence, and policies. Load a local community pack directory with load_pack("name", base_dir=path).

Demo

python examples/ecommerce/demo.py                      # e-commerce
python examples/ecommerce/demo.py --pack saas          # any built-in pack
python examples/ecommerce/demo.py --pack finance --question "What is the portfolio value?"
python examples/ecommerce/demo.py --mcp                # serve over MCP instead

Schema Connectors

Map database schemas into semantic models (tables become entities, foreign keys become relations). SQLite works out of the box; PostgreSQL and MySQL require their extras:

from semantic_runtime.connectors import SQLiteConnector, map_schema
from semantic_runtime.core import SemanticRuntime

schema = SQLiteConnector("shop.db").load_schema()
runtime = SemanticRuntime(map_schema(schema))

pip install 'semantic-runtime[postgres]'   # or [mysql]

from semantic_runtime.connectors import PostgresConnector, map_schema

schema = PostgresConnector("postgres://user:pass@localhost/shop").load_schema()

Contributing

See CONTRIBUTING.md for ground rules, setup, and how to propose changes. All participants agree to the Code of Conduct. Report security issues privately per SECURITY.md.

License

MIT — see LICENSE.