feat: add Sigma data model connector

[mattsenicksigma]

Summary

Adds a sigma connector that ingests Sigma data model YAML files into four new normalized tables, giving agents a queryable semantic surface for Sigma workbooks.

• AGENTS.SIGMA_DATA_MODEL — one row per .sigma.yaml file (name, description, source file path)
• AGENTS.SIGMA_ELEMENT — one row per kind: table element; PK is the dotted warehouse path (ANALYTICS.REVENUE.ORDERS), which joins to the column and metric tables
• AGENTS.SIGMA_COLUMN — all columns with a kind field (direct for bare [TABLE/Col] references, computed for derived expressions)
• AGENTS.SIGMA_METRIC — metrics whose formula is a single standard SQL aggregate (Sum, Avg, Count, CountDistinct, Min, Max over one column)

Design decisions worth noting

source_path as PK, not Sigma's UUID. The warehouse path is human-readable, stable across data model renames, and meaningful to agents querying the table. Sigma's internal dataModelId/element id fields are opaque UUIDs that convey nothing to a language model.

Metric filtering. Only metrics with a direct SQL aggregate equivalent are written. Conditional aggregations (SumIf, CountDistinctIf), cross-metric references ([Metrics/A] / [Metrics/B]), multi-field expressions (Sum([Qty] * [Price])), and statistical functions (PercentileCont) are silently skipped. The SPEC documents exactly which patterns are excluded and why.

Deduplication. When two data model files reference the same warehouse table, the first file alphabetically wins. This is deterministic (files are sorted before ingest) and documented in SPEC.

ai_context not included. Sigma exposes AI context in the UI (File > Set AI context) but it is not returned by the GET /v2/dataModels/{id}/spec?format=yaml API endpoint used to export data model YAML — confirmed against the API spec. It cannot be ingested.

Malformed YAML safety. An empty or non-mapping .sigma.yaml file raises ValueError with a clear message ("{file}: expected a YAML mapping, got NoneType") rather than an opaque AttributeError mid-ingest. ValueError is now also caught at the CLI level (this also improves the existing lookml connector, which raises ValueError for unterminated blocks).

Files changed

File	Change
src/agents_schema/sigma.py	New connector (189 lines)
src/agents_schema/cli.py	sigma subcommand; ValueError added to error handler
src/agents_schema/root.py	5 sigma ROOT_ENTRIES
tests/test_sigma.py	103 tests
tests/test_root.py	Sigma root entries assertion
tests/test_connector_root.py	Sigma connector root ordering
SPEC.md	Full sigma section (DDL, column descriptions, metric exclusion table)
sigma-setup.md	Setup guide (API export, warehouse credentials, workflow example)
README.md	Sigma added to TOC and supported sources
pyproject.toml	Description and keywords updated
.github/workflows/agents-schema-sigma.yml	Reusable workflow
.github/actions/agents-schema-sigma/action.yml	Composite action

Version pin note

The composite action pins agents-schema==0.0.9. The sigma subcommand will be available once a new version is published to PyPI — the pin should be updated to that version before the action is live. Happy to do that in a follow-up commit once the release version is decided.

Test plan

• 103 unit tests pass (pytest tests/)
• agents-schema sigma --sigma-dir <path> works against a real Sigma YAML export
• Connector root ordering verified (test_connector_root.py)
• All edge cases covered: empty YAML, no pages, no table elements, duplicate source paths, missing formula, missing metric name

🤖 Generated with Claude Code

[mattsenicksigma]

A more human comment
Overall: I want to start using this internally here at Sigma, and of course that means making it work with Sigma

Sigma Data Models are OSI compliant, and this conversion tries to map all elements to items maintained by the concepts of this repo

The following considerations were made in the making of this pr:

• Sigma allows for nontrivial formulas in the formulas they allow in data models, only "simple" functions are allowed in the metric conversion here
• Previous architecture is referenced as much as possible, only handling exceptions with the Sigma API, which hope to be resolved in future pr's as the sigma REST API matures
• Extensive testing is provided
• Sigma maintains id's for all objects -> but wherever possible these are ignored and the database path is utilized
• Malformed yaml errors out and does not compile
• Sigma does not provide an ai_context field via the REST API just yet, but will hopefully soon (I'll speak with the team owning this endpoint)
• All documentation is updated analogously to other sources of semantic layering
• the 5 core items offered are: overview, data_model, element, column, metric

[abhijeethp]

LGTM!

[levonkorganyan]

@mattsenicksigma Pending merge conflict resolution this is good to go

[mattsenicksigma]

@levonkorganyan / @abhijeethp resolved the one line conflict, just need a restamp here and I can merge!

[mattsenicksigma]

@levonkorganyan / @abhijeethp just resolved the new merge conflict