vizier-guard 0.3.0__tar.gz

vizier_guard-0.3.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: vizier-guard
+Version: 0.3.0
+Summary: Deterministic authorization and audit guard for AI agent actions
+Author-email: Vassiliy Lakhonin <vassiliy.lakhonin@gmail.com>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/vassiliylakhonin/vizier
+Project-URL: Documentation, https://vizier.vassiliy-lakhonin.workers.dev/docs
+Project-URL: Repository, https://github.com/vassiliylakhonin/vizier
+Keywords: ai,agents,security,authorization,guardrails,langchain,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+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: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: pydantic
+Requires-Dist: pydantic>=2.0; extra == "pydantic"
+Provides-Extra: httpx
+Requires-Dist: httpx>=0.24.0; extra == "httpx"
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1.0; extra == "langchain"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0.0; extra == "test"
+
+# Vizier Guard (Python SDK)
+
+Deterministic Authorization & Audit Firewall for AI Agent Actions.
+
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.9+-green.svg)](pyproject.toml)
+
+Vizier is an ultra-low-latency (sub-2ms) deterministic policy kernel that evaluates proposed AI agent actions before they cause external side-effects (payments, database mutations, external messages, code execution, worker deployments).
+
+---
+
+## Installation
+
+```bash
+pip install vizier-guard
+```
+
+Zero external dependencies required out of the box (uses Python standard library).
+
+---
+
+## 30-Second Quickstart: `@vizier_guard` Decorator
+
+Wrap any dangerous tool or Python function with deterministic policy rules:
+
+```python
+from vizier import VizierClient, vizier_guard
+
+client = VizierClient(
+    base_url="https://vizier.vassiliy-lakhonin.workers.dev",
+    api_key="your-vizier-api-key"
+)
+
+@vizier_guard(
+    client=client,
+    action_type="purchase",
+    max_amount=500.0,
+    currency="USD",
+    allowed_targets=["approved-hotel.com", "supplier-corp.com"]
+)
+def book_hotel(amount: float, target: str):
+    # This only runs if Vizier returns ALLOW
+    print(f"Booking confirmed at {target} for ${amount}")
+    return {"status": "booked", "amount": amount}
+
+# Allowed: $350 <= $500 to approved target
+book_hotel(amount=350.0, target="approved-hotel.com")
+
+# Blocked: $1200 > $500 (raises ActionBlockedError)
+book_hotel(amount=1200.0, target="approved-hotel.com")
+```
+
+---
+
+## LangChain Integration
+
+Protect any LangChain `BaseTool` from agent hallucinations or runaway spending:
+
+```python
+from vizier import VizierClient
+from vizier.integrations.langchain import VizierLangChainToolGuard
+from langchain_community.tools import DuckDuckGoSearchRun
+
+client = VizierClient(api_key="...")
+
+# Wrap your tool
+safe_search = VizierLangChainToolGuard(
+    tool=DuckDuckGoSearchRun(),
+    client=client,
+    allowed_actions=["search"],
+    max_amount=0.0
+)
+
+# Pass safe_search into your LangChain or LangGraph agent
+agent = create_react_agent(llm, tools=[safe_search])
+```
+
+---
+
+## CrewAI Integration
+
+```python
+from vizier.integrations.crewai import VizierCrewAIToolGuard
+
+guarded_tool = VizierCrewAIToolGuard(
+    tool=my_dangerous_payment_tool,
+    max_amount=250.0,
+    agent_id="finance_agent"
+)
+```
+
+---
+
+## Standalone Verification
+
+```python
+from vizier import VizierClient
+
+vizier = VizierClient(api_key="...")
+
+decision = vizier.check(
+    action_type="deploy_worker",
+    target="worker:payment-service",
+    parameters={"git_commit": "abcdef123..."},
+    allowed_actions=["deploy_worker"]
+)
+
+if decision.is_allowed:
+    print(f"Action permitted! Receipt ID: {decision.receipt.id}")
+else:
+    print(f"Action rejected ({decision.decision}): {decision.explanation}")
+```

vizier_guard-0.3.0/README.md

