bricksentry 0.1.0__py3-none-any.whl

bricksentry/policy.py

@@ -0,0 +1,221 @@
+"""Policy-as-code. Deterministic: the verdict always comes from these rules,
+never from an LLM, so agents and CI get the same answer for the same change.
+
+``policy.yml``::
+
+    default: pass
+    notify_owners_on: needs_human
+    rules:
+      - name: duplicate-keys
+        when: {duplicate_keys: true}
+        then: block
+      - name: dropped-column
+        when: {column_removed: true}
+        then: needs_human
+      - name: certified-downstream
+        when: {downstream_tag: certified}
+        then: needs_human
+      - name: big-row-loss
+        when: {removed_pct_gt: 1}
+        then: needs_human
+      - name: revenue-moved
+        when: {column: amount, sum_change_pct_gt: 2}
+        then: needs_human
+      - name: wide-blast-radius
+        when: {downstream_count_gt: 25}
+        then: warn
+
+All conditions inside one ``when`` must hold (AND). Use several rules for OR.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+from typing import Any
+
+from bricksentry.models import ImpactNode, RuleHit, TableDiff, Verdict
+
+DEFAULT_POLICY: dict[str, Any] = {
+    "default": "pass",
+    "notify_owners_on": "needs_human",
+    "rules": [
+        {"name": "diff-failed", "when": {"diff_error": True}, "then": "needs_human"},
+        {"name": "duplicate-keys", "when": {"duplicate_keys": True}, "then": "block"},
+        {"name": "dropped-column", "when": {"column_removed": True}, "then": "needs_human"},
+        {"name": "type-change", "when": {"column_type_changed": True}, "then": "warn"},
+        {"name": "certified-downstream", "when": {"downstream_tag": "certified"}, "then": "needs_human"},
+        {"name": "pii-table", "when": {"tag": "pii"}, "then": "needs_human"},
+        {"name": "row-loss", "when": {"removed_pct_gt": 1}, "then": "needs_human"},
+        {"name": "many-rows-changed", "when": {"changed_pct_gt": 10}, "then": "warn"},
+        {"name": "numeric-total-moved", "when": {"sum_change_pct_gt": 5}, "then": "warn"},
+        {"name": "dashboard-downstream", "when": {"downstream_kind": "dashboard", "any_change": True}, "then": "warn"},
+        {"name": "wide-blast-radius", "when": {"downstream_count_gt": 25}, "then": "warn"},
+    ],
+}
+
+KNOWN_CONDITIONS = {
+    "table", "tag", "downstream_tag", "downstream_kind", "downstream_count_gt",
+    "removed_pct_gt", "added_pct_gt", "changed_pct_gt", "row_count_change_pct_gt",
+    "row_count_drop_pct_gt", "column_removed", "column_type_changed", "column_added",
+    "duplicate_keys", "column", "sum_change_pct_gt", "null_increase_gt",
+    "any_change", "diff_error",
+}
+
+
+class PolicyError(ValueError):
+    pass
+
+
+class Policy:
+    def __init__(self, spec: dict[str, Any] | None = None):
+        spec = spec if spec is not None else DEFAULT_POLICY
+        self.default = Verdict(spec.get("default", "pass"))
+        self.notify_on = Verdict(spec.get("notify_owners_on", "needs_human"))
+        self.rules = spec.get("rules") or []
+        for r in self.rules:
+            unknown = set((r.get("when") or {}).keys()) - KNOWN_CONDITIONS
+            if unknown:
+                raise PolicyError(f"Rule {r.get('name')!r} uses unknown condition(s): {sorted(unknown)}")
+            Verdict(r.get("then", "warn"))
+
+    def evaluate(
+        self,
+        table: str,
+        diff: TableDiff | None,
+        downstream: list[ImpactNode],
+        tags: dict[str, str],
+        diff_error: str | None = None,
+    ) -> tuple[Verdict, list[RuleHit]]:
+        hits: list[RuleHit] = []
+        for r in self.rules:
+            ok, reason = _match(r.get("when") or {}, table, diff, downstream, tags, diff_error)
+            if ok:
+                hits.append(RuleHit(rule=r.get("name", "unnamed"), verdict=Verdict(r.get("then", "warn")), table=table, reason=reason))
+        verdict = Verdict.worst([self.default] + [h.verdict for h in hits])
+        return verdict, hits
+
+
+def _has_tag(tags: dict[str, str], want: Any) -> bool:
+    if isinstance(want, dict):
+        return all(str(tags.get(k, "")).lower() == str(v).lower() for k, v in want.items())
+    want = str(want).lower()
+    for k, v in tags.items():
+        if k.lower() == want and str(v).lower() not in ("false", "no", "0"):
+            return True
+        if str(v).lower() == want:
+            return True
+    return False
+
+
+def _match(
+    when: dict[str, Any],
+    table: str,
+    diff: TableDiff | None,
+    downstream: list[ImpactNode],
+    tags: dict[str, str],
+    diff_error: str | None,
+) -> tuple[bool, str]:
+    reasons: list[str] = []
+    for cond, val in when.items():
+        if cond == "column":
+            continue  # modifier for sum_change_pct_gt / null_increase_gt
+        if cond == "diff_error":
+            if bool(diff_error) != bool(val):
+                return False, ""
+            reasons.append(f"diff could not run: {diff_error}")
+            continue
+        if cond == "table":
+            if not fnmatch.fnmatch(table.lower(), str(val).lower()):
+                return False, ""
+            continue
+        if cond == "tag":
+            if not _has_tag(tags, val):
+                return False, ""
+            reasons.append(f"table is tagged {val}")
+            continue
+        if cond == "downstream_tag":
+            m = [n.name for n in downstream if _has_tag(n.tags, val)]
+            if not m:
+                return False, ""
+            reasons.append(f"{len(m)} downstream asset(s) tagged {val}: {', '.join(m[:3])}")
+            continue
+        if cond == "downstream_kind":
+            m = [n.name for n in downstream if n.kind == str(val).lower()]
+            if not m:
+                return False, ""
+            reasons.append(f"{len(m)} downstream {val}(s): {', '.join(m[:3])}")
+            continue
+        if cond == "downstream_count_gt":
+            if len(downstream) <= float(val):
+                return False, ""
+            reasons.append(f"{len(downstream)} downstream assets")
+            continue
+
+        # Everything below needs a diff.
+        if diff is None:
+            return False, ""
+        if cond == "any_change":
+            if diff.is_identical == bool(val):
+                return False, ""
+            continue
+        if cond == "duplicate_keys":
+            dup = diff.duplicate_keys_candidate > diff.duplicate_keys_base
+            if dup != bool(val):
+                return False, ""
+            reasons.append(f"{diff.duplicate_keys_candidate} duplicate key(s) in candidate (base had {diff.duplicate_keys_base})")
+            continue
+        if cond == "column_removed":
+            if bool(diff.schema.removed) != bool(val):
+                return False, ""
+            reasons.append(f"columns removed: {', '.join(diff.schema.removed)}")
+            continue
+        if cond == "column_added":
+            if bool(diff.schema.added) != bool(val):
+                return False, ""
+            reasons.append(f"columns added: {', '.join(diff.schema.added)}")
+            continue
+        if cond == "column_type_changed":
+            if bool(diff.schema.type_changed) != bool(val):
+                return False, ""
+            reasons.append(
+                "type changes: " + ", ".join(f"{k} {a}->{b}" for k, (a, b) in diff.schema.type_changed.items())
+            )
+            continue
+        if cond in ("removed_pct_gt", "added_pct_gt", "changed_pct_gt"):
+            attr = cond.replace("_gt", "")
+            pct = getattr(diff, attr)
+            if pct <= float(val):
+                return False, ""
+            reasons.append(f"{attr.replace('_pct', '')} {pct:.2f}% of rows (> {val}%)")
+            continue
+        if cond == "row_count_change_pct_gt":
+            if abs(diff.row_count_change_pct) <= float(val):
+                return False, ""
+            reasons.append(f"row count changed {diff.row_count_change_pct:+.2f}%")
+            continue
+        if cond == "row_count_drop_pct_gt":
+            if -diff.row_count_change_pct <= float(val):
+                return False, ""
+            reasons.append(f"row count dropped {-diff.row_count_change_pct:.2f}%")
+            continue
+        if cond == "sum_change_pct_gt":
+            col = when.get("column")
+            cols = [c for c in diff.columns if (col is None or c.column == col) and c.sum_change_pct is not None]
+            m = [c for c in cols if abs(c.sum_change_pct) > float(val)]
+            if not m:
+                return False, ""
+            reasons.append(", ".join(f"sum({c.column}) {c.sum_change_pct:+.2f}%" for c in m[:3]))
+            continue
+        if cond == "null_increase_gt":
+            col = when.get("column")
+            m = [
+                c for c in diff.columns
+                if (col is None or c.column == col)
+                and c.base_nulls is not None and c.candidate_nulls is not None
+                and (c.candidate_nulls - c.base_nulls) > float(val)
+            ]
+            if not m:
+                return False, ""
+            reasons.append(", ".join(f"{c.column} nulls +{c.candidate_nulls - c.base_nulls}" for c in m[:3]))
+            continue
+    return True, "; ".join(reasons) or "matched"

bricksentry/preview.py

@@ -0,0 +1,79 @@
+"""``preview_write``: see what a write would do *before* it touches production.
+
+1. Clone the target into the sandbox schema (Delta SHALLOW CLONE on Databricks:
+   metadata only, no data copied).
+2. Point the write at the clone (``{{target}}`` placeholder, or the target name
+   is rewritten to the clone name).
+3. Run the write against the clone and diff clone vs. the untouched target.
+4. Drop the clone (unless ``keep=True``).
+
+Guards: a single statement only, it must be INSERT / MERGE / UPDATE / DELETE /
+CREATE OR REPLACE TABLE whose write target is the clone, and the production
+table name must not survive the rewrite. So a preview cannot write to production.
+"""
+
+from __future__ import annotations
+
+import re
+import uuid
+
+PLACEHOLDER = "{{target}}"
+
+_WRITE_RE = re.compile(
+    r"^\s*(?:INSERT\s+(?:INTO|OVERWRITE)(?:\s+TABLE)?|MERGE\s+INTO|UPDATE|DELETE\s+FROM|"
+    r"CREATE\s+OR\s+REPLACE\s+TABLE|REPLACE\s+TABLE)\s+(?P<target>[`\"\w.\-]+)",
+    re.IGNORECASE,
+)
+_FORBIDDEN_RE = re.compile(r"\b(DROP|TRUNCATE|GRANT|REVOKE|ALTER|VACUUM|RESTORE)\b", re.IGNORECASE)
+
+
+class PreviewGuardError(ValueError):
+    pass
+
+
+def sandbox_name(sandbox_schema: str, target: str) -> str:
+    short = target.split(".")[-1]
+    return f"{sandbox_schema}.{short}__preview_{uuid.uuid4().hex[:8]}"
+
+
+def _strip_quotes(name: str) -> str:
+    return name.replace("`", "").replace('"', "").lower()
+
+
+def _strip_sql_comments_and_strings(sql: str) -> str:
+    sql = re.sub(r"--[^\n]*", " ", sql)
+    sql = re.sub(r"/\*.*?\*/", " ", sql, flags=re.S)
+    return re.sub(r"'(?:[^'\\]|\\.|'')*'", "''", sql)
+
+
+def rewrite_for_preview(sql: str, target: str, clone: str, quote) -> str:
+    """Return SQL that writes to ``clone`` instead of ``target``. Raises PreviewGuardError if unsafe."""
+    body = sql.strip().rstrip(";").strip()
+    code = _strip_sql_comments_and_strings(body)
+    if ";" in code:
+        raise PreviewGuardError("preview_write accepts exactly one SQL statement")
+    if _FORBIDDEN_RE.search(code):
+        raise PreviewGuardError("preview_write only runs INSERT / MERGE / UPDATE / DELETE / CREATE OR REPLACE TABLE")
+
+    clone_q = ".".join(quote(p) for p in clone.split("."))
+    if PLACEHOLDER in body:
+        out = body.replace(PLACEHOLDER, clone_q)
+    else:
+        parts = [re.escape(p) for p in target.split(".")]
+        pattern = r"(?<![\w.])" + r"\.".join(rf"[`\"]?{p}[`\"]?" for p in parts) + r"(?![\w])"
+        out, n = re.subn(pattern, clone_q, body, flags=re.IGNORECASE)
+        if n == 0:
+            raise PreviewGuardError(
+                f"Could not find {target} in the SQL. Write it literally or use the {PLACEHOLDER} placeholder."
+            )
+
+    m = _WRITE_RE.match(out)
+    if not m:
+        raise PreviewGuardError("Statement must start with INSERT, MERGE, UPDATE, DELETE or CREATE OR REPLACE TABLE")
+    if _strip_quotes(m.group("target")) != _strip_quotes(clone):
+        raise PreviewGuardError(f"The write target must be {target}; got {m.group('target')}")
+
+    leftover = re.compile(r"(?<![\w.])" + re.escape(_strip_quotes(target)) + r"(?![\w])")
+    if leftover.search(_strip_quotes(_strip_sql_comments_and_strings(out))):
+        raise PreviewGuardError("Production table name still present after rewrite; refusing to run")
+    return out

bricksentry/report.py

@@ -0,0 +1,88 @@
+"""Markdown report for pull-request comments and job summaries."""
+
+from __future__ import annotations
+
+from bricksentry.models import Assessment, TableAssessment, Verdict
+
+MARKER = "<!-- bricksentry-report -->"
+
+_ICON = {
+    Verdict.PASS: "🟢",
+    Verdict.WARN: "🟡",
+    Verdict.NEEDS_HUMAN: "🟠",
+    Verdict.BLOCK: "🔴",
+}
+_TITLE = {
+    Verdict.PASS: "Safe to ship",
+    Verdict.WARN: "Safe to ship, with warnings",
+    Verdict.NEEDS_HUMAN: "Needs human review",
+    Verdict.BLOCK: "Blocked",
+}
+
+
+def to_markdown(a: Assessment, max_downstream: int = 15) -> str:
+    v = a.verdict
+    lines = [
+        MARKER,
+        f"## {_ICON[v]} bricksentry: {_TITLE[v]}",
+        "",
+        f"**Risk tier:** `{v.risk_tier}` · **Tables checked:** {len(a.tables)} · **Assessment:** `{a.id}`",
+    ]
+    if a.notify:
+        lines.append(f"**Review requested from:** {', '.join(a.notify)}")
+    lines.append("")
+    if a.hits:
+        lines += ["### Why", "", "| Verdict | Rule | Table | Reason |", "|---|---|---|---|"]
+        for h in sorted(a.hits, key=lambda h: -h.verdict.rank):
+            lines.append(f"| {_ICON[h.verdict]} `{h.verdict.value}` | {h.rule} | `{h.table}` | {_esc(h.reason)} |")
+        lines.append("")
+    for t in a.tables:
+        lines += _table_section(t, max_downstream)
+    lines += ["", "<sub>Generated by bricksentry. Verdicts come from policy rules, not from an LLM.</sub>"]
+    return "\n".join(lines)
+
+
+def _table_section(t: TableAssessment, max_downstream: int) -> list[str]:
+    out = [f"### {_ICON[t.verdict]} `{t.table}`", "", t.summary, ""]
+    d = t.diff
+    if d and not d.error:
+        out += [
+            "| Base rows | Candidate rows | Added | Removed | Changed | Unchanged |",
+            "|---:|---:|---:|---:|---:|---:|",
+            f"| {d.base_rows:,} | {d.candidate_rows:,} | {d.added_rows:,} | {d.removed_rows:,} | "
+            f"{d.changed_rows:,} | {d.unchanged_rows:,} |",
+            "",
+        ]
+        changed_cols = [c for c in d.columns if c.changed_rows or (c.sum_change_pct and abs(c.sum_change_pct) > 0.01)]
+        if changed_cols:
+            out += ["<details><summary>Column changes</summary>", "",
+                    "| Column | Rows changed | Nulls (base → cand.) | Sum change |", "|---|---:|---|---:|"]
+            for c in sorted(changed_cols, key=lambda c: -c.changed_rows):
+                sc = f"{c.sum_change_pct:+.2f}%" if c.sum_change_pct is not None else "–"
+                out.append(f"| `{c.column}` | {c.changed_rows:,} | {c.base_nulls} → {c.candidate_nulls} | {sc} |")
+            samples = [c for c in changed_cols if c.samples]
+            if samples:
+                out += ["", "**Sample changes**", ""]
+                for c in samples[:3]:
+                    for s in c.samples[:3]:
+                        key = ", ".join(f"{k}={s.get(k)}" for k in d.keys)
+                        out.append(f"- `{c.column}` @ {key}: `{s.get('base_value')}` → `{s.get('candidate_value')}`")
+            out += ["", "</details>", ""]
+    if t.downstream:
+        out += [f"<details><summary>Blast radius: {len(t.downstream)} downstream asset(s)</summary>", "",
+                "| Depth | Kind | Name | Owner | Tags |", "|---:|---|---|---|---|"]
+        for n in sorted(t.downstream, key=lambda n: (n.depth, n.kind))[:max_downstream]:
+            tags = ", ".join(f"{k}={v}" if v else k for k, v in n.tags.items()) or "–"
+            out.append(f"| {n.depth} | {n.kind} | `{n.name}` | {n.owner or '–'} | {tags} |")
+        if len(t.downstream) > max_downstream:
+            out.append(f"| … | | {len(t.downstream) - max_downstream} more | | |")
+        out += ["", "</details>", ""]
+    if t.rollback and t.rollback.startswith("RESTORE"):
+        out += ["**Rollback:**", "```sql", t.rollback, "```", ""]
+    elif t.rollback:
+        out += [f"**Rollback:** {t.rollback}", ""]
+    return out
+
+
+def _esc(s: str) -> str:
+    return s.replace("|", "\\|").replace("\n", " ")

bricksentry-0.1.0.dist-info/METADATA

@@ -0,0 +1,186 @@
+Metadata-Version: 2.5
+Name: bricksentry
+Version: 0.1.0
+Summary: Change-safety for Databricks pipelines and the AI agents that edit them: data diffs, Unity Catalog blast radius, policy verdicts and rollback plans.
+Author: Brahma
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: ai-agents,ci,data-diff,data-engineering,data-quality,databricks,delta-lake,impact-analysis,lineage,mcp,unity-catalog
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: all
+Requires-Dist: databricks-sdk>=0.30; extra == 'all'
+Requires-Dist: duckdb>=1.0; extra == 'all'
+Requires-Dist: mcp>=1.10; extra == 'all'
+Provides-Extra: databricks
+Requires-Dist: databricks-sdk>=0.30; extra == 'databricks'
+Provides-Extra: dev
+Requires-Dist: databricks-sdk>=0.30; extra == 'dev'
+Requires-Dist: duckdb>=1.0; extra == 'dev'
+Requires-Dist: mcp>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Provides-Extra: duckdb
+Requires-Dist: duckdb>=1.0; extra == 'duckdb'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.10; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# bricksentry
+
+**Change-safety for Databricks pipelines and the AI agents that edit them.**
+
+Before a change reaches production, bricksentry answers three questions, in a
+pull-request comment for humans and in structured JSON for agents:
+
+1. **What does it do to the data?** A key-based data diff: added, removed and changed rows, schema changes, per-column changes, numeric totals, duplicate keys, and *where* the change is concentrated ("100% of affected rows are region = APAC").
+2. **Who gets hurt?** The downstream blast radius from Unity Catalog lineage: tables, jobs, notebooks, Lakeflow pipelines, dashboards and queries, with owners and tags.
+3. **Is it safe, and how do I undo it?** A deterministic policy verdict (`pass` · `warn` · `needs_human` · `block`) and the exact `RESTORE TABLE … VERSION AS OF n` rollback.
+
+```
+pip install "bricksentry[databricks,mcp]"
+```
+
+## Why it exists
+
+AI now writes much of our pipeline code, and checking what that code does to the data hasn't kept up. Code review can't see a silent 3% revenue shift or a join that fans out. The tools that do catch this mostly cover dbt, or need a paid platform. Most Databricks work is PySpark notebooks, Jobs and Lakeflow pipelines, and bricksentry is built for that work:
+
+- **Unity Catalog runtime lineage**, not SQL parsing, so PySpark notebooks and jobs are included.
+- **SQL pushdown**: all diffing runs on your SQL warehouse, so no Spark session is needed and calls stay cheap enough for an agent loop.
+- **One engine, three faces**: CLI and GitHub Action · Python API · MCP server.
+
+## For AI agents: the MCP server
+
+```bash
+bricksentry mcp --config bricksentry.yml                 # stdio
+claude mcp add bricksentry -- bricksentry mcp --config /abs/path/bricksentry.yml
+```
+
+| Tool | What the agent gets |
+|---|---|
+| `whats_downstream(table, depth)` | Downstream assets with owners and tags. Call it *before* editing. |
+| `rollback_plan(table)` | The restore SQL. Capture it *before* changing anything. |
+| `preview_write(sql, target, keys?)` | Runs one write against a **disposable shallow clone**, never production, and returns the diff plus verdict. |
+| `assess_change(tables, candidates?, pr?)` | Diffs prod vs. the candidate built by your change, plus lineage and policy. Returns a verdict and an `id`. |
+| `explain_diff(assessment_id or table)` | Plain-English summary. |
+| `safe_to_ship(assessment_id)` | `safe_to_ship`, the reasons, and an explicit `next_step` to follow. |
+
+Designed for agents:
+
+- **The verdict never comes from an LLM.** Rules in `policy.yml` decide, so the same change always gets the same answer.
+- **Read-only by default.** Only `preview_write` writes, and only to a sandbox clone. It accepts a single INSERT / MERGE / UPDATE / DELETE / CREATE OR REPLACE whose target must be the clone, and it refuses DROP, TRUNCATE, ALTER, GRANT and multiple statements.
+- **Errors come back as `{"error": ...}`**, so agents can recover instead of crashing.
+- **Bounded cost:** deterministic hash sampling (`sample_pct`), capped samples, and lineage limited by depth and lookback window.
+
+The same tools are plain Python functions in `bricksentry.agent_tools`, so you can use them from LangGraph, the OpenAI Agents SDK or the Databricks Agent Framework without MCP.
+
+### See the agent loop (no Databricks needed)
+
+```bash
+pip install "bricksentry[duckdb]"
+python examples/demo/agent_loop_demo.py
+```
+
+In the demo, an agent previews a risky DELETE (needs_human, production untouched), ships a pipeline change with a join fan-out (**blocked**: 40 duplicate keys), fixes it, and gets routed to the certified table's owners. It ends with the pull-request comment a reviewer would see.
+
+## For data engineers: CLI and CI
+
+```bash
+bricksentry init                                        # starter bricksentry.yml + policy.yml
+bricksentry impact main.sales.orders                    # blast radius
+bricksentry diff main.sales.orders main.sales_pr_42.orders
+bricksentry preview main.sales.orders --sql "MERGE INTO {{target}} t USING updates u ON t.order_id = u.order_id WHEN MATCHED THEN UPDATE SET *"
+bricksentry assess --from-git origin/main --pr 42 --format markdown --fail-on needs_human
+bricksentry rollback main.sales.orders
+```
+
+Exit codes: `0` below `--fail-on`, `1` at or above it, `2` for configuration errors.
+
+**In GitHub Actions.** Build your PR's version of the pipeline into a per-PR schema (for example with a Databricks Asset Bundle `ci` target), then add:
+
+```yaml
+- run: pip install "bricksentry[databricks]"
+- run: >
+    bricksentry assess
+    --from-git origin/${{ github.base_ref }}
+    --pr ${{ github.event.pull_request.number }}
+    --comment --output bricksentry-report.md
+    --fail-on needs_human
+  env:
+    GITHUB_TOKEN: ${{ github.token }}
+    DATABRICKS_HOST: ${{ secrets.DATABRICKS_HOST }}
+    DATABRICKS_CLIENT_ID: ${{ secrets.DATABRICKS_CLIENT_ID }}
+    DATABRICKS_CLIENT_SECRET: ${{ secrets.DATABRICKS_CLIENT_SECRET }}
+    DATABRICKS_WAREHOUSE_ID: ${{ secrets.DATABRICKS_WAREHOUSE_ID }}
+```
+
+It detects changed tables from the files in the PR and posts or updates one PR comment. Check out with `fetch-depth: 0` and give the job `pull-requests: write` permission. The source repository also ships a composite `action.yml` that wraps these steps.
+
+## Python API
+
+```python
+from bricksentry import Sentry
+
+s = Sentry()                                   # reads ./bricksentry.yml
+a = s.assess(["main.sales.orders"], pr="42")
+print(a.verdict, a.notify)
+print(a.tables[0].summary)
+
+s.preview_write("DELETE FROM main.sales.orders WHERE status = 'test'", "main.sales.orders")
+```
+
+## Configuration
+
+```yaml
+backend: {type: databricks, warehouse_id: abc123}      # auth: standard Databricks SDK chain
+sandbox_schema: main.bricksentry_sandbox
+candidate_pattern: "{catalog}.{schema}_pr_{pr}.{table}"
+sample_pct: 10
+lineage: {type: databricks, depth: 3, lookback_days: 90}
+tables:
+  main.sales.orders:
+    keys: [order_id]
+    segment_by: [region]
+    paths: ["src/pipelines/orders/**", "resources/orders_job.yml"]
+policy: policy.yml
+```
+
+### Policy conditions
+
+`table` (glob) · `tag` · `downstream_tag` · `downstream_kind` · `downstream_count_gt` · `removed_pct_gt` · `added_pct_gt` · `changed_pct_gt` · `row_count_change_pct_gt` · `row_count_drop_pct_gt` · `column_removed` · `column_added` · `column_type_changed` · `duplicate_keys` · `sum_change_pct_gt` / `null_increase_gt` (optionally with `column`) · `any_change` · `diff_error`
+
+All conditions in a `when` must hold. The most severe matching rule sets the verdict. Unknown conditions are rejected at load time, so a typo can't silently disable a rule.
+
+## Permissions needed on Databricks
+
+- `CAN USE` on a SQL warehouse.
+- `SELECT` on the tables you assess and their candidates.
+- `SELECT` on `system.access.table_lineage`, plus `system.information_schema` for owners and tags. Without these, bricksentry still diffs; lineage is just empty.
+- `CREATE TABLE` on `sandbox_schema`, for `preview_write`.
+
+## Known limits (v0.1)
+
+- **Lineage is recorded at runtime.** Brand-new tables have no downstream history yet. Unity Catalog doesn't capture RDD operations, and UDFs hide column-level mapping.
+- **Keys are required.** Tables without a stable key can't be diffed row by row yet (an aggregate-profile mode is planned).
+- **Changed-table detection uses path globs** from config. It doesn't parse Asset Bundles yet.
+- **The Databricks backend is tested against a mocked SDK.** Run it against a dev workspace before relying on it in CI.
+
+## Roadmap
+
+Asset Bundle parsing for automatic table detection · column-level blast radius from `system.access.column_lineage` · an aggregate diff for keyless tables · Lakeflow expectations in the verdict · `bricksentry watch` for scheduled drift checks · a Databricks App UI.
+
+## License
+
+Apache-2.0

bricksentry-0.1.0.dist-info/RECORD

@@ -0,0 +1,25 @@
+bricksentry/__init__.py,sha256=X8DV-XCMXInzsomkoj1P0uU3hgM1SDWM4FxmhxgCsg8,661
+bricksentry/agent_tools.py,sha256=LTY279hdNd7JeDh_ZNjfpmPLxM-ey1ARSgiacgn8kDY,4968
+bricksentry/assess.py,sha256=kCLbcqF8XLvL9fo2VfbcPdvngWB8x8A6jvR3Zhsl3zo,6585
+bricksentry/changes.py,sha256=gT0lLYZS68BzqueEDbQSoMtqxclG6kBeRdB2AZdq_b4,1013
+bricksentry/cli.py,sha256=c6zXWm-s8RB8biJOtULwRTQj4b5_kqtk6xOJmkZ8Vm4,9837
+bricksentry/config.py,sha256=9np7IW2JNBho8JZIf-tLz_TcApqQdEy3xjwnn8AHr1E,4329
+bricksentry/diff.py,sha256=zsGohP6zKZiQdJXFUSCFn_og_q61Sp4dsaDuEAKQmK0,7141
+bricksentry/explain.py,sha256=dMUa6jv5u4ndxjziyl0XoXTP7M0Px2MQiygka4Hxsxs,3651
+bricksentry/github.py,sha256=iu4fVXsYYKu08tx11YB8OwcxRANJMnLdD2Klt_5A4FI,1993
+bricksentry/lineage.py,sha256=3dKYlPlyYEFh3THmC8mlrZbI8LVoCQQpaA1qXIvm_7s,9054
+bricksentry/mcp_server.py,sha256=g2EvKi6-vz-XW4mGjeWe4rJWumKTEiBEwveT4twz7Fc,1785
+bricksentry/models.py,sha256=XJQiQnvcVr69yQKA3jaNcRK3m6QFNs_2w8skTfb_K2w,5977
+bricksentry/policy.py,sha256=FwFwraB8keEsoQhEGD_T64JHE7_4EPsPcaAK9Bhnvqs,9031
+bricksentry/preview.py,sha256=y27u4oQNrHOx_l38uWkuwL3CUW8v_ba-jH1knigHEhc,3278
+bricksentry/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+bricksentry/report.py,sha256=5Sm35lHnelPhhYXjHaOTrDTfoJVv0bACHum130CEVA0,3967
+bricksentry/backends/__init__.py,sha256=JRX-XiI2R1qlaCobzW8yhgRqhJUUw4l55dVizYAwVZc,99
+bricksentry/backends/base.py,sha256=AZW7KlAAOSN2masgimBxZvH3mO7jLnFaewAoswvLlkw,3234
+bricksentry/backends/databricks_backend.py,sha256=Na2ZOWI8DhPD_pPRox-hU8MgheH1rxO4t7QZDV1Pvg8,5829
+bricksentry/backends/duckdb_backend.py,sha256=Q1z-jyW7H0WvH2vDaaasgP_38LvFGB0jBKiVEgKo-DI,1850
+bricksentry-0.1.0.dist-info/METADATA,sha256=BO6kioJxcVJl88iPr3wfJyH1ZTPwON3eoOQUHSKO_zw,9500
+bricksentry-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+bricksentry-0.1.0.dist-info/entry_points.txt,sha256=sWHWuzVCxUOUxH5dLTqQgLgVGdiWWWeClQa3xKLcjHA,54
+bricksentry-0.1.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+bricksentry-0.1.0.dist-info/RECORD,,

bricksentry-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

bricksentry-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+bricksentry = bricksentry.cli:entry