volidator-python 0.1.0__py3-none-any.whl

volidator/compliance.py

@@ -0,0 +1,70 @@
+from typing import Any, Optional
+
+
+class VolidatorCompliance:
+    def __init__(self, client):
+        self.client = client
+
+    def _log_with_control(
+        self,
+        action: str,
+        soc2_control: str,
+        iso_control: str,
+        payload: dict[str, Any],
+        max_meta_override: Optional[int] = None
+    ) -> bool:
+        metadata = payload.get("metadata") or {}
+        enriched_metadata = {
+            **metadata,
+            "soc2_control": soc2_control,
+            "iso27001": iso_control,
+        }
+        full_payload = {**payload, "action": action, "metadata": enriched_metadata}
+        return self.client.log(full_payload, max_meta_override)
+
+    async def _log_with_control_async(
+        self,
+        action: str,
+        soc2_control: str,
+        iso_control: str,
+        payload: dict[str, Any],
+        max_meta_override: Optional[int] = None
+    ) -> bool:
+        metadata = payload.get("metadata") or {}
+        enriched_metadata = {
+            **metadata,
+            "soc2_control": soc2_control,
+            "iso27001": iso_control,
+        }
+        full_payload = {**payload, "action": action, "metadata": enriched_metadata}
+        return await self.client.log_async(full_payload, max_meta_override)
+
+    def access_revoked(self, payload: dict[str, Any]) -> bool:
+        return self._log_with_control("access.revoked", "CC6.1", "A.9.2.6", payload)
+
+    async def access_revoked_async(self, payload: dict[str, Any]) -> bool:
+        return await self._log_with_control_async("access.revoked", "CC6.1", "A.9.2.6", payload)
+
+    def access_granted(self, payload: dict[str, Any]) -> bool:
+        return self._log_with_control("access.granted", "CC6.1", "A.9.2.1", payload)
+
+    async def access_granted_async(self, payload: dict[str, Any]) -> bool:
+        return await self._log_with_control_async("access.granted", "CC6.1", "A.9.2.1", payload)
+
+    def data_exported(self, payload: dict[str, Any]) -> bool:
+        return self._log_with_control("data.exported", "CC6.6", "A.12.4.1", payload)
+
+    async def data_exported_async(self, payload: dict[str, Any]) -> bool:
+        return await self._log_with_control_async("data.exported", "CC6.6", "A.12.4.1", payload)
+
+    def system_config_changed(self, payload: dict[str, Any]) -> bool:
+        return self._log_with_control("system.config_changed", "CC6.2", "A.12.1.2", payload)
+
+    async def system_config_changed_async(self, payload: dict[str, Any]) -> bool:
+        return await self._log_with_control_async("system.config_changed", "CC6.2", "A.12.1.2", payload)
+
+    def mfa_enabled(self, payload: dict[str, Any]) -> bool:
+        return self._log_with_control("mfa.enabled", "CC6.3", "A.9.4.2", payload)
+
+    async def mfa_enabled_async(self, payload: dict[str, Any]) -> bool:
+        return await self._log_with_control_async("mfa.enabled", "CC6.3", "A.9.4.2", payload)

volidator/plugins/__init__.py

@@ -0,0 +1 @@
+# Volidator framework integration plugins

volidator/plugins/langchain.py