@@ -0,0 +1,112 @@
+# Vizier Guard (Python SDK)
+
+Deterministic Authorization & Audit Firewall for AI Agent Actions.
+
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.9+-green.svg)](pyproject.toml)
+
+Vizier is an ultra-low-latency (sub-2ms) deterministic policy kernel that evaluates proposed AI agent actions before they cause external side-effects (payments, database mutations, external messages, code execution, worker deployments).
+
+---
+
+## Installation
+
+```bash
+pip install vizier-guard
+```
+
+Zero external dependencies required out of the box (uses Python standard library).
+
+---
+
+## 30-Second Quickstart: `@vizier_guard` Decorator
+
+Wrap any dangerous tool or Python function with deterministic policy rules:
+
+```python
+from vizier import VizierClient, vizier_guard
+
+client = VizierClient(
+    base_url="https://vizier.vassiliy-lakhonin.workers.dev",
+    api_key="your-vizier-api-key"
+)
+
+@vizier_guard(
+    client=client,
+    action_type="purchase",
+    max_amount=500.0,
+    currency="USD",
+    allowed_targets=["approved-hotel.com", "supplier-corp.com"]
+)
+def book_hotel(amount: float, target: str):
+    # This only runs if Vizier returns ALLOW
+    print(f"Booking confirmed at {target} for ${amount}")
+    return {"status": "booked", "amount": amount}
+
+# Allowed: $350 <= $500 to approved target
+book_hotel(amount=350.0, target="approved-hotel.com")
+
+# Blocked: $1200 > $500 (raises ActionBlockedError)
+book_hotel(amount=1200.0, target="approved-hotel.com")
+```
+
+---
+
+## LangChain Integration
+
+Protect any LangChain `BaseTool` from agent hallucinations or runaway spending:
+
+```python
+from vizier import VizierClient
+from vizier.integrations.langchain import VizierLangChainToolGuard
+from langchain_community.tools import DuckDuckGoSearchRun
+
+client = VizierClient(api_key="...")
+
+# Wrap your tool
+safe_search = VizierLangChainToolGuard(
+    tool=DuckDuckGoSearchRun(),
+    client=client,
+    allowed_actions=["search"],
+    max_amount=0.0
+)
+
+# Pass safe_search into your LangChain or LangGraph agent
+agent = create_react_agent(llm, tools=[safe_search])
+```
+
+---
+
+## CrewAI Integration
+
+```python
+from vizier.integrations.crewai import VizierCrewAIToolGuard
+
+guarded_tool = VizierCrewAIToolGuard(
+    tool=my_dangerous_payment_tool,
+    max_amount=250.0,
+    agent_id="finance_agent"
+)
+```
+
+---
+
+## Standalone Verification
+
+```python
+from vizier import VizierClient
+
+vizier = VizierClient(api_key="...")
+
+decision = vizier.check(
+    action_type="deploy_worker",
+    target="worker:payment-service",
+    parameters={"git_commit": "abcdef123..."},
+    allowed_actions=["deploy_worker"]
+)
+
+if decision.is_allowed:
+    print(f"Action permitted! Receipt ID: {decision.receipt.id}")
+else:
+    print(f"Action rejected ({decision.decision}): {decision.explanation}")
+```

