agentic-data-contracts 0.2.3__tar.gz → 0.2.4__tar.gz

{agentic_data_contracts-0.2.3 → agentic_data_contracts-0.2.4}/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.2.4] - 2026-03-29
+
+### Added
+
+- **Wildcard table support**: Use `tables: ["*"]` in `allowed_tables` to allow all tables in a schema, discovered from the database at runtime via `adapter.list_tables()`
+- **`DataContract.resolve_tables(adapter)`**: Expands wildcard entries using the database adapter; called automatically by `create_tools()` when an adapter is provided
+- **`DatabaseAdapter.list_tables(schema)`**: New protocol method for listing tables in a schema; implemented in `DuckDBAdapter` via `information_schema.tables`
+
 ## [0.2.3] - 2026-03-29
 
 ### Added

{agentic_data_contracts-0.2.3 → agentic_data_contracts-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-data-contracts
-Version: 0.2.3
+Version: 0.2.4
 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
@@ -117,7 +117,9 @@ semantic:
     path: "./semantic.yml"
   allowed_tables:
     - schema: analytics
-      tables: [orders, customers, subscriptions]
+      tables: ["*"]          # all tables in schema (discovered from database)
+    - schema: marketing
+      tables: [campaigns]    # or list specific tables
   forbidden_operations: [DELETE, DROP, TRUNCATE, UPDATE, INSERT]
   rules:
     - name: tenant_isolation

{agentic_data_contracts-0.2.3 → agentic_data_contracts-0.2.4}/README.md

@@ -64,7 +64,9 @@ semantic:
     path: "./semantic.yml"
   allowed_tables:
     - schema: analytics
-      tables: [orders, customers, subscriptions]
+      tables: ["*"]          # all tables in schema (discovered from database)
+    - schema: marketing
+      tables: [campaigns]    # or list specific tables
   forbidden_operations: [DELETE, DROP, TRUNCATE, UPDATE, INSERT]
   rules:
     - name: tenant_isolation

{agentic_data_contracts-0.2.3 → agentic_data_contracts-0.2.4}/pyproject.toml

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

{agentic_data_contracts-0.2.3 → agentic_data_contracts-0.2.4}/src/agentic_data_contracts/adapters/base.py

@@ -37,6 +37,7 @@ class DatabaseAdapter(Protocol):
     def execute(self, sql: str) -> QueryResult: ...
     def explain(self, sql: str) -> ExplainResult: ...
     def describe_table(self, schema: str, table: str) -> TableSchema: ...
+    def list_tables(self, schema: str) -> list[str]: ...
 
     @property
     def dialect(self) -> str: ...

{agentic_data_contracts-0.2.3 → agentic_data_contracts-0.2.4}/src/agentic_data_contracts/adapters/duckdb.py

@@ -59,6 +59,18 @@ class DuckDBAdapter:
                 last_estimate = int(match.group(1))
         return last_estimate
 
+    def list_tables(self, schema: str) -> list[str]:
+        rows = self.connection.execute(
+            """
+            SELECT table_name
+            FROM information_schema.tables
+            WHERE table_schema = ?
+            ORDER BY table_name
+            """,
+            [schema],
+        ).fetchall()
+        return [row[0] for row in rows]
+
     def describe_table(self, schema: str, table: str) -> TableSchema:
         rows = self.connection.execute(
             """

{agentic_data_contracts-0.2.3 → agentic_data_contracts-0.2.4}/src/agentic_data_contracts/core/contract.py

@@ -14,6 +14,7 @@ from agentic_data_contracts.core.schema import (
 )
 
 if TYPE_CHECKING:
+    from agentic_data_contracts.adapters.base import DatabaseAdapter
     from agentic_data_contracts.semantic.base import SemanticSource
 
 
@@ -38,10 +39,27 @@ class DataContract:
         schema = DataContractSchema.model_validate(raw)
         return cls(schema=schema)
 
+    def has_wildcard_tables(self) -> bool:
+        """Check if any schema uses wildcard ('*') for tables."""
+        return any("*" in entry.tables for entry in self.schema.semantic.allowed_tables)
+
+    def resolve_tables(self, adapter: DatabaseAdapter) -> None:
+        """Expand wildcard tables using the database adapter.
+
+        Replaces ["*"] entries with actual table names from the database.
+        Call this once after creating the adapter. Results are cached
+        on the schema object.
+        """
+        for entry in self.schema.semantic.allowed_tables:
+            if "*" in entry.tables:
+                entry.tables = adapter.list_tables(entry.schema_)
+
     def allowed_table_names(self) -> list[str]:
         names: list[str] = []
         for entry in self.schema.semantic.allowed_tables:
             for table in entry.tables:
+                if table == "*":
+                    continue  # unresolved wildcard — skip
                 names.append(f"{entry.schema_}.{table}")
         return names
 

{agentic_data_contracts-0.2.3 → agentic_data_contracts-0.2.4}/src/agentic_data_contracts/tools/factory.py

@@ -41,6 +41,10 @@ def create_tools(
     if semantic_source is None:
         semantic_source = contract.load_semantic_source()
 
+    # Resolve wildcard tables if adapter is available
+    if adapter is not None and contract.has_wildcard_tables():
+        contract.resolve_tables(adapter)
+
     dialect = adapter.dialect if adapter else None
     validator = Validator(contract, dialect=dialect, explain_adapter=adapter)
 
@@ -60,6 +64,11 @@ def create_tools(
         for entry in contract.schema.semantic.allowed_tables:
             if schema_filter and entry.schema_ != schema_filter:
                 continue
+            if "*" in entry.tables:
+                return _text_response(
+                    f"Schema '{entry.schema_}' uses wildcard tables"
+                    " but no database adapter is available to resolve them."
+                )
             for table in entry.tables:
                 info: dict[str, Any] = {
                     "schema": entry.schema_,

agentic_data_contracts-0.2.4/tests/test_core/test_wildcard_tables.py

@@ -0,0 +1,106 @@
+"""Tests for wildcard table support in allowed_tables."""
+
+from agentic_data_contracts.adapters.duckdb import DuckDBAdapter
+from agentic_data_contracts.core.contract import DataContract
+from agentic_data_contracts.core.schema import (
+    AllowedTable,
+    DataContractSchema,
+    SemanticConfig,
+)
+
+
+def _make_contract(tables_config: list[dict]) -> DataContract:
+    allowed = [AllowedTable.model_validate(t) for t in tables_config]
+    schema = DataContractSchema(
+        name="test",
+        semantic=SemanticConfig(allowed_tables=allowed),
+    )
+    return DataContract(schema)
+
+
+def _make_adapter() -> DuckDBAdapter:
+    db = DuckDBAdapter(":memory:")
+    db.connection.execute("""
+        CREATE SCHEMA IF NOT EXISTS analytics;
+        CREATE TABLE analytics.orders (id INTEGER);
+        CREATE TABLE analytics.customers (id INTEGER);
+        CREATE TABLE analytics.products (id INTEGER);
+        CREATE SCHEMA IF NOT EXISTS raw;
+        CREATE TABLE raw.events (id INTEGER);
+    """)
+    return db
+
+
+def test_has_wildcard_tables_true() -> None:
+    dc = _make_contract([{"schema": "analytics", "tables": ["*"]}])
+    assert dc.has_wildcard_tables()
+
+
+def test_has_wildcard_tables_false() -> None:
+    dc = _make_contract(
+        [
+            {"schema": "analytics", "tables": ["orders"]},
+        ]
+    )
+    assert not dc.has_wildcard_tables()
+
+
+def test_resolve_tables_expands_wildcard() -> None:
+    dc = _make_contract([{"schema": "analytics", "tables": ["*"]}])
+    adapter = _make_adapter()
+    dc.resolve_tables(adapter)
+
+    names = dc.allowed_table_names()
+    assert "analytics.orders" in names
+    assert "analytics.customers" in names
+    assert "analytics.products" in names
+    assert not any(n.startswith("raw.") for n in names)
+
+
+def test_resolve_tables_mixed() -> None:
+    dc = _make_contract(
+        [
+            {"schema": "analytics", "tables": ["*"]},
+            {"schema": "raw", "tables": []},
+        ]
+    )
+    adapter = _make_adapter()
+    dc.resolve_tables(adapter)
+
+    names = dc.allowed_table_names()
+    assert "analytics.orders" in names
+    assert not any(n.startswith("raw.") for n in names)
+
+
+def test_resolve_tables_preserves_explicit() -> None:
+    dc = _make_contract(
+        [
+            {"schema": "analytics", "tables": ["orders"]},
+        ]
+    )
+    adapter = _make_adapter()
+    dc.resolve_tables(adapter)
+
+    names = dc.allowed_table_names()
+    assert names == ["analytics.orders"]
+
+
+def test_unresolved_wildcard_skipped() -> None:
+    dc = _make_contract([{"schema": "analytics", "tables": ["*"]}])
+    # Without calling resolve_tables, wildcard is skipped
+    names = dc.allowed_table_names()
+    assert names == []
+
+
+def test_adapter_list_tables() -> None:
+    adapter = _make_adapter()
+    tables = adapter.list_tables("analytics")
+    assert "orders" in tables
+    assert "customers" in tables
+    assert "products" in tables
+
+
+def test_adapter_list_tables_empty_schema() -> None:
+    adapter = _make_adapter()
+    tables = adapter.list_tables("nonexistent")
+    assert tables == []

agentic_data_contracts-0.2.4/tests/test_tools/test_wildcard_tools.py

@@ -0,0 +1,76 @@
+"""Tests for tools with wildcard table resolution."""
+
+import json
+
+import pytest
+
+from agentic_data_contracts.adapters.duckdb import DuckDBAdapter
+from agentic_data_contracts.core.contract import DataContract
+from agentic_data_contracts.core.schema import (
+    AllowedTable,
+    DataContractSchema,
+    SemanticConfig,
+)
+from agentic_data_contracts.tools.factory import create_tools
+
+
+@pytest.fixture
+def adapter() -> DuckDBAdapter:
+    db = DuckDBAdapter(":memory:")
+    db.connection.execute("""
+        CREATE SCHEMA IF NOT EXISTS analytics;
+        CREATE TABLE analytics.orders (id INTEGER, amount DECIMAL);
+        CREATE TABLE analytics.customers (id INTEGER, name VARCHAR);
+        INSERT INTO analytics.orders VALUES (1, 100.00);
+    """)
+    return db
+
+
+@pytest.fixture
+def wildcard_contract() -> DataContract:
+    schema = DataContractSchema(
+        name="test",
+        semantic=SemanticConfig(
+            allowed_tables=[
+                AllowedTable.model_validate({"schema": "analytics", "tables": ["*"]}),
+            ],
+        ),
+    )
+    return DataContract(schema)
+
+
+@pytest.mark.asyncio
+async def test_list_tables_after_wildcard_resolve(
+    wildcard_contract: DataContract, adapter: DuckDBAdapter
+) -> None:
+    tools = create_tools(wildcard_contract, adapter=adapter)
+    tool = next(t for t in tools if t.name == "list_tables")
+    result = await tool.callable({})
+    text = result["content"][0]["text"]
+    data = json.loads(text)
+    table_names = [t["table"] for t in data["tables"]]
+    assert "orders" in table_names
+    assert "customers" in table_names
+
+
+@pytest.mark.asyncio
+async def test_run_query_with_wildcard_tables(
+    wildcard_contract: DataContract, adapter: DuckDBAdapter
+) -> None:
+    tools = create_tools(wildcard_contract, adapter=adapter)
+    tool = next(t for t in tools if t.name == "run_query")
+    result = await tool.callable({"sql": "SELECT id, amount FROM analytics.orders"})
+    text = result["content"][0]["text"]
+    assert "100" in text
+
+
+@pytest.mark.asyncio
+async def test_validate_query_with_wildcard_tables(
+    wildcard_contract: DataContract, adapter: DuckDBAdapter
+) -> None:
+    tools = create_tools(wildcard_contract, adapter=adapter)
+    tool = next(t for t in tools if t.name == "validate_query")
+    # analytics.orders should be allowed after wildcard resolution
+    result = await tool.callable({"sql": "SELECT id FROM analytics.orders"})
+    text = result["content"][0]["text"]
+    assert "valid" in text.lower()

{agentic_data_contracts-0.2.3 → agentic_data_contracts-0.2.4}/uv.lock

@@ -9,7 +9,7 @@ resolution-markers = [
 
 [[package]]
 name = "agentic-data-contracts"
-version = "0.2.3"
+version = "0.2.4"
 source = { editable = "." }
 dependencies = [
     { name = "pydantic" },