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

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

@@ -2,6 +2,23 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.2.5] - 2026-03-29
+
+### Added
+
+- **Table relationship metadata**: `Relationship` dataclass and `get_relationships()` on `SemanticSource` protocol for declaring join paths between tables (from/to column + relationship type)
+- **Relationships in system prompt**: `to_system_prompt()` includes join paths so the agent knows how to combine tables correctly
+- **YamlSource relationships**: Parsed from `relationships` section in semantic YAML files
+- DbtSource and CubeSource return empty relationships (ready for future parsing of native join metadata)
+
+## [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.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-data-contracts
-Version: 0.2.3
+Version: 0.2.5
 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
@@ -275,6 +277,23 @@ semantic:
     path: "./cube/schema.yml"
 ```
 
+## Table Relationships
+
+Define join paths so the agent knows how to combine tables correctly:
+
+```yaml
+# semantic.yml
+relationships:
+  - from: analytics.orders.customer_id
+    to: analytics.customers.id
+    type: many_to_one
+  - from: analytics.orders.product_id
+    to: analytics.products.id
+    type: many_to_one
+```
+
+The agent sees these in its system prompt and uses them to write correct JOINs instead of guessing from column names.
+
 ## Scalable Metric Discovery
 
 For large data lakes with hundreds of KPIs, group metrics by domain and let the agent discover them efficiently:

{agentic_data_contracts-0.2.3 → agentic_data_contracts-0.2.5}/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
@@ -222,6 +224,23 @@ semantic:
     path: "./cube/schema.yml"
 ```
 
+## Table Relationships
+
+Define join paths so the agent knows how to combine tables correctly:
+
+```yaml
+# semantic.yml
+relationships:
+  - from: analytics.orders.customer_id
+    to: analytics.customers.id
+    type: many_to_one
+  - from: analytics.orders.product_id
+    to: analytics.products.id
+    type: many_to_one
+```
+
+The agent sees these in its system prompt and uses them to write correct JOINs instead of guessing from column names.
+
 ## Scalable Metric Discovery
 
 For large data lakes with hundreds of KPIs, group metrics by domain and let the agent discover them efficiently:

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

@@ -1,6 +1,6 @@
 [project]
 name = "agentic-data-contracts"
-version = "0.2.3"
+version = "0.2.5"
 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.5}/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.5}/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.5}/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
 
@@ -153,6 +171,17 @@ class DataContract:
             )
             sections.append(line)
 
+        # Table relationships
+        if semantic_source is not None:
+            rels = semantic_source.get_relationships()
+            if rels:
+                sections.append(
+                    "\n### Table Relationships\n"
+                    "Use these join paths when combining tables:"
+                )
+                for r in rels:
+                    sections.append(f"- {r.from_} \u2192 {r.to} ({r.type})")
+
         # Resource limits
         res = self.schema.resources
         if res:

{agentic_data_contracts-0.2.3 → agentic_data_contracts-0.2.5}/src/agentic_data_contracts/semantic/base.py

@@ -20,12 +20,20 @@ class MetricDefinition:
     filters: list[str] = field(default_factory=list)
 
 
+@dataclass
+class Relationship:
+    from_: str  # "schema.table.column"
+    to: str  # "schema.table.column"
+    type: str = "many_to_one"  # many_to_one | one_to_one | many_to_many
+
+
 @runtime_checkable
 class SemanticSource(Protocol):
     def get_metrics(self) -> list[MetricDefinition]: ...
     def get_metric(self, name: str) -> MetricDefinition | None: ...
     def get_table_schema(self, schema: str, table: str) -> TableSchema | None: ...
     def search_metrics(self, query: str) -> list[MetricDefinition]: ...