vizier_guard-0.3.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vizier-guard"
+version = "0.3.0"
+description = "Deterministic authorization and audit guard for AI agent actions"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Apache-2.0" }
+authors = [
+    { name = "Vassiliy Lakhonin", email = "vassiliy.lakhonin@gmail.com" }
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Security",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+keywords = ["ai", "agents", "security", "authorization", "guardrails", "langchain", "mcp"]
+dependencies = []
+
+[project.optional-dependencies]
+pydantic = ["pydantic>=2.0"]
+httpx = ["httpx>=0.24.0"]
+langchain = ["langchain-core>=0.1.0"]
+test = [
+    "pytest>=7.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/vassiliylakhonin/vizier"
+Documentation = "https://vizier.vassiliy-lakhonin.workers.dev/docs"
+Repository = "https://github.com/vassiliylakhonin/vizier"
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

vizier_guard-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vizier_guard-0.3.0/src/vizier/__init__.py

@@ -0,0 +1,43 @@
+"""
+Vizier: Deterministic Authorization & Audit Kernel for AI Agents.
+"""
+
+from .canonical import canonicalize, sha256_canonical_json
+from .client import VizierClient, VizierError
+from .decorators import vizier_guard, ActionBlockedError
+from .models import (
+    Action,
+    Agent,
+    Authority,
+    AuthorityConstraints,
+    Context,
+    Decision,
+    PolicyResult,
+    Principal,
+    Receipt,
+    ReceiptGrant,
+    VerificationRequest,
+    VerificationResponse,
+)
+
+__version__ = "0.3.0"
+__all__ = [
+    "VizierClient",
+    "VizierError",
+    "vizier_guard",
+    "ActionBlockedError",
+    "VerificationRequest",
+    "VerificationResponse",
+    "Decision",
+    "Agent",
+    "Principal",
+    "Action",
+    "Authority",
+    "AuthorityConstraints",
+    "Context",
+    "PolicyResult",
+    "Receipt",
+    "ReceiptGrant",
+    "canonicalize",
+    "sha256_canonical_json",
+]

vizier_guard-0.3.0/src/vizier/canonical.py

@@ -0,0 +1,35 @@
+import hashlib
+import json
+from typing import Any
+
+def canonicalize(value: Any) -> str:
+    """
+    RFC 8785-like deterministic JSON canonicalization matching Vizier TS kernel:
+    - Booleans, strings, nulls, and numbers are serialized cleanly
+    - Float values with integral value format without trailing .0 (matching ECMAScript JSON.stringify)
+    - Arrays preserve order with canonical elements
+    - Dictionaries sort keys lexicographically
+    """
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (int, float)):
+        # ECMAScript JSON.stringify formats integral numbers without .0
+        if isinstance(value, float) and value.is_integer():
+            return str(int(value))
+        return json.dumps(value, separators=(",", ":"))
+    if isinstance(value, str):
+        return json.dumps(value, ensure_ascii=False, separators=(",", ":"))
+    if isinstance(value, (list, tuple)):
+        return "[" + ",".join(canonicalize(item) for item in value) + "]"
+    if isinstance(value, dict):
+        sorted_keys = sorted(value.keys())
+        items = [f"{json.dumps(k, ensure_ascii=False)}:{canonicalize(value[k])}" for k in sorted_keys]
+        return "{" + ",".join(items) + "}"
+    raise TypeError(f"Value of type {type(value)} is not canonicalizable JSON.")
+
+def sha256_canonical_json(value: Any) -> str:
+    """Compute SHA-256 hex digest of canonicalized JSON."""
+    raw = canonicalize(value).encode("utf-8")
+    return hashlib.sha256(raw).hexdigest()

vizier_guard-0.3.0/src/vizier/client.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+import json
+import urllib.request
+import urllib.error
+from typing import Any, Dict, List, Optional, Union
+
+from .models import (
+    Action,
+    Agent,
+    Authority,
+    AuthorityConstraints,
+    Context,
+    Principal,
+    VerificationRequest,
+    VerificationResponse,
+)
+from .canonical import sha256_canonical_json
+
+class VizierError(Exception):
+    def __init__(self, message: str, status: int = 0, code: str = "ERROR", details: Any = None):
+        super().__init__(f"[{code}] {message} (HTTP {status})")
+        self.message = message
+        self.status = status
+        self.code = code
+        self.details = details
+
+class VizierClient:
+    """
+    Official Vizier Authorization & Governance Client for AI Agents.
+    Zero external dependencies required (uses Python standard library).
+    """
+
+    def __init__(
+        self,
+        base_url: str = "https://vizier.vassiliy-lakhonin.workers.dev",
+        api_key: Optional[str] = None,
+        timeout: float = 5.0,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.timeout = timeout
+
+    def _request(self, path: str, data: Dict[str, Any]) -> Dict[str, Any]:
+        url = f"{self.base_url}{path}"
+        headers = {
+            "Content-Type": "application/json",
+            "User-Agent": "vizier-guard-python/0.3.0",
+        }
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+
+        payload_bytes = json.dumps(data).encode("utf-8")
+        req = urllib.request.Request(url, data=payload_bytes, headers=headers, method="POST")
+
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as response:
+                body = response.read().decode("utf-8")
+                return json.loads(body)
+        except urllib.error.HTTPError as err:
+            try:
+                body = err.read().decode("utf-8")
+                err_data = json.loads(body)
+                err_info = err_data.get("error", {})
+                msg = err_info.get("message", "Request failed")
+                code = err_info.get("code", "REQUEST_FAILED")
+                details = err_info.get("details")
+            except Exception:
+                msg = err.reason
+                code = "HTTP_ERROR"
+                details = None
+            raise VizierError(message=msg, status=err.code, code=code, details=details) from err
+        except urllib.error.URLError as err:
+            raise VizierError(message=str(err.reason), status=0, code="CONNECTION_FAILED") from err
+        except Exception as err:
+            raise VizierError(message=str(err), status=0, code="UNKNOWN_ERROR") from err
+
+    def verify(
+        self,
+        request: Union[VerificationRequest, Dict[str, Any]],
+        verify_receipt_hash: bool = True,
+    ) -> VerificationResponse:
+        """
+        Submit a proposed agent action to Vizier for deterministic authorization.
+        Returns VerificationResponse with decision: ALLOW, REVIEW, or BLOCK.
+        """
+        payload: Dict[str, Any]
+        if isinstance(request, VerificationRequest):
+            payload = request.to_dict()
+        elif isinstance(request, dict):
+            payload = request
+        else:
+            raise TypeError("request must be VerificationRequest or dict")
+
+        # Force source="rest" for client calls
+        if "context" not in payload or payload["context"] is None:
+            payload["context"] = {"source": "rest"}
+        else:
+            payload["context"]["source"] = "rest"
+
+        raw_response = self._request("/v1/verify", payload)
+        resp = VerificationResponse.from_dict(raw_response)
+
+        # Non-repudiation integrity check
+        if verify_receipt_hash:
+            expected_hash = sha256_canonical_json(payload)
+            if resp.receipt.request_hash != expected_hash:
+                raise VizierError(
+                    message=f"Receipt hash mismatch: expected {expected_hash}, got {resp.receipt.request_hash}",
+                    status=200,
+                    code="HASH_MISMATCH",
+                )
+
+        return resp
+
+    def check(
+        self,
+        action_type: str,
+        target: str,
+        parameters: Optional[Dict[str, Any]] = None,
+        allowed_actions: Optional[List[str]] = None,
+        max_amount: Optional[float] = None,
+        currency: Optional[str] = None,
+        allowed_targets: Optional[List[str]] = None,
+        blocked_targets: Optional[List[str]] = None,
+        agent_id: str = "agent",
+        principal_id: str = "principal",
+        is_reversible: Optional[bool] = None,
+        grant: Optional[str] = None,
+    ) -> VerificationResponse:
+        """
+        Convenience method: verify an action in a single line of code.
+        """
+        req = VerificationRequest(
+            agent=Agent(id=agent_id),
+            principal=Principal(id=principal_id),
+            action=Action(
+                type=action_type,
+                target=target,
+                parameters=parameters or {},
+                is_reversible=is_reversible,
+            ),
+            authority=Authority(
+                allowed_actions=allowed_actions or [action_type],
+                constraints=AuthorityConstraints(
+                    max_amount=max_amount,
+                    currency=currency,
+                    allowed_targets=allowed_targets,
+                    blocked_targets=blocked_targets,
+                ),
+            ),
+            grant=grant,
+        )
+        return self.verify(req)

vizier_guard-0.3.0/src/vizier/decorators.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+import functools
+import inspect
+from typing import Any, Callable, Dict, List, Optional, Union
+
+from .client import VizierClient
+from .models import VerificationResponse
+
+class ActionBlockedError(Exception):
+    def __init__(self, response: VerificationResponse):
+        super().__init__(
+            f"Action blocked by Vizier ({response.decision}): {response.explanation}. Reason codes: {response.reason_codes}"
+        )
+        self.response = response
+
+def vizier_guard(
+    client: Optional[VizierClient] = None,
+    action_type: Optional[str] = None,
+    target: Optional[Union[str, Callable[..., str]]] = None,
+    allowed_actions: Optional[List[str]] = None,
+    max_amount: Optional[Union[float, Callable[..., Optional[float]]]] = None,
+    currency: Optional[str] = None,
+    allowed_targets: Optional[List[str]] = None,
+    blocked_targets: Optional[List[str]] = None,
+    agent_id: str = "agent",
+    principal_id: str = "principal",
+    on_block: str = "raise", # "raise" or "callback"
+    on_block_callback: Optional[Callable[[VerificationResponse], Any]] = None,
+):
+    """
+    Decorator to protect any Python function / agent tool with Vizier deterministic authorization.
+    Before the function executes, Vizier checks the proposed action, parameters, and constraints.
+    If ALLOW, the function executes.
+    If BLOCK or REVIEW, execution is halted immediately.
+    """
+    viz_client = client or VizierClient()
+
+    def decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
+        act_type = action_type or fn.__name__
+
+        @functools.wraps(fn)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            # Bind arguments to function signature
+            sig = inspect.signature(fn)
+            bound = sig.bind(*args, **kwargs)
+            bound.apply_defaults()
+            params = dict(bound.arguments)
+
+            # Resolve target
+            if callable(target):
+                resolved_target = target(*args, **kwargs)
+            elif isinstance(target, str):
+                resolved_target = target
+            else:
+                resolved_target = params.get("target") or params.get("destination") or "default_target"
+
+            # Resolve max amount if dynamic
+            resolved_max_amount: Optional[float]
+            if callable(max_amount):
+                resolved_max_amount = max_amount(*args, **kwargs)
+            else:
+                resolved_max_amount = max_amount
+
+            # Check if amount and currency are inside parameters
+            amount = params.get("amount") or params.get("price")
+            curr = params.get("currency") or currency
+            if curr and "currency" not in params:
+                params["currency"] = curr
+
+            verification = viz_client.check(
+                action_type=act_type,
+                target=str(resolved_target),
+                parameters=params,
+                allowed_actions=allowed_actions or [act_type],
+                max_amount=resolved_max_amount,
+                currency=curr,
+                allowed_targets=allowed_targets,
+                blocked_targets=blocked_targets,
+                agent_id=agent_id,
+                principal_id=principal_id,
+            )
+
+            if not verification.is_allowed:
+                if on_block == "callback" and on_block_callback:
+                    return on_block_callback(verification)
+                raise ActionBlockedError(verification)
+
+            # Store the receipt in a context attribute if possible
+            result = fn(*args, **kwargs)
+            return result
+
+        # Attach reference to verification check on the wrapper
+        wrapper.__vizier_client__ = viz_client  # type: ignore
+        return wrapper
+
+    return decorator

vizier_guard-0.3.0/src/vizier/integrations/__init__.py

@@ -0,0 +1,4 @@
+from .langchain import VizierLangChainToolGuard
+from .crewai import VizierCrewAIToolGuard
+
+__all__ = ["VizierLangChainToolGuard", "VizierCrewAIToolGuard"]

vizier_guard-0.3.0/src/vizier/integrations/crewai.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+from typing import Any, Callable, Dict, List, Optional
+
+from ..client import VizierClient
+from ..models import VerificationResponse
+
+class VizierCrewAIToolGuard:
+    """
+    CrewAI Tool wrapper. Protects agents in CrewAI from unauthorized or out-of-budget actions.
+    """
+
+    def __init__(
+        self,
+        tool: Any,
+        client: Optional[VizierClient] = None,
+        max_amount: Optional[float] = None,
+        allowed_targets: Optional[List[str]] = None,
+        agent_id: str = "crewai_agent",
+        principal_id: str = "principal",
+    ):
+        self.tool = tool
+        self.client = client or VizierClient()
+        self.max_amount = max_amount
+        self.allowed_targets = allowed_targets
+        self.agent_id = agent_id
+        self.principal_id = principal_id
+
+        self.name = getattr(tool, "name", "guarded_tool")
+        self.description = getattr(tool, "description", "")
+
+    def _run(self, *args: Any, **kwargs: Any) -> Any:
+        params: Dict[str, Any] = kwargs if kwargs else (args[0] if args and isinstance(args[0], dict) else {"input": args})
+        target = str(params.get("target") or self.name)
+
+        res = self.client.check(
+            action_type=self.name,
+            target=target,
+            parameters=params,
+            allowed_actions=[self.name],
+            max_amount=self.max_amount,
+            allowed_targets=self.allowed_targets,
+            agent_id=self.agent_id,
+            principal_id=self.principal_id,
+        )
+
+        if not res.is_allowed:
+            return f"Action blocked by Vizier ({res.decision}): {res.explanation}. Reason codes: {res.reason_codes}"
+
+        if hasattr(self.tool, "_run"):
+            return self.tool._run(*args, **kwargs)
+        if callable(self.tool):
+            return self.tool(*args, **kwargs)
+        return "Tool executed"

vizier_guard-0.3.0/src/vizier/integrations/langchain.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+from typing import Any, Callable, Dict, List, Optional
+
+from ..client import VizierClient
+from ..decorators import ActionBlockedError
+from ..models import VerificationResponse
+
+class VizierLangChainToolGuard:
+    """
+    Wrapper for LangChain BaseTool instances.
+    Intercepts tool calls, verifies with Vizier, and blocks execution on BLOCK or REVIEW.
+    """
+
+    def __init__(
+        self,
+        tool: Any,
+        client: Optional[VizierClient] = None,
+        allowed_actions: Optional[List[str]] = None,
+        max_amount: Optional[float] = None,
+        currency: Optional[str] = None,
+        allowed_targets: Optional[List[str]] = None,
+        blocked_targets: Optional[List[str]] = None,
+        agent_id: str = "langchain_agent",
+        principal_id: str = "principal",
+    ):
+        self.tool = tool
+        self.client = client or VizierClient()
+        self.allowed_actions = allowed_actions or [getattr(tool, "name", "tool")]
+        self.max_amount = max_amount
+        self.currency = currency
+        self.allowed_targets = allowed_targets
+        self.blocked_targets = blocked_targets
+        self.agent_id = agent_id
+        self.principal_id = principal_id
+
+        # Preserve LangChain tool metadata
+        self.name = getattr(tool, "name", "guarded_tool")
+        self.description = getattr(tool, "description", "")
+        self.args_schema = getattr(tool, "args_schema", None)
+
+    def _verify(self, tool_input: Any) -> VerificationResponse:
+        params: Dict[str, Any]
+        if isinstance(tool_input, dict):
+            params = tool_input
+        else:
+            params = {"input": tool_input}
+
+        target = str(params.get("target") or params.get("destination") or self.name)
+        return self.client.check(
+            action_type=self.name,
+            target=target,
+            parameters=params,
+            allowed_actions=self.allowed_actions,
+            max_amount=self.max_amount,
+            currency=self.currency,
+            allowed_targets=self.allowed_targets,
+            blocked_targets=self.blocked_targets,
+            agent_id=self.agent_id,
+            principal_id=self.principal_id,
+        )
+
+    def run(self, *args: Any, **kwargs: Any) -> Any:
+        tool_input = kwargs if kwargs else (args[0] if args else {})
+        res = self._verify(tool_input)
+        if not res.is_allowed:
+            return f"Error: Tool execution blocked by security policy ({res.decision}): {res.explanation}"
+        return self.tool.run(*args, **kwargs)
+
+    async def arun(self, *args: Any, **kwargs: Any) -> Any:
+        tool_input = kwargs if kwargs else (args[0] if args else {})
+        res = self._verify(tool_input)
+        if not res.is_allowed:
+            return f"Error: Tool execution blocked by security policy ({res.decision}): {res.explanation}"
+        return await self.tool.arun(*args, **kwargs)
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        return self.run(*args, **kwargs)

vizier_guard-0.3.0/src/vizier/models.py

@@ -0,0 +1,177 @@
+from __future__ import annotations
+from dataclasses import dataclass, field, asdict
+from typing import Any, Dict, List, Literal, Optional, Union
+
+Decision = Literal["ALLOW", "REVIEW", "BLOCK"]
+Source = Literal["a2a", "mcp", "rest", "internal", "unknown"]
+AuthorityProvenance = Literal["principal_signed", "trusted_integration", "unverified"]
+
+@dataclass
+class Agent:
+    id: str
+    owner: Optional[str] = None
+
+@dataclass
+class Principal:
+    id: str
+
+@dataclass
+class Action:
+    type: str
+    target: str
+    parameters: Dict[str, Any] = field(default_factory=dict)
+    is_reversible: Optional[bool] = None
+
+@dataclass
+class AuthorityConstraints:
+    max_amount: Optional[float] = None
+    currency: Optional[str] = None
+    allowed_targets: Optional[List[str]] = None
+    blocked_targets: Optional[List[str]] = None
+    allowed_sensitive_actions: Optional[List[str]] = None
+    require_review_for_irreversible: Optional[bool] = None
+
+@dataclass
+class Authority:
+    allowed_actions: List[str] = field(default_factory=list)
+    constraints: AuthorityConstraints = field(default_factory=AuthorityConstraints)
+
+@dataclass
+class Context:
+    request_id: Optional[str] = None
+    timestamp: Optional[str] = None
+    source: Source = "rest"
+
+@dataclass
+class VerificationRequest:
+    agent: Agent
+    principal: Optional[Principal]
+    action: Action
+    authority: Authority
+    context: Context = field(default_factory=Context)
+    grant: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        d: Dict[str, Any] = {
+            "agent": {"id": self.agent.id, "owner": self.agent.owner},
+            "principal": {"id": self.principal.id} if self.principal else None,
+            "action": {
+                "type": self.action.type,
+                "target": self.action.target,
+                "parameters": self.action.parameters,
+            },
+            "authority": {
+                "allowed_actions": self.authority.allowed_actions,
+                "constraints": {},
+            },
+            "context": {
+                "request_id": self.context.request_id,
+                "timestamp": self.context.timestamp,
+                "source": self.context.source,
+            },
+        }
+        if self.action.is_reversible is not None:
+            d["action"]["is_reversible"] = self.action.is_reversible
+
+        c = self.authority.constraints
+        cd = d["authority"]["constraints"]
+        if c.max_amount is not None:
+            cd["max_amount"] = c.max_amount
+        if c.currency is not None:
+            cd["currency"] = c.currency
+        if c.allowed_targets is not None:
+            cd["allowed_targets"] = c.allowed_targets
+        if c.blocked_targets is not None:
+            cd["blocked_targets"] = c.blocked_targets
+        if c.allowed_sensitive_actions is not None:
+            cd["allowed_sensitive_actions"] = c.allowed_sensitive_actions
+        if c.require_review_for_irreversible is not None:
+            cd["require_review_for_irreversible"] = c.require_review_for_irreversible
+
+        if self.grant is not None:
+            d["grant"] = self.grant
+        return d
+
+@dataclass
+class PolicyResult:
+    rule_id: str
+    result: Literal["PASS", "REVIEW", "FAIL"]
+    reason_code: Optional[str]
+    details: Dict[str, Any] = field(default_factory=dict)
+
+@dataclass
+class ReceiptGrant:
+    jti: str
+    issuer: str
+    subject: str
+    key_id: str
+    expires_at: str
+
+@dataclass
+class Receipt:
+    id: str
+    created_at: str
+    request_hash: str
+    decision: Decision
+    risk_score: float
+    policy_rule_ids: List[str]
+    reason_codes: List[str]
+    authority_provenance: AuthorityProvenance
+    grant: Optional[ReceiptGrant] = None
+
+@dataclass
+class VerificationResponse:
+    decision: Decision
+    risk_score: float
+    reason_codes: List[str]
+    explanation: str
+    policy_results: List[PolicyResult]
+    receipt: Receipt
+
+    @property
+    def is_allowed(self) -> bool:
+        return self.decision == "ALLOW"
+
+    @property
+    def is_blocked(self) -> bool:
+        return self.decision == "BLOCK"
+
+    @property
+    def requires_review(self) -> bool:
+        return self.decision == "REVIEW"
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> VerificationResponse:
+        results = [
+            PolicyResult(
+                rule_id=r["rule_id"],
+                result=r["result"],
+                reason_code=r.get("reason_code"),
+                details=r.get("details", {}),
+            )
+            for r in data.get("policy_results", [])
+        ]
+        rc = data["receipt"]
+        grant_data = rc.get("grant")
+        grant = ReceiptGrant(**grant_data) if grant_data else None
+
+        receipt = Receipt(
+            id=rc["id"],
+            created_at=rc["created_at"],
+            request_hash=rc["request_hash"],
+            decision=rc["decision"],
+            risk_score=float(rc["risk_score"]),
+            policy_rule_ids=list(rc.get("policy_rule_ids", [])),
+            reason_codes=list(rc.get("reason_codes", [])),
+            authority_provenance=rc.get("authority_provenance", "unverified"),
+            grant=grant,
+        )
+
+        return cls(
+            decision=data["decision"],
+            risk_score=float(data["risk_score"]),
+            reason_codes=list(data.get("reason_codes", [])),
+            explanation=data.get("explanation", ""),
+            policy_results=results,
+            receipt=receipt,
+        )

vizier_guard-0.3.0/src/vizier_guard.egg-info/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: vizier-guard
+Version: 0.3.0
+Summary: Deterministic authorization and audit guard for AI agent actions
+Author-email: Vassiliy Lakhonin <vassiliy.lakhonin@gmail.com>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/vassiliylakhonin/vizier
+Project-URL: Documentation, https://vizier.vassiliy-lakhonin.workers.dev/docs
+Project-URL: Repository, https://github.com/vassiliylakhonin/vizier
+Keywords: ai,agents,security,authorization,guardrails,langchain,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+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: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: pydantic
+Requires-Dist: pydantic>=2.0; extra == "pydantic"
+Provides-Extra: httpx
+Requires-Dist: httpx>=0.24.0; extra == "httpx"
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1.0; extra == "langchain"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0.0; extra == "test"
+
+# Vizier Guard (Python SDK)
+
+Deterministic Authorization & Audit Firewall for AI Agent Actions.
+
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.9+-green.svg)](pyproject.toml)
+
+Vizier is an ultra-low-latency (sub-2ms) deterministic policy kernel that evaluates proposed AI agent actions before they cause external side-effects (payments, database mutations, external messages, code execution, worker deployments).
+
+---
+
+## Installation
+
+```bash
+pip install vizier-guard
+```
+
+Zero external dependencies required out of the box (uses Python standard library).
+
+---
+
+## 30-Second Quickstart: `@vizier_guard` Decorator
+
+Wrap any dangerous tool or Python function with deterministic policy rules:
+
+```python
+from vizier import VizierClient, vizier_guard
+
+client = VizierClient(
+    base_url="https://vizier.vassiliy-lakhonin.workers.dev",
+    api_key="your-vizier-api-key"
+)
+
+@vizier_guard(
+    client=client,
+    action_type="purchase",
+    max_amount=500.0,
+    currency="USD",
+    allowed_targets=["approved-hotel.com", "supplier-corp.com"]
+)
+def book_hotel(amount: float, target: str):
+    # This only runs if Vizier returns ALLOW
+    print(f"Booking confirmed at {target} for ${amount}")
+    return {"status": "booked", "amount": amount}
+
+# Allowed: $350 <= $500 to approved target
+book_hotel(amount=350.0, target="approved-hotel.com")
+
+# Blocked: $1200 > $500 (raises ActionBlockedError)
+book_hotel(amount=1200.0, target="approved-hotel.com")
+```
+
+---
+
+## LangChain Integration
+
+Protect any LangChain `BaseTool` from agent hallucinations or runaway spending:
+
+```python
+from vizier import VizierClient
+from vizier.integrations.langchain import VizierLangChainToolGuard
+from langchain_community.tools import DuckDuckGoSearchRun
+
+client = VizierClient(api_key="...")
+
+# Wrap your tool
+safe_search = VizierLangChainToolGuard(
+    tool=DuckDuckGoSearchRun(),
+    client=client,
+    allowed_actions=["search"],
+    max_amount=0.0
+)
+
+# Pass safe_search into your LangChain or LangGraph agent
+agent = create_react_agent(llm, tools=[safe_search])
+```
+
+---
+
+## CrewAI Integration
+
+```python
+from vizier.integrations.crewai import VizierCrewAIToolGuard
+
+guarded_tool = VizierCrewAIToolGuard(
+    tool=my_dangerous_payment_tool,
+    max_amount=250.0,
+    agent_id="finance_agent"
+)
+```
+
+---
+
+## Standalone Verification
+
+```python
+from vizier import VizierClient
+
+vizier = VizierClient(api_key="...")
+
+decision = vizier.check(
+    action_type="deploy_worker",
+    target="worker:payment-service",
+    parameters={"git_commit": "abcdef123..."},
+    allowed_actions=["deploy_worker"]
+)
+
+if decision.is_allowed:
+    print(f"Action permitted! Receipt ID: {decision.receipt.id}")
+else:
+    print(f"Action rejected ({decision.decision}): {decision.explanation}")
+```

