control-zero 0.2.0__tar.gz → 0.3.0__tar.gz

{control_zero-0.2.0 → control_zero-0.3.0}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: control-zero
-Version: 0.2.0
+Version: 0.3.0
 Summary: Enterprise MCP governance SDK - secrets, policies, and observability
-Project-URL: Homepage, https://controlzero.dev
-Project-URL: Documentation, https://docs.controlzero.dev
-Author-email: Control Zero <hello@controlzero.dev>
+Project-URL: Homepage, https://controlzero.ai
+Project-URL: Documentation, https://docs.controlzero.ai
+Author-email: Control Zero <hello@controlzero.ai>
 License: Proprietary
 License-File: LICENSE
 Keywords: governance,mcp,observability,policy,secrets
@@ -47,11 +47,11 @@ Provides-Extra: mcp
 Requires-Dist: mcp>=0.1.0; extra == 'mcp'
 Description-Content-Type: text/markdown
 
-# Control Zero Python SDK
+# control-zero
 
-Enterprise MCP governance - secrets, policies, and observability for AI agents.
+AI agent governance SDK for Python.
 
-## Installation
+## Install
 
 ```bash
 pip install control-zero
@@ -62,6 +62,48 @@ pip install control-zero
 ```python
 from control_zero import ControlZeroClient
 
+cz = ControlZeroClient(api_key="cz_test_yourkey")
+
+# Log a tool call
+cz.log_tool_call("my-agent", "github", "list_issues", {"repo": "myorg/myrepo"})
+```
+
+## With OpenAI
+
+```python
+from control_zero.integrations.openai import GovernedOpenAI
+import openai
+
+cz = ControlZeroClient(api_key="cz_test_yourkey")
+client = GovernedOpenAI(openai.OpenAI(), cz)
+response = client.chat.completions.create(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "Hello"}]
+)
+# Token counts and costs are tracked automatically
+```
+
+## With Anthropic
+
+```python
+from control_zero.integrations.anthropic import GovernedAnthropic
+import anthropic
+
+cz = ControlZeroClient(api_key="cz_test_yourkey")
+client = GovernedAnthropic(anthropic.Anthropic(), cz)
+response = client.messages.create(
+    model="claude-opus-4-5",
+    max_tokens=1024,
+    messages=[{"role": "user", "content": "Hello"}]
+)
+# Token counts and costs are tracked automatically
+```
+
+## Full Client API
+
+```python
+from control_zero import ControlZeroClient
+
 # Initialize with your API key
 client = ControlZeroClient(api_key="cz_live_xxx")
 
@@ -80,6 +122,7 @@ client.close()
 ### Automatic Secret Injection
 
 Secrets configured in the Control Zero dashboard are automatically:
+
 1. Fetched encrypted from the server
 2. Decrypted in memory
 3. Injected into your MCP calls
@@ -153,10 +196,58 @@ result = await wrapped.call_tool("github", "list_issues")
 client = ControlZeroClient(
     api_key="cz_live_xxx",           # Required
     agent_name="marketing-bot",       # Optional, for logging
-    base_url="https://api.controlzero.dev",  # Or self-hosted
+    base_url="https://api.controlzero.ai",  # Or self-hosted
 )
 ```
 
+## Deployment Modes
+
+Control Zero supports three deployment modes for different environments:
+
+### Cloud Mode (Default)
+
+Policies are fetched from the API on initialization. Best for cloud deployments with internet connectivity.
+
+```python
+client = ControlZeroClient(api_key="cz_live_xxx")
+# Policies automatically fetched from API
+```
+
+### Hybrid Mode (Recommended for Production)
+
+Policies are cached locally and refreshed in the background. Works offline with cached policies.
+
+```python
+client = ControlZeroClient(
+    api_key="cz_live_xxx",
+    policy_mode="hybrid",
+    policy_cache_path="./cache/policies.json",  # Optional
+    policy_refresh_interval=300,  # Refresh every 5 minutes
+)
+```
+
+### Local Mode (Air-Gapped)
+
+Policies are loaded from a local file. No network calls for policy fetching.
+
+```python
+client = ControlZeroClient(
+    api_key="cz_live_xxx",
+    policy_mode="local",
+    policy_path="./policies.czpolicy",
+)
+```
+
+Download policy bundles from your project dashboard or via API:
+
+```bash
+curl -H "Authorization: Bearer $API_KEY" \
+  https://api.controlzero.ai/api/projects/{projectID}/policies/download \
+  -o policies.czpolicy
+```
+
+See [deployment modes documentation](https://docs.controlzero.ai/deployment-modes) for detailed comparison and migration guides.
+
 ## API Key Types
 
 - `cz_live_*` - Production keys (real secrets, real logging)
@@ -207,7 +298,7 @@ See the [examples/](./examples/) directory for complete usage examples:
 
 - **slack_bot.py** - Secure Slack messaging with channel restrictions
 - **database_agent.py** - PostgreSQL with read-only policies
-- **analytics_agent.py** - ClickHouse queries with governance
+- **analytics_agent.py** - Analytics queries with governance
 - **github_agent.py** - GitHub operations with branch protection
 - **multi_tool_agent.py** - Complete multi-tool workflow
 

{control_zero-0.2.0 → control_zero-0.3.0}/README.md

@@ -1,8 +1,8 @@
-# Control Zero Python SDK
+# control-zero
 
-Enterprise MCP governance - secrets, policies, and observability for AI agents.
+AI agent governance SDK for Python.
 
-## Installation
+## Install
 
 ```bash
 pip install control-zero
