agentic-data-contracts 0.3.0__tar.gz → 0.4.0__tar.gz

{agentic_data_contracts-0.3.0 → agentic_data_contracts-0.4.0}/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.4.0] - 2026-03-31
+
+### Added
+
+- **Unified rule engine**: Rules now support `query_check` (pre-execution) and `result_check` (post-execution) blocks, replacing the old `filter_column` shorthand. All rules live in one `rules` list; the engine determines execution phase automatically.
+- **Table scoping**: Every rule can be scoped to a specific table (`table: "schema.table"`) or apply globally (omitted or `"*"`). Pre-execution and post-execution rules both support scoping.
+- **5 built-in query checks**: `required_filter`, `no_select_star`, `blocked_columns`, `require_limit`, `max_joins` — all declarative in YAML, no Python needed.
+- **6 built-in result checks**: `min_value`/`max_value` (numeric column bounds), `not_null`, `min_rows`/`max_rows` — validated against actual query output post-execution.
+- **Advisory rules**: Rules with neither `query_check` nor `result_check` appear in the system prompt as guidance but don't enforce anything.
+- **Session cost enforcement**: `run_query` now records estimated cost from EXPLAIN and enforces cumulative `cost_limit_usd` across the session.
+- **`validate_results()` on Validator**: New method for post-execution result validation, used transparently inside `run_query`.
+- **`validate_query` result check notes**: Output now lists pending result checks that will run at execution time.
+- **New checker classes**: `BlockedColumnsChecker`, `RequireLimitChecker`, `MaxJoinsChecker`, `ResultCheckRunner` — all exported from `validation` module.
+
+### Changed
+
+- **Checker protocol**: All checkers now use `check_ast(ast)` instead of `check_sql(sql)`. SQL is parsed once by the Validator and the AST is passed to all checkers.
+- **`extract_tables()` utility**: Extracted from `TableAllowlistChecker` into a standalone function for shared use by the Validator's table scoping logic.
+- **`ValidationResult`**: Gains `estimated_cost_usd: float | None` field for session cost passthrough from EXPLAIN.
+- **Three-phase validation**: Validator now runs query checks (Phase 1) → EXPLAIN (Phase 2) → result checks (Phase 3), up from the previous two-phase pipeline.
+
+### Removed
+
+- **`SemanticRule.filter_column`**: Replaced by `query_check: { required_filter: <column> }`. No backward compatibility — the old field is removed entirely.
+- **Heuristic filter detection**: The regex-based `_extract_filter_column()` method that guessed filter columns from rule descriptions is gone. Filters are now explicit in `query_check`.
+
 ## [0.3.0] - 2026-03-30
 
 ### Added