vizier_guard-0.3.0/src/vizier_guard.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+README.md
+pyproject.toml
+src/vizier/__init__.py
+src/vizier/canonical.py
+src/vizier/client.py
+src/vizier/decorators.py
+src/vizier/models.py
+src/vizier/integrations/__init__.py
+src/vizier/integrations/crewai.py
+src/vizier/integrations/langchain.py
+src/vizier_guard.egg-info/PKG-INFO
+src/vizier_guard.egg-info/SOURCES.txt
+src/vizier_guard.egg-info/dependency_links.txt
+src/vizier_guard.egg-info/requires.txt
+src/vizier_guard.egg-info/top_level.txt
+tests/test_canonical.py
+tests/test_decorators.py
+tests/test_models.py

vizier_guard-0.3.0/src/vizier_guard.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

vizier_guard-0.3.0/src/vizier_guard.egg-info/requires.txt

@@ -0,0 +1,12 @@
+
+[httpx]
+httpx>=0.24.0
+
+[langchain]
+langchain-core>=0.1.0
+
+[pydantic]
+pydantic>=2.0
+
+[test]
+pytest>=7.0.0

vizier_guard-0.3.0/src/vizier_guard.egg-info/top_level.txt

@@ -0,0 +1 @@
+vizier

vizier_guard-0.3.0/tests/test_canonical.py

