SemZero is a dbt-first semantic assumption check for SQL changes.

Early alpha: semzero==0.8.0a6 is intended for local review and advisory PR comments. It should not be used as an automatic production merge blocker yet.

Install

pip install semzero==0.8.0a6

For local development from this repository:

pip install -e ".[dev]"
pytest

Quickstart

Run SemZero from inside a dbt project tracked by git:

semzero doctor
semzero check

semzero doctor explains what SemZero can see: git, dbt project files, dbt availability, manifest files, and write access for run artifacts.

semzero check compares your current branch or working tree against an inferred git base, analyzes changed dbt SQL, writes artifacts to .semzero/runs/<run-id>/, and prints a short human summary.

Typical quiet output:

SemZero Assumption Gate
Result: QUIET
Changed files: 1
dbt compile: unavailable
Analysis fidelity: medium
No review-worthy semantic assumption change detected.
Artifacts: .semzero/runs/<run-id>/

Typical review output:

SemZero Assumption Gate
Result: REVIEW RECOMMENDED
Primary risk: Enum Domain Closure
File: models/intermediate/int_payment_summary.sql
Why: CASE fallback changed from 'pending' to 'unresolved'.
Recommended next check:
  dbt build --select int_payment_summary+
Artifacts: .semzero/runs/<run-id>/

Exit codes are scriptable:

• 0 means quiet / no review-worthy semantic change detected.
• 1 means review recommended.
• 2 means SemZero setup or runtime error.

Static SQL Fallback

SemZero tries to use dbt compile artifacts when they are available. Many engineers do not have local warehouse credentials or a working dbt profile on a laptop, so semzero check falls back to static SQL plus git diff analysis instead of crashing.

When dbt compile is unavailable, the terminal summary says:

Analysis fidelity: medium
Note: dbt compile unavailable; used static SQL fallback.

Fallback mode is useful for first-pass review, but compiled SQL and dbt artifacts provide higher-fidelity lineage and evidence.

Validated Alpha Capabilities

The current public alpha is intentionally narrow and dbt-first. Validated behavior includes:

• Local semzero check and semzero doctor with no SemZero-specific config.
• Static SQL fallback when dbt compile is unavailable.
• Advisory GitHub PR comments for dbt SQL changes.
• Enum/domain closure changes such as changed CASE fallbacks.
• Grain and join structural risks such as GROUP BY key changes or join-key changes.
• Schema contract breaks when a removed selected column is used downstream.
• Used-vs-unused schema distinction to avoid over-firing on local-only changes.
• Format-only and CTE-rename/refactor silence.
• Messy or massive rewrite broad warnings when precise ranking would be misleading.
• JSON/Markdown artifacts for receipts, comments, ranking decisions, changed files, and summaries.

Known Limitations

• Metric-formula drift and filter/population drift are still experimental and are not promoted as confident production findings yet.
• SemZero is optimized for dbt SQL projects. Kafka, streaming contracts, and broad warehouse monitoring are not current public scope.
• Static fallback has lower fidelity than compiled dbt analysis.
• The public alpha is advisory. Review findings manually before using SemZero as a required CI gate.
• Memory/flywheel scoring is not wired into public ranking yet.
• SemZero does not repair SQL or make warehouse changes.

GitHub PR Path

The local command is the simplest first-user path. Teams can also run SemZero in GitHub Actions for advisory PR comments and uploaded artifacts. The same dbt-first assumption-gate behavior powers both surfaces.

Generated artifacts commonly include:

• receipt.json
• comment.md
• production_ranking_adapter.json
• shadow_hypothesis_receipt.json
• ranking_comparison.json
• changed_files.txt
• changed.diff
• dbt_compile.status.json
• repo_snapshot.json

Experimental And Legacy Surfaces

Some older modules remain in the repository for research, compatibility, or future product work, including broader warehouse replay, chaos/wind-tunnel experiments, repair automation, and legacy lab commands.

They are not the recommended public alpha path. For external dbt users, start with:

semzero doctor
semzero check

Security

SemZero may process dbt manifests, compiled SQL, model names, table names, lineage metadata, and optional warehouse metadata. Do not include production secrets, credentials, private customer data, or sensitive query output in public bug reports.

See SECURITY.md.

Release Notes

• 0.8.0a6