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

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

@@ -2,6 +2,23 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.2.3] - 2026-03-29
+
+### Added
+
+- **SDK MCP server convenience method**: `create_sdk_mcp_server(contract, adapter=...)` wraps all 10 tools with the SDK's `@tool` decorator and bundles them into a ready-to-use MCP server for `ClaudeAgentOptions.mcp_servers`
+- **Top-level export**: `from agentic_data_contracts import create_sdk_mcp_server`
+
+### Changed
+
+- **SDK dependency**: Bumped `claude-agent-sdk` minimum to `>=0.1.52`
+
+## [0.2.2] - 2026-03-28
+
+### Added
+
+- **SDK config generation**: `DataContract.to_sdk_config()` maps contract limits to Claude Agent SDK options (`token_budget` → `task_budget`, `max_retries` → `max_turns`)
+
 ## [0.2.1] - 2026-03-28
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-data-contracts
-Version: 0.2.1
+Version: 0.2.3
 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
@@ -27,10 +27,10 @@ Requires-Dist: thefuzz>=0.22.1
 Provides-Extra: agent-contracts
 Requires-Dist: ai-agent-contracts>=0.2.0; extra == 'agent-contracts'
 Provides-Extra: agent-sdk
-Requires-Dist: claude-agent-sdk; extra == 'agent-sdk'
+Requires-Dist: claude-agent-sdk>=0.1.52; extra == 'agent-sdk'
 Provides-Extra: all
 Requires-Dist: ai-agent-contracts>=0.2.0; extra == 'all'
-Requires-Dist: claude-agent-sdk; extra == 'all'
+Requires-Dist: claude-agent-sdk>=0.1.52; extra == 'all'
 Requires-Dist: duckdb; extra == 'all'
 Requires-Dist: google-cloud-bigquery; extra == 'all'
 Requires-Dist: psycopg2-binary; extra == 'all'
@@ -150,25 +150,26 @@ adapter = DuckDBAdapter("analytics.duckdb")
 tools = create_tools(dc, adapter=adapter)
 ```
 
-### 3. Use with the Claude Agent SDK
+### 3. Use with the Claude Agent SDK (requires `claude-agent-sdk>=0.1.52`)
 
 ```python
 import asyncio
+from agentic_data_contracts import create_sdk_mcp_server
 from claude_agent_sdk import (
     ClaudeAgentOptions,
     AssistantMessage,
     TextBlock,
-    create_sdk_mcp_server,
     query,
 )
 
-server = create_sdk_mcp_server(name="data-contracts", version="1.0.0", tools=tools)
+# One-liner: wraps all 10 tools and bundles into an SDK MCP server
+server = create_sdk_mcp_server(dc, adapter=adapter)
 
 options = ClaudeAgentOptions(
     model="claude-sonnet-4-6",
     system_prompt=f"You are a revenue analytics assistant.\n\n{dc.to_system_prompt()}",
     mcp_servers={"dc": server},
-    allowed_tools=[f"mcp__dc__{t.name}" for t in tools],
+    **dc.to_sdk_config(),  # token_budget → task_budget, max_retries → max_turns
 )
 
 async def run(prompt: str) -> None:

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

@@ -97,25 +97,26 @@ adapter = DuckDBAdapter("analytics.duckdb")
 tools = create_tools(dc, adapter=adapter)
 ```
 
-### 3. Use with the Claude Agent SDK
+### 3. Use with the Claude Agent SDK (requires `claude-agent-sdk>=0.1.52`)
 
 ```python
 import asyncio
+from agentic_data_contracts import create_sdk_mcp_server
 from claude_agent_sdk import (
     ClaudeAgentOptions,
     AssistantMessage,
     TextBlock,
-    create_sdk_mcp_server,
     query,
 )
 
