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

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

@@ -2,6 +2,46 @@
 
 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
+
+- **`PromptRenderer` protocol**: New `@runtime_checkable` protocol for custom system prompt formatting. Users can implement `render(contract, semantic_source) -> str` to control how contracts are presented to their model of choice.
+- **`ClaudePromptRenderer`**: Built-in XML-structured renderer optimized for Claude models (Sonnet 4.6+). Uses XML tags for structural boundaries, places constraints at the end for better instruction-following, and merges resource/temporal limits into a single section.
+- **Custom renderer support**: `to_system_prompt(renderer=MyRenderer())` delegates entirely to a user-provided renderer.
+- **Top-level exports**: `from agentic_data_contracts import PromptRenderer, ClaudePromptRenderer`
+
+### Changed
+
+- **Default system prompt format**: `to_system_prompt()` now generates XML output (was Markdown). Pass a custom renderer if you need a different format.
+- **`contract.py` simplified**: `to_system_prompt()` is now a thin delegate (~7 lines). All prompt-building logic moved to `core/prompt.py`.
+
 ## [0.2.6] - 2026-03-29
 
 ### Changed

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-data-contracts
-Version: 0.2.6
+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
 
@@ -294,6 +345,29 @@ relationships:
 
 The agent sees these in its system prompt and uses them to write correct JOINs instead of guessing from column names.
 
+## Custom Prompt Rendering
+
+The system prompt is generated by a `PromptRenderer`. The default `ClaudePromptRenderer` produces XML-structured output optimized for Claude models:
+
+```python
+dc = DataContract.from_yaml("contract.yml")
+print(dc.to_system_prompt())  # XML output, optimized for Claude
+```
+
+For other models (GPT-4, Gemini, Llama), implement the `PromptRenderer` protocol:
+
+```python
+from agentic_data_contracts import PromptRenderer, DataContract
+
+class MarkdownRenderer:
+    def render(self, contract, semantic_source=None):
+        tables = "\n".join(f"- {t}" for t in contract.allowed_table_names())
+        return f"## {contract.name}\n\nAllowed tables:\n{tables}"
+
+dc = DataContract.from_yaml("contract.yml")
+print(dc.to_system_prompt(renderer=MarkdownRenderer()))
+```
+
 ## Scalable Metric Discovery
 
 For large data lakes with hundreds of KPIs, group metrics by domain and let the agent discover them efficiently:
@@ -348,6 +422,33 @@ resources:
 | `agent-sdk` | `claude-agent-sdk` | Claude Agent SDK integration |
 | `agent-contracts` | `ai-agent-contracts>=0.2.0` | ai-agent-contracts bridge |
 
+## Optional: Formal Governance with ai-agent-contracts
+
+The library works standalone with lightweight enforcement. Install [`ai-agent-contracts`](https://pypi.org/project/ai-agent-contracts/) to upgrade to the formal governance framework:
+
+```bash
+pip install "agentic-data-contracts[agent-contracts]"
+```
+
+```python
+from agentic_data_contracts.bridge.compiler import compile_to_contract
+
+contract = compile_to_contract(dc)  # YAML → formal 7-tuple Contract
+```
+
+**What you get with the bridge:**
+
+| Concern | Standalone | With ai-agent-contracts |
+|---|---|---|
+| Resource tracking | Manual counters | Formal `ResourceConstraints` with auto-enforcement |
+| Rule violations | Exception + retry | `TerminationCondition` with contract state machine |
+| Success evaluation | Log-based | Weighted `SuccessCriterion` scoring, LLM judge support |
+| Contract lifecycle | None | `DRAFTED → ACTIVE → FULFILLED / VIOLATED / TERMINATED` |
+| Framework support | Claude Agent SDK | + LiteLLM, LangChain, LangGraph, Google ADK |
+| Multi-agent | Single agent | Coordination patterns (sequential, parallel, hierarchical) |
+
+**When to use it:** formal audit trails, success scoring, multi-agent coordination, or integration with non-Claude agent frameworks.
+
 ## Example
 
 See [`examples/revenue_agent/`](examples/revenue_agent/) for a complete working example with a DuckDB database, YAML semantic source, and Claude Agent SDK integration.

{agentic_data_contracts-0.2.6 → 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
 
@@ -241,6 +292,29 @@ relationships:
 
 The agent sees these in its system prompt and uses them to write correct JOINs instead of guessing from column names.
 
+## Custom Prompt Rendering
+
+The system prompt is generated by a `PromptRenderer`. The default `ClaudePromptRenderer` produces XML-structured output optimized for Claude models:
+
+```python
+dc = DataContract.from_yaml("contract.yml")
+print(dc.to_system_prompt())  # XML output, optimized for Claude
+```
+
+For other models (GPT-4, Gemini, Llama), implement the `PromptRenderer` protocol:
+
+```python
+from agentic_data_contracts import PromptRenderer, DataContract
+
+class MarkdownRenderer:
+    def render(self, contract, semantic_source=None):
+        tables = "\n".join(f"- {t}" for t in contract.allowed_table_names())
+        return f"## {contract.name}\n\nAllowed tables:\n{tables}"
+
+dc = DataContract.from_yaml("contract.yml")
+print(dc.to_system_prompt(renderer=MarkdownRenderer()))
+```
+
 ## Scalable Metric Discovery
 
 For large data lakes with hundreds of KPIs, group metrics by domain and let the agent discover them efficiently:
@@ -295,6 +369,33 @@ resources:
 | `agent-sdk` | `claude-agent-sdk` | Claude Agent SDK integration |
 | `agent-contracts` | `ai-agent-contracts>=0.2.0` | ai-agent-contracts bridge |
 
+## Optional: Formal Governance with ai-agent-contracts
+
+The library works standalone with lightweight enforcement. Install [`ai-agent-contracts`](https://pypi.org/project/ai-agent-contracts/) to upgrade to the formal governance framework:
+
+```bash
+pip install "agentic-data-contracts[agent-contracts]"
+```
+
+```python
+from agentic_data_contracts.bridge.compiler import compile_to_contract
+
+contract = compile_to_contract(dc)  # YAML → formal 7-tuple Contract
+```
+
+**What you get with the bridge:**
+
+| Concern | Standalone | With ai-agent-contracts |
+|---|---|---|
+| Resource tracking | Manual counters | Formal `ResourceConstraints` with auto-enforcement |
+| Rule violations | Exception + retry | `TerminationCondition` with contract state machine |
+| Success evaluation | Log-based | Weighted `SuccessCriterion` scoring, LLM judge support |
+| Contract lifecycle | None | `DRAFTED → ACTIVE → FULFILLED / VIOLATED / TERMINATED` |
+| Framework support | Claude Agent SDK | + LiteLLM, LangChain, LangGraph, Google ADK |
+| Multi-agent | Single agent | Coordination patterns (sequential, parallel, hierarchical) |
+
+**When to use it:** formal audit trails, success scoring, multi-agent coordination, or integration with non-Claude agent frameworks.
+
 ## Example
 
 See [`examples/revenue_agent/`](examples/revenue_agent/) for a complete working example with a DuckDB database, YAML semantic source, and Claude Agent SDK integration.

{agentic_data_contracts-0.2.6 → 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