+    def get_relationships(self) -> list[Relationship]: ...
 
 
 def fuzzy_search_metrics(

{agentic_data_contracts-0.2.3 → agentic_data_contracts-0.2.5}/src/agentic_data_contracts/semantic/cube.py

@@ -7,7 +7,11 @@ from pathlib import Path
 import yaml
 
 from agentic_data_contracts.adapters.base import Column, TableSchema
-from agentic_data_contracts.semantic.base import MetricDefinition, fuzzy_search_metrics
+from agentic_data_contracts.semantic.base import (
+    MetricDefinition,
+    Relationship,
+    fuzzy_search_metrics,
+)
 
 
 class CubeSource:
@@ -54,5 +58,8 @@ class CubeSource:
     def search_metrics(self, query: str) -> list[MetricDefinition]:
         return fuzzy_search_metrics(self._metrics, self.get_metric, query)
 
+    def get_relationships(self) -> list[Relationship]:
+        return []  # TODO: parse from Cube joins config
+
     def get_table_schema(self, schema: str, table: str) -> TableSchema | None:
         return self._tables.get(f"{schema}.{table}")

{agentic_data_contracts-0.2.3 → agentic_data_contracts-0.2.5}/src/agentic_data_contracts/semantic/dbt.py

@@ -7,7 +7,11 @@ from pathlib import Path
 from typing import Any
 
 from agentic_data_contracts.adapters.base import Column, TableSchema
-from agentic_data_contracts.semantic.base import MetricDefinition, fuzzy_search_metrics
+from agentic_data_contracts.semantic.base import (
+    MetricDefinition,
+    Relationship,
+    fuzzy_search_metrics,
+)
 
 
 class DbtSource:
@@ -77,5 +81,8 @@ class DbtSource:
     def search_metrics(self, query: str) -> list[MetricDefinition]:
         return fuzzy_search_metrics(self._metrics, self.get_metric, query)
 
+    def get_relationships(self) -> list[Relationship]:
+        return []  # TODO: parse from dbt manifest relationships/refs
+
     def get_table_schema(self, schema: str, table: str) -> TableSchema | None:
         return self._tables.get(f"{schema}.{table}")

{agentic_data_contracts-0.2.3 → agentic_data_contracts-0.2.5}/src/agentic_data_contracts/semantic/yaml_source.py

@@ -7,7 +7,11 @@ from pathlib import Path
 import yaml
 
 from agentic_data_contracts.adapters.base import Column, TableSchema
-from agentic_data_contracts.semantic.base import MetricDefinition, fuzzy_search_metrics
+from agentic_data_contracts.semantic.base import (
+    MetricDefinition,
+    Relationship,
+    fuzzy_search_metrics,
+)
 
 
 class YamlSource:
@@ -38,6 +42,14 @@ class YamlSource:
                     for c in t.get("columns", [])
                 ]
             )
+        self._relationships = [
+            Relationship(
+                from_=r["from"],
+                to=r["to"],
+                type=r.get("type", "many_to_one"),
+            )
+            for r in raw.get("relationships", [])
+        ]
 
     def get_metrics(self) -> list[MetricDefinition]:
         return list(self._metrics)
@@ -51,5 +63,8 @@ class YamlSource:
     def search_metrics(self, query: str) -> list[MetricDefinition]:
         return fuzzy_search_metrics(self._metrics, self.get_metric, query)
 
+    def get_relationships(self) -> list[Relationship]:
+        return list(self._relationships)
+
     def get_table_schema(self, schema: str, table: str) -> TableSchema | None:
         return self._tables.get(f"{schema}.{table}")

{agentic_data_contracts-0.2.3 → agentic_data_contracts-0.2.5}/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.3 → agentic_data_contracts-0.2.5}/tests/fixtures/semantic_source.yml

@@ -29,3 +29,24 @@ tables:
       - name: status
         type: VARCHAR
         description: "Order status: pending, completed, cancelled"
+      - name: customer_id
+        type: INTEGER
+        description: "FK to customers"
+
+  - schema: analytics
+    table: customers
+    columns:
+      - name: id
+        type: INTEGER
+        description: "Primary key"
+      - name: name
+        type: VARCHAR
+        description: "Customer name"
+      - name: region
+        type: VARCHAR
+        description: "Geographic region"
+
+relationships:
+  - from: analytics.orders.customer_id
+    to: analytics.customers.id
+    type: many_to_one