@@ -13,6 +13,48 @@ pip install control-zero
 ```python
 from control_zero import ControlZeroClient
 
+cz = ControlZeroClient(api_key="cz_test_yourkey")
+
+# Log a tool call
+cz.log_tool_call("my-agent", "github", "list_issues", {"repo": "myorg/myrepo"})
+```
+
+## With OpenAI
+
+```python
+from control_zero.integrations.openai import GovernedOpenAI
+import openai
+
+cz = ControlZeroClient(api_key="cz_test_yourkey")
+client = GovernedOpenAI(openai.OpenAI(), cz)
+response = client.chat.completions.create(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "Hello"}]
+)
+# Token counts and costs are tracked automatically
+```
+
+## With Anthropic
+
+```python
+from control_zero.integrations.anthropic import GovernedAnthropic
+import anthropic
+
+cz = ControlZeroClient(api_key="cz_test_yourkey")
+client = GovernedAnthropic(anthropic.Anthropic(), cz)
+response = client.messages.create(
+    model="claude-opus-4-5",
+    max_tokens=1024,
+    messages=[{"role": "user", "content": "Hello"}]
+)
+# Token counts and costs are tracked automatically
+```
+
+## Full Client API
+
+```python
+from control_zero import ControlZeroClient
+
 # Initialize with your API key
 client = ControlZeroClient(api_key="cz_live_xxx")
 
@@ -31,6 +73,7 @@ client.close()
 ### Automatic Secret Injection
 
 Secrets configured in the Control Zero dashboard are automatically:
+
 1. Fetched encrypted from the server
 2. Decrypted in memory
 3. Injected into your MCP calls
@@ -104,10 +147,58 @@ result = await wrapped.call_tool("github", "list_issues")
 client = ControlZeroClient(
     api_key="cz_live_xxx",           # Required
     agent_name="marketing-bot",       # Optional, for logging
-    base_url="https://api.controlzero.dev",  # Or self-hosted
+    base_url="https://api.controlzero.ai",  # Or self-hosted
 )
 ```
 
