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

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

@@ -2,6 +2,28 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.6.0] - 2026-04-09
+
+### Added
+
+- **Relationship `description` field**: Optional free-text description on `Relationship` for communicating join conditions, data quality caveats, or usage guidance to the agent. Rendered as an XML attribute in the system prompt when present.
+- **Relationship `required_filter` field**: Optional structured filter condition (e.g., `"attribution_model = 'last_touch'"`) that must be applied when using a relationship. Rendered as a `<required_filter>` element in the system prompt, giving agents a clear, unambiguous signal about mandatory join conditions — especially useful for bridge/junction tables.
+- **Contract-relative path resolution**: `DataContract.from_yaml()` now resolves `source.path` relative to the contract file's directory, not the process CWD. This means `path: "./semantic.yml"` in `contracts/contract.yml` correctly loads `contracts/semantic.yml` regardless of where the process runs. Absolute paths and `from_yaml_string()` are unaffected.
+
+### Fixed
+
+- **Example contract**: Removed invalid `filter_column` field from `examples/revenue_agent/contract.yml` (the field was removed in v0.4.0 in favor of `query_check.required_filter`).
+
+## [0.5.0] - 2026-04-04
+
+### Added
+
+- **`SqlNormalizer` protocol**: Optional pre-processing hook for adapters serving non-standard SQL dialects (e.g., Denodo VQL, Teradata). Adapters implement `normalize_sql(sql) -> str` to rewrite proprietary syntax into a form sqlglot can parse, while the original SQL is preserved for `execute()` and `explain()`.
+- **Auto-detection in factory and middleware**: When an adapter implements both `DatabaseAdapter` and `SqlNormalizer`, the factory and middleware automatically wire normalization into the `Validator` — no API changes needed.
+- **Normalization in `validate_results()`**: Table-scoped result checks now also benefit from SQL normalization, ensuring scoped checks fire correctly for non-standard dialects.
+- **Adapter package exports**: `adapters/__init__.py` now re-exports `Column`, `DatabaseAdapter`, `QueryResult`, `SqlNormalizer`, and `TableSchema`.
+- **Root export**: `SqlNormalizer` is available via `from agentic_data_contracts import SqlNormalizer`.
+
 ## [0.4.0] - 2026-03-31
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-data-contracts
-Version: 0.4.0
+Version: 0.6.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
@@ -289,7 +289,7 @@ rules:
 
 ## Semantic Sources
 
-A semantic source provides metric and table schema metadata to the agent.
+A semantic source provides metric, table schema, and relationship metadata to the agent. Paths are resolved relative to the contract file's directory (not the process CWD).
 
 **YAML** (built-in):
 ```yaml
@@ -338,11 +338,24 @@ relationships:
   - from: analytics.orders.customer_id
     to: analytics.customers.id
     type: many_to_one
-  - from: analytics.orders.product_id
-    to: analytics.products.id
+    description: >
+      Join orders to customers for region-level breakdowns.
+      Every order has exactly one customer.
+
+  - from: analytics.bdg_attribution.contact_id
+    to: analytics.contacts.contact_id
     type: many_to_one
+    description: "Bridge table — filter to avoid fan-out from multiple attribution records."
+    required_filter: "attribution_model = 'last_touch_attribution'"
 ```
 
+| Field | Required | Description |
+|-------|----------|-------------|
+| `from` / `to` | Yes | Fully qualified column references (`schema.table.column`) |
+| `type` | No | Cardinality: `many_to_one` (default), `one_to_one`, `many_to_many` |
+| `description` | No | Free-text context for the agent (join guidance, caveats, data quality notes) |
+| `required_filter` | No | SQL condition that **must** be applied when using this join (e.g., bridge table disambiguation) |
+
 The agent sees these in its system prompt and uses them to write correct JOINs instead of guessing from column names.
 
 ## Custom Prompt Rendering