@@ -0,0 +1,115 @@
+import time
+from typing import Any, Optional
+from ..client import agent_context_store
+
+try:
+    from langchain_core.callbacks import BaseCallbackHandler  # type: ignore
+    HAS_LANGCHAIN = True
+except ImportError:
+    class BaseCallbackHandler:
+        pass
+    HAS_LANGCHAIN = False
+
+
+class VolidatorLangChainHandler(BaseCallbackHandler):
+    def __init__(self, client, actor: str, tenant: Optional[str] = None):
+        if not HAS_LANGCHAIN:
+            raise RuntimeError(
+                "langchain-core is not installed. Please install it with 'pip install langchain-core' to use this handler."
+            )
+        super().__init__()
+        self.client = client
+        self.actor = actor
+        self.tenant = tenant
+        self.run_map = {}
+        self._tokens = {}
+
+    def on_tool_start(
+        self,
+        serialized: dict[str, Any],
+        input_str: str,
+        *,
+        run_id: Any,
+        parent_run_id: Optional[Any] = None,
+        **kwargs: Any
+    ) -> None:
+        tool_name = serialized.get("name") or "unnamed_tool"
+        rationale = f"Executing tool {tool_name} with input: {input_str[:100]}"
+
+        # Bind agent context in contextvars
+        token = agent_context_store.set({
+            "traceId": str(run_id),
+            "toolName": tool_name,
+            "rationale": rationale,
+        })
+        self._tokens[str(run_id)] = token
+
+        self.run_map[str(run_id)] = {
+            "toolName": tool_name,
+            "toolInput": {"input": input_str},
+            "startTime": time.time(),
+        }
+
+    def on_tool_end(
+        self,
+        output: str,
+        *,
+        run_id: Any,
+        parent_run_id: Optional[Any] = None,
+        **kwargs: Any
+    ) -> None:
+        # Prevent token leaking
+        token = self._tokens.pop(str(run_id), None)
+        if token:
+            agent_context_store.reset(token)
+
+        run = self.run_map.pop(str(run_id), None)
+        if not run:
+            return
+
+        latency_ms = int((time.time() - run["startTime"]) * 1000)
+
+        try:
+            self.client.agent.tool_call({
+                "actor": self.actor,
+                "tenant": self.tenant,
+                "toolName": run["toolName"],
+                "toolInput": run["toolInput"],
+                "toolOutput": {"output": str(output)},
+                "latencyMs": latency_ms,
+                "success": True,
+            })
+        except Exception:
+            pass
+
+    def on_tool_error(
+        self,
+        error: BaseException,
+        *,
+        run_id: Any,
+        parent_run_id: Optional[Any] = None,
+        **kwargs: Any
+    ) -> None:
+        # Prevent token leaking
+        token = self._tokens.pop(str(run_id), None)
+        if token:
+            agent_context_store.reset(token)
+
+        run = self.run_map.pop(str(run_id), None)
+        if not run:
+            return
+
+        latency_ms = int((time.time() - run["startTime"]) * 1000)
+
+        try:
+            self.client.agent.tool_call({
+                "actor": self.actor,
+                "tenant": self.tenant,
+                "toolName": run["toolName"],
+                "toolInput": run["toolInput"],
+                "toolOutput": {"error": str(error)},
+                "latencyMs": latency_ms,
+                "success": False,
+            })
+        except Exception:
+            pass

volidator/plugins/llamaindex.py

@@ -0,0 +1,96 @@
+import time
+from typing import Any, Optional
+from ..client import agent_context_store
+
+try:
+    from llama_index.core.callbacks.base_handler import BaseCallbackHandler  # type: ignore
+    from llama_index.core.callbacks.schema import CBEventType  # type: ignore
+    HAS_LLAMAINDEX = True
+except ImportError:
+    class BaseCallbackHandler:
+        pass
+    class CBEventType:
+        TOOL = "tool"
+    HAS_LLAMAINDEX = False
+
+
+class VolidatorLlamaIndexHandler(BaseCallbackHandler):
+    def __init__(self, client, actor: str, tenant: Optional[str] = None):
+        if not HAS_LLAMAINDEX:
+            raise RuntimeError(
+                "llama-index-core is not installed. Please install it with 'pip install llama-index-core' to use this handler."
+            )
+        # Call llama-index BaseCallbackHandler constructor if it exists
+        if hasattr(BaseCallbackHandler, "__init__"):
+            super().__init__(event_starts_to_ignore=[], event_ends_to_ignore=[])
+        self.client = client
+        self.actor = actor
+        self.tenant = tenant
+        self.run_map = {}
+        self._tokens = {}
+
+    def on_event_start(
+        self,
+        event_type: CBEventType,
+        payload: Optional[dict[str, Any]] = None,
+        event_id: str = "",
+        **kwargs: Any
+    ) -> str:
+        if event_type == CBEventType.TOOL:
+            tool_name = "unnamed_tool"
+            tool_input = {}
+            if payload and "tool" in payload:
+                tool_name = payload["tool"].name
+                tool_input = payload.get("input", {})
+
+            rationale = f"Executing LlamaIndex tool {tool_name}"
+
+            token = agent_context_store.set({
+                "traceId": event_id,
+                "toolName": tool_name,
+                "rationale": rationale,
+            })
+            self._tokens[event_id] = token
+
+            self.run_map[event_id] = {
+                "toolName": tool_name,
+                "toolInput": tool_input,
+                "startTime": time.time(),
+            }
+        return event_id
+
+    def on_event_end(
+        self,
+        event_type: CBEventType,
+        payload: Optional[dict[str, Any]] = None,
+        event_id: str = "",
+        **kwargs: Any
+    ) -> None:
+        token = self._tokens.pop(event_id, None)
+        if token:
+            agent_context_store.reset(token)
+
+        if event_type == CBEventType.TOOL:
+            run = self.run_map.pop(event_id, None)
+            if not run:
+                return
+
+            latency_ms = int((time.time() - run["startTime"]) * 1000)
+
+            tool_output = {}
+            success = True
+            if payload and "response" in payload:
+                tool_output = {"output": str(payload["response"])}
+
+            try:
+                self.client.agent.tool_call({
+                    "actor": self.actor,
+                    "tenant": self.tenant,
+                    "toolName": run["toolName"],
+                    "toolInput": run["toolInput"],
+                    "toolOutput": tool_output,
+                    "latencyMs": latency_ms,
+                    "success": success,
+                })
+            except Exception:
+                pass

