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

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

@@ -2,6 +2,42 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.5.0] - 2026-04-04
+
+### Added
+
+- **`SqlNormalizer` protocol**: Optional pre-processing hook for adapters serving non-standard SQL dialects (e.g., Denodo VQL, Teradata). Adapters implement `normalize_sql(sql) -> str` to rewrite proprietary syntax into a form sqlglot can parse, while the original SQL is preserved for `execute()` and `explain()`.
+- **Auto-detection in factory and middleware**: When an adapter implements both `DatabaseAdapter` and `SqlNormalizer`, the factory and middleware automatically wire normalization into the `Validator` — no API changes needed.
+- **Normalization in `validate_results()`**: Table-scoped result checks now also benefit from SQL normalization, ensuring scoped checks fire correctly for non-standard dialects.
+- **Adapter package exports**: `adapters/__init__.py` now re-exports `Column`, `DatabaseAdapter`, `QueryResult`, `SqlNormalizer`, and `TableSchema`.
+- **Root export**: `SqlNormalizer` is available via `from agentic_data_contracts import SqlNormalizer`.
+
+## [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.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-data-contracts
-Version: 0.3.0
+Version: 0.5.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.5.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.5.0}/docs/architecture.md

@@ -1,7 +1,7 @@
 # Agentic Data Contracts — Architecture
 
-**Date:** 2026-03-28
-**Status:** Implemented (v0.2.2)
+**Date:** 2026-04-04
+**Status:** Implemented (v0.5.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)
@@ -361,8 +393,17 @@ class DatabaseAdapter(Protocol):
     def describe_table(self, schema: str, table: str) -> TableSchema: ...
     @property
     def dialect(self) -> str: ...  # "bigquery", "snowflake", "postgres", "duckdb"
