agentic-data-contracts 0.9.1__tar.gz → 0.9.2__tar.gz

{agentic_data_contracts-0.9.1 → agentic_data_contracts-0.9.2}/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.9.2] - 2026-04-15
+
+### Fixed
+
+- **Lazy session timer**: `ContractSession` no longer starts its wall-clock timer at construction. The timer now starts on the first `check_limits()` call, so idle time before the user's first interaction does not count against `temporal.max_duration_seconds`. This fixes premature "session expired" errors in long-lived agent setups (Chainlit, Webex bots) where the session object is created well before the first user message. (#16)
+
+### Added
+
+- **`ContractSession.reset_timer()`**: New method that resets the duration timer so it restarts on the next `check_limits()` call. Useful for frameworks with their own idle-timeout mechanisms that want to restart the clock on user activity.
+
 ## [0.9.1] - 2026-04-13
 
 ### Added

{agentic_data_contracts-0.9.1 → agentic_data_contracts-0.9.2}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: agentic-data-contracts
-Version: 0.9.1
-Summary: YAML-first data contract governance for AI agents
+Version: 0.9.2
+Summary: YAML-first, domain-driven data governance for AI agents
 Project-URL: Homepage, https://github.com/flyersworder/agentic-data-contracts
 Project-URL: Repository, https://github.com/flyersworder/agentic-data-contracts
 Project-URL: Issues, https://github.com/flyersworder/agentic-data-contracts/issues
@@ -9,7 +9,7 @@ Project-URL: Documentation, https://github.com/flyersworder/agentic-data-contrac
 Author-email: Qing <qingye779@gmail.com>
 License: MIT
 License-File: LICENSE
-Keywords: ai-agents,analytics,claude,data-contracts,data-governance,dbt,llm,sql-validation
+Keywords: ai-agents,analytics,claude,data-contracts,data-governance,dbt,domain-driven,llm,semantic-layer,sql-validation
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
@@ -21,16 +21,16 @@ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.12
 Requires-Dist: pydantic>=2.0
-Requires-Dist: pyyaml>=6.0
+Requires-Dist: pyyaml>=6.0.3
 Requires-Dist: sqlglot>=23.0
 Requires-Dist: thefuzz>=0.22.1
 Provides-Extra: agent-contracts
-Requires-Dist: ai-agent-contracts>=0.2.0; extra == 'agent-contracts'
+Requires-Dist: ai-agent-contracts>=0.3.0; extra == 'agent-contracts'
 Provides-Extra: agent-sdk
-Requires-Dist: claude-agent-sdk>=0.1.52; extra == 'agent-sdk'
+Requires-Dist: claude-agent-sdk>=0.1.58; extra == 'agent-sdk'
 Provides-Extra: all
-Requires-Dist: ai-agent-contracts>=0.2.0; extra == 'all'
-Requires-Dist: claude-agent-sdk>=0.1.52; extra == 'all'
+Requires-Dist: ai-agent-contracts>=0.3.0; extra == 'all'
+Requires-Dist: claude-agent-sdk>=0.1.58; extra == 'all'
 Requires-Dist: duckdb; extra == 'all'
 Requires-Dist: google-cloud-bigquery; extra == 'all'
 Requires-Dist: psycopg2-binary; extra == 'all'
@@ -39,10 +39,10 @@ Provides-Extra: bigquery
 Requires-Dist: google-cloud-bigquery; extra == 'bigquery'
 Provides-Extra: dev
 Requires-Dist: duckdb; extra == 'dev'
-Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
-Requires-Dist: pytest-cov>=6.0; extra == 'dev'
-Requires-Dist: pytest>=8.0; extra == 'dev'
-Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1.3.0; extra == 'dev'
+Requires-Dist: pytest-cov>=7.1.0; extra == 'dev'
+Requires-Dist: pytest>=9.0.3; extra == 'dev'
+Requires-Dist: ruff>=0.15.10; extra == 'dev'
 Provides-Extra: duckdb
 Requires-Dist: duckdb; extra == 'duckdb'
 Provides-Extra: postgres
