agentic-data-contracts 0.2.6__tar.gz → 0.3.0__tar.gz

{agentic_data_contracts-0.2.6 → agentic_data_contracts-0.3.0}/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.3.0] - 2026-03-30
+
+### Added
+
+- **`PromptRenderer` protocol**: New `@runtime_checkable` protocol for custom system prompt formatting. Users can implement `render(contract, semantic_source) -> str` to control how contracts are presented to their model of choice.
+- **`ClaudePromptRenderer`**: Built-in XML-structured renderer optimized for Claude models (Sonnet 4.6+). Uses XML tags for structural boundaries, places constraints at the end for better instruction-following, and merges resource/temporal limits into a single section.
+- **Custom renderer support**: `to_system_prompt(renderer=MyRenderer())` delegates entirely to a user-provided renderer.
+- **Top-level exports**: `from agentic_data_contracts import PromptRenderer, ClaudePromptRenderer`
+
+### Changed
+
+- **Default system prompt format**: `to_system_prompt()` now generates XML output (was Markdown). Pass a custom renderer if you need a different format.
+- **`contract.py` simplified**: `to_system_prompt()` is now a thin delegate (~7 lines). All prompt-building logic moved to `core/prompt.py`.
+
 ## [0.2.6] - 2026-03-29
 
 ### Changed