@@ -0,0 +1,31 @@
+import pytest
+from vizier.canonical import canonicalize, sha256_canonical_json
+
+def test_primitives():
+    assert canonicalize(None) == "null"
+    assert canonicalize(True) == "true"
+    assert canonicalize(False) == "false"
+    assert canonicalize(42) == "42"
+    assert canonicalize("hello") == '"hello"'
+
+def test_dict_key_sorting():
+    d1 = {"z": 1, "a": 2, "m": 3}
+    d2 = {"a": 2, "m": 3, "z": 1}
+    assert canonicalize(d1) == '{"a":2,"m":3,"z":1}'
+    assert canonicalize(d1) == canonicalize(d2)
+    assert sha256_canonical_json(d1) == sha256_canonical_json(d2)
+
+def test_nested_structures():
+    data = {
+        "user": {"name": "alice", "id": 1},
+        "tags": ["prod", "agent"],
+        "active": True
+    }
+    expected = '{"active":true,"tags":["prod","agent"],"user":{"id":1,"name":"alice"}}'
+    assert canonicalize(data) == expected
+
+def test_hash_consistency():
+    obj = {"action": "purchase", "amount": 100}
+    h = sha256_canonical_json(obj)
+    assert len(h) == 64
+    assert h == sha256_canonical_json({"amount": 100, "action": "purchase"})