-server = create_sdk_mcp_server(name="data-contracts", version="1.0.0", tools=tools)
+# One-liner: wraps all 10 tools and bundles into an SDK MCP server
+server = create_sdk_mcp_server(dc, adapter=adapter)
 
 options = ClaudeAgentOptions(
     model="claude-sonnet-4-6",
     system_prompt=f"You are a revenue analytics assistant.\n\n{dc.to_system_prompt()}",
     mcp_servers={"dc": server},
-    allowed_tools=[f"mcp__dc__{t.name}" for t in tools],
+    **dc.to_sdk_config(),  # token_budget → task_budget, max_retries → max_turns
 )
 
 async def run(prompt: str) -> None:

{agentic_data_contracts-0.2.1 → agentic_data_contracts-0.2.3}/docs/architecture.md

@@ -1,7 +1,7 @@
 # Agentic Data Contracts — Architecture
 
 **Date:** 2026-03-28
-**Status:** Implemented (v0.2.1)
+**Status:** Implemented (v0.2.2)
 **Author:** Qing Ye + Claude
 
 ## Problem Statement

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

@@ -1,6 +1,6 @@
 [project]
 name = "agentic-data-contracts"
-version = "0.2.1"
+version = "0.2.3"
 description = "YAML-first data contract governance for AI agents"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -41,7 +41,7 @@ Issues = "https://github.com/flyersworder/agentic-data-contracts/issues"
 Documentation = "https://github.com/flyersworder/agentic-data-contracts/blob/main/docs/architecture.md"
 
 [project.optional-dependencies]
-agent-sdk = ["claude-agent-sdk"]
+agent-sdk = ["claude-agent-sdk>=0.1.52"]
 agent-contracts = ["ai-agent-contracts>=0.2.0"]
 bigquery = ["google-cloud-bigquery"]
 snowflake = ["snowflake-connector-python"]

{agentic_data_contracts-0.2.1 → agentic_data_contracts-0.2.3}/src/agentic_data_contracts/__init__.py

@@ -3,5 +3,11 @@
 from agentic_data_contracts.core.contract import DataContract
 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__ = ["DataContract", "create_tools", "contract_middleware"]
+__all__ = [
+    "DataContract",
+    "create_tools",
+    "contract_middleware",
+    "create_sdk_mcp_server",
+]

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

@@ -60,6 +60,21 @@ class DataContract:
             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.
 

agentic_data_contracts-0.2.3/src/agentic_data_contracts/tools/sdk.py