{agentic_data_contracts-0.2.6 → agentic_data_contracts-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-data-contracts
-Version: 0.2.6
+Version: 0.3.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
@@ -294,6 +294,29 @@ relationships:
 
 The agent sees these in its system prompt and uses them to write correct JOINs instead of guessing from column names.
 
+## Custom Prompt Rendering
+
+The system prompt is generated by a `PromptRenderer`. The default `ClaudePromptRenderer` produces XML-structured output optimized for Claude models:
+
+```python
+dc = DataContract.from_yaml("contract.yml")
+print(dc.to_system_prompt())  # XML output, optimized for Claude
+```
+
+For other models (GPT-4, Gemini, Llama), implement the `PromptRenderer` protocol:
+
+```python
+from agentic_data_contracts import PromptRenderer, DataContract
+
+class MarkdownRenderer:
+    def render(self, contract, semantic_source=None):
+        tables = "\n".join(f"- {t}" for t in contract.allowed_table_names())
+        return f"## {contract.name}\n\nAllowed tables:\n{tables}"
+
+dc = DataContract.from_yaml("contract.yml")
+print(dc.to_system_prompt(renderer=MarkdownRenderer()))
+```
+
 ## Scalable Metric Discovery
 
 For large data lakes with hundreds of KPIs, group metrics by domain and let the agent discover them efficiently:
@@ -348,6 +371,33 @@ resources:
 | `agent-sdk` | `claude-agent-sdk` | Claude Agent SDK integration |
 | `agent-contracts` | `ai-agent-contracts>=0.2.0` | ai-agent-contracts bridge |
 
+## Optional: Formal Governance with ai-agent-contracts
+
+The library works standalone with lightweight enforcement. Install [`ai-agent-contracts`](https://pypi.org/project/ai-agent-contracts/) to upgrade to the formal governance framework:
+
+```bash
+pip install "agentic-data-contracts[agent-contracts]"
+```
+
+```python
+from agentic_data_contracts.bridge.compiler import compile_to_contract
+
+contract = compile_to_contract(dc)  # YAML → formal 7-tuple Contract
+```
+
+**What you get with the bridge:**
+
+| Concern | Standalone | With ai-agent-contracts |
+|---|---|---|
+| Resource tracking | Manual counters | Formal `ResourceConstraints` with auto-enforcement |
+| Rule violations | Exception + retry | `TerminationCondition` with contract state machine |
+| Success evaluation | Log-based | Weighted `SuccessCriterion` scoring, LLM judge support |
+| Contract lifecycle | None | `DRAFTED → ACTIVE → FULFILLED / VIOLATED / TERMINATED` |
+| Framework support | Claude Agent SDK | + LiteLLM, LangChain, LangGraph, Google ADK |
+| Multi-agent | Single agent | Coordination patterns (sequential, parallel, hierarchical) |
+
+**When to use it:** formal audit trails, success scoring, multi-agent coordination, or integration with non-Claude agent frameworks.
+
 ## 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.

{agentic_data_contracts-0.2.6 → agentic_data_contracts-0.3.0}/README.md

@@ -241,6 +241,29 @@ relationships:
 
 The agent sees these in its system prompt and uses them to write correct JOINs instead of guessing from column names.
 
+## Custom Prompt Rendering
+
+The system prompt is generated by a `PromptRenderer`. The default `ClaudePromptRenderer` produces XML-structured output optimized for Claude models:
+
+```python
+dc = DataContract.from_yaml("contract.yml")
+print(dc.to_system_prompt())  # XML output, optimized for Claude
+```
+
+For other models (GPT-4, Gemini, Llama), implement the `PromptRenderer` protocol:
+
+```python
+from agentic_data_contracts import PromptRenderer, DataContract
+
+class MarkdownRenderer:
+    def render(self, contract, semantic_source=None):
+        tables = "\n".join(f"- {t}" for t in contract.allowed_table_names())
+        return f"## {contract.name}\n\nAllowed tables:\n{tables}"
+
+dc = DataContract.from_yaml("contract.yml")
+print(dc.to_system_prompt(renderer=MarkdownRenderer()))
+```
+
 ## Scalable Metric Discovery
 
 For large data lakes with hundreds of KPIs, group metrics by domain and let the agent discover them efficiently:
@@ -295,6 +318,33 @@ resources:
 | `agent-sdk` | `claude-agent-sdk` | Claude Agent SDK integration |
 | `agent-contracts` | `ai-agent-contracts>=0.2.0` | ai-agent-contracts bridge |
 
+## Optional: Formal Governance with ai-agent-contracts
+
+The library works standalone with lightweight enforcement. Install [`ai-agent-contracts`](https://pypi.org/project/ai-agent-contracts/) to upgrade to the formal governance framework:
+
+```bash
+pip install "agentic-data-contracts[agent-contracts]"
+```
+
+```python
+from agentic_data_contracts.bridge.compiler import compile_to_contract
+
+contract = compile_to_contract(dc)  # YAML → formal 7-tuple Contract
+```
+
+**What you get with the bridge:**
+
+| Concern | Standalone | With ai-agent-contracts |
+|---|---|---|
+| Resource tracking | Manual counters | Formal `ResourceConstraints` with auto-enforcement |
+| Rule violations | Exception + retry | `TerminationCondition` with contract state machine |
+| Success evaluation | Log-based | Weighted `SuccessCriterion` scoring, LLM judge support |
+| Contract lifecycle | None | `DRAFTED → ACTIVE → FULFILLED / VIOLATED / TERMINATED` |
+| Framework support | Claude Agent SDK | + LiteLLM, LangChain, LangGraph, Google ADK |
+| Multi-agent | Single agent | Coordination patterns (sequential, parallel, hierarchical) |
+
+**When to use it:** formal audit trails, success scoring, multi-agent coordination, or integration with non-Claude agent frameworks.
+
 ## 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.

{agentic_data_contracts-0.2.6 → agentic_data_contracts-0.3.0}/pyproject.toml

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

{agentic_data_contracts-0.2.6 → agentic_data_contracts-0.3.0}/src/agentic_data_contracts/__init__.py

@@ -1,13 +1,16 @@
 """Agentic Data Contracts — YAML-first data contract governance for AI agents."""
 
 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
 from agentic_data_contracts.tools.middleware import contract_middleware
 from agentic_data_contracts.tools.sdk import create_sdk_mcp_server
 
 __all__ = [
+    "ClaudePromptRenderer",
     "DataContract",
-    "create_tools",
+    "PromptRenderer",
     "contract_middleware",
     "create_sdk_mcp_server",
+    "create_tools",
 ]

agentic_data_contracts-0.3.0/src/agentic_data_contracts/core/contract.py

@@ -0,0 +1,148 @@
+"""DataContract — loads YAML, provides accessors and system prompt generation."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import yaml
+
+from agentic_data_contracts.core.schema import (
+    DataContractSchema,
+    Enforcement,
+    SemanticRule,
+)
+
+if TYPE_CHECKING:
+    from agentic_data_contracts.adapters.base import DatabaseAdapter
+    from agentic_data_contracts.core.prompt import PromptRenderer
+    from agentic_data_contracts.semantic.base import SemanticSource
+
+
+class DataContract:
+    """Main entry point: load a YAML data contract and interact with it."""
+
+    def __init__(self, schema: DataContractSchema) -> None:
+        self.schema = schema
+        self._tables_resolved: bool = False
+
+    @property
+    def name(self) -> str:
+        return self.schema.name
+
+    @classmethod
+    def from_yaml(cls, path: str | Path) -> DataContract:
+        text = Path(path).read_text()
+        return cls.from_yaml_string(text)
+
+    @classmethod
+    def from_yaml_string(cls, text: str) -> DataContract:
+        raw = yaml.safe_load(text)
+        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, *, force: bool = False) -> None:
+        """Expand wildcard tables using the database adapter.
+
+        Replaces ["*"] entries with actual table names from the database.
+        Results are cached — subsequent calls are no-ops unless force=True.
+        """
+        if self._tables_resolved and not force:
+            return
+        for entry in self.schema.semantic.allowed_tables:
+            if "*" in entry.tables:
+                entry.tables = adapter.list_tables(entry.schema_)
+        self._tables_resolved = True
+
+    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
+
+    def block_rules(self) -> list[SemanticRule]:
+        return [
+            r for r in self.schema.semantic.rules if r.enforcement == Enforcement.BLOCK
+        ]
+
+    def warn_rules(self) -> list[SemanticRule]:
+        return [
+            r for r in self.schema.semantic.rules if r.enforcement == Enforcement.WARN
+        ]
+
+    def log_rules(self) -> list[SemanticRule]:
+        return [
+            r for r in self.schema.semantic.rules if r.enforcement == Enforcement.LOG
+        ]
+
+    def to_sdk_config(self) -> dict[str, object]:
+        """Generate Claude Agent SDK configuration from contract limits.
+
+        Returns a dict of SDK options derived from contract resource/temporal
+        constraints, suitable for passing to ClaudeAgentOptions.
+        """
+        config: dict[str, object] = {}
+        res = self.schema.resources
+        if res:
+            if res.token_budget is not None:
+                config["task_budget"] = res.token_budget
+            if res.max_retries is not None:
+                config["max_turns"] = res.max_retries
+        return config
+
+    def load_semantic_source(self) -> SemanticSource | None:
+        """Auto-load the semantic source from the contract's source config.
+
+        Returns None if no source is configured.
+        """
+        source_config = self.schema.semantic.source
+        if source_config is None:
+            return None
+
+        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
+
+        source_type = source_config.type.lower()
+        path = source_config.path
+
+        loaders: dict[str, type] = {
+            "yaml": YamlSource,
+            "dbt": DbtSource,
+            "cube": CubeSource,
+        }
+
+        loader_cls = loaders.get(source_type)
+        if loader_cls is None:
+            msg = (
+                f"Unknown semantic source type: '{source_type}'."
+                f" Supported: {list(loaders.keys())}"
+            )
+            raise ValueError(msg)
+
+        return loader_cls(path)
+
+    def to_system_prompt(
+        self,
+        semantic_source: SemanticSource | None = None,
+        *,
+        renderer: PromptRenderer | None = None,
+    ) -> str:
+        """Generate a formatted system prompt section for an AI agent.
+
+        Args:
+            semantic_source: Optional semantic source for metric/relationship data.
+            renderer: Optional custom prompt renderer. Defaults to ClaudePromptRenderer.
+        """
+        if renderer is None:
+            from agentic_data_contracts.core.prompt import ClaudePromptRenderer
+
+            renderer = ClaudePromptRenderer()
+        return renderer.render(self, semantic_source)

agentic_data_contracts-0.3.0/src/agentic_data_contracts/core/prompt.py

@@ -0,0 +1,249 @@
+"""PromptRenderer protocol and ClaudePromptRenderer implementation."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from agentic_data_contracts.core.contract import DataContract
+    from agentic_data_contracts.semantic.base import SemanticSource
+
+
+@runtime_checkable
+class PromptRenderer(Protocol):
+    """Renders a DataContract into a string prompt."""
+
+    def render(
+        self,
+        contract: DataContract,
+        semantic_source: SemanticSource | None = None,
+    ) -> str: ...
+
+
+class ClaudePromptRenderer:
+    """Renders a DataContract as XML-structured output for Claude agents."""
+
+    # Max metrics to list individually before switching to compact summaries.
+    METRIC_DETAIL_THRESHOLD = 20
+
+    def render(
+        self,
+        contract: DataContract,
+        semantic_source: SemanticSource | None = None,
+    ) -> str:
+        lines: list[str] = []
+
+        # Opening wrapper
+        lines.append(f'<data_contract name="{contract.name}">')
+
+        # 1. Allowed tables
+        lines.extend(self._render_allowed_tables(contract))
+
+        # 2. Available metrics or semantic_source fallback
+        metrics_lines = self._render_metrics(contract, semantic_source)
+        if metrics_lines:
+            lines.extend(metrics_lines)
+        elif contract.schema.semantic.source:
+            lines.extend(self._render_semantic_source_fallback(contract))
+
+        # 3. Table relationships
+        rel_lines = self._render_relationships(semantic_source)
+        if rel_lines:
+            lines.extend(rel_lines)
+
+        # 4. Resource limits (resources + temporal merged)
+        resource_lines = self._render_resource_limits(contract)
+        if resource_lines:
+            lines.extend(resource_lines)
+
+        # 5. Constraints (forbidden ops + rules)
+        lines.extend(self._render_constraints(contract))
+
+        # Closing wrapper
+        lines.append("</data_contract>")
+
+        return "\n".join(lines)
+
+    # ------------------------------------------------------------------
+    # Section renderers
+    # ------------------------------------------------------------------
+
+    def _render_allowed_tables(self, contract: DataContract) -> list[str]:
+        lines = ["<allowed_tables>", "Only query these tables:"]
+        for name in contract.allowed_table_names():
+            lines.append(f"- {name}")
+        lines.append("</allowed_tables>")
+        return lines
+
+    def _render_metrics(
+        self,
+        contract: DataContract,
+        semantic_source: SemanticSource | None,
+    ) -> list[str]:
+        if semantic_source is None:
+            return []
+
+        metrics = semantic_source.get_metrics()
+        if not metrics:
+            return []
+
+        lines: list[str] = ["<available_metrics>"]
+        domains = contract.schema.semantic.domains
+        compact = len(metrics) > self.METRIC_DETAIL_THRESHOLD
+
+        if compact and domains:
+            # Large metric set with domains — show counts only
+            metric_names = {m.name for m in metrics}
+            for domain, names in domains.items():
+                count = sum(1 for n in names if n in metric_names)
+                if count:
+                    lines.append(f'  <domain name="{domain}" count="{count}" />')
+            lines.append(
+                '  <hint>Use list_metrics(domain="...") to browse,'
+                ' lookup_metric("...") to get SQL definitions.</hint>'
+            )
+        elif domains:
+            # Small metric set with domains — list with descriptions
+            metric_map = {m.name: m for m in metrics}
+            for domain, names in domains.items():
+                entries = [metric_map[n] for n in names if n in metric_map]
+                if entries:
+                    lines.append(f'  <domain name="{domain}">')
+                    for m in entries:
+                        lines.append(
+                            f'    <metric name="{m.name}">{m.description}</metric>'
+                        )
+                    lines.append("  </domain>")
+            lines.append(
+                "  <hint>Use lookup_metric tool to get the SQL definition"
+                " before computing any KPI.</hint>"
+            )
+        elif compact:
+            # Large metric set without domains — just count
+            lines.append(f"  <count>{len(metrics)} metrics available.</count>")
+            lines.append(
+                "  <hint>Use list_metrics() to browse,"
+                ' lookup_metric("...") to get SQL definitions.</hint>'
+            )
+        else:
+            # Small metric set without domains — list all
+            for m in metrics:
+                lines.append(f'  <metric name="{m.name}">{m.description}</metric>')
+            lines.append(
+                "  <hint>Use lookup_metric tool to get the SQL definition"
+                " before computing any KPI.</hint>"
+            )
+
+        lines.append("</available_metrics>")
+        return lines
+
+    def _render_semantic_source_fallback(self, contract: DataContract) -> list[str]:
+        src = contract.schema.semantic.source
+        assert src is not None
+        lines = [
+            "<semantic_source>",
+            f"  <type>{src.type}</type>",
+            f"  <path>{src.path}</path>",
+            "  <hint>Consult this source for metric definitions"
+            " before computing metrics.</hint>",
+            "</semantic_source>",
+        ]
+        return lines
+
+    def _render_relationships(
+        self, semantic_source: SemanticSource | None
+    ) -> list[str]:
+        if semantic_source is None:
+            return []
+        rels = semantic_source.get_relationships()
+        if not rels:
+            return []
+
+        lines = ["<table_relationships>"]
+        for r in rels:
+            lines.append(
+                f'  <relationship type="{r.type}">'
+                f"<from>{r.from_}</from>"
+                f"<to>{r.to}</to>"
+                "</relationship>"
+            )
+        lines.append("</table_relationships>")
+        return lines
+
+    def _render_resource_limits(self, contract: DataContract) -> list[str]:
+        res = contract.schema.resources
+        temporal = contract.schema.temporal
+
+        has_resources = res is not None and any(
+            v is not None
+            for v in [
+                res.cost_limit_usd,
+                res.max_query_time_seconds,
+                res.max_retries,
+                res.max_rows_scanned,
+                res.token_budget,
+            ]
+        )
+        has_temporal = (
+            temporal is not None and temporal.max_duration_seconds is not None
+        )
+
+        if not has_resources and not has_temporal:
+            return []
+
+        lines = ["<resource_limits>"]
+        if res is not None:
+            if res.cost_limit_usd is not None:
+                lines.append(
+                    f"  <cost_limit_usd>{res.cost_limit_usd:.2f}</cost_limit_usd>"
+                )
+            if res.max_query_time_seconds is not None:
+                val = res.max_query_time_seconds
+                lines.append(
+                    f"  <max_query_time_seconds>{val}</max_query_time_seconds>"
+                )
+            if res.max_retries is not None:
+                lines.append(f"  <max_retries>{res.max_retries}</max_retries>")
+            if res.max_rows_scanned is not None:
+                lines.append(
+                    f"  <max_rows_scanned>{res.max_rows_scanned}</max_rows_scanned>"
+                )
+            if res.token_budget is not None:
+                lines.append(f"  <token_budget>{res.token_budget}</token_budget>")
+        if has_temporal:
+            assert temporal is not None
+            dur = temporal.max_duration_seconds
+            lines.append(f"  <max_duration_seconds>{dur}</max_duration_seconds>")
+        lines.append("</resource_limits>")
+        return lines
+
+    def _render_constraints(self, contract: DataContract) -> list[str]:
+        forbidden = contract.schema.semantic.forbidden_operations
+        block_rules = contract.block_rules()
+        warn_rules = contract.warn_rules()
+        if not forbidden and not block_rules and not warn_rules:
+            return []
+
+        lines = ["<constraints>"]
+
+        # Forbidden operations
+        if forbidden:
+            ops = ", ".join(forbidden)
+            lines.append(f"Forbidden operations: {ops}")
+
+        # Block rules
+        if block_rules:
+            lines.append("")
+            lines.append("Rules (violations block execution):")
+            for rule in block_rules:
+                lines.append(f"- [{rule.name}] {rule.description}")
+
+        # Warn rules
+        if warn_rules:
+            lines.append("")
+            lines.append("Rules (violations produce warnings):")
+            for rule in warn_rules:
+                lines.append(f"- [{rule.name}] {rule.description}")
+
+        lines.append("</constraints>")
+        return lines