vizier_guard-0.3.0/tests/test_decorators.py

@@ -0,0 +1,75 @@
+import pytest
+from unittest.mock import MagicMock
+
+from vizier import vizier_guard, ActionBlockedError, VerificationResponse
+from vizier.models import Receipt, PolicyResult
+
+def make_mock_response(decision: str, explanation: str = "ok"):
+    return VerificationResponse(
+        decision=decision,
+        risk_score=0.0 if decision == "ALLOW" else 0.8,
+        reason_codes=[] if decision == "ALLOW" else ["AMOUNT_LIMIT_EXCEEDED"],
+        explanation=explanation,
+        policy_results=[
+            PolicyResult(rule_id="amount.limit", result="PASS" if decision == "ALLOW" else "FAIL", reason_code=None)
+        ],
+        receipt=Receipt(
+            id="vrf_test_123",
+            created_at="2026-09-11T00:00:00Z",
+            request_hash="a" * 64,
+            decision=decision,
+            risk_score=0.0,
+            policy_rule_ids=["amount.limit"],
+            reason_codes=[],
+            authority_provenance="trusted_integration",
+        ),
+    )
+
+def test_decorator_allows_valid_action():
+    mock_client = MagicMock()
+    mock_client.check.return_value = make_mock_response("ALLOW")
+
+    @vizier_guard(client=mock_client, action_type="test_action", max_amount=100.0)
+    def do_work(amount: float, target: str):
+        return f"worked on {target} with {amount}"
+
+    result = do_work(50.0, target="server-1")
+    assert result == "worked on server-1 with 50.0"
+    assert mock_client.check.called
+    kwargs = mock_client.check.call_args[1]
+    assert kwargs["action_type"] == "test_action"
+    assert kwargs["target"] == "server-1"
+    assert kwargs["max_amount"] == 100.0
+
+def test_decorator_blocks_invalid_action():
+    mock_client = MagicMock()
+    mock_client.check.return_value = make_mock_response("BLOCK", explanation="Amount exceeded limit")
+
+    @vizier_guard(client=mock_client, action_type="transfer", max_amount=100.0)
+    def transfer(amount: float, target: str):
+        return "transferred"
+
+    with pytest.raises(ActionBlockedError) as exc_info:
+        transfer(500.0, target="untrusted_account")
+
+    assert "blocked by Vizier (BLOCK)" in str(exc_info.value)
+    assert exc_info.value.response.decision == "BLOCK"
+
+def test_decorator_callback_mode():
+    mock_client = MagicMock()
+    mock_client.check.return_value = make_mock_response("REVIEW", explanation="Manual approval required")
+
+    def handle_block(resp):
+        return {"status": "paused_for_human", "decision": resp.decision}
+
+    @vizier_guard(
+        client=mock_client,
+        action_type="delete_db",
+        on_block="callback",
+        on_block_callback=handle_block
+    )
+    def delete_data(db_name: str):
+        return "deleted"
+
+    res = delete_data("prod_users")
+    assert res == {"status": "paused_for_human", "decision": "REVIEW"}