@@ -58,7 +58,7 @@ Description-Content-Type: text/markdown
 [![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**Domain-driven data governance for AI agents.**
+**YAML-first, domain-driven data governance for AI agents.**
 
 `agentic-data-contracts` takes a domain-driven approach to AI agent governance: instead of letting agents figure out your data landscape by trial and error, you teach them your business domains, metrics, and rules upfront — in YAML. The agent starts by understanding *what* a business domain means, then discovers *which* metrics to use, then builds queries that comply with your governance rules. All enforced automatically at query time via SQL validation powered by [sqlglot](https://github.com/tobymao/sqlglot).
 
@@ -68,6 +68,19 @@ Description-Content-Type: text/markdown
 
 ## How It Works
 
+The agent follows a domain-driven workflow — understanding business context before writing SQL:
+
+```
+1. Agent receives: "How is revenue trending?"
+2. lookup_domain("revenue")     → "Revenue is recognized at fulfillment, not booking"
+3. lookup_metric("total_revenue") → SUM(amount) FILTER (WHERE status = 'completed')
+4. Agent writes SQL using the metric definition
+5. validate_query(sql)          → VALID (passes all contract rules)
+6. run_query(sql)               → results returned
+```
+
+Governance rules are enforced automatically at query time:
+
 ```
 Agent: "SELECT * FROM analytics.orders"
   -> BLOCKED (no SELECT * — specify explicit columns)
@@ -77,12 +90,9 @@ Agent: "SELECT order_id, amount FROM analytics.orders"
 
 Agent: "SELECT order_id, amount FROM analytics.orders WHERE tenant_id = 'acme'"
   -> PASSED + WARN (consider using semantic revenue definition)
-
-Agent: "DELETE FROM analytics.orders WHERE id = 1"
-  -> BLOCKED (forbidden operation: DELETE)
 ```
 
-The contract defines the rules. The library enforces them — before the query ever reaches the database.
+The contract defines the domains, metrics, and rules. The library enforces them — before the query ever reaches the database.
 
 ## Installation
 
@@ -123,6 +133,13 @@ semantic:
     - schema: marketing
       tables: [campaigns]    # or list specific tables
   forbidden_operations: [DELETE, DROP, TRUNCATE, UPDATE, INSERT]
+  domains:
+    - name: revenue
+      summary: "Financial metrics from completed orders"
+      description: >
+        Revenue is recognized at fulfillment, not at booking.
+        Excludes refunds and chargebacks unless stated.
+      metrics: [total_revenue]
   rules:
     - name: tenant_isolation
       description: "All queries must filter by tenant_id"
@@ -216,7 +233,7 @@ asyncio.run(demo())
 
 | Tool | Description |
 |------|-------------|
-| `list_schemas` | List all allowed database schemas from the contract |
+| `list_schemas` | List allowed schemas with descriptions and preferred flags |
 | `list_tables` | List allowed tables, optionally filtered by schema |
 | `describe_table` | Get full column details for an allowed table |
 | `preview_table` | Preview sample rows from an allowed table |
@@ -229,6 +246,57 @@ asyncio.run(demo())
 | `run_query` | Validate and execute a SQL query, returning results |
 | `get_contract_info` | Get the full contract: rules, limits, domains, and session status |
 
+## Domain-Driven Agent Workflow
+
+The core design principle: **agents should understand the business domain before writing SQL.** Instead of dumping table schemas and hoping for the best, the contract teaches the agent your business vocabulary through progressive disclosure:
+
+```
+1. Domain context     →  "What does 'revenue' mean here?"
+2. Metric definitions →  "How is 'total_revenue' calculated?"
+3. Query execution    →  "Run the validated SQL"
+```
+
+### Defining domains
+
+Each domain carries a description that teaches the agent your business rules — things the SQL alone can't express:
+
+```yaml
+semantic:
+  domains:
+    - name: acquisition
+      summary: "Customer acquisition costs and conversion metrics"
+      description: >
+        Acquisition metrics track the cost and efficiency of
+        acquiring new customers across all channels.
+        CAC is calculated using fully-loaded cost, not just ad spend.
+      metrics: [CAC, CPA, CPL, click_through_rate]
+    - name: retention
+      summary: "Customer retention, churn, and lifetime value"
+      description: >
+        Retention metrics measure how well we keep customers.
+        Churn is measured on a 30-day rolling window.
+        A customer is "active" if they had at least one qualifying
+        action in the window.
+      metrics: [churn_rate, LTV, retention_30d]
+```
+
+### How the agent uses domains
+
+The system prompt gives the agent a compact domain index. When a user asks a domain-specific question, the agent explores progressively:
+
+```
+lookup_domain("acquisition")        → business context + metric descriptions
+lookup_metric("CAC")                → SQL expression, source table, filters
+lookup_metric("acquisition cost")   → fuzzy match, returns [CAC, CPA] as candidates
+list_metrics(domain="retention")    → all metrics in the retention domain
+```
+
+This means the agent knows that "revenue is recognized at fulfillment, not at booking" *before* it writes a single line of SQL — reducing hallucinated metrics and incorrect calculations.
+
+### Why progressive disclosure works
+
+This pattern — compact index in the prompt, detailed context on demand — is the same philosophy validated by agent skill systems, MCP tool servers, and RAG architectures. Instead of overloading the agent's context window with everything upfront, you give it just enough to know *where to look*, then let it pull details when needed. The result is better token efficiency, more focused reasoning, and fewer hallucinations from context overload.
+
 ## Contract Rules
 
 Rules are enforced at three levels:
@@ -397,53 +465,6 @@ dc = DataContract.from_yaml("contract.yml")
 print(dc.to_system_prompt(renderer=MarkdownRenderer()))
 ```
 
-## Domain-Driven Agent Workflow
-
-The core design principle: **agents should understand the business domain before writing SQL.** Instead of dumping table schemas and hoping for the best, the contract teaches the agent your business vocabulary through progressive disclosure:
-
-```
-1. Domain context     →  "What does 'revenue' mean here?"
-2. Metric definitions →  "How is 'total_revenue' calculated?"
-3. Query execution    →  "Run the validated SQL"
-```
-
-### Defining domains
-
-Each domain carries a description that teaches the agent your business rules — things the SQL alone can't express:
-
-```yaml
-semantic:
-  domains:
-    - name: acquisition
-      summary: "Customer acquisition costs and conversion metrics"
-      description: >
-        Acquisition metrics track the cost and efficiency of
-        acquiring new customers across all channels.
-        CAC is calculated using fully-loaded cost, not just ad spend.
-      metrics: [CAC, CPA, CPL, click_through_rate]
-    - name: retention
-      summary: "Customer retention, churn, and lifetime value"
-      description: >
-        Retention metrics measure how well we keep customers.
-        Churn is measured on a 30-day rolling window.
-        A customer is "active" if they had at least one qualifying
-        action in the window.
-      metrics: [churn_rate, LTV, retention_30d]
-```
-
-### How the agent uses domains
-
-The system prompt gives the agent a compact domain index. When a user asks a domain-specific question, the agent explores progressively:
-
-```
-lookup_domain("acquisition")        → business context + metric descriptions
-lookup_metric("CAC")                → SQL expression, source table, filters
-lookup_metric("acquisition cost")   → fuzzy match, returns [CAC, CPA] as candidates
-list_metrics(domain="retention")    → all metrics in the retention domain
-```
-
-This means the agent knows that "revenue is recognized at fulfillment, not at booking" *before* it writes a single line of SQL — reducing hallucinated metrics and incorrect calculations.
-
 ## Scaling to Large Organizations
 
 Tested for 200+ tables, 300+ metrics, 50+ relationships across multiple schemas.

{agentic_data_contracts-0.9.1 → agentic_data_contracts-0.9.2}/README.md

@@ -5,7 +5,7 @@
 [![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**Domain-driven data governance for AI agents.**
+**YAML-first, domain-driven data governance for AI agents.**
 
 `agentic-data-contracts` takes a domain-driven approach to AI agent governance: instead of letting agents figure out your data landscape by trial and error, you teach them your business domains, metrics, and rules upfront — in YAML. The agent starts by understanding *what* a business domain means, then discovers *which* metrics to use, then builds queries that comply with your governance rules. All enforced automatically at query time via SQL validation powered by [sqlglot](https://github.com/tobymao/sqlglot).
 
@@ -15,6 +15,19 @@
 
 ## How It Works
 
+The agent follows a domain-driven workflow — understanding business context before writing SQL:
+
+```
+1. Agent receives: "How is revenue trending?"
+2. lookup_domain("revenue")     → "Revenue is recognized at fulfillment, not booking"
+3. lookup_metric("total_revenue") → SUM(amount) FILTER (WHERE status = 'completed')
+4. Agent writes SQL using the metric definition
+5. validate_query(sql)          → VALID (passes all contract rules)
+6. run_query(sql)               → results returned
+```
+
+Governance rules are enforced automatically at query time:
+
 ```
 Agent: "SELECT * FROM analytics.orders"
   -> BLOCKED (no SELECT * — specify explicit columns)
@@ -24,12 +37,9 @@ Agent: "SELECT order_id, amount FROM analytics.orders"
 
 Agent: "SELECT order_id, amount FROM analytics.orders WHERE tenant_id = 'acme'"
   -> PASSED + WARN (consider using semantic revenue definition)
-
-Agent: "DELETE FROM analytics.orders WHERE id = 1"
-  -> BLOCKED (forbidden operation: DELETE)
 ```
 
-The contract defines the rules. The library enforces them — before the query ever reaches the database.
+The contract defines the domains, metrics, and rules. The library enforces them — before the query ever reaches the database.
 
 ## Installation
 
@@ -70,6 +80,13 @@ semantic:
     - schema: marketing
       tables: [campaigns]    # or list specific tables
   forbidden_operations: [DELETE, DROP, TRUNCATE, UPDATE, INSERT]
+  domains:
+    - name: revenue
+      summary: "Financial metrics from completed orders"
+      description: >
+        Revenue is recognized at fulfillment, not at booking.
+        Excludes refunds and chargebacks unless stated.
+      metrics: [total_revenue]
   rules:
     - name: tenant_isolation
       description: "All queries must filter by tenant_id"
@@ -163,7 +180,7 @@ asyncio.run(demo())
 
 | Tool | Description |
 |------|-------------|
-| `list_schemas` | List all allowed database schemas from the contract |
+| `list_schemas` | List allowed schemas with descriptions and preferred flags |
 | `list_tables` | List allowed tables, optionally filtered by schema |
 | `describe_table` | Get full column details for an allowed table |
 | `preview_table` | Preview sample rows from an allowed table |
@@ -176,6 +193,57 @@ asyncio.run(demo())
 | `run_query` | Validate and execute a SQL query, returning results |
 | `get_contract_info` | Get the full contract: rules, limits, domains, and session status |
 
+## Domain-Driven Agent Workflow
+
+The core design principle: **agents should understand the business domain before writing SQL.** Instead of dumping table schemas and hoping for the best, the contract teaches the agent your business vocabulary through progressive disclosure:
+
+```
+1. Domain context     →  "What does 'revenue' mean here?"
+2. Metric definitions →  "How is 'total_revenue' calculated?"
+3. Query execution    →  "Run the validated SQL"
+```
+
+### Defining domains
+
+Each domain carries a description that teaches the agent your business rules — things the SQL alone can't express:
+
+```yaml
+semantic:
+  domains:
+    - name: acquisition
+      summary: "Customer acquisition costs and conversion metrics"
+      description: >
+        Acquisition metrics track the cost and efficiency of
+        acquiring new customers across all channels.
+        CAC is calculated using fully-loaded cost, not just ad spend.
+      metrics: [CAC, CPA, CPL, click_through_rate]
+    - name: retention
+      summary: "Customer retention, churn, and lifetime value"
+      description: >
+        Retention metrics measure how well we keep customers.
+        Churn is measured on a 30-day rolling window.
+        A customer is "active" if they had at least one qualifying
+        action in the window.
+      metrics: [churn_rate, LTV, retention_30d]
+```
+
+### How the agent uses domains
+
+The system prompt gives the agent a compact domain index. When a user asks a domain-specific question, the agent explores progressively:
+
+```
+lookup_domain("acquisition")        → business context + metric descriptions
+lookup_metric("CAC")                → SQL expression, source table, filters
+lookup_metric("acquisition cost")   → fuzzy match, returns [CAC, CPA] as candidates
+list_metrics(domain="retention")    → all metrics in the retention domain
+```
+
+This means the agent knows that "revenue is recognized at fulfillment, not at booking" *before* it writes a single line of SQL — reducing hallucinated metrics and incorrect calculations.
+
+### Why progressive disclosure works
+
+This pattern — compact index in the prompt, detailed context on demand — is the same philosophy validated by agent skill systems, MCP tool servers, and RAG architectures. Instead of overloading the agent's context window with everything upfront, you give it just enough to know *where to look*, then let it pull details when needed. The result is better token efficiency, more focused reasoning, and fewer hallucinations from context overload.
+
 ## Contract Rules
 
 Rules are enforced at three levels:
@@ -344,53 +412,6 @@ dc = DataContract.from_yaml("contract.yml")
 print(dc.to_system_prompt(renderer=MarkdownRenderer()))
 ```
 
-## Domain-Driven Agent Workflow
-
-The core design principle: **agents should understand the business domain before writing SQL.** Instead of dumping table schemas and hoping for the best, the contract teaches the agent your business vocabulary through progressive disclosure:
-
-```
-1. Domain context     →  "What does 'revenue' mean here?"
-2. Metric definitions →  "How is 'total_revenue' calculated?"
-3. Query execution    →  "Run the validated SQL"
-```
-
-### Defining domains
-
-Each domain carries a description that teaches the agent your business rules — things the SQL alone can't express:
-
-```yaml
-semantic:
-  domains:
-    - name: acquisition
-      summary: "Customer acquisition costs and conversion metrics"
-      description: >
-        Acquisition metrics track the cost and efficiency of
-        acquiring new customers across all channels.
-        CAC is calculated using fully-loaded cost, not just ad spend.
-      metrics: [CAC, CPA, CPL, click_through_rate]
-    - name: retention
-      summary: "Customer retention, churn, and lifetime value"
-      description: >
-        Retention metrics measure how well we keep customers.
-        Churn is measured on a 30-day rolling window.
-        A customer is "active" if they had at least one qualifying
-        action in the window.
-      metrics: [churn_rate, LTV, retention_30d]
-```
-
-### How the agent uses domains
-
-The system prompt gives the agent a compact domain index. When a user asks a domain-specific question, the agent explores progressively:
-
-```
-lookup_domain("acquisition")        → business context + metric descriptions
-lookup_metric("CAC")                → SQL expression, source table, filters
-lookup_metric("acquisition cost")   → fuzzy match, returns [CAC, CPA] as candidates
-list_metrics(domain="retention")    → all metrics in the retention domain
-```
-
-This means the agent knows that "revenue is recognized at fulfillment, not at booking" *before* it writes a single line of SQL — reducing hallucinated metrics and incorrect calculations.
-
 ## Scaling to Large Organizations
 
 Tested for 200+ tables, 300+ metrics, 50+ relationships across multiple schemas.

{agentic_data_contracts-0.9.1 → agentic_data_contracts-0.9.2}/docs/architecture.md

@@ -1,7 +1,7 @@
 # Agentic Data Contracts — Architecture
 
 **Date:** 2026-04-13
-**Status:** Implemented (v0.9.1)
+**Status:** Implemented (v0.9.2)
 **Author:** Qing Ye + Claude
 
 ## Problem Statement
@@ -188,7 +188,7 @@ When `ai-agent-contracts` is NOT installed, `ContractSession` provides self-cont
 
 - **Retry count** — incremented on each failed query attempt, checked against `max_retries`
 - **Token usage** — tracked via callback, checked against `token_budget`
-- **Wall-clock duration** — start time recorded, checked against `max_duration_seconds`
+- **Wall-clock duration** — lazy start on first `check_limits()` call (not at construction), checked against `max_duration_seconds`. Can be reset via `reset_timer()` for frameworks that manage their own idle timeouts.
 - **Cost estimate** — if EXPLAIN adapter returns cost info, checked against `cost_limit_usd`
 
 These are simple counters/timers with guard checks before each tool call. No formal state machine.

{agentic_data_contracts-0.9.1 → agentic_data_contracts-0.9.2}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "agentic-data-contracts"
-version = "0.9.1"
-description = "YAML-first data contract governance for AI agents"
+version = "0.9.2"
+description = "YAML-first, domain-driven data governance for AI agents"
 readme = "README.md"
 requires-python = ">=3.12"
 authors = [{ name = "Qing", email = "qingye779@gmail.com" }]
@@ -10,9 +10,11 @@ keywords = [
     "ai-agents",
     "data-contracts",
     "data-governance",
+    "domain-driven",
     "sql-validation",
     "llm",
     "claude",
+    "semantic-layer",
     "analytics",
     "dbt",
 ]
@@ -30,7 +32,7 @@ classifiers = [
 dependencies = [
     "sqlglot>=23.0",
     "pydantic>=2.0",
-    "pyyaml>=6.0",
+    "pyyaml>=6.0.3",
     "thefuzz>=0.22.1",
 ]
 
@@ -41,17 +43,17 @@ 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>=0.1.52"]
-agent-contracts = ["ai-agent-contracts>=0.2.0"]
+agent-sdk = ["claude-agent-sdk>=0.1.58"]
+agent-contracts = ["ai-agent-contracts>=0.3.0"]
 bigquery = ["google-cloud-bigquery"]
 snowflake = ["snowflake-connector-python"]
 postgres = ["psycopg2-binary"]
 duckdb = ["duckdb"]
 dev = [
-    "pytest>=8.0",
-    "pytest-asyncio>=0.23",
-    "pytest-cov>=6.0",
-    "ruff>=0.8.0",
+    "pytest>=9.0.3",
+    "pytest-asyncio>=1.3.0",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.15.10",
     "duckdb",
 ]
 all = [

{agentic_data_contracts-0.9.1 → agentic_data_contracts-0.9.2}/src/agentic_data_contracts/core/session.py

@@ -20,12 +20,23 @@ class ContractSession:
         self.retries: int = 0
         self.tokens_used: int = 0
         self.cost_usd: float = 0.0
-        self._start_time: float = time.monotonic()
+        self._start_time: float | None = None
+
+    def _ensure_timer(self) -> None:
+        """Start the timer if not already running."""
+        if self._start_time is None:
+            self._start_time = time.monotonic()
 
     @property
     def elapsed_seconds(self) -> float:
+        if self._start_time is None:
+            return 0.0
         return time.monotonic() - self._start_time
 
+    def reset_timer(self) -> None:
+        """Reset the timer so it restarts on the next check_limits() call."""
+        self._start_time = None
+
     def record_retry(self) -> None:
         self.retries += 1
 
@@ -36,6 +47,7 @@ class ContractSession:
         self.cost_usd += amount
 
     def check_limits(self) -> None:
+        self._ensure_timer()
         res = self.contract.schema.resources
         if res is None:
             return

{agentic_data_contracts-0.9.1 → agentic_data_contracts-0.9.2}/tests/test_core/test_session.py

@@ -60,6 +60,7 @@ def test_session_blocks_on_cost_limit(fixtures_dir: Path) -> None:
 def test_session_elapsed_seconds(fixtures_dir: Path) -> None:
     dc = DataContract.from_yaml(fixtures_dir / "valid_contract.yml")
     session = ContractSession(dc)
+    session.check_limits()  # starts the timer
     assert session.elapsed_seconds >= 0.0
 
 
@@ -85,3 +86,61 @@ def test_session_remaining_budget(fixtures_dir: Path) -> None:
     assert info["retries_remaining"] == 2
     assert info["tokens_remaining"] == 40000
     assert info["cost_remaining_usd"] == pytest.approx(3.50)
+
+
+# --- Lazy timer tests (issue #16) ---
+
+
+def test_timer_not_started_at_construction(fixtures_dir: Path) -> None:
+    """Timer should not start at construction — elapsed should be 0."""
+    dc = DataContract.from_yaml(fixtures_dir / "valid_contract.yml")
+    session = ContractSession(dc)
+    assert session.elapsed_seconds == 0.0
+
+
+def test_timer_starts_on_first_check_limits(fixtures_dir: Path) -> None:
+    """Timer should start lazily on the first check_limits() call."""
+    dc = DataContract.from_yaml(fixtures_dir / "valid_contract.yml")
+    session = ContractSession(dc)
+    assert session._start_time is None
+    session.check_limits()
+    assert session._start_time is not None
+    assert session.elapsed_seconds >= 0.0
+
+
+def test_reset_timer(fixtures_dir: Path) -> None:
+    """reset_timer() should clear the timer so elapsed returns 0."""
+    dc = DataContract.from_yaml(fixtures_dir / "valid_contract.yml")
+    session = ContractSession(dc)
+    session.check_limits()  # starts timer
+    session.reset_timer()
+    assert session.elapsed_seconds == 0.0
+    assert session._start_time is None
+
+
+def test_reset_timer_restarts_on_next_check(fixtures_dir: Path) -> None:
+    """After reset, timer should restart on the next check_limits() call."""
+    dc = DataContract.from_yaml(fixtures_dir / "valid_contract.yml")
+    session = ContractSession(dc)
+    session.check_limits()  # starts timer
+    session.reset_timer()
+    session.check_limits()  # restarts timer
+    assert session._start_time is not None
+
+
+def test_reset_timer_before_started_is_noop(fixtures_dir: Path) -> None:
+    """reset_timer() on an unstarted timer should be a safe no-op."""
+    dc = DataContract.from_yaml(fixtures_dir / "valid_contract.yml")
+    session = ContractSession(dc)
+    session.reset_timer()  # should not raise
+    assert session._start_time is None
+    assert session.elapsed_seconds == 0.0
+
+
+def test_remaining_before_timer_started(fixtures_dir: Path) -> None:
+    """remaining() should show full duration budget when timer not started."""
+    dc = DataContract.from_yaml(fixtures_dir / "valid_contract.yml")
+    session = ContractSession(dc)
+    info = session.remaining()
+    assert "seconds_remaining" in info
+    assert info["seconds_remaining"] == 300.0

{agentic_data_contracts-0.9.1 → agentic_data_contracts-0.9.2}/uv.lock

@@ -8,12 +8,12 @@ resolution-markers = [
 ]
 
 [options]
-exclude-newer = "2026-04-10T18:45:17.227262Z"
+exclude-newer = "2026-04-12T16:17:12.933746Z"
 exclude-newer-span = "P3D"
 
 [[package]]
 name = "agentic-data-contracts"
-version = "0.9.1"
+version = "0.9.2"
 source = { editable = "." }
 dependencies = [
     { name = "pydantic" },
@@ -60,18 +60,18 @@ snowflake = [
 [package.metadata]
 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'", specifier = ">=0.1.52" },
+    { name = "ai-agent-contracts", marker = "extra == 'agent-contracts'", specifier = ">=0.3.0" },
+    { name = "claude-agent-sdk", marker = "extra == 'agent-sdk'", specifier = ">=0.1.58" },
     { name = "duckdb", marker = "extra == 'dev'" },
     { name = "duckdb", marker = "extra == 'duckdb'" },
     { name = "google-cloud-bigquery", marker = "extra == 'bigquery'" },
     { name = "psycopg2-binary", marker = "extra == 'postgres'" },
     { name = "pydantic", specifier = ">=2.0" },
-    { name = "pytest", marker = "extra == 'dev'", specifier = ">=8.0" },
-    { name = "pytest-asyncio", marker = "extra == 'dev'", specifier = ">=0.23" },
-    { name = "pytest-cov", marker = "extra == 'dev'", specifier = ">=6.0" },
-    { name = "pyyaml", specifier = ">=6.0" },
-    { name = "ruff", marker = "extra == 'dev'", specifier = ">=0.8.0" },
+    { name = "pytest", marker = "extra == 'dev'", specifier = ">=9.0.3" },
+    { name = "pytest-asyncio", marker = "extra == 'dev'", specifier = ">=1.3.0" },
+    { name = "pytest-cov", marker = "extra == 'dev'", specifier = ">=7.1.0" },
+    { name = "pyyaml", specifier = ">=6.0.3" },
+    { name = "ruff", marker = "extra == 'dev'", specifier = ">=0.15.10" },
     { name = "snowflake-connector-python", marker = "extra == 'snowflake'" },
     { name = "sqlglot", specifier = ">=23.0" },
     { name = "thefuzz", specifier = ">=0.22.1" },
@@ -2202,27 +2202,27 @@ wheels = [
 
 [[package]]
 name = "ruff"
-version = "0.15.9"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/e6/97/e9f1ca355108ef7194e38c812ef40ba98c7208f47b13ad78d023caa583da/ruff-0.15.9.tar.gz", hash = "sha256:29cbb1255a9797903f6dde5ba0188c707907ff44a9006eb273b5a17bfa0739a2", size = 4617361, upload-time = "2026-04-02T18:17:20.829Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/0b/1f/9cdfd0ac4b9d1e5a6cf09bedabdf0b56306ab5e333c85c87281273e7b041/ruff-0.15.9-py3-none-linux_armv6l.whl", hash = "sha256:6efbe303983441c51975c243e26dff328aca11f94b70992f35b093c2e71801e1", size = 10511206, upload-time = "2026-04-02T18:16:41.574Z" },
-    { url = "https://files.pythonhosted.org/packages/3d/f6/32bfe3e9c136b35f02e489778d94384118bb80fd92c6d92e7ccd97db12ce/ruff-0.15.9-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:4965bac6ac9ea86772f4e23587746f0b7a395eccabb823eb8bfacc3fa06069f7", size = 10923307, upload-time = "2026-04-02T18:17:08.645Z" },
-    { url = "https://files.pythonhosted.org/packages/ca/25/de55f52ab5535d12e7aaba1de37a84be6179fb20bddcbe71ec091b4a3243/ruff-0.15.9-py3-none-macosx_11_0_arm64.whl", hash = "sha256:eaf05aad70ca5b5a0a4b0e080df3a6b699803916d88f006efd1f5b46302daab8", size = 10316722, upload-time = "2026-04-02T18:16:44.206Z" },
-    { url = "https://files.pythonhosted.org/packages/48/11/690d75f3fd6278fe55fff7c9eb429c92d207e14b25d1cae4064a32677029/ruff-0.15.9-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:9439a342adb8725f32f92732e2bafb6d5246bd7a5021101166b223d312e8fc59", size = 10623674, upload-time = "2026-04-02T18:16:50.951Z" },
-    { url = "https://files.pythonhosted.org/packages/bd/ec/176f6987be248fc5404199255522f57af1b4a5a1b57727e942479fec98ad/ruff-0.15.9-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:9c5e6faf9d97c8edc43877c3f406f47446fc48c40e1442d58cfcdaba2acea745", size = 10351516, upload-time = "2026-04-02T18:16:57.206Z" },
-    { url = "https://files.pythonhosted.org/packages/b2/fc/51cffbd2b3f240accc380171d51446a32aa2ea43a40d4a45ada67368fbd2/ruff-0.15.9-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:7b34a9766aeec27a222373d0b055722900fbc0582b24f39661aa96f3fe6ad901", size = 11150202, upload-time = "2026-04-02T18:17:06.452Z" },
-    { url = "https://files.pythonhosted.org/packages/d6/d4/25292a6dfc125f6b6528fe6af31f5e996e19bf73ca8e3ce6eb7fa5b95885/ruff-0.15.9-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:89dd695bc72ae76ff484ae54b7e8b0f6b50f49046e198355e44ea656e521fef9", size = 11988891, upload-time = "2026-04-02T18:17:18.575Z" },
-    { url = "https://files.pythonhosted.org/packages/13/e1/1eebcb885c10e19f969dcb93d8413dfee8172578709d7ee933640f5e7147/ruff-0.15.9-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:ce187224ef1de1bd225bc9a152ac7102a6171107f026e81f317e4257052916d5", size = 11480576, upload-time = "2026-04-02T18:16:52.986Z" },
-    { url = "https://files.pythonhosted.org/packages/ff/6b/a1548ac378a78332a4c3dcf4a134c2475a36d2a22ddfa272acd574140b50/ruff-0.15.9-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:2b0c7c341f68adb01c488c3b7d4b49aa8ea97409eae6462d860a79cf55f431b6", size = 11254525, upload-time = "2026-04-02T18:17:02.041Z" },
-    { url = "https://files.pythonhosted.org/packages/42/aa/4bb3af8e61acd9b1281db2ab77e8b2c3c5e5599bf2a29d4a942f1c62b8d6/ruff-0.15.9-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:55cc15eee27dc0eebdfcb0d185a6153420efbedc15eb1d38fe5e685657b0f840", size = 11204072, upload-time = "2026-04-02T18:17:13.581Z" },
-    { url = "https://files.pythonhosted.org/packages/69/48/d550dc2aa6e423ea0bcc1d0ff0699325ffe8a811e2dba156bd80750b86dc/ruff-0.15.9-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:a6537f6eed5cda688c81073d46ffdfb962a5f29ecb6f7e770b2dc920598997ed", size = 10594998, upload-time = "2026-04-02T18:16:46.369Z" },
-    { url = "https://files.pythonhosted.org/packages/63/47/321167e17f5344ed5ec6b0aa2cff64efef5f9e985af8f5622cfa6536043f/ruff-0.15.9-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:6d3fcbca7388b066139c523bda744c822258ebdcfbba7d24410c3f454cc9af71", size = 10359769, upload-time = "2026-04-02T18:17:10.994Z" },
-    { url = "https://files.pythonhosted.org/packages/67/5e/074f00b9785d1d2c6f8c22a21e023d0c2c1817838cfca4c8243200a1fa87/ruff-0.15.9-py3-none-musllinux_1_2_i686.whl", hash = "sha256:058d8e99e1bfe79d8a0def0b481c56059ee6716214f7e425d8e737e412d69677", size = 10850236, upload-time = "2026-04-02T18:16:48.749Z" },
-    { url = "https://files.pythonhosted.org/packages/76/37/804c4135a2a2caf042925d30d5f68181bdbd4461fd0d7739da28305df593/ruff-0.15.9-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:8e1ddb11dbd61d5983fa2d7d6370ef3eb210951e443cace19594c01c72abab4c", size = 11358343, upload-time = "2026-04-02T18:16:55.068Z" },
-    { url = "https://files.pythonhosted.org/packages/88/3d/1364fcde8656962782aa9ea93c92d98682b1ecec2f184e625a965ad3b4a6/ruff-0.15.9-py3-none-win32.whl", hash = "sha256:bde6ff36eaf72b700f32b7196088970bf8fdb2b917b7accd8c371bfc0fd573ec", size = 10583382, upload-time = "2026-04-02T18:17:04.261Z" },
-    { url = "https://files.pythonhosted.org/packages/4c/56/5c7084299bd2cacaa07ae63a91c6f4ba66edc08bf28f356b24f6b717c799/ruff-0.15.9-py3-none-win_amd64.whl", hash = "sha256:45a70921b80e1c10cf0b734ef09421f71b5aa11d27404edc89d7e8a69505e43d", size = 11744969, upload-time = "2026-04-02T18:16:59.611Z" },
-    { url = "https://files.pythonhosted.org/packages/03/36/76704c4f312257d6dbaae3c959add2a622f63fcca9d864659ce6d8d97d3d/ruff-0.15.9-py3-none-win_arm64.whl", hash = "sha256:0694e601c028fd97dc5c6ee244675bc241aeefced7ef80cd9c6935a871078f53", size = 11005870, upload-time = "2026-04-02T18:17:15.773Z" },
+version = "0.15.10"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/e7/d9/aa3f7d59a10ef6b14fe3431706f854dbf03c5976be614a9796d36326810c/ruff-0.15.10.tar.gz", hash = "sha256:d1f86e67ebfdef88e00faefa1552b5e510e1d35f3be7d423dc7e84e63788c94e", size = 4631728, upload-time = "2026-04-09T14:06:09.884Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/eb/00/a1c2fdc9939b2c03691edbda290afcd297f1f389196172826b03d6b6a595/ruff-0.15.10-py3-none-linux_armv6l.whl", hash = "sha256:0744e31482f8f7d0d10a11fcbf897af272fefdfcb10f5af907b18c2813ff4d5f", size = 10563362, upload-time = "2026-04-09T14:06:21.189Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/15/006990029aea0bebe9d33c73c3e28c80c391ebdba408d1b08496f00d422d/ruff-0.15.10-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:b1e7c16ea0ff5a53b7c2df52d947e685973049be1cdfe2b59a9c43601897b22e", size = 10951122, upload-time = "2026-04-09T14:06:02.236Z" },
+    { url = "https://files.pythonhosted.org/packages/f2/c0/4ac978fe874d0618c7da647862afe697b281c2806f13ce904ad652fa87e4/ruff-0.15.10-py3-none-macosx_11_0_arm64.whl", hash = "sha256:93cc06a19e5155b4441dd72808fdf84290d84ad8a39ca3b0f994363ade4cebb1", size = 10314005, upload-time = "2026-04-09T14:06:00.026Z" },
+    { url = "https://files.pythonhosted.org/packages/da/73/c209138a5c98c0d321266372fc4e33ad43d506d7e5dd817dd89b60a8548f/ruff-0.15.10-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:83e1dd04312997c99ea6965df66a14fb4f03ba978564574ffc68b0d61fd3989e", size = 10643450, upload-time = "2026-04-09T14:05:42.137Z" },
+    { url = "https://files.pythonhosted.org/packages/ec/76/0deec355d8ec10709653635b1f90856735302cb8e149acfdf6f82a5feb70/ruff-0.15.10-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:8154d43684e4333360fedd11aaa40b1b08a4e37d8ffa9d95fee6fa5b37b6fab1", size = 10379597, upload-time = "2026-04-09T14:05:49.984Z" },
+    { url = "https://files.pythonhosted.org/packages/dc/be/86bba8fc8798c081e28a4b3bb6d143ccad3fd5f6f024f02002b8f08a9fa3/ruff-0.15.10-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:8ab88715f3a6deb6bde6c227f3a123410bec7b855c3ae331b4c006189e895cef", size = 11146645, upload-time = "2026-04-09T14:06:12.246Z" },
+    { url = "https://files.pythonhosted.org/packages/a8/89/140025e65911b281c57be1d385ba1d932c2366ca88ae6663685aed8d4881/ruff-0.15.10-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:a768ff5969b4f44c349d48edf4ab4f91eddb27fd9d77799598e130fb628aa158", size = 12030289, upload-time = "2026-04-09T14:06:04.776Z" },
+    { url = "https://files.pythonhosted.org/packages/88/de/ddacca9545a5e01332567db01d44bd8cf725f2db3b3d61a80550b48308ea/ruff-0.15.10-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:0ee3ef42dab7078bda5ff6a1bcba8539e9857deb447132ad5566a038674540d0", size = 11496266, upload-time = "2026-04-09T14:05:55.485Z" },
+    { url = "https://files.pythonhosted.org/packages/bc/bb/7ddb00a83760ff4a83c4e2fc231fd63937cc7317c10c82f583302e0f6586/ruff-0.15.10-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:51cb8cc943e891ba99989dd92d61e29b1d231e14811db9be6440ecf25d5c1609", size = 11256418, upload-time = "2026-04-09T14:05:57.69Z" },
+    { url = "https://files.pythonhosted.org/packages/dc/8d/55de0d35aacf6cd50b6ee91ee0f291672080021896543776f4170fc5c454/ruff-0.15.10-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:e59c9bdc056a320fb9ea1700a8d591718b8faf78af065484e801258d3a76bc3f", size = 11288416, upload-time = "2026-04-09T14:05:44.695Z" },
+    { url = "https://files.pythonhosted.org/packages/68/cf/9438b1a27426ec46a80e0a718093c7f958ef72f43eb3111862949ead3cc1/ruff-0.15.10-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:136c00ca2f47b0018b073f28cb5c1506642a830ea941a60354b0e8bc8076b151", size = 10621053, upload-time = "2026-04-09T14:05:52.782Z" },
+    { url = "https://files.pythonhosted.org/packages/4c/50/e29be6e2c135e9cd4cb15fbade49d6a2717e009dff3766dd080fcb82e251/ruff-0.15.10-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:8b80a2f3c9c8a950d6237f2ca12b206bccff626139be9fa005f14feb881a1ae8", size = 10378302, upload-time = "2026-04-09T14:06:14.361Z" },
+    { url = "https://files.pythonhosted.org/packages/18/2f/e0b36a6f99c51bb89f3a30239bc7bf97e87a37ae80aa2d6542d6e5150364/ruff-0.15.10-py3-none-musllinux_1_2_i686.whl", hash = "sha256:e3e53c588164dc025b671c9df2462429d60357ea91af7e92e9d56c565a9f1b07", size = 10850074, upload-time = "2026-04-09T14:06:16.581Z" },
+    { url = "https://files.pythonhosted.org/packages/11/08/874da392558ce087a0f9b709dc6ec0d60cbc694c1c772dab8d5f31efe8cb/ruff-0.15.10-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:b0c52744cf9f143a393e284125d2576140b68264a93c6716464e129a3e9adb48", size = 11358051, upload-time = "2026-04-09T14:06:18.948Z" },
+    { url = "https://files.pythonhosted.org/packages/e4/46/602938f030adfa043e67112b73821024dc79f3ab4df5474c25fa4c1d2d14/ruff-0.15.10-py3-none-win32.whl", hash = "sha256:d4272e87e801e9a27a2e8df7b21011c909d9ddd82f4f3281d269b6ba19789ca5", size = 10588964, upload-time = "2026-04-09T14:06:07.14Z" },
+    { url = "https://files.pythonhosted.org/packages/25/b6/261225b875d7a13b33a6d02508c39c28450b2041bb01d0f7f1a83d569512/ruff-0.15.10-py3-none-win_amd64.whl", hash = "sha256:28cb32d53203242d403d819fd6983152489b12e4a3ae44993543d6fe62ab42ed", size = 11745044, upload-time = "2026-04-09T14:05:39.473Z" },
+    { url = "https://files.pythonhosted.org/packages/58/ed/dea90a65b7d9e69888890fb14c90d7f51bf0c1e82ad800aeb0160e4bacfd/ruff-0.15.10-py3-none-win_arm64.whl", hash = "sha256:601d1610a9e1f1c2165a4f561eeaa2e2ea1e97f3287c5aa258d3dab8b57c6188", size = 11035607, upload-time = "2026-04-09T14:05:47.593Z" },
 ]
 
 [[package]]