volidator_python-0.1.0.dist-info/METADATA

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: volidator-python
+Version: 0.1.0
+Summary: Zero-knowledge, server-blind audit logging for Python and agentic workflows.
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: cryptography>=3.4.0
+Provides-Extra: test
+Requires-Dist: pytest>=7.0.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.18.0; extra == "test"
+Requires-Dist: httpx>=0.20.0; extra == "test"
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1.0; extra == "langchain"
+Provides-Extra: llamaindex
+Requires-Dist: llama-index-core>=0.10.0; extra == "llamaindex"
+
+# Volidator Python SDK
+
+**Zero-knowledge, server-blind audit logging for Python and autonomous AI agentic workflows.**
+
+Volidator encrypts every log entry locally — on your server — before sending it. The Volidator backend stores only ciphertext and blind indexes. Your plaintext data never leaves your infrastructure unencrypted.
+
+---
+
+## Installation
+
+```bash
+pip install volidator-python
+```
+
+---
+
+## Environment Setup
+
+Generate a secure 32-byte encryption key (64 hex characters) with the `vol-dek-` prefix:
+```bash
+python -c "import os; print('vol-dek-' + os.urandom(32).hex())"
+```
+
+Add secrets to your environment:
+```bash
+VOLIDATOR_API_KEY="val_live_xxxxxxxx..."
+VOLIDATOR_ENCRYPTION_KEY="vol-dek-xxxxxxxx..."
+```
+
+---
+
+## Quick Start
+
+```python
+import os
+from volidator import VolidatorClient
+
+volidator = VolidatorClient(
+    api_key=os.environ["VOLIDATOR_API_KEY"],
+    encryption_key=os.environ["VOLIDATOR_ENCRYPTION_KEY"]
+)
+
+# Log a system event
+volidator.log({
+    "actor": "usr_12345",
+    "action": "user.login.success",
+    "target": "workspace_abc789",
+    "metadata": {
+        "device": "Workstation",
+        "auth_provider": "Okta"
+    }
+})
+```
+
+---
+
+## AI Agent Auditing (`VolidatorAgent`)
+
+For auditing LLM chains, agent reasoning loops, and multi-agent handoffs, use the `volidator.agent` namespace:
+
+```python
+# Log a decision made autonomously by the model
+volidator.agent.decision({
+    "actor": "writer-agent-v1",
+    "traceId": "run-xyz-456",
+    "decision": "publish_article",
+    "rationale": "grammar check and safety alignments passed verification checks",
+    "confidenceScore": 0.98,
+    "modelId": "gpt-4o"
+})
+
+# Log a tool execution call
+volidator.agent.tool_call({
+    "actor": "search-agent-v1",
+    "traceId": "run-xyz-456",
+    "toolName": "web_search",
+    "toolInput": {"query": "AI regulation"},
+    "toolOutput": {"results": [...]},
+    "success": True,
+    "latencyMs": 245
+})
+```

volidator_python-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+volidator/__init__.py,sha256=-r28T-iGsOZO_GhUrcFCVLo961UKb1Mug-_N8LdLAeQ,186
+volidator/agent.py,sha256=cHnP4cKIn_CtpXeyMeoshYUhrDprgusgPFZdhmoaE6Q,4982
+volidator/client.py,sha256=0NalVvOg5yJKraytUQsNgt7X5VPsipQe4HOS5CpaxYI,44745
+volidator/compliance.py,sha256=_Ci4C4QT4kOopLW4K6fWMjyUUSgxho-RxDHIwOFRcyU,2877
+volidator/plugins/__init__.py,sha256=HvRs6AxjXeGeLI8exhFMRWH_Wdpn0dh49LT8VHWZ8f8,42
+volidator/plugins/langchain.py,sha256=b1HTK51PXHH6SqS4skpQa2EbThHr7b3VhVTwsTMF_HQ,3329
+volidator/plugins/llamaindex.py,sha256=4YrmM9yLfXx-FWSOJHnIQnxdr99qCc9Ce33unvz8_-Y,3169
+volidator_python-0.1.0.dist-info/METADATA,sha256=1RkJviwt0SVRuOIAsoFdsYS0CDrBwXm9jY609fiYI7o,2781
+volidator_python-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+volidator_python-0.1.0.dist-info/top_level.txt,sha256=7taXS7XldS3KWgMj_tly0_mG0o4wUN-rpEhfluSs3U4,10
+volidator_python-0.1.0.dist-info/RECORD,,

volidator_python-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

volidator_python-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+volidator