vizier_guard-0.3.0/tests/test_models.py

@@ -0,0 +1,59 @@
+import pytest
+from vizier.models import (
+    Agent, Principal, Action, Authority, AuthorityConstraints,
+    VerificationRequest, VerificationResponse
+)
+
+def test_verification_request_to_dict():
+    req = VerificationRequest(
+        agent=Agent(id="ag_1", owner="corp"),
+        principal=Principal(id="corp"),
+        action=Action(type="deploy", target="worker:1", parameters={"v": 2}),
+        authority=Authority(
+            allowed_actions=["deploy"],
+            constraints=AuthorityConstraints(max_amount=50.0, currency="USD", allowed_targets=["worker:1"])
+        )
+    )
+    d = req.to_dict()
+    assert d["agent"] == {"id": "ag_1", "owner": "corp"}
+    assert d["principal"] == {"id": "corp"}
+    assert d["action"]["type"] == "deploy"
+    assert d["authority"]["allowed_actions"] == ["deploy"]
+    assert d["authority"]["constraints"]["max_amount"] == 50.0
+    assert d["authority"]["constraints"]["allowed_targets"] == ["worker:1"]
+    assert d["context"]["source"] == "rest"
+
+def test_verification_response_from_dict():
+    raw = {
+        "decision": "ALLOW",
+        "risk_score": 0.0,
+        "reason_codes": [],
+        "explanation": "Action allowed",
+        "policy_results": [
+            {"rule_id": "rule.1", "result": "PASS", "reason_code": None, "details": {}}
+        ],
+        "receipt": {
+            "id": "vrf_1",
+            "created_at": "2026-09-11T00:00:00Z",
+            "request_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+            "decision": "ALLOW",
+            "risk_score": 0.0,
+            "policy_rule_ids": ["rule.1"],
+            "reason_codes": [],
+            "authority_provenance": "principal_signed",
+            "grant": {
+                "jti": "g_1",
+                "issuer": "corp",
+                "subject": "ag_1",
+                "key_id": "k_1",
+                "expires_at": "2026-09-12T00:00:00Z"
+            }
+        }
+    }
+    resp = VerificationResponse.from_dict(raw)
+    assert resp.is_allowed is True
+    assert resp.is_blocked is False
+    assert resp.receipt.id == "vrf_1"
+    assert resp.receipt.grant is not None
+    assert resp.receipt.grant.key_id == "k_1"
+    assert resp.policy_results[0].rule_id == "rule.1"