+## Deployment Modes
+
+Control Zero supports three deployment modes for different environments:
+
+### Cloud Mode (Default)
+
+Policies are fetched from the API on initialization. Best for cloud deployments with internet connectivity.
+
+```python
+client = ControlZeroClient(api_key="cz_live_xxx")
+# Policies automatically fetched from API
+```
+
+### Hybrid Mode (Recommended for Production)
+
+Policies are cached locally and refreshed in the background. Works offline with cached policies.
+
+```python
+client = ControlZeroClient(
+    api_key="cz_live_xxx",
+    policy_mode="hybrid",
+    policy_cache_path="./cache/policies.json",  # Optional
+    policy_refresh_interval=300,  # Refresh every 5 minutes
+)
+```
+
+### Local Mode (Air-Gapped)
+
+Policies are loaded from a local file. No network calls for policy fetching.
+
+```python
+client = ControlZeroClient(
+    api_key="cz_live_xxx",
+    policy_mode="local",
+    policy_path="./policies.czpolicy",
+)
+```
+
+Download policy bundles from your project dashboard or via API:
+
+```bash
+curl -H "Authorization: Bearer $API_KEY" \
+  https://api.controlzero.ai/api/projects/{projectID}/policies/download \
+  -o policies.czpolicy
+```
+
+See [deployment modes documentation](https://docs.controlzero.ai/deployment-modes) for detailed comparison and migration guides.
+
 ## API Key Types
 
 - `cz_live_*` - Production keys (real secrets, real logging)
@@ -158,7 +249,7 @@ See the [examples/](./examples/) directory for complete usage examples:
 
 - **slack_bot.py** - Secure Slack messaging with channel restrictions
 - **database_agent.py** - PostgreSQL with read-only policies
-- **analytics_agent.py** - ClickHouse queries with governance
+- **analytics_agent.py** - Analytics queries with governance
 - **github_agent.py** - GitHub operations with branch protection
 - **multi_tool_agent.py** - Complete multi-tool workflow
 

control_zero-0.3.0/control_zero/__init__.py

@@ -0,0 +1,97 @@
+"""
+Control Zero - Enterprise MCP Governance SDK
+
+The "magic" SDK that handles authentication, secret injection, policy enforcement,
+and observability for MCP tool calls.
+
+Usage:
+    import controlzero
+
+    # Quickstart: one-line init using CZ_API_KEY env var
+    cz = controlzero.init()
+
+    # Or explicitly:
+    from control_zero import ControlZeroClient
+    client = ControlZeroClient(api_key="cz_live_xxx")
+
+    # Call MCP tools - secrets are injected automatically
+    result = client.call_tool("github", "list_issues", {"repo": "acme/app"})
+"""
+
+from control_zero.client import ControlZeroClient, AsyncControlZeroClient
+from control_zero.mcp import MCPMiddleware
+from control_zero.policy import (
+    PolicyDecision,
+    PolicyDeniedError,
+    BundleVerificationError,
+    BundleTamperError,
+)
+from control_zero.types import ToolConfig, SessionConfig
+
+# Alias: docs and quickstart reference `ControlZero` and `controlzero.init()`
+ControlZero = ControlZeroClient
+
+
+def init(api_key: str = None, **kwargs) -> ControlZeroClient:
+    """Create and return a ControlZeroClient.
+
+    Reads the CZ_API_KEY environment variable if api_key is not provided.
+    The client lazily initializes on first use, so calling init() alone does
+    not make a network request.
+
+    For local-only mode (no API key, no account), pass policy_path
+    without an api_key::
+
+        cz = controlzero.init(policy_path="./policies.json")
+
+    Args:
+        api_key: A Control Zero API key (cz_live_* or cz_test_*).
+                 Falls back to the CZ_API_KEY environment variable.
+                 Can be omitted when policy_path is provided (local-only mode).
+        **kwargs: Additional keyword arguments forwarded to ControlZeroClient.
+
+    Returns:
+        A configured ControlZeroClient instance.
+    """
+    import os
+    key = api_key or os.environ.get("CZ_API_KEY") or None
+    client = ControlZeroClient(api_key=key, **kwargs)
+    return client
+
+
+__version__ = "0.2.0"
+
+# Pre-release build warning
+# Versions like 0.3.0a1, 0.3.0.dev1, or anything with 'a', 'b', 'rc', 'dev'
+# are test builds published from CI. They are NOT connected to production
+# accounts and may contain breaking changes.
+import re as _re
+if _re.search(r"(a|b|rc|dev)\d*$", __version__):
+    import warnings as _warnings
+    _warnings.warn(
+        f"\n"
+        f"  You are using a TEST BUILD of control-zero (v{__version__}).\n"
+        f"  This build is not stable and may contain breaking changes.\n"
+        f"  It is NOT connected to your production account.\n"
+        f"\n"
+        f"  For production use, install the stable version:\n"
+        f"    pip install control-zero\n"
+        f"\n"
+        f"  Test builds are for development and evaluation only.",
+        UserWarning,
+        stacklevel=2,
+    )
+
+__all__ = [
+    "ControlZeroClient",
+    "AsyncControlZeroClient",
+    "ControlZero",
+    "init",
+    "MCPMiddleware",
+    "PolicyDecision",
+    "PolicyDeniedError",
+    "BundleVerificationError",
+    "BundleTamperError",
+    "ToolConfig",
+    "SessionConfig",
+]