feat: add table relationship metadata for join guidance (v0.2.5)

- Add Relationship dataclass (from_, to, type) to semantic.base
- Add get_relationships() to SemanticSource protocol
- Implement in YamlSource (parsed from YAML), DbtSource and CubeSource
  (empty, ready for native join metadata parsing)
- Include relationships in to_system_prompt() so agent knows join paths
- Update semantic_source.yml fixture with relationships section
- 6 new tests (177 total)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: flyersworder

CHANGELOG.md

@@ -2,6 +2,15 @@
 
 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

pyproject.toml

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

src/agentic_data_contracts/core/contract.py

@@ -171,6 +171,17 @@ def to_system_prompt(self, semantic_source: SemanticSource | None = None) -> str
             )
             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:

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(

src/agentic_data_contracts/semantic/cube.py

@@ -7,7 +7,11 @@
 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 @@ def get_metric(self, name: str) -> MetricDefinition | None:
     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}")

src/agentic_data_contracts/semantic/dbt.py

@@ -7,7 +7,11 @@
 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 @@ def get_metric(self, name: str) -> MetricDefinition | None:
     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}")

src/agentic_data_contracts/semantic/yaml_source.py

@@ -7,7 +7,11 @@
 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 @@ def __init__(self, path: str | Path) -> None:
                     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 @@ def get_metric(self, name: str) -> MetricDefinition | None:
     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}")

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

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

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