{agentic_data_contracts-0.3.0 → agentic_data_contracts-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-data-contracts
-Version: 0.3.0
+Version: 0.4.0
 Summary: YAML-first data contract governance for AI agents
 Project-URL: Homepage, https://github.com/flyersworder/agentic-data-contracts
 Project-URL: Repository, https://github.com/flyersworder/agentic-data-contracts
@@ -125,10 +125,13 @@ semantic:
     - name: tenant_isolation
       description: "All queries must filter by tenant_id"
       enforcement: block
-      filter_column: tenant_id
+      query_check:
+        required_filter: tenant_id
     - name: no_select_star
       description: "Must specify explicit columns"
       enforcement: block
+      query_check:
+        no_select_star: true
 
 resources:
   cost_limit_usd: 5.00
@@ -230,11 +233,59 @@ Rules are enforced at three levels:
 - **`warn`** — query proceeds but a warning is included in the response
 - **`log`** — violation is recorded but not surfaced to the agent
 
-Built-in checkers enforce:
-- **Table allowlist** — only tables listed in `allowed_tables` may be queried
-- **Operation blocklist** — `forbidden_operations` (DELETE, DROP, etc.) are rejected
-- **Required filters** — rules with `filter_column` require a matching WHERE clause
-- **No SELECT \*** — queries must name explicit columns
+Each rule carries a `query_check` (pre-execution) or `result_check` (post-execution) block. Rules with neither are advisory — they appear in the system prompt but don't enforce anything. Every rule can be scoped to a specific table or applied globally.
+
+**Built-in query checks** (pre-execution, validated against SQL AST):
+
+| Check | Description |
+|-------|-------------|
+| `required_filter` | Require a column in WHERE clause (e.g., `tenant_id`) |
+| `no_select_star` | Forbid `SELECT *` — require explicit columns |
+| `blocked_columns` | Forbid specific columns in SELECT (e.g., PII) |
+| `require_limit` | Require a LIMIT clause |
+| `max_joins` | Cap the number of JOINs |
+
+**Built-in result checks** (post-execution, validated against query output):
+
+| Check | Description |
+|-------|-------------|
+| `min_value` / `max_value` | Numeric bounds on a column's values |
+| `not_null` | Column must not contain nulls |
+| `min_rows` / `max_rows` | Row count bounds on the result set |
+
+Example with table scoping and both check types:
+
+```yaml
+rules:
+  - name: tenant_isolation
+    description: "Orders must filter by tenant_id"
+    enforcement: block
+    table: "analytics.orders"      # only applies to this table
+    query_check:
+      required_filter: tenant_id
+
+  - name: hide_pii
+    description: "Do not select PII columns from customers"
+    enforcement: block
+    table: "analytics.customers"
+    query_check:
+      blocked_columns: [ssn, email, phone]
+
+  - name: wau_sanity
+    description: "WAU should not exceed world population"
+    enforcement: warn
+    table: "analytics.user_metrics"
+    result_check:
+      column: wau
+      max_value: 8_000_000_000
+
+  - name: no_negative_revenue
+    description: "Revenue must not be negative"
+    enforcement: block
+    result_check:
+      column: revenue
+      min_value: 0
+```
 
 ## Semantic Sources
 

{agentic_data_contracts-0.3.0 → agentic_data_contracts-0.4.0}/README.md

@@ -72,10 +72,13 @@ semantic:
     - name: tenant_isolation
       description: "All queries must filter by tenant_id"
       enforcement: block
-      filter_column: tenant_id
+      query_check:
+        required_filter: tenant_id
     - name: no_select_star
       description: "Must specify explicit columns"
       enforcement: block
+      query_check:
+        no_select_star: true
 
 resources:
   cost_limit_usd: 5.00
@@ -177,11 +180,59 @@ Rules are enforced at three levels:
 - **`warn`** — query proceeds but a warning is included in the response
 - **`log`** — violation is recorded but not surfaced to the agent
 
-Built-in checkers enforce:
-- **Table allowlist** — only tables listed in `allowed_tables` may be queried
-- **Operation blocklist** — `forbidden_operations` (DELETE, DROP, etc.) are rejected
-- **Required filters** — rules with `filter_column` require a matching WHERE clause
-- **No SELECT \*** — queries must name explicit columns
+Each rule carries a `query_check` (pre-execution) or `result_check` (post-execution) block. Rules with neither are advisory — they appear in the system prompt but don't enforce anything. Every rule can be scoped to a specific table or applied globally.
+
+**Built-in query checks** (pre-execution, validated against SQL AST):
+
+| Check | Description |
+|-------|-------------|
+| `required_filter` | Require a column in WHERE clause (e.g., `tenant_id`) |
+| `no_select_star` | Forbid `SELECT *` — require explicit columns |
+| `blocked_columns` | Forbid specific columns in SELECT (e.g., PII) |
+| `require_limit` | Require a LIMIT clause |
+| `max_joins` | Cap the number of JOINs |
+
+**Built-in result checks** (post-execution, validated against query output):
+
+| Check | Description |
+|-------|-------------|
+| `min_value` / `max_value` | Numeric bounds on a column's values |
+| `not_null` | Column must not contain nulls |
+| `min_rows` / `max_rows` | Row count bounds on the result set |
+
+Example with table scoping and both check types:
+
+```yaml
+rules:
+  - name: tenant_isolation
+    description: "Orders must filter by tenant_id"
+    enforcement: block
+    table: "analytics.orders"      # only applies to this table
+    query_check:
+      required_filter: tenant_id
+
+  - name: hide_pii
+    description: "Do not select PII columns from customers"
+    enforcement: block
+    table: "analytics.customers"
+    query_check:
+      blocked_columns: [ssn, email, phone]
+
+  - name: wau_sanity
+    description: "WAU should not exceed world population"
+    enforcement: warn
+    table: "analytics.user_metrics"
+    result_check:
+      column: wau
+      max_value: 8_000_000_000
+
+  - name: no_negative_revenue
+    description: "Revenue must not be negative"
+    enforcement: block
+    result_check:
+      column: revenue
+      min_value: 0
+```
 
 ## Semantic Sources
 

{agentic_data_contracts-0.3.0 → agentic_data_contracts-0.4.0}/docs/architecture.md

@@ -1,7 +1,7 @@
 # Agentic Data Contracts — Architecture
 
-**Date:** 2026-03-28
-**Status:** Implemented (v0.2.2)
+**Date:** 2026-03-31
+**Status:** Implemented (v0.4.0)
 **Author:** Qing Ye + Claude
 
 ## Problem Statement
@@ -106,19 +106,24 @@ semantic:
     engagement: [active_customers, churn_rate]
 
   # Governance rules (per-rule enforcement)
+  # Each rule has a query_check (pre-execution) or result_check (post-execution)
+  # Rules with neither are advisory (shown in prompt only)
   rules:
     - name: tenant_isolation
       description: "All queries must include a WHERE tenant_id = filter"
       enforcement: block               # block | warn | log
-      filter_column: tenant_id         # explicit column for required filter
+      query_check:
+        required_filter: tenant_id
 
     - name: use_approved_metrics
       description: "Revenue calculations must use the semantic layer definition"
-      enforcement: warn
+      enforcement: warn                # advisory — no check block
 
     - name: no_select_star
       description: "Queries must specify explicit columns, no SELECT *"
       enforcement: block
+      query_check:
+        no_select_star: true
 
 # Resource governance
 resources:
@@ -180,31 +185,39 @@ When `ai-agent-contracts` IS installed, enforcement is delegated to the formal f
 
 ## Validation Layer
 
-Two-layer validation architecture. Dependencies: `sqlglot`.
+Three-phase validation architecture. Dependencies: `sqlglot`.
 
-### Layer 1: Static Validation (always available)
+### Phase 1: Query Checks (pre-execution, always available)
 
 ```python
 class Checker(Protocol):
-    def check(self, parsed_sql: Expression, contract: DataContract) -> CheckResult: ...
+    def check_ast(self, ast: Expression, *args) -> CheckResult: ...
 ```
 
-**Built-in checkers:**
+SQL is parsed once into a sqlglot AST. The Validator passes the AST to all applicable checkers, respecting table scoping.
+
+**Structural checkers** (from top-level config):
 
 | Checker | What it validates |
 |---|---|
 | `TableAllowlistChecker` | All referenced tables are in `allowed_tables` |
 | `OperationBlocklistChecker` | No forbidden SQL operations (DELETE, DROP, etc.) |
-| `RequiredFilterChecker` | Required WHERE clauses present (e.g., `tenant_id`) |
-| `NoSelectStarChecker` | No `SELECT *` statements |
+
+**Rule-based query checkers** (from `query_check` blocks):
+
+| Check | Checker | What it validates |
+|---|---|---|
+| `required_filter` | `RequiredFilterChecker` | Required WHERE clauses present |
+| `no_select_star` | `NoSelectStarChecker` | No `SELECT *` statements |
+| `blocked_columns` | `BlockedColumnsChecker` | Forbidden columns not in SELECT |
+| `require_limit` | `RequireLimitChecker` | LIMIT clause present |
+| `max_joins` | `MaxJoinsChecker` | JOIN count within limit |
 
 `CheckResult` contains: `passed: bool`, `severity: block | warn | log`, `message: str`.
 
 The validator runs all applicable checkers and aggregates results — any `block` result stops execution, `warn` results are surfaced to the agent, `log` results are recorded silently.
 
-Rules that cannot be statically checked (e.g., "use semantic layer definition for revenue") become:
-- An instruction injected into the agent's context via `to_system_prompt()`
-- A post-hoc `SuccessCriterion` for evaluation by LLM judge or human review
+Rules that cannot be statically checked (e.g., "use semantic layer definition for revenue") become advisory rules — they appear in the system prompt but don't enforce anything. They can also be used as `SuccessCriterion` for post-hoc evaluation.
 
 ### Layer 2: EXPLAIN Dry-Run (optional, requires database adapter)
 
@@ -226,16 +239,35 @@ class ExplainAdapter(Protocol):
 | Postgres | `EXPLAIN` (no ANALYZE) | Row estimates |
 | DuckDB | `EXPLAIN` | Row estimates |
 
+### Phase 3: Result Checks (post-execution, from `result_check` blocks)
+
+After a query executes successfully, `run_query` calls `validator.validate_results()` to check the actual output against `result_check` rules.
+
+**Built-in result checks:**
+
+| Check | What it validates |
+|---|---|
+| `min_value` / `max_value` | Numeric column values within bounds |
+| `not_null` | Column contains no null values |
+| `min_rows` / `max_rows` | Result set row count within bounds |
+
+If a result check with `enforcement: block` fails, the query data is **discarded** — the agent sees only the violation message (with actual violating values for debugging). If `enforcement: warn`, the data is returned with warnings prepended.
+
 ### Validation Flow
 
 ```
 SQL string
-  → sqlglot.parse(sql, dialect=contract.dialect)
-  → Layer 1: run all checkers
+  → sqlglot.parse(sql, dialect=contract.dialect) — parse once
+  → Phase 1: structural checkers + rule-based query_check checkers (table-scoped)
   → any block? → return ValidationResult(blocked=True, reasons=[...])
-  → Layer 2 available? → explain adapter
+  → Phase 2 available? → explain adapter
   → cost/rows exceed limits? → return ValidationResult(blocked=True, reasons=[...])
-  → return ValidationResult(blocked=False, warnings=[...])
+  → record estimated cost in session
+  → execute query
+  → Phase 3: result_check rules against actual output (table-scoped)
+  → any block? → discard data, return violation
+  → any warn? → prepend warnings to response
+  → return results
 ```
 
 ## Tools Layer (Claude Agent SDK Integration)
@@ -443,7 +475,7 @@ agentic-data-contracts/
 │   ├── validation/
 │   │   ├── __init__.py
 │   │   ├── validator.py         # Orchestrates checkers, aggregates results
-│   │   ├── checkers.py          # Built-in checkers (4 checkers)
+│   │   ├── checkers.py          # Built-in checkers (7 query checkers + ResultCheckRunner)
 │   │   └── explain.py           # EXPLAIN adapter orchestration
 │   ├── tools/
 │   │   ├── __init__.py