agentic-data-contracts 0.1.0__tar.gz

agentic_data_contracts-0.1.0/.github/dependabot.yml

@@ -0,0 +1,15 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 10
+    labels:
+      - "dependencies"
+    groups:
+      minor-and-patch:
+        update-types:
+          - "minor"
+          - "patch"

agentic_data_contracts-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,58 @@
+name: CI and Publish to PyPI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  release:
+    types: [created]
+  workflow_dispatch:
+    inputs:
+      run_publish:
+        description: 'Set to true to run the publish job'
+        required: false
+        default: 'false'
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+          cache-dependency-glob: "pyproject.toml"
+      - run: uv python install 3.13
+      - run: uv sync --all-extras --dev
+      - run: uv run ruff check src/ tests/
+      - run: uv run ruff format --check src/ tests/
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+          cache-dependency-glob: "pyproject.toml"
+      - run: uv python install ${{ matrix.python-version }}
+      - run: uv sync --all-extras --dev
+      - run: uv run pytest --cov=agentic_data_contracts --cov-report=term-missing
+
+  publish:
+    needs: [lint, test]
+    if: github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && github.event.inputs.run_publish == 'true')
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+      - run: uv python install 3.13
+      - run: uv build --no-sources
+      - uses: pypa/gh-action-pypi-publish@release/v1

agentic_data_contracts-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+*.duckdb
+*.duckdb.wal

agentic_data_contracts-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,16 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.8
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: ty-check
+        name: ty check
+        entry: ty check
+        language: system
+        types: [python]
+        pass_filenames: false

agentic_data_contracts-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

agentic_data_contracts-0.1.0/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.0] - 2026-03-27
+
+### Added
+
+- **Core layer**: YAML-first data contract schema with Pydantic validation, `DataContract` class with YAML loading and system prompt generation, `ContractSession` for lightweight resource enforcement (retries, tokens, cost, duration)
+- **Validation layer**: Four built-in SQL checkers via sqlglot (table allowlist, operation blocklist, required filters, no SELECT *), `Validator` orchestrator with two-layer pipeline (static checkers + optional EXPLAIN dry-run for cost/row enforcement)
+- **Tools layer**: `create_tools()` factory producing 10 agent tools (list_schemas, list_tables, describe_table, preview_table, list_metrics, lookup_metric, validate_query, query_cost_estimate, run_query, get_contract_info), `contract_middleware` decorator for wrapping existing tools
+- **Semantic layer**: `SemanticSource` protocol with three implementations — `YamlSource`, `DbtSource` (manifest.json), `CubeSource` (Cube schema YAML)
+- **Database adapters**: `DatabaseAdapter` protocol with `DuckDB` implementation (execute, explain with row estimate parsing, describe_table)
+- **Bridge layer**: Optional `ai-agent-contracts` integration via `compile_to_contract()` mapping YAML contracts to the formal 7-tuple Contract model
+- **Example**: Revenue analysis agent with DuckDB, YAML semantic source, and Claude Agent SDK fallback demo mode
+- **Developer tooling**: uv for dependency management, prek pre-commit hooks (ruff + ty), 124 tests

agentic_data_contracts-0.1.0/CLAUDE.md

@@ -0,0 +1,52 @@
+# CLAUDE.md
+
+## Project Overview
+
+`agentic-data-contracts` is a Python library for YAML-first data contract governance for AI agents. It lets data engineers define what tables an agent may query, which operations are forbidden, and what resource limits apply — then enforces those rules automatically at query time.
+
+## Tech Stack
+
+- Python 3.12+, uv for dependency management
+- Pydantic 2 for schema validation, sqlglot for SQL parsing
+- pytest + pytest-asyncio for testing, DuckDB for integration tests
+- ruff for linting/formatting, ty for type checking
+- prek for pre-commit hooks
+
+## Project Structure
+
+```
+src/agentic_data_contracts/
+├── core/          # YAML loading, Pydantic models, lightweight enforcement
+├── validation/    # sqlglot checkers, Validator (Layer 1 + 2), EXPLAIN protocol
+├── tools/         # 10-tool factory + middleware for Claude Agent SDK
+├── semantic/      # dbt/Cube/YAML source integrations
+├── adapters/      # DatabaseAdapter protocol + DuckDB implementation
+└── bridge/        # Optional ai-agent-contracts compilation
+```
+
+## Common Commands
+
+```bash
+uv sync --all-extras          # Install all dependencies
+uv run pytest -v              # Run all tests
+uv run pytest tests/test_core # Run specific test suite
+uv run ruff check src/ tests/ # Lint
+uv run ruff format src/ tests/ # Format
+ty check                      # Type check
+prek run --all-files          # Run pre-commit hooks
+```
+
+## Key Design Decisions
+
+- **Optional `ai-agent-contracts` dependency**: Library works standalone with lightweight enforcement; `ai-agent-contracts` upgrades to formal 7-tuple Contract model
+- **Protocol-based extensibility**: `DatabaseAdapter`, `SemanticSource`, `ExplainAdapter`, and `Checker` are all `@runtime_checkable` protocols
+- **Two-layer validation**: Layer 1 (sqlglot static analysis) always runs; Layer 2 (EXPLAIN dry-run) runs when a database adapter is available
+- **Tools are plain async functions**: Compatible with Claude Agent SDK via `create_sdk_mcp_server()` but framework-agnostic
+
+## Conventions
+
+- Follow TDD: write tests first, then implement
+- Each layer is independently testable with its own test suite under `tests/test_<layer>/`
+- YAML fixtures live in `tests/fixtures/`
+- Use `uv run` to execute anything Python-related
+- Pre-commit hooks (ruff + ty) run automatically on commit via prek