@@ -0,0 +1,71 @@
+"""Claude Agent SDK integration — wraps ToolDefs into an SDK MCP server."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from agentic_data_contracts.adapters.base import DatabaseAdapter
+from agentic_data_contracts.core.contract import DataContract
+from agentic_data_contracts.core.session import ContractSession
+from agentic_data_contracts.semantic.base import SemanticSource
+from agentic_data_contracts.tools.factory import ToolDef, create_tools
+
+
+def create_sdk_mcp_server(
+    contract: DataContract,
+    *,
+    adapter: DatabaseAdapter | None = None,
+    semantic_source: SemanticSource | None = None,
+    session: ContractSession | None = None,
+    tools: list[ToolDef] | None = None,
+    server_name: str = "data-contracts",
+    server_version: str = "1.0.0",
+) -> Any:
+    """Create a Claude Agent SDK MCP server from a DataContract.
+
+    Wraps all 10 contract tools with the SDK's @tool decorator and
+    bundles them into an MCP server ready for ClaudeAgentOptions.mcp_servers.
+
+    Args:
+        contract: The data contract to enforce.
+        adapter: Optional database adapter for query execution.
+        semantic_source: Optional semantic source (auto-loaded if not given).
+        session: Optional session for tracking enforcement state.
+        tools: Pre-built ToolDefs (if None, created via create_tools).
+        server_name: Name for the MCP server.
+        server_version: Version for the MCP server.
+
+    Returns:
+        McpSdkServerConfig ready for ClaudeAgentOptions.mcp_servers.
+
+    Raises:
+        ImportError: If claude-agent-sdk is not installed.
+    """
+    try:
+        from claude_agent_sdk import create_sdk_mcp_server as _create_server
+        from claude_agent_sdk import tool as sdk_tool
+    except ImportError:
+        msg = (
+            "claude-agent-sdk is required for SDK integration. "
+            "Install with: pip install agentic-data-contracts[agent-sdk]"
+        )
+        raise ImportError(msg) from None
+
+    if tools is None:
+        tools = create_tools(
+            contract,
+            adapter=adapter,
+            semantic_source=semantic_source,
+            session=session,
+        )
+
+    sdk_tools = []
+    for t in tools:
+        decorated = sdk_tool(t.name, t.description, t.input_schema)(t.callable)
+        sdk_tools.append(decorated)
+
+    return _create_server(
+        name=server_name,
+        version=server_version,
+        tools=sdk_tools,
+    )

agentic_data_contracts-0.2.3/tests/test_core/test_sdk_config.py

@@ -0,0 +1,36 @@
+"""Tests for DataContract.to_sdk_config()."""
+
+from pathlib import Path
+
+from agentic_data_contracts.core.contract import DataContract
+from agentic_data_contracts.core.schema import (
+    DataContractSchema,
+    ResourceConfig,
+    SemanticConfig,
+)
+
+
+def test_sdk_config_from_full_contract(fixtures_dir: Path) -> None:
+    dc = DataContract.from_yaml(fixtures_dir / "valid_contract.yml")
+    config = dc.to_sdk_config()
+    assert config["task_budget"] == 50000
+    assert config["max_turns"] == 3
+
+
+def test_sdk_config_no_resources() -> None:
+    schema = DataContractSchema(name="test", semantic=SemanticConfig())
+    dc = DataContract(schema)
+    config = dc.to_sdk_config()
+    assert config == {}
+
+
+def test_sdk_config_partial_resources() -> None:
+    schema = DataContractSchema(
+        name="test",
+        semantic=SemanticConfig(),
+        resources=ResourceConfig(token_budget=10000),
+    )
+    dc = DataContract(schema)
+    config = dc.to_sdk_config()
+    assert config["task_budget"] == 10000
+    assert "max_turns" not in config

agentic_data_contracts-0.2.3/tests/test_tools/test_sdk.py

@@ -0,0 +1,116 @@
+"""Tests for Claude Agent SDK MCP server integration."""
+
+from pathlib import Path
+
+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
+from agentic_data_contracts.tools.sdk import create_sdk_mcp_server
+
+
+@pytest.fixture
+def contract_no_source() -> DataContract:
+    """Contract without a semantic source — avoids file path issues."""
+    schema = DataContractSchema(
+        name="test",
+        semantic=SemanticConfig(
+            allowed_tables=[
+                AllowedTable.model_validate(
+                    {"schema": "analytics", "tables": ["orders"]}
+                ),
+            ],
+        ),
+    )
+    return DataContract(schema)
+
+
+@pytest.fixture
+def contract_with_source(fixtures_dir: Path) -> DataContract:
+    """Contract with semantic source pointing to real fixture."""
+    from agentic_data_contracts.core.schema import (
+        SemanticSource as SemanticSourceConfig,
+    )
+
+    schema = DataContractSchema(
+        name="test",
+        semantic=SemanticConfig(
+            source=SemanticSourceConfig(
+                type="yaml",
+                path=str(fixtures_dir / "semantic_source.yml"),
+            ),
+            allowed_tables=[
+                AllowedTable.model_validate(
+                    {"schema": "analytics", "tables": ["orders"]}
+                ),
+            ],
+        ),
+    )
+    return DataContract(schema)
+
+
+@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(10,2), tenant_id VARCHAR
+        );
+        INSERT INTO analytics.orders VALUES (1, 100.00, 'acme');
+        """
+    )
+    return db
+
+
+def test_create_sdk_mcp_server_returns_config(
+    contract_no_source: DataContract, adapter: DuckDBAdapter
+) -> None:
+    server = create_sdk_mcp_server(contract_no_source, adapter=adapter)
+    assert server is not None
+
+
+def test_create_sdk_mcp_server_with_prebuilt_tools(
+    contract_no_source: DataContract, adapter: DuckDBAdapter
+) -> None:
+    tools = create_tools(contract_no_source, adapter=adapter)
+    server = create_sdk_mcp_server(contract_no_source, tools=tools)
+    assert server is not None
+
+
+def test_create_sdk_mcp_server_with_semantic_source(
+    contract_with_source: DataContract, adapter: DuckDBAdapter
+) -> None:
+    server = create_sdk_mcp_server(contract_with_source, adapter=adapter)
+    assert server is not None
+
+
+def test_create_sdk_mcp_server_auto_creates_tools(
+    contract_no_source: DataContract,
+) -> None:
+    server = create_sdk_mcp_server(contract_no_source)
+    assert server is not None
+
+
+def test_create_sdk_mcp_server_custom_name(
+    contract_no_source: DataContract,
+) -> None:
+    server = create_sdk_mcp_server(
+        contract_no_source,
+        server_name="my-server",
+        server_version="2.0.0",
+    )
+    assert server is not None
+
+
+def test_top_level_import() -> None:
+    from agentic_data_contracts import create_sdk_mcp_server as fn
+
+    assert fn is not None

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

