agenticdome-python-sdk 1.2.8__tar.gz → 1.2.10__tar.gz

{agenticdome_python_sdk-1.2.8 → agenticdome_python_sdk-1.2.10}/MANIFEST.in

@@ -4,6 +4,7 @@ include pyproject.toml
 include setup.py
 
 recursive-include examples *.py
+recursive-include examples *.md
 recursive-include tests *.py
 global-exclude __pycache__
 global-exclude *.py[cod]

{agenticdome_python_sdk-1.2.8 → agenticdome_python_sdk-1.2.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agenticdome-python-sdk
-Version: 1.2.8
+Version: 1.2.10
 Summary: Official Python SDK for AgenticDome security guardrails, DLP, tool authorization, and multi-agent delegation enforcement.
 Author: AgenticDome
 License: Proprietary
@@ -8,6 +8,7 @@ Project-URL: Homepage, https://www.agenticdome.io
 Project-URL: Repository, https://github.com/agenticdome/agenticdome-python-sdk
 Project-URL: Documentation, https://github.com/agenticdome/agenticdome-python-sdk#readme
 Project-URL: Issues, https://github.com/agenticdome/agenticdome-python-sdk/issues
+Project-URL: Examples, https://github.com/agenticdome/agenticdome-python-sdk/tree/main/examples
 Keywords: agentguard,agenticdome,ai-security,agent-security,guardrails,a2a,mcp,zero-trust,runtime-security
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
@@ -27,16 +28,16 @@ License-File: LICENSE
 Requires-Dist: requests>=2.31.0
 Requires-Dist: urllib3>=2.0.0
 Provides-Extra: crewai
-Requires-Dist: crewai<=1.15.10,>=1.15.5; extra == "crewai"
+Requires-Dist: crewai<=1.15.14,>=1.15.5; extra == "crewai"
 Provides-Extra: redis
 Requires-Dist: redis>=4.5.0; extra == "redis"
 Provides-Extra: pop
 Requires-Dist: cryptography>=42.0.0; extra == "pop"
 Provides-Extra: pydanticai
-Requires-Dist: pydantic-ai<=2.22.0,>=2.16.0; extra == "pydanticai"
+Requires-Dist: pydantic-ai<=2.27.1,>=2.16.0; extra == "pydanticai"
 Requires-Dist: anyio>=4.0.0; extra == "pydanticai"
 Provides-Extra: pydantic
-Requires-Dist: pydantic-ai<=2.22.0,>=2.16.0; extra == "pydantic"
+Requires-Dist: pydantic-ai<=2.27.1,>=2.16.0; extra == "pydantic"
 Requires-Dist: anyio>=4.0.0; extra == "pydantic"
 Provides-Extra: langgraph
 Requires-Dist: langgraph<=1.2.10,>=1.2.9; extra == "langgraph"
@@ -52,48 +53,48 @@ Provides-Extra: foundry
 Requires-Dist: azure-ai-projects<=2.4.0,>=2.3.0; extra == "foundry"
 Requires-Dist: azure-identity==1.25.3; extra == "foundry"
 Provides-Extra: agno
-Requires-Dist: agno<=2.8.6,>=2.8.0; extra == "agno"
+Requires-Dist: agno<=2.8.7,>=2.8.0; extra == "agno"
 Provides-Extra: openai-agents
-Requires-Dist: openai-agents<=0.19.2,>=0.18.3; extra == "openai-agents"
+Requires-Dist: openai-agents<=0.20.0,>=0.18.3; extra == "openai-agents"
 Provides-Extra: mcp
 Requires-Dist: mcp<=1.28.1,>=1.26.0; extra == "mcp"
 Provides-Extra: bedrock
-Requires-Dist: boto3<=1.43.62,>=1.43.54; extra == "bedrock"
+Requires-Dist: boto3<=1.43.68,>=1.43.54; extra == "bedrock"
 Provides-Extra: aws-bedrock
-Requires-Dist: boto3<=1.43.62,>=1.43.54; extra == "aws-bedrock"
+Requires-Dist: boto3<=1.43.68,>=1.43.54; extra == "aws-bedrock"
 Provides-Extra: llamaindex
 Requires-Dist: llama-index==0.14.23; extra == "llamaindex"
 Provides-Extra: llama-index
 Requires-Dist: llama-index==0.14.23; extra == "llama-index"
 Provides-Extra: google-adk
-Requires-Dist: google-adk<=2.6.1,>=2.5.0; extra == "google-adk"
+Requires-Dist: google-adk<=2.6.3,>=2.5.0; extra == "google-adk"
 Provides-Extra: adk
-Requires-Dist: google-adk<=2.6.1,>=2.5.0; extra == "adk"
+Requires-Dist: google-adk<=2.6.3,>=2.5.0; extra == "adk"
 Provides-Extra: claude
-Requires-Dist: claude-agent-sdk<=0.2.128,>=0.2.126; extra == "claude"
+Requires-Dist: claude-agent-sdk<=0.2.135,>=0.2.126; extra == "claude"
 Provides-Extra: claude-agent-sdk
-Requires-Dist: claude-agent-sdk<=0.2.128,>=0.2.126; extra == "claude-agent-sdk"
+Requires-Dist: claude-agent-sdk<=0.2.135,>=0.2.126; extra == "claude-agent-sdk"
 Provides-Extra: smolagents
 Requires-Dist: smolagents==1.26.0; extra == "smolagents"
 Provides-Extra: all
-Requires-Dist: crewai<=1.15.10,>=1.15.5; extra == "all"
+Requires-Dist: crewai<=1.15.14,>=1.15.5; extra == "all"
 Requires-Dist: redis>=4.5.0; extra == "all"
 Requires-Dist: cryptography>=42.0.0; extra == "all"
-Requires-Dist: pydantic-ai<=2.22.0,>=2.16.0; extra == "all"
+Requires-Dist: pydantic-ai<=2.27.1,>=2.16.0; extra == "all"
 Requires-Dist: anyio>=4.0.0; extra == "all"
 Requires-Dist: langgraph<=1.2.10,>=1.2.9; extra == "all"
 Requires-Dist: langchain-core<=1.5.3,>=1.5.0; extra == "all"
 Requires-Dist: langchain-openai==1.3.5; extra == "all"
 Requires-Dist: autogen-agentchat==0.7.5; extra == "all"
-Requires-Dist: agno<=2.8.6,>=2.8.0; extra == "all"
+Requires-Dist: agno<=2.8.7,>=2.8.0; extra == "all"
 Requires-Dist: azure-ai-projects<=2.4.0,>=2.3.0; extra == "all"
 Requires-Dist: azure-identity==1.25.3; extra == "all"
-Requires-Dist: openai-agents<=0.19.2,>=0.18.3; extra == "all"
+Requires-Dist: openai-agents<=0.20.0,>=0.18.3; extra == "all"
 Requires-Dist: mcp<=1.28.1,>=1.26.0; extra == "all"
-Requires-Dist: boto3<=1.43.62,>=1.43.54; extra == "all"
+Requires-Dist: boto3<=1.43.68,>=1.43.54; extra == "all"
 Requires-Dist: llama-index==0.14.23; extra == "all"
-Requires-Dist: google-adk<=2.6.1,>=2.5.0; extra == "all"
-Requires-Dist: claude-agent-sdk<=0.2.128,>=0.2.126; extra == "all"
+Requires-Dist: google-adk<=2.6.3,>=2.5.0; extra == "all"
+Requires-Dist: claude-agent-sdk<=0.2.135,>=0.2.126; extra == "all"
 Requires-Dist: smolagents==1.26.0; extra == "all"
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0.0; extra == "dev"
@@ -112,10 +113,57 @@ Dynamic: license-file
 
 > **Production-grade security guardrails, DLP, tool authorization, and cryptographically verified multi-agent delegation for Python autonomous AI runtimes.**
 
-`agenticdome-python-sdk` is the official Python SDK and middleware package for [AgenticDome](https://agenticdome.io). It enforces deterministic security controls at every boundary your agents cross — prompt ingress, tool execution, agent-to-agent handoffs, and output egress — backed by the AgenticDome central policy plane.
+`agenticdome-python-sdk` is the official Python SDK and middleware package for [AgenticDome](https://agenticdome.io). It enforces deterministic security controls at every boundary your agents cross — prompt ingress, tool execution, agent-to-agent handoffs, and output egress — using the tenant's assigned AgenticDome runtime sidecar.
 
 **One security pattern, fifteen runtimes:** CrewAI · PydanticAI · LangGraph/LangChain · Microsoft Agent Framework · Microsoft AutoGen · Microsoft AI Foundry · OpenAI Agents SDK · Claude Agent SDK · Hugging Face smolagents · Agno · Google ADK · LlamaIndex · AWS Bedrock · MCP hosts/gateways · custom Python.
 
+## Five-minute developer trial
+
+### 1. Install
+
+```bash
+pip install agenticdome-python-sdk
+```
+
+### 2. Enable the offline simulator
+
+```bash
+export AGENTICDOME_MODE=local_sim
+```
+
+No account, API key, tenant, network connection, or third-party framework package is required.
+
+### 3. See one allowed and one blocked action
+
+```bash
+agenticdome-demo --framework langgraph --scenario both
+```
+
+Look for `ALLOWED — TOOL WOULD EXECUTE` followed by `BLOCKED — TOOL WOULD NOT EXECUTE`. These are simulations: the example does not execute either tool.
+
+### 4. Select your framework
+
+```bash
+agenticdome-demo --list-frameworks
+agenticdome-demo --framework all --scenario both
+```
+
+You can also open the [framework example gallery](examples/README.md) and run the individual example matching your stack. Before editing production code, use the [production integration playbook](examples/PRODUCTION_INTEGRATION.md) to find the exact construction file, public attachment call and local execution boundary for your framework.
+
+### 5. Connect the same integration to AgenticDome
+
+When you are ready to test real tenant policy, remove `AGENTICDOME_MODE=local_sim`, obtain the assigned runtime sidecar URL, Runtime/SDK API key and tenant ID from AgenticDome, and configure:
+
+```bash
+unset AGENTICDOME_MODE
+export AGENTICDOME_API_BASE="https://your-assigned-sidecar.example"
+export AGENTICDOME_API_KEY="your_runtime_sdk_key"
+export AGENTICDOME_TENANT_ID="your_tenant_id"
+agenticdome-demo --framework langgraph --scenario both --live
+```
+
+Offline simulation demonstrates the SDK decision flow using a bundled public baseline. Only live mode applies the customer's policy, topology, telemetry, signed decisions and runtime enforcement.
+
 ```python
 # The 30-second version: block a prompt-injected refund before it executes.
 import agenticdome_sdk.crewai   # registers global CrewAI security hooks
@@ -129,18 +177,19 @@ result = crew.kickoff()          # hostile prompts, unsafe tools, and rogue
 
 ## Contents
 
-1. [Why AgenticDome](#why-agenticdome)
-2. [How It Works](#how-it-works)
-3. [Quickstart](#quickstart)
-4. [Installation](#installation)
-5. [Configuration](#configuration)
-6. [Choosing Your Integration Point](#choosing-your-integration-point)
-7. [Framework Integrations](#framework-integrations)
-   - [CrewAI](#crewai) · [PydanticAI](#pydanticai) · [LangGraph](#langgraph) · [Microsoft Agent Framework](#microsoft-agent-framework) · [Microsoft AutoGen](#microsoft-autogen) · [Microsoft AI Foundry](#microsoft-ai-foundry) · [OpenAI Agents SDK](#openai-agents-sdk) · [Agno](#agno) · [Google ADK](#google-adk) · [LlamaIndex](#llamaindex) · [AWS Bedrock](#aws-bedrock) · [MCP Host / Gateway](#mcp-host--gateway)
-8. [Core SDK Client (Custom Runtimes)](#core-sdk-client-custom-runtimes)
-9. [Production Deployment](#production-deployment)
-10. [Package Build and Verification](#package-build-and-verification)
-11. [License](#license)
+1. [Five-minute developer trial](#five-minute-developer-trial)
+2. [Why AgenticDome](#why-agenticdome)
+3. [How It Works](#how-it-works)
+4. [Quickstart](#quickstart)
+5. [Installation](#installation)
+6. [Configuration](#configuration)
+7. [Choosing Your Integration Point](#choosing-your-integration-point)
+8. [Framework Integrations](#framework-integrations)
+   - [CrewAI](#crewai) · [PydanticAI](#pydanticai) · [LangGraph](#langgraph) · [Microsoft Agent Framework](#microsoft-agent-framework) · [Microsoft AutoGen](#microsoft-autogen) · [Microsoft AI Foundry](#microsoft-ai-foundry) · [OpenAI Agents SDK](#openai-agents-sdk) · [Claude Agent SDK](#claude-agent-sdk) · [Hugging Face smolagents](#hugging-face-smolagents) · [Agno](#agno) · [Google ADK](#google-adk) · [LlamaIndex](#llamaindex) · [AWS Bedrock](#aws-bedrock) · [MCP Host / Gateway](#mcp-host--gateway)
+9. [Core SDK Client (Custom Runtimes)](#core-sdk-client-custom-runtimes)
+10. [Production Deployment](#production-deployment)
+11. [Package Build and Verification](#package-build-and-verification)
+12. [License](#license)
 
 ---
 
@@ -247,17 +296,33 @@ AgenticDome uses a **hybrid split-plane architecture**. Your local Python runtim
 
 ## Quickstart
 
-Five steps from zero to a protected runtime.
+Start with a network-free simulation, then connect the same SDK to your assigned runtime sidecar for real tenant enforcement.
 
-**1. Onboard.** Create an account in the AgenticDome Management Console (AU region), copy your tenant identifier from organization settings, and generate a production API key from the access-control section.
+**1. Try the installed local simulation.** No account, API key, tenant, network call, telemetry, or framework package is required:
 
-**2. Install** the SDK with the extra matching your framework:
+```bash
+pip install agenticdome-python-sdk
+# Show one ALLOWED and one BLOCKED action for LangGraph.
+agenticdome-demo --framework langgraph --scenario both
+
+# Or prove the same offline contract across all 15 integrations.
+agenticdome-demo --framework all --scenario both
+agenticdome-demo --list-frameworks
+```
+
+This is visibly labelled **LOCAL SIMULATION — NOT CLOUD ENFORCEMENT**. It evaluates a small bundled demonstration policy through the real public client contract, but it does not load tenant policy, issue signed decision tokens or execution receipts, write cloud evidence, or provide runtime assurance. To exercise any wrapper inside your own process without credentials, set `AGENTICDOME_MODE=local_sim`. The SDK refuses that mode when `AGENTICDOME_PRODUCTION_MODE=true`.
+
+Browse the public [`examples/`](examples/README.md) gallery for a runnable allowed/blocked example for CrewAI, PydanticAI, LangGraph, Microsoft Agent Framework, AutoGen, AI Foundry, OpenAI Agents, Claude, smolagents, Agno, Google ADK, LlamaIndex, Bedrock, MCP, and custom Python. Local blocked/redacted results emit safe terminal logs containing verdict metadata only—not raw prompts, arguments, keys, or secrets.
+
+**2. Onboard for real enforcement.** Create an account in the AgenticDome Management Console, obtain your tenant identifier and Runtime / SDK API key, and identify the tenant's assigned runtime sidecar.
+
+**3. Install** the SDK with the extra matching your framework:
 
 ```bash
 pip install "agenticdome-python-sdk[crewai]"     # or pydanticai, langgraph, ...
 ```
 
-**3. Configure** the three required environment variables (all clients fail with a configuration error rather than silently running unprotected):
+**4. Configure** the three required production environment variables (live clients fail with a configuration error rather than silently running unprotected):
 
 ```bash
 # Tenant runtime sidecar URL. Do not use the control-plane website URL here.
@@ -266,7 +331,7 @@ export AGENTICDOME_API_KEY="your_api_key_abc123..."
 export AGENTICDOME_TENANT_ID="your_tenant_id_xyz789..."
 ```
 
-**4. Attach** AgenticDome at your framework's boundary — environment variables alone never intercept execution; every framework needs its one-time code attachment (see [Choosing Your Integration Point](#choosing-your-integration-point)):
+**5. Attach** AgenticDome at your framework's boundary — environment variables alone never intercept execution; every framework needs its one-time code attachment (see [Choosing Your Integration Point](#choosing-your-integration-point)):
 
 ```python
 # CrewAI example: one import in your bootstrap, before crews are built.
@@ -277,14 +342,26 @@ crew = Crew(agents=[manager, specialist], tasks=[task])
 result = crew.kickoff()
 ```
 
-**5. Verify** by running the vulnerable-vs-protected attack demo:
+**6. Verify** locally or against the real assigned sidecar:
 
 ```bash
-python examples/attack_demo.py --framework crewai --scenario refund_hijack
-python examples/attack_demo.py --framework claude --scenario metadata_exfil
-python examples/attack_demo.py --framework smolagents --scenario generated_code_exfil
+# Local, deterministic and network-free.
+agenticdome-demo --framework crewai --scenario both
+agenticdome-demo --framework langgraph --scenario both
+agenticdome-demo --framework claude --scenario both
+agenticdome-demo --framework smolagents --scenario both
+agenticdome-demo --framework all --scenario both
+
+# Additional blocked-only examples for focused attack demonstrations.
+agenticdome-demo --framework claude --scenario metadata_exfil
+agenticdome-demo --framework smolagents --scenario metadata_exfil
+
+# Live: uses AGENTICDOME_API_BASE/API_KEY/TENANT_ID and the assigned sidecar.
+agenticdome-demo --framework langgraph --scenario safe_lookup --live
 ```
 
+Every Python integration listed below is selectable through `agenticdome-demo --framework ...`; the demo prints the correct package extra and integration import for that framework. Local simulation proves SDK compatibility and control flow only. The live command proves the configured tenant-sidecar path.
+
 ---
 
 ## Installation
@@ -334,6 +411,18 @@ AgenticDome has two setup layers, and both are required:
 
 Environment variables do **not** intercept framework execution by themselves.
 
+### Offline community trial
+
+Every supported Python integration inherits the same credential-free, network-free simulator:
+
+```bash
+export AGENTICDOME_MODE="local_sim"
+```
+
+No API base, API key, tenant ID, or third-party framework package is needed to run the public demonstration. `ALLOWED` decisions are logged at `INFO`; `BLOCKED` and `REDACTED` decisions are logged at `WARNING` so they are visible in a normal terminal. Logs contain decision metadata only and exclude raw prompt text and tool arguments.
+
+Local simulation is deliberately limited: it uses the bundled public baseline, does not execute tools, does not use tenant policy, topology, signed provenance, runtime telemetry, decision tokens, or execution receipts, and cannot satisfy an enforced execution broker. It is refused whenever `AGENTICDOME_PRODUCTION_MODE=true`.
+
 ### Required variables
 
 ```bash
@@ -390,6 +479,7 @@ export AGENTICDOME_PRODUCTION_MODE="false"            # production hardening (st
 | `AGENTICDOME_API_BASE` | string | required | Tenant runtime sidecar origin, e.g. `https://demo-sidecar.agenticdome.io`. Separate from the control-plane console URL. |
 | `AGENTICDOME_API_KEY` | string | required | API key generated in the AgenticDome console. |
 | `AGENTICDOME_TENANT_ID` | string | required | Tenant or organization isolation namespace. |
+| `AGENTICDOME_MODE` | `live` / `local_sim` | `live` | Selects real sidecar enforcement or the credential-free, network-free demonstration evaluator. `local_sim` is refused in production mode. |
 | `AGENTICDOME_PLATFORM` | string | framework-specific | Runtime platform label included in policy context. |
 | `AGENTICDOME_TIMEOUT_S` | integer | `20` | HTTP timeout in seconds for SDK calls. |
 | `AGENTICDOME_FAIL_CLOSED` | boolean | `true` | Blocks execution if security checks fail. |
@@ -492,6 +582,8 @@ Every framework adapter exposes the same family of local hardening controls, pre
 
 One table, one decision. Find your runtime, apply the required code action, and jump to its guide. In every case, environment config alone is **not** enough — hooks activate only after the code attachment shown here.
 
+For a shorter operator/developer handoff, use the [production integration playbook](examples/PRODUCTION_INTEGRATION.md). It includes the attachment boundary, bypass warning and production proof checklist for every supported framework without exposing private policy or detection internals.
+
 | Runtime | SDK module | Global code location | Required code action | Tool-level enforcement |
 | :--- | :--- | :--- | :--- | :--- |
 | [CrewAI](#crewai) | `agenticdome_sdk.crewai` | Application bootstrap, before crews are created | `import agenticdome_sdk.crewai` once for global hooks, or `AgenticDomeCrewAIFirewall().attach(...)` for scoped hooks | `secure_tool(...)` for explicit local wrapper enforcement, schema validation, sanitized-argument execution |
@@ -2426,6 +2518,44 @@ client.report_incident(
 
 ---
 
+## Brokered Execution and the Enforcement Gateway
+
+For high-impact tools, authorise at the last responsible moment and bind the decision to the real destination, HTTP method, tool version/digest, and workload identity. The sidecar returns a short-lived, single-use execution receipt; attach it to the actual outbound request that traverses the AgenticDome enforcement gateway.
+
+```python
+from agenticdome_sdk import AgentGuardClient
+
+client = AgentGuardClient(
+    "https://your-sidecar.example.com",
+    execution_broker_mode="enforce",
+)
+decision = client.guardrail_validate(
+    text="Read customer account",
+    agent_id="support-agent-1",
+    direction="outbound",
+    platform="mcp",
+    tool_name="crm.lookup",
+    tool_args={"customer_id": "123"},
+    tool_version="1.4.2",
+    tool_digest="sha256:" + "a" * 64,
+    execution_destination="https://crm.example.com/customers/123",
+    execution_http_method="GET",
+    workload_id="spiffe://customer.example/agent/support-agent-1",
+)
+
+# Apply these headers to the real HTTP request, not to a simulated callback.
+headers = client.enforcement_headers(
+    decision,
+    workload_id="spiffe://customer.example/agent/support-agent-1",
+)
+```
+
+The control-plane website, provenance registry, SBOM registry, and LLM are not called on this request path. Approved provenance and policy bundles are already cached in the assigned sidecar. If the gateway is in enforce mode, a missing, expired, replayed, destination-mismatched, method-mismatched, or workload-mismatched receipt fails closed.
+
+Framework adapters share this core client, but the application still owns the final executor boundary: pass the real destination/method and attach the returned headers where the framework invokes the external tool. Customers using an AgenticDome-managed sidecar install only the SDK; the deployment administrator operates Envoy, Tetragon/eBPF, SPIFFE, and sandbox infrastructure.
+
+---
+
 ## Production Deployment
 
 ### Fail-safe behavior
@@ -2506,6 +2636,7 @@ python -m pytest -q tests/test_langgraph_integration.py
 | :--- | :--- | :--- |
 | Core SDK client | `python -m pytest -q tests/test_client.py` | Request validation, headers, guardrail calls, A2A/MCP JSON-RPC calls, Mesh DLP, HTTP errors, JSON handling |
 | Attack demos | `python -m pytest -q tests/test_attack_demo.py` | Offline vulnerable-vs-protected CLI coverage, including AutoGen, Claude Agent SDK, and Hugging Face smolagents |
+| Local simulation parity | `python -m pytest -q tests/test_local_simulation.py` | No-credential/no-network mode, production refusal, broker fail-closed behavior, installed demo catalog and constructor coverage for every supported Python adapter |
 | CrewAI | `python -m pytest -q tests/test_crewai_integration.py` | Prompt/tool hooks, handoff token injection, specialist verification, output redaction, schema checks, rate limits, retries, streaming DLP |
 | PydanticAI | `python -m pytest -q tests/test_pydanticai_integration.py` | Agent hooks, secure tools, sanitized arguments, token-store fallback, production session enforcement, rate limits, retries, streaming output |
 | LangGraph / LangChain | `python -m pytest -q tests/test_langgraph_integration.py` | Graph input, transition, tool, retrieval, middleware, security routing, token consumption, output DLP, streaming events |