agentic_data_contracts-0.2.5/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.5/tests/test_semantic/test_relationships.py

@@ -0,0 +1,83 @@
+"""Tests for table relationship metadata."""
+
+from pathlib import Path
+
+from agentic_data_contracts.core.contract import DataContract
+from agentic_data_contracts.core.schema import (
+    AllowedTable,
+    DataContractSchema,
+    SemanticConfig,
+)
+from agentic_data_contracts.semantic.cube import CubeSource
+from agentic_data_contracts.semantic.dbt import DbtSource
+from agentic_data_contracts.semantic.yaml_source import YamlSource
+
+
+def test_yaml_source_loads_relationships(fixtures_dir: Path) -> None:
+    source = YamlSource(fixtures_dir / "semantic_source.yml")
+    rels = source.get_relationships()
+    assert len(rels) == 1
+    assert rels[0].from_ == "analytics.orders.customer_id"
+    assert rels[0].to == "analytics.customers.id"
+    assert rels[0].type == "many_to_one"
+
+
+def test_yaml_source_no_relationships(tmp_path: Path) -> None:
+    (tmp_path / "empty.yml").write_text("metrics: []")
+    source = YamlSource(tmp_path / "empty.yml")
+    assert source.get_relationships() == []
+
+
+def test_dbt_source_returns_empty_relationships(
+    fixtures_dir: Path,
+) -> None:
+    source = DbtSource(fixtures_dir / "sample_dbt_manifest.json")
+    assert source.get_relationships() == []
+
+
+def test_cube_source_returns_empty_relationships(
+    fixtures_dir: Path,
+) -> None:
+    source = CubeSource(fixtures_dir / "sample_cube_schema.yml")
+    assert source.get_relationships() == []
+
+
+def test_system_prompt_includes_relationships(
+    fixtures_dir: Path,
+) -> None:
+    source = YamlSource(fixtures_dir / "semantic_source.yml")
+    schema = DataContractSchema(
+        name="test",
+        semantic=SemanticConfig(
+            allowed_tables=[
+                AllowedTable.model_validate(
+                    {"schema": "analytics", "tables": ["orders", "customers"]}
+                ),
+            ],
+        ),
+    )
+    dc = DataContract(schema)
+    prompt = dc.to_system_prompt(semantic_source=source)
+    assert "Table Relationships" in prompt
+    assert "analytics.orders.customer_id" in prompt
+    assert "analytics.customers.id" in prompt
+    assert "many_to_one" in prompt
+
+
+def test_system_prompt_no_relationships_when_empty(
+    fixtures_dir: Path,
+) -> None:
+    source = DbtSource(fixtures_dir / "sample_dbt_manifest.json")
+    schema = DataContractSchema(
+        name="test",
+        semantic=SemanticConfig(
+            allowed_tables=[
+                AllowedTable.model_validate(
+                    {"schema": "analytics", "tables": ["orders"]}
+                ),
+            ],
+        ),
+    )
+    dc = DataContract(schema)
+    prompt = dc.to_system_prompt(semantic_source=source)
+    assert "Table Relationships" not in prompt

{agentic_data_contracts-0.2.3 → agentic_data_contracts-0.2.5}/tests/test_semantic/test_yaml_source.py

@@ -39,7 +39,7 @@ def test_get_metric_not_found(source: YamlSource) -> None:
 def test_get_table_schema(source: YamlSource) -> None:
     schema = source.get_table_schema("analytics", "orders")
     assert schema is not None
-    assert len(schema.columns) == 4
+    assert len(schema.columns) == 5
     col_names = [c.name for c in schema.columns]
     assert "id" in col_names
     assert "amount" in col_names

agentic_data_contracts-0.2.5/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.5}/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" },