@@ -9,7 +9,7 @@ resolution-markers = [
 
 [[package]]
 name = "agentic-data-contracts"
-version = "0.2.0"
+version = "0.2.3"
 source = { editable = "." }
 dependencies = [
     { name = "pydantic" },
@@ -57,7 +57,7 @@ snowflake = [
 requires-dist = [
     { name = "agentic-data-contracts", extras = ["agent-sdk", "agent-contracts", "bigquery", "snowflake", "postgres", "duckdb"], marker = "extra == 'all'" },
     { name = "ai-agent-contracts", marker = "extra == 'agent-contracts'", specifier = ">=0.2.0" },
-    { name = "claude-agent-sdk", marker = "extra == 'agent-sdk'" },
+    { name = "claude-agent-sdk", marker = "extra == 'agent-sdk'", specifier = ">=0.1.52" },
     { name = "duckdb", marker = "extra == 'dev'" },
     { name = "duckdb", marker = "extra == 'duckdb'" },
     { name = "google-cloud-bigquery", marker = "extra == 'bigquery'" },
@@ -412,19 +412,19 @@ wheels = [
 
 [[package]]
 name = "claude-agent-sdk"
-version = "0.1.50"
+version = "0.1.52"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "anyio" },
     { name = "mcp" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/24/eb/42a7027a02d3827c6e49f97375a00e6da4708f81295d9afa1a0009ce4abd/claude_agent_sdk-0.1.50.tar.gz", hash = "sha256:e15157792857ecb55274a71f08981efcfda2e169bee7894cbdc245d05ac43203", size = 99070, upload-time = "2026-03-20T23:00:58.646Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/b1/d7/a56b7ba793918e5cc557447b25f2d428e11d6f025b6c0c7b1e6e3fa373c0/claude_agent_sdk-0.1.52.tar.gz", hash = "sha256:c27f35d850521c7cff18448b38ff0dd5e899a4aeb6de9d28c0b2a66863eaf134", size = 116267, upload-time = "2026-03-29T02:40:25.554Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/b2/97/66bc98d5026dbed68b7469a4990de71d8c40d19713e37dafacf32ba3be3b/claude_agent_sdk-0.1.50-py3-none-macosx_11_0_arm64.whl", hash = "sha256:858b1822451209b2c3ad8df27458168d29ac19fd628680853f7707ea017fea73", size = 58223299, upload-time = "2026-03-20T23:01:01.742Z" },
-    { url = "https://files.pythonhosted.org/packages/35/0d/65dda40016faa30a63a950d48b400ad26913e8e333e418651faf04d20673/claude_agent_sdk-0.1.50-py3-none-macosx_11_0_x86_64.whl", hash = "sha256:44e75b9d076bd6030742729f99eb38777b80f052b22338d0a028d8190fc59e52", size = 61019645, upload-time = "2026-03-20T23:01:04.742Z" },
-    { url = "https://files.pythonhosted.org/packages/ec/c0/e5c7c6b9e378553fe24bb5367caede725e274a494b6d126e719971c53b8b/claude_agent_sdk-0.1.50-py3-none-manylinux_2_17_aarch64.whl", hash = "sha256:7363d431dc6efd83fa658a045e14fa4357440352b548002bfb9096d8f04d143c", size = 74590847, upload-time = "2026-03-20T23:01:07.899Z" },
-    { url = "https://files.pythonhosted.org/packages/3d/af/658a28cb070e0b59ac98e88411536f6f9b8d81e8ddde9a8340106b0b8b0f/claude_agent_sdk-0.1.50-py3-none-manylinux_2_17_x86_64.whl", hash = "sha256:493d8cc43f4166291606749cf47b03e822f03b7f371cc77af697564017ccf579", size = 75231505, upload-time = "2026-03-20T23:01:11.45Z" },
-    { url = "https://files.pythonhosted.org/packages/41/44/ff1f2c137406392fa0a69e3c3ff37150267da664decddb6dee83b80ba162/claude_agent_sdk-0.1.50-py3-none-win_amd64.whl", hash = "sha256:2e44caf3e5bce56e26a18158acf3e1c2c2784cf8fa15e425afe92816c987eb1a", size = 75846174, upload-time = "2026-03-20T23:01:15.277Z" },
+    { url = "https://files.pythonhosted.org/packages/31/e0/6759f98c699ef5da84750b93de543a839f3e3b905b5ce20424a5033c58fa/claude_agent_sdk-0.1.52-py3-none-macosx_11_0_arm64.whl", hash = "sha256:0f15c91319c20831f881fd4b6bcec1772a3599d66da5e7c057d79945bf603e1a", size = 57872944, upload-time = "2026-03-29T02:40:28.742Z" },
+    { url = "https://files.pythonhosted.org/packages/cd/e8/d3c3ef7cb104d3ebb6348a82eab7574b8c0eaddb683efd3f606f3c22bc21/claude_agent_sdk-0.1.52-py3-none-macosx_11_0_x86_64.whl", hash = "sha256:f32ca2ca95e312678af63ee60a5fb1b765f98ed47825ea3ba90322ceb26736ff", size = 59615855, upload-time = "2026-03-29T02:40:31.765Z" },
+    { url = "https://files.pythonhosted.org/packages/f0/b7/2c4def1c5c67b9bad8966b8839d6d9da812a6458050650dbaba3526d3824/claude_agent_sdk-0.1.52-py3-none-manylinux_2_17_aarch64.whl", hash = "sha256:97c238fda13f0bea057e546895a3dc67468fc1acdbbc00d0b53a46cb3ba588dc", size = 71217617, upload-time = "2026-03-29T02:40:35.127Z" },
+    { url = "https://files.pythonhosted.org/packages/44/9e/4be542b58610bd74056dfed37dbdc5a12224a2fbde41a333ddbcd8255a8a/claude_agent_sdk-0.1.52-py3-none-manylinux_2_17_x86_64.whl", hash = "sha256:4cd3f2e6fd5b272b16114fbc8dcd4348cbe8615dcc1b3bea251a7d489bf83a5d", size = 71292911, upload-time = "2026-03-29T02:40:38.919Z" },
+    { url = "https://files.pythonhosted.org/packages/93/73/4601d43d57354bd6e664444970bd5c1de8003542745a4388cf84611c9f26/claude_agent_sdk-0.1.52-py3-none-win_amd64.whl", hash = "sha256:a8a5455d248b76c17126abee0f69d0f9870cbc0d52cb2f8ad5eb3deddb05af39", size = 73447753, upload-time = "2026-03-29T02:40:42.786Z" },
 ]
 
 [[package]]