{agentic_data_contracts-0.4.0 → agentic_data_contracts-0.6.0}/README.md

@@ -236,7 +236,7 @@ rules:
 
 ## Semantic Sources
 
-A semantic source provides metric and table schema metadata to the agent.
+A semantic source provides metric, table schema, and relationship metadata to the agent. Paths are resolved relative to the contract file's directory (not the process CWD).
 
 **YAML** (built-in):
 ```yaml
@@ -285,11 +285,24 @@ relationships:
   - from: analytics.orders.customer_id
     to: analytics.customers.id
     type: many_to_one
-  - from: analytics.orders.product_id
-    to: analytics.products.id
+    description: >
+      Join orders to customers for region-level breakdowns.
+      Every order has exactly one customer.
+
+  - from: analytics.bdg_attribution.contact_id
+    to: analytics.contacts.contact_id
     type: many_to_one
+    description: "Bridge table — filter to avoid fan-out from multiple attribution records."
+    required_filter: "attribution_model = 'last_touch_attribution'"
 ```
 
+| Field | Required | Description |
+|-------|----------|-------------|
+| `from` / `to` | Yes | Fully qualified column references (`schema.table.column`) |
+| `type` | No | Cardinality: `many_to_one` (default), `one_to_one`, `many_to_many` |
+| `description` | No | Free-text context for the agent (join guidance, caveats, data quality notes) |
+| `required_filter` | No | SQL condition that **must** be applied when using this join (e.g., bridge table disambiguation) |
+
 The agent sees these in its system prompt and uses them to write correct JOINs instead of guessing from column names.
 
 ## Custom Prompt Rendering

{agentic_data_contracts-0.4.0 → agentic_data_contracts-0.6.0}/docs/architecture.md

@@ -1,7 +1,7 @@
 # Agentic Data Contracts — Architecture
 
-**Date:** 2026-03-31
-**Status:** Implemented (v0.4.0)
+**Date:** 2026-04-09
+**Status:** Implemented (v0.6.0)
 **Author:** Qing Ye + Claude
 
 ## Problem Statement
@@ -88,7 +88,7 @@ name: revenue-analysis
 semantic:
   source:
     type: dbt                          # dbt | cube | yaml | custom
-    path: "./dbt/manifest.json"        # local path or URL
+    path: "./dbt/manifest.json"        # resolved relative to contract file
 
   # What the agent is allowed to access
   allowed_tables:
@@ -369,6 +369,7 @@ class SemanticSource(Protocol):
     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]: ...
 ```
 
 **Fuzzy metric search:** When `lookup_metric` receives a query that doesn't exactly match a metric name, it falls back to `search_metrics()` which uses `thefuzz` (`token_set_ratio` scorer, cutoff 50) to find the best matches by name + description. A shared `fuzzy_search_metrics()` helper in `base.py` provides this logic for all source implementations.
@@ -379,9 +380,10 @@ class SemanticSource(Protocol):
 |---|---|---|
 | `DbtSource` | `manifest.json` | Metrics, models, columns |
 | `CubeSource` | Cube meta API or schema files | Metrics, dimensions |
-| `YamlSource` | Inline YAML definitions | Simple metric/table definitions for teams not using dbt/Cube |
+| `YamlSource` | Inline YAML definitions | Simple metric/table/relationship definitions for teams not using dbt/Cube |
 
 `MetricDefinition`: `name`, `description`, `sql_expression`, `source_model`, `filters`.
+`Relationship`: `from_`, `to`, `type`, `description`, `required_filter`.
 `TableSchema`: `columns: list[Column]` with name, type, description.
 
 ## Database Adapters
@@ -393,8 +395,17 @@ class DatabaseAdapter(Protocol):
     def describe_table(self, schema: str, table: str) -> TableSchema: ...
     @property
     def dialect(self) -> str: ...  # "bigquery", "snowflake", "postgres", "duckdb"
+
+class SqlNormalizer(Protocol):
+    def normalize_sql(self, sql: str) -> str: ...
 ```
 