agentic_data_contracts-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Qing Ye
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentic_data_contracts-0.1.0/PKG-INFO

@@ -0,0 +1,282 @@
+Metadata-Version: 2.4
+Name: agentic-data-contracts
+Version: 0.1.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
+Project-URL: Issues, https://github.com/flyersworder/agentic-data-contracts/issues
+Project-URL: Documentation, https://github.com/flyersworder/agentic-data-contracts/blob/main/docs/architecture.md
+Author-email: Qing <qingye779@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai-agents,analytics,claude,data-contracts,data-governance,dbt,llm,sql-validation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: sqlglot>=23.0
+Provides-Extra: agent-contracts
+Requires-Dist: ai-agent-contracts>=0.2.0; extra == 'agent-contracts'
+Provides-Extra: agent-sdk
+Requires-Dist: claude-agent-sdk; extra == 'agent-sdk'
+Provides-Extra: all
+Requires-Dist: ai-agent-contracts>=0.2.0; extra == 'all'
+Requires-Dist: claude-agent-sdk; extra == 'all'
+Requires-Dist: duckdb; extra == 'all'
+Requires-Dist: google-cloud-bigquery; extra == 'all'
+Requires-Dist: psycopg2-binary; extra == 'all'
+Requires-Dist: snowflake-connector-python; extra == 'all'
+Provides-Extra: bigquery
+Requires-Dist: google-cloud-bigquery; extra == 'bigquery'
+Provides-Extra: dev
+Requires-Dist: duckdb; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Provides-Extra: duckdb
+Requires-Dist: duckdb; extra == 'duckdb'
+Provides-Extra: postgres
+Requires-Dist: psycopg2-binary; extra == 'postgres'
+Provides-Extra: snowflake
+Requires-Dist: snowflake-connector-python; extra == 'snowflake'
+Description-Content-Type: text/markdown
+
+# agentic-data-contracts
+
+YAML-first data contract governance for AI agents. Define what tables an agent may query, which operations are forbidden, and what resource limits apply — then enforce those rules automatically at query time.
+
+## Installation
+
+```bash
+uv add agentic-data-contracts
+# or
+pip install agentic-data-contracts
+```
+
+With optional database adapters:
+
+```bash
+uv add "agentic-data-contracts[duckdb]"      # DuckDB
+uv add "agentic-data-contracts[bigquery]"    # BigQuery
+uv add "agentic-data-contracts[snowflake]"   # Snowflake
+uv add "agentic-data-contracts[postgres]"    # PostgreSQL
+uv add "agentic-data-contracts[agent-sdk]"   # Claude Agent SDK integration
+```
+
+## Quick Start
+
+### 1. Write a YAML contract
+
+```yaml
+# contract.yml
+version: "1.0"
+name: revenue-analysis
+
+semantic:
+  allowed_tables:
+    - schema: analytics
+      tables: [orders, customers, subscriptions]
+  forbidden_operations: [DELETE, DROP, TRUNCATE, UPDATE, INSERT]
+  rules:
+    - name: tenant_isolation
+      description: "All queries must filter by tenant_id"
+      enforcement: block
+      filter_column: tenant_id
+    - name: no_select_star
+      description: "Must specify explicit columns"
+      enforcement: block
+
+resources:
+  cost_limit_usd: 5.00
+  max_retries: 3
+  token_budget: 50000
+
+temporal:
+  max_duration_seconds: 300
+```
+
+### 2. Load the contract and create tools
+
+```python
+from agentic_data_contracts import DataContract, create_tools
+from agentic_data_contracts.adapters.duckdb import DuckDBAdapter
+from agentic_data_contracts.semantic.yaml_source import YamlSource
+
+dc = DataContract.from_yaml("contract.yml")
+adapter = DuckDBAdapter("analytics.duckdb")
+semantic = YamlSource("semantic.yml")
+
+tools = create_tools(dc, adapter=adapter, semantic_source=semantic)
+```
+
+### 3. Use with the Claude Agent SDK
+
+```python
+import asyncio
+from claude_agent_sdk import (
+    ClaudeAgentOptions,
+    AssistantMessage,
+    TextBlock,
+    create_sdk_mcp_server,
+    query,
+)
+
+server = create_sdk_mcp_server(name="data-contracts", version="1.0.0", tools=tools)
+
+options = ClaudeAgentOptions(
+    model="claude-sonnet-4-6",
+    system_prompt=f"You are a revenue analytics assistant.\n\n{dc.to_system_prompt()}",
+    mcp_servers={"dc": server},
+    allowed_tools=[f"mcp__dc__{t.name}" for t in tools],
+)
+
+async def run(prompt: str) -> None:
+    async for message in query(prompt=prompt, options=options):
+        if isinstance(message, AssistantMessage):
+            for block in message.content:
+                if isinstance(block, TextBlock):
+                    print(block.text)
+
+asyncio.run(run("What was total revenue by region in Q1 2025?"))
+```
+
+### 4. Or use the tools directly (no SDK required)
+
+```python
+import asyncio
+
+async def demo() -> None:
+    # Validate a query without executing
+    validate = next(t for t in tools if t.name == "validate_query")
+    result = await validate.callable(
+        {"sql": "SELECT id, amount FROM analytics.orders WHERE tenant_id = 'acme'"}
+    )
+    print(result["content"][0]["text"])
+    # VALID — Query passed all checks.
+
+    # Blocked query
+    result = await validate.callable({"sql": "SELECT * FROM analytics.orders"})
+    print(result["content"][0]["text"])
+    # BLOCKED — Violations:
+    # - SELECT * is not allowed — specify explicit columns
+
+asyncio.run(demo())
+```
+
+## The 10 Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_schemas` | List all allowed database schemas from the contract |
+| `list_tables` | List allowed tables, optionally filtered by schema |
+| `describe_table` | Get full column details for an allowed table |
+| `preview_table` | Preview sample rows from an allowed table |
+| `list_metrics` | List all metric definitions from the semantic source |
+| `lookup_metric` | Get the full definition of a specific metric |
+| `validate_query` | Validate a SQL query against contract rules without executing |
+| `query_cost_estimate` | Estimate cost and row count via EXPLAIN |
+| `run_query` | Validate and execute a SQL query, returning results |
+| `get_contract_info` | Get the full contract: rules, limits, and session status |
+
+## Contract Rules
+
+Rules are enforced at three levels:
+
+- **`block`** — query is rejected and an error is returned to the agent
+- **`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
+
+## Semantic Sources
+
+A semantic source provides metric and table schema metadata to the agent.
+
+**YAML** (built-in):
+```yaml
+# semantic.yml
+metrics:
+  - name: total_revenue
+    description: "Total revenue from completed orders"
+    sql_expression: "SUM(amount) FILTER (WHERE status = 'completed')"
+    source_model: analytics.orders
+
+tables:
+  - schema: analytics
+    table: orders
+    columns:
+      - name: id
+        type: INTEGER
+      - name: amount
+        type: DECIMAL
+      - name: tenant_id
+        type: VARCHAR
+```
+
+**dbt** — point to a `manifest.json`:
+```yaml
+semantic:
+  source:
+    type: dbt
+    path: "./dbt/manifest.json"
+```
+
+**Cube** — point to a Cube schema file:
+```yaml
+semantic:
+  source:
+    type: cube
+    path: "./cube/schema.yml"
+```
+
+## Resource Limits
+
+```yaml
+resources:
+  cost_limit_usd: 5.00          # max estimated query cost
+  max_retries: 3                 # max blocked queries per session
+  token_budget: 50000            # max tokens consumed
+  max_query_time_seconds: 30     # max wall-clock query time
+  max_rows_scanned: 1000000      # max rows an EXPLAIN may estimate
+```
+
+## Optional Dependencies
+
+| Extra | Package | Purpose |
+|-------|---------|---------|
+| `duckdb` | `duckdb` | DuckDB adapter |
+| `bigquery` | `google-cloud-bigquery` | BigQuery adapter |
+| `snowflake` | `snowflake-connector-python` | Snowflake adapter |
+| `postgres` | `psycopg2-binary` | PostgreSQL adapter |
+| `agent-sdk` | `claude-agent-sdk` | Claude Agent SDK integration |
+| `agent-contracts` | `ai-agent-contracts>=0.2.0` | ai-agent-contracts bridge |
+
+## 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.
+
+```bash
+uv run python examples/revenue_agent/setup_db.py
+uv run python examples/revenue_agent/agent.py "What was Q1 revenue by region?"
+```
+
+## Architecture
+
+See [`docs/architecture.md`](docs/architecture.md) for the full design spec covering the layered architecture, YAML schema, validation pipeline, tool design, semantic sources, database adapters, and the optional `ai-agent-contracts` bridge.
+
+## License
+
+MIT