agentlattice 0.3.0__tar.gz

agentlattice-0.3.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+*.egg

agentlattice-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AgentLattice
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentlattice-0.3.0/PKG-INFO

@@ -0,0 +1,221 @@
+Metadata-Version: 2.4
+Name: agentlattice
+Version: 0.3.0
+Summary: Governance SDK for AI agents — audit trails, policy engine, approval gates.
+Project-URL: Homepage, https://agentlattice.com
+Project-URL: Repository, https://github.com/inder/agentlattice
+Project-URL: Documentation, https://agentlattice.com/docs
+License: MIT
+License-File: LICENSE
+Keywords: agents,ai,approval,audit,governance
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.25.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# agentlattice — Python SDK
+
+Governance-aware SDK for AI agents. Wraps agent actions with audit trails,
+approval gates, and circuit breaker integration.
+
+## Install
+
+```bash
+pip install agentlattice
+```
+
+## Quickstart
+
+```python
+import asyncio
+import os
+from agentlattice import AgentLattice
+
+al = AgentLattice(api_key=os.environ["AL_API_KEY"])
+
+async def main():
+    # gate() blocks until approved — your agent code only runs if it passes
+    await al.gate("pr.merge")
+    await merge_pr(42)
+
+asyncio.run(main())
+```
+
+Handle denials and timeouts:
+
+```python
+from agentlattice import AgentLattice, AgentLatticeDeniedError, AgentLatticeTimeoutError
+
+al = AgentLattice(api_key=os.environ["AL_API_KEY"])
+
+async def main():
+    try:
+        await al.gate("code.commit")
+    except AgentLatticeDeniedError as e:
+        print(f"Denied: {e.reason}, policy: {e.policy}")
+        print(f"Failed conditions: {e.conditions}")
+    except AgentLatticeTimeoutError as e:
+        print(f"Approval timed out: {e.approval_id}")
+
+asyncio.run(main())
+```
+
+## Sync usage
+
+If you're not in an async context:
+
+```python
+import os
+from agentlattice import AgentLattice
+
+al = AgentLattice(api_key=os.environ["AL_API_KEY"])
+al.gate_sync("code.commit")
+```
+
+## API
+
+### `AgentLattice(api_key, *, base_url?, gate_poll_timeout_ms?, gate_poll_interval_ms?)`
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `api_key` | required | Bearer token — pass via `os.environ["AL_API_KEY"]`, never hardcoded |
+| `base_url` | `https://agentlattice.com` | Override for self-hosted or staging |
+| `gate_poll_timeout_ms` | `8 * 60 * 60 * 1000` (8 hours) | How long `gate()` polls for approval |
+| `gate_poll_interval_ms` | `5000` | Poll interval in ms |
+
+### `await al.execute(action_type, options?)`
+
+Submit an action and return immediately. Returns an `ActionResult`. Does not block.
+
+```python
+from agentlattice import AgentLattice, ActionOptions
+
+al = AgentLattice(api_key="al_...")
+result = await al.execute("pr.open", ActionOptions(
+    data_accessed=[{"type": "source_code", "count": 5, "sensitivity": "low"}],
+    metadata={"pr_number": 42},
+    event_id="my-idempotency-key",   # optional: dedup by your own key
+))
+
+if result.status == "executed":
+    print(f"Auto-executed under policy: {result.policy_name}")
+elif result.status == "requested":
+    print(f"Awaiting approval: {result.approval_id}")
+elif result.status == "denied":
+    print(f"Denied ({result.denial_reason}): {result.conditions_evaluated}")
+```
+
+### `await al.gate(action_type, options?)`
+
+Submit an action and block until it is approved or denied.
+
+```python
+try:
+    await al.gate("pr.merge")
+except AgentLatticeDeniedError as e:
+    # e.reason:     "CONDITIONS_DENIED" | "POLICY_TAMPERED" | "DENIED_BY_REVIEWER"
+    # e.policy:     name of the governing policy (if conditions-based)
+    # e.conditions: list of ConditionResult (which rule failed and why)
+    # e.approval_id: set if a human reviewer denied it
+    ...
+except AgentLatticeTimeoutError as e:
+    # e.approval_id: the approval that timed out
+    ...
+```
+
+### `al.gate_sync(action_type, options?)` / `al.execute_sync(action_type, options?)`
+
+Synchronous wrappers — identical semantics, no `asyncio.run()` needed.
+
+## ActionResult
+
+```python
+@dataclass
+class ActionResult:
+    status: str                          # "executed" | "requested" | "denied" | ...
+    audit_event_id: str
+    approval_id: str | None              # set when status="requested"
+    message: str | None
+    timeout_at: str | None
+    denial_reason: str | None            # "CONDITIONS_DENIED" | "POLICY_TAMPERED" | ...
+    policy_name: str | None              # governing policy name
+    conditions_evaluated: list[ConditionResult]  # which rules passed/failed
+```
+
+## ConditionResult
+
+```python
+@dataclass
+class ConditionResult:
+    field: str       # e.g. "pr_size"
+    operator: str    # e.g. "lt"
+    expected: Any    # e.g. 100
+    result: bool     # True = passed, False = failed
+```
+
+Agents can read `conditions_evaluated` to understand exactly which governance
+rule blocked them and adapt their behavior accordingly.
+
+## Self-correcting agent pattern
+
+`conditions_evaluated` is what makes this more than a compliance layer — it
+closes the feedback loop so agents can adapt, not just fail.
+
+```python
+from agentlattice import AgentLattice, AgentLatticeDeniedError, ActionOptions
+
+al = AgentLattice(api_key=os.environ["AL_API_KEY"])
+
+async def commit_with_governance(files: list[str]) -> None:
+    try:
+        await al.gate("pr.open", ActionOptions(
+            metadata={"pr_size": len(files), "repo": "acme/backend"},
+        ))
+        await open_pr(files)
+
+    except AgentLatticeDeniedError as e:
+        if e.reason == "CONDITIONS_DENIED":
+            # Find which rules failed and why
+            failed = [c for c in e.conditions if not c.result]
+            # e.g. [ConditionResult(field="pr_size", operator="lt", expected=50, result=False)]
+
+            for rule in failed:
+                if rule.field == "pr_size":
+                    # Policy says PRs must be < 50 files — split and retry
+                    mid = len(files) // 2
+                    await commit_with_governance(files[:mid])
+                    await commit_with_governance(files[mid:])
+                    return
+
+        # Reviewer denial or policy tamper — no retry
+        raise
+```
+
+## Error hierarchy
+
+```
+AgentLatticeError          base — code, message, details
+  AgentLatticeDeniedError  approval_id?, reason?, policy?, conditions?
+  AgentLatticeTimeoutError approval_id
+```
+
+## Reliability
+
+`execute()` and `gate()` retry automatically on 5xx and network errors — up to 3 attempts with 1s/2s/4s exponential backoff. Each request has a 30-second timeout. Pass `event_id` to make retries idempotent.
+
+`execute_sync()` and `gate_sync()` are safe in async runtimes (LangGraph, FastAPI, CrewAI) — they detect a running event loop and dispatch to a thread pool automatically.
+
+## License
+
+MIT