+### SQL Normalization for Non-Standard Dialects
+
+Adapters for databases with proprietary SQL extensions (Denodo VQL, Teradata, ClickHouse) can implement `SqlNormalizer` alongside `DatabaseAdapter`. The `Validator` calls `normalize_sql()` before `sqlglot.parse_one()` to rewrite non-standard syntax into a form sqlglot can parse. The original SQL is preserved for `execute()` and `explain()`.
+
+Detection is automatic: `create_tools()` and `contract_middleware()` check `isinstance(adapter, SqlNormalizer)` and wire it into the `Validator` if present. Standard-dialect adapters are unaffected.
+
 **`describe_table` maps to native commands:**
 
 | Database | Command | What you get |
@@ -489,7 +500,8 @@ agentic-data-contracts/
 │   │   └── yaml_source.py       # YamlSource
 │   ├── adapters/
 │   │   ├── __init__.py
-│   │   ├── base.py              # DatabaseAdapter protocol
+│   │   ├── _normalizer.py       # SqlNormalizer protocol (avoids circular import)
+│   │   ├── base.py              # DatabaseAdapter protocol + SqlNormalizer re-export
 │   │   ├── bigquery.py          # BigQuery adapter
 │   │   ├── snowflake.py         # Snowflake adapter
 │   │   ├── postgres.py          # Postgres adapter

{agentic_data_contracts-0.4.0 → agentic_data_contracts-0.6.0}/examples/revenue_agent/contract.yml

@@ -15,7 +15,6 @@ semantic:
     - name: tenant_isolation
       description: "All queries must filter by tenant_id"
       enforcement: block
-      filter_column: tenant_id
     - name: use_semantic_revenue
       description: "Revenue calculations must use the metric definitions"
       enforcement: warn

{agentic_data_contracts-0.4.0 → agentic_data_contracts-0.6.0}/examples/revenue_agent/semantic.yml

@@ -20,3 +20,7 @@ relationships:
   - from: analytics.orders.customer_id
     to: analytics.customers.id
     type: many_to_one
+    description: >
+      Join orders to customers for region-level breakdowns.
+      Every order has exactly one customer.
+    required_filter: "status != 'cancelled'"

{agentic_data_contracts-0.4.0 → agentic_data_contracts-0.6.0}/pyproject.toml

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

{agentic_data_contracts-0.4.0 → agentic_data_contracts-0.6.0}/src/agentic_data_contracts/__init__.py

@@ -1,5 +1,6 @@
 """Agentic Data Contracts — YAML-first data contract governance for AI agents."""
 
+from agentic_data_contracts.adapters.base import SqlNormalizer
 from agentic_data_contracts.core.contract import DataContract
 from agentic_data_contracts.core.prompt import ClaudePromptRenderer, PromptRenderer
 from agentic_data_contracts.tools.factory import create_tools