+
+class SqlNormalizer(Protocol):
+    def normalize_sql(self, sql: str) -> str: ...
 ```
 
+### SQL Normalization for Non-Standard Dialects
+
+Adapters for databases with proprietary SQL extensions (Denodo VQL, Teradata, ClickHouse) can implement `SqlNormalizer` alongside `DatabaseAdapter`. The `Validator` calls `normalize_sql()` before `sqlglot.parse_one()` to rewrite non-standard syntax into a form sqlglot can parse. The original SQL is preserved for `execute()` and `explain()`.
+
+Detection is automatic: `create_tools()` and `contract_middleware()` check `isinstance(adapter, SqlNormalizer)` and wire it into the `Validator` if present. Standard-dialect adapters are unaffected.
+
 **`describe_table` maps to native commands:**
 
 | Database | Command | What you get |
@@ -443,7 +484,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
@@ -457,7 +498,8 @@ agentic-data-contracts/
 │   │   └── yaml_source.py       # YamlSource
 │   ├── adapters/
 │   │   ├── __init__.py
-│   │   ├── base.py              # DatabaseAdapter protocol
+│   │   ├── _normalizer.py       # SqlNormalizer protocol (avoids circular import)
+│   │   ├── base.py              # DatabaseAdapter protocol + SqlNormalizer re-export
 │   │   ├── bigquery.py          # BigQuery adapter
 │   │   ├── snowflake.py         # Snowflake adapter
 │   │   ├── postgres.py          # Postgres adapter

{agentic_data_contracts-0.3.0 → agentic_data_contracts-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentic-data-contracts"
-version = "0.3.0"
+version = "0.5.0"
 description = "YAML-first data contract governance for AI agents"
 readme = "README.md"
 requires-python = ">=3.12"

{agentic_data_contracts-0.3.0 → agentic_data_contracts-0.5.0}/src/agentic_data_contracts/__init__.py

@@ -1,5 +1,6 @@
 """Agentic Data Contracts — YAML-first data contract governance for AI agents."""
 
+from agentic_data_contracts.adapters.base import SqlNormalizer
 from agentic_data_contracts.core.contract import DataContract
 from agentic_data_contracts.core.prompt import ClaudePromptRenderer, PromptRenderer
 from agentic_data_contracts.tools.factory import create_tools
@@ -10,6 +11,7 @@ __all__ = [
     "ClaudePromptRenderer",
     "DataContract",
     "PromptRenderer",
+    "SqlNormalizer",
     "contract_middleware",
     "create_sdk_mcp_server",
     "create_tools",

agentic_data_contracts-0.5.0/src/agentic_data_contracts/adapters/__init__.py

@@ -0,0 +1,15 @@
+from agentic_data_contracts.adapters.base import (
+    Column,
+    DatabaseAdapter,
+    QueryResult,
+    SqlNormalizer,
+    TableSchema,
+)
+
+__all__ = [
+    "Column",
+    "DatabaseAdapter",
+    "QueryResult",
+    "SqlNormalizer",
+    "TableSchema",
+]

agentic_data_contracts-0.5.0/src/agentic_data_contracts/adapters/_normalizer.py

@@ -0,0 +1,20 @@
+"""SqlNormalizer protocol — standalone module to avoid circular imports."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class SqlNormalizer(Protocol):
+    """Rewrite database-specific SQL into a form sqlglot can parse.
+
+    Called by the Validator before AST parsing. Adapters for non-standard
+    dialects implement this alongside DatabaseAdapter. Standard-dialect
+    adapters do not need to implement this — the Validator treats its
+    absence as a no-op.
+
+    The original (un-normalized) SQL is still passed to execute() and explain().
+    """
+
+    def normalize_sql(self, sql: str) -> str: ...

{agentic_data_contracts-0.3.0 → agentic_data_contracts-0.5.0}/src/agentic_data_contracts/adapters/base.py

@@ -41,3 +41,15 @@ class DatabaseAdapter(Protocol):
 
     @property
     def dialect(self) -> str: ...
+
+
+# Re-export SqlNormalizer so consumers can import from adapters.base
+from agentic_data_contracts.adapters._normalizer import SqlNormalizer  # noqa: E402
+
+__all__ = [
+    "Column",
+    "DatabaseAdapter",
+    "QueryResult",
+    "SqlNormalizer",
+    "TableSchema",
+]

{agentic_data_contracts-0.3.0 → agentic_data_contracts-0.5.0}/src/agentic_data_contracts/core/schema.py

@@ -3,8 +3,9 @@
 from __future__ import annotations
 
 from enum import StrEnum
+from typing import Self
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, field_validator, model_validator
 
 
 class Enforcement(StrEnum):
@@ -25,11 +26,47 @@ class AllowedTable(BaseModel):
     model_config = {"populate_by_name": True}
 
 
+class QueryCheck(BaseModel):
+    required_filter: str | None = None
+    no_select_star: bool | None = None
+    blocked_columns: list[str] | None = None
+    require_limit: bool | None = None
+    max_joins: int | None = None
+
+
+class ResultCheck(BaseModel):
+    column: str | None = None
+    min_value: float | None = None
+    max_value: float | None = None
+    not_null: bool | None = None
+    min_rows: int | None = None
+    max_rows: int | None = None
+
+
 class SemanticRule(BaseModel):
+    model_config = {"extra": "forbid"}
+
     name: str
     description: str
     enforcement: Enforcement
-    filter_column: str | None = None  # explicit column for required filter rules
+    table: str | None = None
+    query_check: QueryCheck | None = None
+    result_check: ResultCheck | None = None
+
+    @field_validator("table")
+    @classmethod
+    def table_must_be_qualified(cls, v: str | None) -> str | None:
+        if v is not None and v != "*" and "." not in v:
+            raise ValueError(
+                f"table must be fully qualified as 'schema.table', got '{v}'"
+            )
+        return v
+
+    @model_validator(mode="after")
+    def at_most_one_check(self) -> Self:
+        if self.query_check is not None and self.result_check is not None:
+            raise ValueError("Rule must not have both query_check and result_check")
+        return self
 
 
 class SemanticConfig(BaseModel):

{agentic_data_contracts-0.3.0 → agentic_data_contracts-0.5.0}/src/agentic_data_contracts/tools/factory.py

@@ -6,7 +6,7 @@ import json
 from dataclasses import dataclass
 from typing import Any
 
-from agentic_data_contracts.adapters.base import DatabaseAdapter
+from agentic_data_contracts.adapters.base import DatabaseAdapter, SqlNormalizer
 from agentic_data_contracts.core.contract import DataContract
 from agentic_data_contracts.core.session import ContractSession, LimitExceededError
 from agentic_data_contracts.semantic.base import SemanticSource
@@ -46,7 +46,13 @@ def create_tools(
         contract.resolve_tables(adapter)
 
     dialect = adapter.dialect if adapter else None
-    validator = Validator(contract, dialect=dialect, explain_adapter=adapter)
+    sql_normalizer = adapter if isinstance(adapter, SqlNormalizer) else None
+    validator = Validator(
+        contract,
+        dialect=dialect,
+        explain_adapter=adapter,
+        sql_normalizer=sql_normalizer,
+    )
 
     # ── Tool 1: list_schemas ──────────────────────────────────────────────────
     async def list_schemas(args: dict[str, Any]) -> dict[str, Any]:
@@ -220,9 +226,16 @@ def create_tools(
             if result.warnings:
                 msg += "\nWarnings:\n" + "\n".join(f"- {w}" for w in result.warnings)
         else:
-            msg = "VALID — Query passed all checks."
+            msg = "VALID — Query passed all pre-execution checks."
             if result.warnings:
                 msg += "\nWarnings:\n" + "\n".join(f"- {w}" for w in result.warnings)
+            # Note pending result checks
+            pending = validator.pending_result_check_names()
+            if pending:
+                msg += (
+                    f"\nNote: {len(pending)} result check(s) will run after execution: "
+                    + ", ".join(pending)
+                )
         return _text_response(msg)
 
     # ── Tool 8: query_cost_estimate ───────────────────────────────────────────
@@ -253,7 +266,7 @@ def create_tools(
         except LimitExceededError as e:
             return _text_response(f"BLOCKED — Session limit exceeded: {e}")
 
-        # Validate the query
+        # Phase 1 + 2: query checks + EXPLAIN
         vresult = validator.validate(sql)
         if vresult.blocked:
             session.record_retry()
@@ -262,6 +275,13 @@ def create_tools(
             )
             return _text_response(msg)
 
+        # Record estimated cost from EXPLAIN — charged before execution because
+        # the cost budget tracks database resource consumption, not successful
+        # operations. Even if result checks later block the output, the database
+        # work was performed.
+        if vresult.estimated_cost_usd is not None:
+            session.record_cost(vresult.estimated_cost_usd)
+
         if adapter is None:
             return _text_response(
                 "No database adapter configured — cannot execute query."
@@ -273,13 +293,32 @@ def create_tools(
             session.record_retry()
             return _text_response(f"BLOCKED — Query execution failed: {e}")
 
+        # Phase 3: result checks
+        rresult = validator.validate_results(
+            sql, qresult.columns, [tuple(r) for r in qresult.rows]
+        )
+        if rresult.blocked:
+            session.record_retry()
+            msg = "BLOCKED — Result check violations:\n" + "\n".join(
+                f"- {r}" for r in rresult.reasons
+            )
+            return _text_response(msg)
+
         rows = [dict(zip(qresult.columns, row)) for row in qresult.rows]
         data = {
             "columns": qresult.columns,
             "rows": rows,
             "row_count": qresult.row_count,
         }
-        return _text_response(json.dumps(data, default=str))
+        response_text = json.dumps(data, default=str)
+
+        # Prepend warnings from both query checks and result checks
+        all_warnings = vresult.warnings + rresult.warnings
+        if all_warnings:
+            warning_text = "WARNINGS:\n" + "\n".join(f"- {w}" for w in all_warnings)
+            response_text = warning_text + "\n\n" + response_text
+
+        return _text_response(response_text)
 
     # ── Tool 10: get_contract_info ────────────────────────────────────────────
     async def get_contract_info(args: dict[str, Any]) -> dict[str, Any]:

{agentic_data_contracts-0.3.0 → agentic_data_contracts-0.5.0}/src/agentic_data_contracts/tools/middleware.py

@@ -6,7 +6,7 @@ import functools
 from collections.abc import Callable
 from typing import Any
 
-from agentic_data_contracts.adapters.base import DatabaseAdapter
+from agentic_data_contracts.adapters.base import DatabaseAdapter, SqlNormalizer
 from agentic_data_contracts.core.contract import DataContract
 from agentic_data_contracts.core.session import ContractSession, LimitExceededError
 from agentic_data_contracts.validation.validator import Validator
@@ -22,7 +22,13 @@ def contract_middleware(
         session = ContractSession(contract)
 
     dialect = adapter.dialect if adapter else None
-    validator = Validator(contract, dialect=dialect, explain_adapter=adapter)
+    sql_normalizer = adapter if isinstance(adapter, SqlNormalizer) else None
+    validator = Validator(
+        contract,
+        dialect=dialect,
+        explain_adapter=adapter,
+        sql_normalizer=sql_normalizer,
+    )
 
     def decorator(fn):
         @functools.wraps(fn)

agentic_data_contracts-0.5.0/src/agentic_data_contracts/validation/__init__.py

@@ -0,0 +1,36 @@
+from agentic_data_contracts.validation.checkers import (
+    BlockedColumnsChecker,
+    CheckResult,
+    MaxJoinsChecker,
+    NoSelectStarChecker,
+    OperationBlocklistChecker,
+    RequiredFilterChecker,
+    RequireLimitChecker,
+    ResultCheckRunner,
+    TableAllowlistChecker,
+    extract_tables,
+)
+from agentic_data_contracts.validation.explain import ExplainAdapter, ExplainResult
+from agentic_data_contracts.validation.validator import (
+    Checker,
+    ValidationResult,
+    Validator,
+)
+
+__all__ = [
+    "BlockedColumnsChecker",
+    "CheckResult",
+    "Checker",
+    "ExplainAdapter",
+    "ExplainResult",
+    "MaxJoinsChecker",
+    "NoSelectStarChecker",
+    "OperationBlocklistChecker",
+    "RequiredFilterChecker",
+    "RequireLimitChecker",
+    "ResultCheckRunner",
+    "TableAllowlistChecker",
+    "ValidationResult",
+    "Validator",
+    "extract_tables",
+]