agentlattice-0.3.0/README.md

@@ -0,0 +1,195 @@
+# agentlattice — Python SDK
+
+Governance-aware SDK for AI agents. Wraps agent actions with audit trails,
+approval gates, and circuit breaker integration.
+
+## Install
+
+```bash
+pip install agentlattice
+```
+
+## Quickstart
+
+```python
+import asyncio
+import os
+from agentlattice import AgentLattice
+
+al = AgentLattice(api_key=os.environ["AL_API_KEY"])
+
+async def main():
+    # gate() blocks until approved — your agent code only runs if it passes
+    await al.gate("pr.merge")
+    await merge_pr(42)
+
+asyncio.run(main())
+```
+
+Handle denials and timeouts:
+
+```python
+from agentlattice import AgentLattice, AgentLatticeDeniedError, AgentLatticeTimeoutError
+
+al = AgentLattice(api_key=os.environ["AL_API_KEY"])
+
+async def main():
+    try:
+        await al.gate("code.commit")
+    except AgentLatticeDeniedError as e:
+        print(f"Denied: {e.reason}, policy: {e.policy}")
+        print(f"Failed conditions: {e.conditions}")
+    except AgentLatticeTimeoutError as e:
+        print(f"Approval timed out: {e.approval_id}")
+
+asyncio.run(main())
+```
+
+## Sync usage
+
+If you're not in an async context:
+
+```python
+import os
+from agentlattice import AgentLattice
+
+al = AgentLattice(api_key=os.environ["AL_API_KEY"])
+al.gate_sync("code.commit")
+```
+
+## API
+
+### `AgentLattice(api_key, *, base_url?, gate_poll_timeout_ms?, gate_poll_interval_ms?)`
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `api_key` | required | Bearer token — pass via `os.environ["AL_API_KEY"]`, never hardcoded |
+| `base_url` | `https://agentlattice.com` | Override for self-hosted or staging |
+| `gate_poll_timeout_ms` | `8 * 60 * 60 * 1000` (8 hours) | How long `gate()` polls for approval |
+| `gate_poll_interval_ms` | `5000` | Poll interval in ms |
+
+### `await al.execute(action_type, options?)`
+
+Submit an action and return immediately. Returns an `ActionResult`. Does not block.
+
+```python
+from agentlattice import AgentLattice, ActionOptions
+
+al = AgentLattice(api_key="al_...")
+result = await al.execute("pr.open", ActionOptions(
+    data_accessed=[{"type": "source_code", "count": 5, "sensitivity": "low"}],
+    metadata={"pr_number": 42},
+    event_id="my-idempotency-key",   # optional: dedup by your own key
+))
+
+if result.status == "executed":
+    print(f"Auto-executed under policy: {result.policy_name}")
+elif result.status == "requested":
+    print(f"Awaiting approval: {result.approval_id}")
+elif result.status == "denied":
+    print(f"Denied ({result.denial_reason}): {result.conditions_evaluated}")
+```
+
+### `await al.gate(action_type, options?)`
+
+Submit an action and block until it is approved or denied.
+
+```python
+try:
+    await al.gate("pr.merge")
+except AgentLatticeDeniedError as e:
+    # e.reason:     "CONDITIONS_DENIED" | "POLICY_TAMPERED" | "DENIED_BY_REVIEWER"
+    # e.policy:     name of the governing policy (if conditions-based)
+    # e.conditions: list of ConditionResult (which rule failed and why)
+    # e.approval_id: set if a human reviewer denied it
+    ...
+except AgentLatticeTimeoutError as e:
+    # e.approval_id: the approval that timed out
+    ...
+```
+
+### `al.gate_sync(action_type, options?)` / `al.execute_sync(action_type, options?)`
+
+Synchronous wrappers — identical semantics, no `asyncio.run()` needed.
+
+## ActionResult
+
+```python
+@dataclass
+class ActionResult:
+    status: str                          # "executed" | "requested" | "denied" | ...
+    audit_event_id: str
+    approval_id: str | None              # set when status="requested"
+    message: str | None
+    timeout_at: str | None
+    denial_reason: str | None            # "CONDITIONS_DENIED" | "POLICY_TAMPERED" | ...
+    policy_name: str | None              # governing policy name
+    conditions_evaluated: list[ConditionResult]  # which rules passed/failed
+```
+
+## ConditionResult
+
+```python
+@dataclass
+class ConditionResult:
+    field: str       # e.g. "pr_size"
+    operator: str    # e.g. "lt"
+    expected: Any    # e.g. 100
+    result: bool     # True = passed, False = failed
+```
+
+Agents can read `conditions_evaluated` to understand exactly which governance
+rule blocked them and adapt their behavior accordingly.
+
+## Self-correcting agent pattern
+
+`conditions_evaluated` is what makes this more than a compliance layer — it
+closes the feedback loop so agents can adapt, not just fail.
+
+```python
+from agentlattice import AgentLattice, AgentLatticeDeniedError, ActionOptions
+
+al = AgentLattice(api_key=os.environ["AL_API_KEY"])
+
+async def commit_with_governance(files: list[str]) -> None:
+    try:
+        await al.gate("pr.open", ActionOptions(
+            metadata={"pr_size": len(files), "repo": "acme/backend"},
+        ))
+        await open_pr(files)
+
+    except AgentLatticeDeniedError as e:
+        if e.reason == "CONDITIONS_DENIED":
+            # Find which rules failed and why
+            failed = [c for c in e.conditions if not c.result]
+            # e.g. [ConditionResult(field="pr_size", operator="lt", expected=50, result=False)]
+
+            for rule in failed:
+                if rule.field == "pr_size":
+                    # Policy says PRs must be < 50 files — split and retry
+                    mid = len(files) // 2
+                    await commit_with_governance(files[:mid])
+                    await commit_with_governance(files[mid:])
+                    return
+
+        # Reviewer denial or policy tamper — no retry
+        raise
+```
+
+## Error hierarchy
+
+```
+AgentLatticeError          base — code, message, details
+  AgentLatticeDeniedError  approval_id?, reason?, policy?, conditions?
+  AgentLatticeTimeoutError approval_id
+```
+
+## Reliability
+
+`execute()` and `gate()` retry automatically on 5xx and network errors — up to 3 attempts with 1s/2s/4s exponential backoff. Each request has a 30-second timeout. Pass `event_id` to make retries idempotent.
+
+`execute_sync()` and `gate_sync()` are safe in async runtimes (LangGraph, FastAPI, CrewAI) — they detect a running event loop and dispatch to a thread pool automatically.
+
+## License
+
+MIT