@@ -10,6 +11,7 @@ __all__ = [
     "ClaudePromptRenderer",
     "DataContract",
     "PromptRenderer",
+    "SqlNormalizer",
     "contract_middleware",
     "create_sdk_mcp_server",
     "create_tools",

agentic_data_contracts-0.6.0/src/agentic_data_contracts/adapters/__init__.py

@@ -0,0 +1,15 @@
+from agentic_data_contracts.adapters.base import (
+    Column,
+    DatabaseAdapter,
+    QueryResult,
+    SqlNormalizer,
+    TableSchema,
+)
+
+__all__ = [
+    "Column",
+    "DatabaseAdapter",
+    "QueryResult",
+    "SqlNormalizer",
+    "TableSchema",
+]

agentic_data_contracts-0.6.0/src/agentic_data_contracts/adapters/_normalizer.py

@@ -0,0 +1,20 @@
+"""SqlNormalizer protocol — standalone module to avoid circular imports."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class SqlNormalizer(Protocol):
+    """Rewrite database-specific SQL into a form sqlglot can parse.
+
+    Called by the Validator before AST parsing. Adapters for non-standard
+    dialects implement this alongside DatabaseAdapter. Standard-dialect
+    adapters do not need to implement this — the Validator treats its
+    absence as a no-op.
+
+    The original (un-normalized) SQL is still passed to execute() and explain().
+    """
+
+    def normalize_sql(self, sql: str) -> str: ...

{agentic_data_contracts-0.4.0 → agentic_data_contracts-0.6.0}/src/agentic_data_contracts/adapters/base.py

@@ -41,3 +41,15 @@ class DatabaseAdapter(Protocol):
 
     @property
     def dialect(self) -> str: ...
+
+
+# Re-export SqlNormalizer so consumers can import from adapters.base
+from agentic_data_contracts.adapters._normalizer import SqlNormalizer  # noqa: E402
+
+__all__ = [
+    "Column",
+    "DatabaseAdapter",
+    "QueryResult",
+    "SqlNormalizer",
+    "TableSchema",
+]

{agentic_data_contracts-0.4.0 → agentic_data_contracts-0.6.0}/src/agentic_data_contracts/core/contract.py

@@ -25,6 +25,7 @@ class DataContract:
     def __init__(self, schema: DataContractSchema) -> None:
         self.schema = schema
         self._tables_resolved: bool = False
+        self._source_dir: Path | None = None
 
     @property
     def name(self) -> str:
@@ -32,8 +33,11 @@ class DataContract:
 
     @classmethod
     def from_yaml(cls, path: str | Path) -> DataContract:
-        text = Path(path).read_text()
-        return cls.from_yaml_string(text)
+        resolved = Path(path).resolve()
+        text = resolved.read_text()
+        contract = cls.from_yaml_string(text)
+        contract._source_dir = resolved.parent
+        return contract
 
     @classmethod
     def from_yaml_string(cls, text: str) -> DataContract:
@@ -112,6 +116,8 @@ class DataContract:
 
         source_type = source_config.type.lower()
         path = source_config.path
+        if self._source_dir is not None and not Path(path).is_absolute():
+            path = str(self._source_dir / path)
 
         loaders: dict[str, type] = {
             "yaml": YamlSource,

{agentic_data_contracts-0.4.0 → agentic_data_contracts-0.6.0}/src/agentic_data_contracts/core/prompt.py

@@ -161,11 +161,18 @@ class ClaudePromptRenderer:
 
         lines = ["<table_relationships>"]
         for r in rels:
+            desc = r.description.strip()
+            desc_attr = f' description="{desc}"' if desc else ""
+            parts = [
+                f"<from>{r.from_}</from>",
+                f"<to>{r.to}</to>",
+            ]
+            if r.required_filter:
+                filt = r.required_filter.strip()
+                parts.append(f"<required_filter>{filt}</required_filter>")
+            inner = "".join(parts)
             lines.append(
-                f'  <relationship type="{r.type}">'
-                f"<from>{r.from_}</from>"
-                f"<to>{r.to}</to>"
-                "</relationship>"
+                f'  <relationship type="{r.type}"{desc_attr}>{inner}</relationship>'
             )
         lines.append("</table_relationships>")
         return lines

{agentic_data_contracts-0.4.0 → agentic_data_contracts-0.6.0}/src/agentic_data_contracts/semantic/base.py

@@ -25,6 +25,8 @@ 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
+    description: str = ""
+    required_filter: str | None = None
 
 
 @runtime_checkable

{agentic_data_contracts-0.4.0 → agentic_data_contracts-0.6.0}/src/agentic_data_contracts/semantic/yaml_source.py

@@ -47,6 +47,8 @@ class YamlSource:
                 from_=r["from"],
                 to=r["to"],
                 type=r.get("type", "many_to_one"),
+                description=r.get("description", ""),
+                required_filter=r.get("required_filter"),
             )
             for r in raw.get("relationships", [])
         ]

{agentic_data_contracts-0.4.0 → agentic_data_contracts-0.6.0}/src/agentic_data_contracts/tools/factory.py

@@ -6,7 +6,7 @@ import json
 from dataclasses import dataclass
 from typing import Any
 
-from agentic_data_contracts.adapters.base import DatabaseAdapter
+from agentic_data_contracts.adapters.base import DatabaseAdapter, SqlNormalizer
 from agentic_data_contracts.core.contract import DataContract
 from agentic_data_contracts.core.session import ContractSession, LimitExceededError
 from agentic_data_contracts.semantic.base import SemanticSource
@@ -46,7 +46,13 @@ def create_tools(
         contract.resolve_tables(adapter)
 
     dialect = adapter.dialect if adapter else None
-    validator = Validator(contract, dialect=dialect, explain_adapter=adapter)
+    sql_normalizer = adapter if isinstance(adapter, SqlNormalizer) else None
+    validator = Validator(
+        contract,
+        dialect=dialect,
+        explain_adapter=adapter,
+        sql_normalizer=sql_normalizer,
+    )
 
     # ── Tool 1: list_schemas ──────────────────────────────────────────────────
     async def list_schemas(args: dict[str, Any]) -> dict[str, Any]:

{agentic_data_contracts-0.4.0 → agentic_data_contracts-0.6.0}/src/agentic_data_contracts/tools/middleware.py

@@ -6,7 +6,7 @@ import functools
 from collections.abc import Callable
 from typing import Any
 
-from agentic_data_contracts.adapters.base import DatabaseAdapter
+from agentic_data_contracts.adapters.base import DatabaseAdapter, SqlNormalizer
 from agentic_data_contracts.core.contract import DataContract
 from agentic_data_contracts.core.session import ContractSession, LimitExceededError
 from agentic_data_contracts.validation.validator import Validator
@@ -22,7 +22,13 @@ def contract_middleware(
         session = ContractSession(contract)
 
     dialect = adapter.dialect if adapter else None
-    validator = Validator(contract, dialect=dialect, explain_adapter=adapter)
+    sql_normalizer = adapter if isinstance(adapter, SqlNormalizer) else None
+    validator = Validator(
+        contract,
+        dialect=dialect,
+        explain_adapter=adapter,
+        sql_normalizer=sql_normalizer,
+    )
 
     def decorator(fn):
         @functools.wraps(fn)

{agentic_data_contracts-0.4.0 → agentic_data_contracts-0.6.0}/src/agentic_data_contracts/validation/validator.py

@@ -8,6 +8,7 @@ from typing import Any, Protocol, cast
 import sqlglot
 from sqlglot import exp
 
+from agentic_data_contracts.adapters._normalizer import SqlNormalizer
 from agentic_data_contracts.core.contract import DataContract
 from agentic_data_contracts.validation.checkers import (
     BlockedColumnsChecker,
@@ -53,10 +54,12 @@ class Validator:
         contract: DataContract,
         dialect: str | None = None,
         explain_adapter: ExplainAdapter | None = None,
+        sql_normalizer: SqlNormalizer | None = None,
     ) -> None:
         self.contract = contract
         self.dialect = dialect
         self.explain_adapter = explain_adapter
+        self.sql_normalizer = sql_normalizer
         self._build_checkers()
 
     def _build_checkers(self) -> None:
@@ -154,7 +157,12 @@ class Validator:
         estimated_cost_usd: float | None = None
 
         try:
-            ast = cast(exp.Expression, sqlglot.parse_one(sql, dialect=self.dialect))
+            normalized = (
+                self.sql_normalizer.normalize_sql(sql) if self.sql_normalizer else sql
+            )
+            ast = cast(
+                exp.Expression, sqlglot.parse_one(normalized, dialect=self.dialect)
+            )
         except sqlglot.errors.ParseError as e:
             return ValidationResult(blocked=True, reasons=[f"SQL parse error: {e}"])
 
@@ -229,7 +237,12 @@ class Validator:
         log_messages: list[str] = []
 
         try:
-            ast = cast(exp.Expression, sqlglot.parse_one(sql, dialect=self.dialect))
+            normalized = (
+                self.sql_normalizer.normalize_sql(sql) if self.sql_normalizer else sql
+            )
+            ast = cast(
+                exp.Expression, sqlglot.parse_one(normalized, dialect=self.dialect)
+            )
         except sqlglot.errors.ParseError:
             referenced_tables: set[str] = set()
         else:

{agentic_data_contracts-0.4.0 → agentic_data_contracts-0.6.0}/tests/fixtures/semantic_source.yml

@@ -50,3 +50,6 @@ relationships:
   - from: analytics.orders.customer_id
     to: analytics.customers.id
     type: many_to_one
+    description: >
+      Each order belongs to exactly one customer.
+      Use this join for customer-level aggregations.

agentic_data_contracts-0.6.0/tests/test_core/test_load_semantic_source.py

@@ -0,0 +1,188 @@
+"""Tests for DataContract.load_semantic_source() auto-loading."""
+
+from pathlib import Path
+
+import pytest
+
+from agentic_data_contracts.core.contract import DataContract
+from agentic_data_contracts.core.schema import (
+    DataContractSchema,
+    SemanticConfig,
+)
+from agentic_data_contracts.core.schema import (
+    SemanticSource as SemanticSourceConfig,
+)
+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_load_yaml_source(fixtures_dir: Path) -> None:
+    schema = DataContractSchema(
+        name="test",
+        semantic=SemanticConfig(
+            source=SemanticSourceConfig(
+                type="yaml",
+                path=str(fixtures_dir / "semantic_source.yml"),
+            ),
+        ),
+    )
+    dc = DataContract(schema)
+    source = dc.load_semantic_source()
+    assert isinstance(source, YamlSource)
+    assert len(source.get_metrics()) == 2
+
+
+def test_load_dbt_source(fixtures_dir: Path) -> None:
+    schema = DataContractSchema(
+        name="test",
+        semantic=SemanticConfig(
+            source=SemanticSourceConfig(
+                type="dbt",
+                path=str(fixtures_dir / "sample_dbt_manifest.json"),
+            ),
+        ),
+    )
+    dc = DataContract(schema)
+    source = dc.load_semantic_source()
+    assert isinstance(source, DbtSource)
+    assert len(source.get_metrics()) == 1
+
+
+def test_load_cube_source(fixtures_dir: Path) -> None:
+    schema = DataContractSchema(
+        name="test",
+        semantic=SemanticConfig(
+            source=SemanticSourceConfig(
+                type="cube",
+                path=str(fixtures_dir / "sample_cube_schema.yml"),
+            ),
+        ),
+    )
+    dc = DataContract(schema)
+    source = dc.load_semantic_source()
+    assert isinstance(source, CubeSource)
+    assert len(source.get_metrics()) == 1
+
+
+def test_load_no_source_returns_none() -> None:
+    schema = DataContractSchema(
+        name="test",
+        semantic=SemanticConfig(),
+    )
+    dc = DataContract(schema)
+    assert dc.load_semantic_source() is None
+
+
+def test_load_unknown_type_raises() -> None:
+    schema = DataContractSchema(
+        name="test",
+        semantic=SemanticConfig(
+            source=SemanticSourceConfig(type="unknown", path="foo.json"),
+        ),
+    )
+    dc = DataContract(schema)
+    with pytest.raises(ValueError, match="Unknown semantic source type"):
+        dc.load_semantic_source()
+
+
+def test_load_case_insensitive(fixtures_dir: Path) -> None:
+    schema = DataContractSchema(
+        name="test",
+        semantic=SemanticConfig(
+            source=SemanticSourceConfig(
+                type="YAML",
+                path=str(fixtures_dir / "semantic_source.yml"),
+            ),
+        ),
+    )
+    dc = DataContract(schema)
+    source = dc.load_semantic_source()
+    assert isinstance(source, YamlSource)
+
+
+def test_load_relative_path_resolves_from_contract_dir(
+    fixtures_dir: Path, tmp_path: Path
+) -> None:
+    """Relative paths in source.path should resolve against the contract file's dir."""
+    # Copy the semantic source into tmp_path alongside the contract
+    import shutil
+
+    shutil.copy(fixtures_dir / "semantic_source.yml", tmp_path / "semantic_source.yml")
+    contract_yaml = (
+        "name: test\n"
+        "semantic:\n"
+        "  allowed_tables:\n"
+        "    - schema: analytics\n"
+        "      tables: [orders]\n"
+        "  source:\n"
+        "    type: yaml\n"
+        "    path: ./semantic_source.yml\n"
+    )
+    (tmp_path / "contract.yml").write_text(contract_yaml)
+    dc = DataContract.from_yaml(tmp_path / "contract.yml")
+    source = dc.load_semantic_source()
+    assert isinstance(source, YamlSource)
+    assert len(source.get_metrics()) == 2
+
+
+def test_load_relative_path_from_subdirectory(
+    fixtures_dir: Path, tmp_path: Path
+) -> None:
+    """Relative path with ../ resolves from contract dir."""
+    # Put a semantic file in tmp_path
+    semantic_content = (
+        "metrics:\n  - name: m1\n    description: test\n    sql_expression: '1'\n"
+    )
+    (tmp_path / "semantic.yml").write_text(semantic_content)
+
+    # Put a contract in a subdirectory that references ../semantic.yml
+    subdir = tmp_path / "contracts"
+    subdir.mkdir()
+    contract_yaml = (
+        "name: test\n"
+        "semantic:\n"
+        "  allowed_tables:\n"
+        "    - schema: s\n"
+        "      tables: [t]\n"
+        "  source:\n"
+        "    type: yaml\n"
+        "    path: ../semantic.yml\n"
+    )
+    (subdir / "contract.yml").write_text(contract_yaml)
+    dc = DataContract.from_yaml(subdir / "contract.yml")
+    source = dc.load_semantic_source()
+    assert isinstance(source, YamlSource)
+    assert len(source.get_metrics()) == 1
+
+
+def test_load_absolute_path_unaffected_by_source_dir(
+    fixtures_dir: Path, tmp_path: Path
+) -> None:
+    """Absolute paths should work regardless of _source_dir."""
+    abs_path = str(fixtures_dir / "semantic_source.yml")
+    contract_yaml = (
+        "name: test\n"
+        "semantic:\n"
+        "  allowed_tables:\n"
+        "    - schema: analytics\n"
+        "      tables: [orders]\n"
+        "  source:\n"
+        "    type: yaml\n"
+        "    path: " + abs_path + "\n"
+    )
+    # Contract in tmp_path, but semantic source path is absolute
+    (tmp_path / "contract.yml").write_text(contract_yaml)
+    dc = DataContract.from_yaml(tmp_path / "contract.yml")
+    source = dc.load_semantic_source()
+    assert isinstance(source, YamlSource)
+    assert len(source.get_metrics()) == 2
+
+
+def test_from_yaml_string_has_no_source_dir() -> None:
+    """Contracts loaded from strings have no _source_dir (backward compat)."""
+    contract_yaml = (
+        "name: test\nsemantic:\n  allowed_tables:\n    - schema: s\n      tables: [t]\n"
+    )
+    dc = DataContract.from_yaml_string(contract_yaml)
+    assert dc._source_dir is None