volidator-python 0.1.0__tar.gz

volidator_python-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,82 @@
+# 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/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=61.0.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "volidator-python"
+version = "0.1.0"
+description = "Zero-knowledge, server-blind audit logging for Python and agentic workflows."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "cryptography>=3.4.0",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.18.0",
+    "httpx>=0.20.0",
+]
+langchain = [
+    "langchain-core>=0.1.0",
+]
+llamaindex = [
+    "llama-index-core>=0.10.0",
+]

volidator_python-0.1.0/setup.cfg

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

volidator_python-0.1.0/tests/test_client.py

@@ -0,0 +1,158 @@
+import asyncio
+import sys
+import time
+from unittest.mock import MagicMock, patch
+import pytest
+from volidator.client import VolidatorClient, agent_context_store, logical_clock_store
+from volidator.plugins.langchain import VolidatorLangChainHandler
+from volidator.plugins.llamaindex import VolidatorLlamaIndexHandler
+
+
+def test_prepare_log_entry():
+    client = VolidatorClient(
+        api_key="val_live_123",
+        encryption_key="vol-dek-0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
+        redact_keys=["actor", "metadata.ssn"],
+        reference_keys=["target"]
+    )
+    
+    payload = {
+        "actor": "sensitive_user_pii",
+        "action": "user.login",
+        "target": {"id": "workspace_999", "pii": "sensitive_workspace_name"},
+        "metadata": {
+            "ssn": "123-456-789",
+            "public_info": "hello"
+        }
+    }
+    
+    entry = client.prepare_log_entry(payload)
+    
+    # 1. Blind indexes should be computed from the plain raw PII values
+    active_hashed_key = client._get_hashed_key("v1")
+    expected_actor_blind = client.generate_blind_index("sensitive_user_pii", active_hashed_key)
+    expected_target_blind = client.generate_blind_index("sensitive_workspace_name", active_hashed_key)
+    
+    assert entry["actorBlindIndex"] == expected_actor_blind
+    assert entry["targetBlindIndex"] == expected_target_blind
+    
+    # 2. Decrypted payload should have redacted actor and JIT reference target
+    decrypted = client.decrypt_payload(entry["encryptedPayload"])
+    assert decrypted["actor"] == "[REDACTED:actor]"
+    assert decrypted["target"] == "[REF:workspace_999]"
+    assert decrypted["metadata"]["ssn"] == "[REDACTED:ssn]"
+    assert decrypted["metadata"]["public_info"] == "hello"
+
+
+def test_contextvar_token_reset():
+    client = VolidatorClient(
+        api_key="val_live_123",
+        encryption_key="vol-dek-0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+    )
+    
+    # Start clean
+    assert agent_context_store.get() is None
+    
+    with client.run_in_agent_context({"traceId": "t-1", "toolName": "search"}):
+        assert agent_context_store.get() == {"traceId": "t-1", "toolName": "search"}
+        
+    # Must reset back to None
+    assert agent_context_store.get() is None
+
+
+def test_trace_from_langchain_reset():
+    client = VolidatorClient(
+        api_key="val_live_123",
+        encryption_key="vol-dek-0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+    )
+    
+    assert agent_context_store.get() is None
+    
+    langchain_config = {
+        "run_id": "lang-run-uuid-123",
+        "configurable": {"thread_id": "graph-thread-456"}
+    }
+    
+    with client.trace_from_langchain(langchain_config):
+        # run_id has priority
+        assert agent_context_store.get() == {"traceId": "lang-run-uuid-123"}
+        
+    assert agent_context_store.get() is None
+
+
+def test_logical_clock_context():
+    client = VolidatorClient(
+        api_key="val_live_123",
+        encryption_key="vol-dek-0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+    )
+    
+    assert logical_clock_store.get() is None
+    
+    with client.run_in_clock_context(10):
+        assert logical_clock_store.get() == {"clock": 10}
+        clock1 = client.get_and_increment_clock()
+        assert clock1 == 11
+        assert logical_clock_store.get() == {"clock": 11}
+        
+    assert logical_clock_store.get() is None
+
+
+def test_batcher_size_and_flush():
+    client = VolidatorClient(
+        api_key="val_live_123",
+        encryption_key="vol-dek-0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+    )
+    
+    mock_log_batch = MagicMock(return_value={"accepted": 3, "rejected": 0})
+    client.log_batch = mock_log_batch
+    
+    batcher = client.batcher({"autoFlushCount": 3})
+    
+    batcher.push({"action": "act-1"})
+    batcher.push({"action": "act-2"})
+    assert batcher.size() == 2
+    
+    # Pushing 3rd should trigger flush automatically in a background thread
+    batcher.push({"action": "act-3"})
+    
+    # Wait briefly for background thread to run flush
+    time.sleep(0.1)
+    
+    assert batcher.size() == 0
+    mock_log_batch.assert_called_once()
+
+
+def test_missing_plugin_dependencies():
+    client = VolidatorClient(
+        api_key="val_live_123",
+        encryption_key="vol-dek-0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+    )
+
+    # Test LangChain ImportError
+    with patch("volidator.plugins.langchain.HAS_LANGCHAIN", False):
+        with pytest.raises(RuntimeError) as exc_info:
+            VolidatorLangChainHandler(client, actor="usr_alice")
+        assert "langchain-core is not installed" in str(exc_info.value)
+
+    # Test LlamaIndex ImportError
+    with patch("volidator.plugins.llamaindex.HAS_LLAMAINDEX", False):
+        with pytest.raises(RuntimeError) as exc_info:
+            VolidatorLlamaIndexHandler(client, actor="usr_alice")
+        assert "llama-index-core is not installed" in str(exc_info.value)
+
+
+@pytest.mark.asyncio
+async def test_urllib_async_fallback_no_httpx():
+    client = VolidatorClient(
+        api_key="val_live_123",
+        encryption_key="vol-dek-0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+    )
+    
+    # Mocking HAS_HTTPX as False
+    with patch("volidator.client.HAS_HTTPX", False):
+        with patch.object(client, "_fetch_with_retry", return_value=b"ok") as mock_fetch:
+            payload = {"actor": "usr_123", "action": "test"}
+            success = await client.log_async(payload)
+            
+            assert success is True
+            mock_fetch.assert_called_once()

volidator_python-0.1.0/tests/test_cryptography.py

@@ -0,0 +1,52 @@
+import datetime
+from volidator.client import VolidatorClient, canonicalize
+
+
+def test_blind_indexing_parity():
+    # Test case matching Node SDK output
+    client = VolidatorClient(
+        api_key="val_live_123",
+        encryption_key="vol-dek-0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+    )
+    
+    # In JS: key hash is SHA256 of "vol-dek-0123456789abcdef..."
+    # HMAC-SHA256 of "usr_12345" using that hashed key
+    active_hashed_key = client._get_hashed_key("v1")
+    blind_index = client.generate_blind_index("usr_12345", active_hashed_key)
+    
+    # Expected output matches the exact SHA256/HMAC layout
+    assert len(blind_index) == 64
+    assert isinstance(blind_index, str)
+
+
+def test_encryption_decryption_roundtrip():
+    client = VolidatorClient(
+        api_key="val_live_123",
+        encryption_key="vol-dek-0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+    )
+    
+    payload = {"actor": "usr_123", "action": "test.action", "target": "workspace_abc"}
+    encrypted_str = client.encrypt_payload(payload)
+    
+    assert encrypted_str.startswith("v1:")
+    
+    decrypted = client.decrypt_payload(encrypted_str)
+    assert decrypted == payload
+
+
+def test_canonicalize():
+    # Sort keys
+    assert canonicalize({"b": 2, "a": 1}) == '{"a":1,"b":2}'
+    
+    # Remove undefined (None) values in dicts
+    assert canonicalize({"x": None, "y": 1}) == '{"x":null,"y":1}'
+    
+    # Replace None with null in arrays
+    assert canonicalize([None, 1]) == '[null,1]'
+    
+    # Handle primitive lists
+    assert canonicalize(["foo", "bar"]) == '["foo","bar"]'
+    
+    # Handle dates
+    dt = datetime.datetime(2026, 7, 11, 5, 39, 10, tzinfo=datetime.timezone.utc)
+    assert canonicalize(dt) == '"2026-07-11T05:39:10.000Z"'

volidator_python-0.1.0/volidator/__init__.py

@@ -0,0 +1,5 @@
+from .client import VolidatorClient
+from .compliance import VolidatorCompliance
+from .agent import VolidatorAgent
+
+__all__ = ["VolidatorClient", "VolidatorCompliance", "VolidatorAgent"]

volidator_python-0.1.0/volidator/agent.py

@@ -0,0 +1,137 @@
+from typing import Any
+
+
+class VolidatorAgent:
+    def __init__(self, client):
+        self.client = client
+
+    def _log_agent(
+        self,
+        action: str,
+        eu_ai_act: str,
+        nist_ai_rmf: str,
+        soc2_control: str,
+        iso_control: str,
+        payload: dict[str, Any]
+    ) -> bool:
+        core_fields = {
+            "actor",
+            "actorId",
+            "target",
+            "targetId",
+            "tenant",
+            "tenantId",
+            "metadata",
+            "context",
+            "telemetry",
+            "req",
+            "traceId",
+            "spanId",
+            "parentSpanId",
+        }
+        
+        # Enriched metadata includes any additional keyword args passed at root level
+        agent_data = {k: v for k, v in payload.items() if k not in core_fields}
+        metadata = payload.get("metadata") or {}
+
+        enriched_metadata = {
+            **metadata,
+            **agent_data,
+            "eu_ai_act": eu_ai_act,
+            "nist_ai_rmf": nist_ai_rmf,
+            "soc2_control": soc2_control,
+            "iso27001": iso_control,
+        }
+
+        # Build base payload structure
+        base_payload = {k: v for k, v in payload.items() if k in core_fields}
+        base_payload["action"] = action
+        base_payload["metadata"] = enriched_metadata
+
+        # AI logs have a larger 5MB metadata allowance
+        return self.client.log(base_payload, max_meta_override=5242880)
+
+    async def _log_agent_async(
+        self,
+        action: str,
+        eu_ai_act: str,
+        nist_ai_rmf: str,
+        soc2_control: str,
+        iso_control: str,
+        payload: dict[str, Any]
+    ) -> bool:
+        core_fields = {
+            "actor",
+            "actorId",
+            "target",
+            "targetId",
+            "tenant",
+            "tenantId",
+            "metadata",
+            "context",
+            "telemetry",
+            "req",
+            "traceId",
+            "spanId",
+            "parentSpanId",
+        }
+        
+        agent_data = {k: v for k, v in payload.items() if k not in core_fields}
+        metadata = payload.get("metadata") or {}
+
+        enriched_metadata = {
+            **metadata,
+            **agent_data,
+            "eu_ai_act": eu_ai_act,
+            "nist_ai_rmf": nist_ai_rmf,
+            "soc2_control": soc2_control,
+            "iso27001": iso_control,
+        }
+
+        base_payload = {k: v for k, v in payload.items() if k in core_fields}
+        base_payload["action"] = action
+        base_payload["metadata"] = enriched_metadata
+
+        return await self.client.log_async(base_payload, max_meta_override=5242880)
+
+    # 1. tool_call / tool_call_async
+    def tool_call(self, payload: dict[str, Any]) -> bool:
+        return self._log_agent("agent.tool_call", "Article 12", "MANAGE 2.2", "CC6.6", "A.12.4.1", payload)
+
+    async def tool_call_async(self, payload: dict[str, Any]) -> bool:
+        return await self._log_agent_async("agent.tool_call", "Article 12", "MANAGE 2.2", "CC6.6", "A.12.4.1", payload)
+
+    # 2. decision / decision_async
+    def decision(self, payload: dict[str, Any]) -> bool:
+        return self._log_agent("agent.decision", "Article 12 & 13", "GOVERN 1.7", "CC6.2", "A.18.1.3", payload)
+
+    async def decision_async(self, payload: dict[str, Any]) -> bool:
+        return await self._log_agent_async("agent.decision", "Article 12 & 13", "GOVERN 1.7", "CC6.2", "A.18.1.3", payload)
+
+    # 3. escalation / escalation_async
+    def escalation(self, payload: dict[str, Any]) -> bool:
+        return self._log_agent("agent.escalation", "Article 14", "GOVERN 5.1", "CC6.3", "A.6.1.2", payload)
+
+    async def escalation_async(self, payload: dict[str, Any]) -> bool:
+        return await self._log_agent_async("agent.escalation", "Article 14", "GOVERN 5.1", "CC6.3", "A.6.1.2", payload)
+
+    # 4. anomaly / anomaly_async
+    def anomaly(self, payload: dict[str, Any]) -> bool:
+        return self._log_agent("agent.anomaly", "Article 9", "MANAGE 2.4", "CC7.2", "A.16.1.2", payload)
+
+    async def anomaly_async(self, payload: dict[str, Any]) -> bool:
+        return await self._log_agent_async("agent.anomaly", "Article 9", "MANAGE 2.4", "CC7.2", "A.16.1.2", payload)
+
+    # 5. refusal / refusal_async
+    def refusal(self, payload: dict[str, Any]) -> bool:
+        return self._log_agent("agent.refusal", "Article 5", "GOVERN 1.1", "CC6.8", "A.18.1.3", payload)
+
+    async def refusal_async(self, payload: dict[str, Any]) -> bool:
+        return await self._log_agent_async("agent.refusal", "Article 5", "GOVERN 1.1", "CC6.8", "A.18.1.3", payload)
+
+    # 6. handoff / handoff_async
+    def handoff(self, payload: dict[str, Any]) -> bool:
+        return self._log_agent("agent.handoff", "Article 12", "MAP 1.6", "CC6.6", "A.12.4.1", payload)
+
+    async def handoff_async(self, payload: dict[str, Any]) -> bool:
+        return await self._log_agent_async("agent.handoff", "Article 12", "MAP 1.6", "CC6.6", "A.12.4.1", payload)