agentlattice-0.3.0/agentlattice/__init__.py

@@ -0,0 +1,50 @@
+"""
+agentlattice — Governance SDK for AI agents.
+
+Usage:
+    import asyncio
+    from agentlattice import AgentLattice, AgentLatticeDeniedError
+
+    al = AgentLattice(api_key="al_...")
+
+    # gate() blocks until approved (or raises if denied/timeout)
+    async def main():
+        await al.gate("code.commit")
+
+    asyncio.run(main())
+
+    # Sync wrappers if you're not in an async context
+    al.gate_sync("code.commit")
+"""
+
+from agentlattice.client import (
+    AgentLattice,
+    AgentLatticeError,
+    AgentLatticeDeniedError,
+    AgentLatticeTimeoutError,
+    ActionResult,
+    ActionOptions,
+    ConditionResult,
+    DelegatedAgent,
+    DelegationContext,
+    SyncDelegationContext,
+    ParallelDelegation,
+    SyncParallelDelegation,
+)
+
+__all__ = [
+    "AgentLattice",
+    "AgentLatticeError",
+    "AgentLatticeDeniedError",
+    "AgentLatticeTimeoutError",
+    "ActionResult",
+    "ActionOptions",
+    "ConditionResult",
+    "DelegatedAgent",
+    "DelegationContext",
+    "SyncDelegationContext",
+    "ParallelDelegation",
+    "SyncParallelDelegation",
+]
+
+__version__ = "0.3.0"