Cosmos Semantic

Cosmos Semantic

An open-source semantic layer with an ontology at its core, so AI agents and apps get the same number on every database, with the proof in every answer.

[Live demo of the console](https://wiliamrosa.github.io/cosmos-semantic-platform/) · Quickstart · Docs · Article (em português)

AI agents that write SQL over raw tables return numbers that look right and that nobody can explain: "revenue" has three definitions, "active customer" means 60 days to one team and 90 to another. Cosmos Semantic defines metrics, business rules and concepts once, serves them to agents over MCP instead of letting them guess SQL, and attaches evidence to every answer.

The YAML format uses the dbt Semantic Layer vocabulary and ships a JSON Schema; Cube and dbt are import sources and export targets, not dependencies. The core is Apache 2.0 within an open-core model (ADR 0005).

Status: phases 0 to 3 are implemented: the engine, the ontology (glossary and business rules), the REST API, the MCP server, OIDC identity, verifiable numbers (evidence, replay, reconciliation, impact, bootstrap), business context (rule versions, usage and cost, knowledge graph, Power BI import, AI-assisted discovery, the retail pack, SKOS export) and the read-only console. See the roadmap.

Quickstart

pip install "cosmos-semantic[duckdb,testdata]"

cosmos init demo && cd demo cosmos demo-data cosmos query revenue average_order_value --by orders.status --evidence cosmos explain rule:active_customer

That is a governed metric with its evidence (formula, rules, policies, as_of and hashes) in about a minute, on a local DuckDB file. The quickstart continues with business rules, row filters, personal data and connecting an AI agent over MCP. Extras: duckdb, postgres, sqlserver, mysql (MySQL and MariaDB), oracle, databricks, snowflake, server (REST and MCP), ai (cosmos suggest), testdata.

Console

cosmos serve also serves a read-only console at /console, in English or Portuguese, for people who decide rather than build:

• metric health and ownership;
• business processes as graphs colored by health;
• the catalog in business words;
• every audited answer, with a button to reproduce it;
• usage and cost per agent.

cosmos check records rule tests and reconciliations against legacy reports, so the console shows health over time.

Development

Requires Python 3.11+ and uv. From a clone of this repository:

uv sync --all-extras

Generate synthetic e-commerce data into a local DuckDB (data/ecommerce.duckdb)

uv run cosmos demo-data -c examples/ecommerce/connections.yml # --locale pt_BR for Brazilian data with CPF

Validate the example model

uv run cosmos validate -m examples/ecommerce/semantic

Revenue and average order value by status

uv run cosmos query revenue average_order_value --by orders.status \ -m examples/ecommerce/semantic -c examples/ecommerce/connections.yml

Same query as CSV (raw values, header + one row per result row) for spreadsheets and scripts

uv run cosmos query revenue average_order_value --by orders.status --csv \ -m examples/ecommerce/semantic -c examples/ecommerce/connections.yml

Metrics from different models, with the user's row filter; --show-sql prints the generated SQL

uv run cosmos query revenue paid_value customer_count --by customers.region -u region=Midwest --show-sql \ -m examples/ecommerce/semantic -c examples/ecommerce/connections.yml

Business rules as a filter and as a grouping; --as-of pins "today"

uv run cosmos query customer_count --where "{rule.active_customer}" --by customers.segment \ -u region=Northeast --as-of 2026-10-22 -m examples/ecommerce/semantic -c examples/ecommerce/connections.yml

Evidence envelope: formulas, rules, policies, as_of and hashes; then replay the audited query

export COSMOS_AUDIT_LOG=data/audit.jsonl uv run cosmos query average_order_value --by customers.segment --where "{rule.active_customer}" -u region=Northeast --evidence -m examples/ecommerce/semantic -c examples/ecommerce/connections.yml uv run cosmos replay -m examples/ecommerce/semantic -c examples/ecommerce/connections.yml

Reconcile a governed metric with legacy SQL or another model, and explain the divergence

uv run cosmos reconcile revenue --by orders.status --sql legacy_revenue.sql -m examples/ecommerce/semantic -c examples/ecommerce/connections.yml uv run cosmos reconcile --cases examples/ecommerce/divergence_zoo.yml -m examples/ecommerce/semantic -c examples/ecommerce/connections.yml

What a change affects, and who queried it (also: --changes-from )

uv run cosmos impact rule:active_customer -m examples/ecommerce/semantic --audit data/audit.jsonl

Past numbers under the rule in effect then, or under today's rule

uv run cosmos query customer_count -w "{rule.active_customer}" --as-of 2026-06-30 --rules-as-of 2026-10-23 -u region=Midwest -m examples/ecommerce/semantic -c examples/ecommerce/connections.yml

Usage and estimated cost per metric, user, agent and data source (rates: cost in connections.yml)

uv run cosmos usage --audit data/audit.jsonl -m examples/ecommerce/semantic -c examples/ecommerce/connections.yml

The business knowledge graph: owners, source systems and processes (Mermaid, DOT or JSON)

uv run cosmos graph --focus process:order_to_cash -m examples/ecommerce/semantic uv run cosmos impact system:payment_gateway -m examples/ecommerce/semantic

AI-assisted discovery: concepts, rules, metrics and descriptions, validated by the engine, for review

(repeat --source to require that each suggestion runs on every database the model serves)

uv run cosmos suggest --source local -m examples/ecommerce/semantic -c examples/ecommerce/connections.yml -o suggestions.yml

Industry pack mapped onto your tables by name (draft + report for review)

uv run cosmos pack list uv run cosmos pack apply retail --source local --schema public -c examples/ecommerce/connections.yml -o semantic/retail.yml

The business glossary as SKOS/RDF for data catalogs (turtle, jsonld or ntriples)

uv run cosmos export skos -m examples/ecommerce/semantic -o glossary.ttl --base https://data.example.com/glossary/

Draft a model from the database catalog (keys, joins, measures, LGPD suggestions), then review it

uv run cosmos bootstrap -c examples/ecommerce/connections.yml -o semantic/draft.yml

Business rule examples (on DuckDB, without touching the data sources) and reference queries

uv run cosmos test -m examples/ecommerce/semantic uv run cosmos reference

Import models from other tools

uv run cosmos import cube path/to/model -o semantic/imported.yml uv run cosmos import dbt path/to/dbt/models --schema analytics -o semantic/dbt.yml uv run cosmos import ossie model.yaml -o semantic/ossie.yml uv run cosmos import powerbi model.bim -o semantic/powerbi.yml # or a TMDL folder

REST API and MCP

cosmos serve starts the REST API at /v1 and the MCP server at /mcp in the same process; interactive docs are at /docs.

# Production: tokens from the OIDC provider (Cosmos only validates, never issues)

export COSMOS_OIDC_ISSUER=https://login.microsoftonline.com/ /v2.0 export COSMOS_OIDC_AUDIENCE=api://cosmos-semantic

Development: API keys bound to a fixed context (a file with keys: { : {subject, user}})

export COSMOS_DEV_API_KEYS=dev-keys.yml

uv run cosmos serve -m examples/ecommerce/semantic -c examples/ecommerce/connections.yml curl -X POST localhost:8080/v1/query -H "X-API-Key: " -H "content-type: application/json" \ -d '{"metrics": ["revenue"], "dimensions": ["customers.segment"]}'

Remote MCP clients use /mcp as an OAuth protected resource: requests without a valid token get HTTP 401 with a WWW-Authenticate header pointing to /.well-known/oauth-protected-resource, which names the identity provider (set COSMOS_PUBLIC_URL behind a proxy).

For local MCP clients (Claude Desktop, Claude Code), use the stdio transport: cosmos mcp -m ... -c ... with COSMOS_API_KEY set. The tools are search_concepts, explain, list_members, query and show_sql. Every call runs as the user who owns the token; personal data never reaches agents.

Data sources

Local Postgres: docker compose -p cosmos-semantic -f deploy/docker-compose.yml up -d, then cosmos demo-data --target postgres and cosmos reference --source postgres. To also run the tests on Postgres, set COSMOS_PG_URI=postgresql://cosmos:cosmos@localhost:15432/cosmos.

Local SQL Server: docker compose -p cosmos-semantic -f deploy/docker-compose.yml --profile sqlserver up -d and COSMOS_MSSQL_URI='mssql+pymssql://sa:Cosmos!Passw0rd@localhost:14330/master'. Every data source accepts a schema_map in connections.yml (for example public: dbo) to use the same model with different schemas.

Local MySQL, MariaDB and Oracle Database Free: docker compose -p cosmos-semantic -f deploy/docker-compose.yml --profile mysql --profile mariadb --profile oracle up -d,