@privacyscrubber/sdk 2.3.7 → 2.4.0

package/examples/python-bridge/fastapi_example.py

@@ -0,0 +1,206 @@
+"""
+PrivacyScrubber ZTDS - FastAPI Zero-Egress Proxy & Microservice Example
+
+Demonstrates:
+1. Lifespan event management with AsyncPrivacyScrubber (zero-overhead async IPC).
+2. /v1/chat/completions OpenAI-compatible proxy endpoint:
+   - Sanitizes raw user prompts before cloud transmission (zero cleartext PII egress).
+   - Re-hydrates LLM answers with original PII in local RAM before responding to the user.
+3. Dedicated microservice endpoints: /api/v1/sanitize and /api/v1/restore.
+4. Direct runnable simulation if uvicorn/fastapi are not installed in the local environment.
+
+Run:
+  python3 fastapi_example.py
+  # or: uvicorn fastapi_example:app --port 8000 --reload
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import sys
+from typing import Any, Dict, List, Optional
+
+from privacyscrubber import AsyncPrivacyScrubber, SanitizeResult
+
+try:
+    from fastapi import FastAPI, Depends, HTTPException, Header, Request, Response
+    from fastapi.responses import JSONResponse
+    from pydantic import BaseModel, Field
+    FASTAPI_AVAILABLE = True
+except ImportError:
+    FASTAPI_AVAILABLE = False
+
+
+# Pydantic Schemas (if FastAPI is available)
+if FASTAPI_AVAILABLE:
+    class ChatMessage(BaseModel):
+        role: str
+        content: str
+
+    class ChatCompletionRequest(BaseModel):
+        model: str = "gpt-4o"
+        messages: List[ChatMessage]
+        temperature: Optional[float] = 0.7
+        profile: Optional[str] = "General"
+
+    class SanitizeRequest(BaseModel):
+        text: str
+        profile: Optional[str] = "General"
+        detect_secrets: Optional[bool] = False
+
+    class RestoreRequest(BaseModel):
+        text: str
+        token_map: Optional[Dict[str, str]] = None
+
+    # Global Scrubber Instance
+    scrubber = AsyncPrivacyScrubber(default_profile="General")
+
+    app = FastAPI(
+        title="PrivacyScrubber ZTDS Sidecar Proxy",
+        description="Zero-Trust Data Sanitization & In-Memory PII Shield for LLM Pipelines",
+        version="2.4.0"
+    )
+
+    @app.on_event("startup")
+    async def startup_event():
+        await scrubber.start()
+        print("[ZTDS Sidecar] PrivacyScrubber async sidecar initialized.")
+
+    @app.on_event("shutdown")
+    async def shutdown_event():
+        await scrubber.close()
+        print("[ZTDS Sidecar] PrivacyScrubber async sidecar closed.")
+
+    @app.get("/health")
+    async def health_check():
+        status = await scrubber.status()
+        ping = await scrubber.ping()
+        return {
+            "status": "healthy",
+            "engine": ping.get("engine"),
+            "version": ping.get("version"),
+            "license_tier": status.get("license_tier"),
+            "memory": status.get("memory_usage")
+        }
+
+    @app.post("/v1/chat/completions")
+    async def chat_completions_proxy(
+        req: ChatCompletionRequest,
+        response: Response
+    ):
+        """
+        OpenAI-compatible chat completion proxy:
+        1. Intercepts incoming messages and sanitizes PII in client RAM (<0.5ms).
+        2. Simulates (or forwards) transmission of tokenized prompt to cloud LLM.
+        3. Restores tokens in the model response before returning to authorized client.
+        """
+        session_token_map: Dict[str, str] = {}
+        scrubbed_messages: List[Dict[str, str]] = []
+
+        # 1. Sanitize incoming conversation messages
+        for msg in req.messages:
+            if msg.role in ("user", "system"):
+                res = await scrubber.sanitize(msg.content, profile=req.profile)
+                scrubbed_messages.append({"role": msg.role, "content": res.sanitized})
+                session_token_map.update(res.token_map)
+            else:
+                scrubbed_messages.append({"role": msg.role, "content": msg.content})
+
+        # 2. Simulated LLM call over tokenized text (Zero Cleartext PII Egress)
+        # In production, forward `scrubbed_messages` to httpx.post("https://api.openai.com/v1/chat/completions")
+        user_query = scrubbed_messages[-1]["content"] if scrubbed_messages else ""
+        simulated_llm_reply = (
+            f"Understood. I have recorded your intake for {user_query}. "
+            f"Verification receipt confirmed for compliance audit."
+        )
+
+        # 3. Restore cleartext tokens in RAM before sending back to user
+        restored = await scrubber.restore(simulated_llm_reply, token_map=session_token_map)
+
+        response.headers["X-ZTDS-Status"] = "ENFORCED"
+        response.headers["X-ZTDS-Tokens-Masked"] = str(len(session_token_map))
+
+        return {
+            "id": "chatcmpl-ztds-simulated",
+            "object": "chat.completion",
+            "model": req.model,
+            "choices": [
+                {
+                    "index": 0,
+                    "message": {
+                        "role": "assistant",
+                        "content": restored.restored_text
+                    },
+                    "finish_reason": "stop"
+                }
+            ],
+            "ztds_meta": {
+                "tokens_masked": len(session_token_map),
+                "zero_egress_verified": True
+            }
+        }
+
+    @app.post("/api/v1/sanitize")
+    async def sanitize_endpoint(req: SanitizeRequest):
+        res = await scrubber.sanitize(
+            req.text,
+            profile=req.profile,
+            detect_secrets=req.detect_secrets
+        )
+        return {
+            "sanitized": res.sanitized,
+            "token_map": res.token_map,
+            "count": res.count,
+            "execution_ms": res.execution_ms,
+            "telemetry": res.telemetry,
+            "audit_receipt": res.audit_receipt
+        }
+
+    @app.post("/api/v1/restore")
+    async def restore_endpoint(req: RestoreRequest):
+        res = await scrubber.restore(req.text, token_map=req.token_map)
+        return {
+            "restored_text": res.restored_text,
+            "restored_count": res.restored_count
+        }
+
+
+# Direct executable simulation runner
+async def run_simulation():
+    print("=== PrivacyScrubber ZTDS: FastAPI Zero-Egress Proxy Simulation ===\n")
+    async with AsyncPrivacyScrubber(default_profile="Healthcare") as ps:
+        # 1. Health check
+        ping = await ps.ping()
+        print(f"1. Connected to ZTDS Engine: {ping.get('engine')} v{ping.get('version')}")
+
+        # 2. Incoming sensitive user payload
+        raw_user_prompt = "Escalation for Patient Sarah Connor (DOB: 1984-05-12, SSN: 000-11-2222, email: sconnor@cyberdyne.org) complaining of acute migraines."
+        print(f"\n2. Incoming Request Payload (Local Client RAM):\n   \"{raw_user_prompt}\"")
+
+        # 3. Pre-LLM Sanitization
+        sanitize_result = await ps.sanitize(raw_user_prompt, profile="Healthcare")
+        print(f"\n3. Sanitized Prompt for Cloud LLM Transmission (Zero PII Egress):\n   \"{sanitize_result.sanitized}\"")
+        print(f"   Tokens Masked: {sanitize_result.count} | Latency: {sanitize_result.execution_ms:.2f}ms")
+        print(f"   Token Map (RAM Only): {json.dumps(sanitize_result.token_map)}")
+
+        # 4. Cloud LLM synthesizes response operating ONLY on surrogate tokens
+        simulated_cloud_ai_response = (
+            f"Based on clinical records for [NAME_1] (ID [ID_1], contact [EMAIL_1]), "
+            f"recommend standard migraine protocol and follow-up consultation."
+        )
+        print(f"\n4. Raw Cloud LLM Output (Contains Only Tokens):\n   \"{simulated_cloud_ai_response}\"")
+
+        # 5. Post-LLM In-Memory Token Restoration
+        restored = await ps.restore(simulated_cloud_ai_response, token_map=sanitize_result.token_map)
+        print(f"\n5. Restored Response for Authorized User (Local RAM Only):\n   \"{restored.restored_text}\"")
+
+        print("\n=== Simulation Complete: 0 Bytes PII Transmitted to Cloud LLM ===")
+
+
+if __name__ == "__main__":
+    if FASTAPI_AVAILABLE and "uvicorn" in sys.modules:
+        import uvicorn
+        uvicorn.run(app, host="0.0.0.0", port=8000)
+    else:
+        asyncio.run(run_simulation())

package/examples/python-bridge/langchain_adapter.py

@@ -0,0 +1,20 @@
+"""
+PrivacyScrubber ZTDS Adapter for LangChain
+Zero-Trust Data Sanitization & Local PII Shield for LangChain Pipelines.
+"""
+
+from __future__ import annotations
+
+from privacyscrubber.langchain import (
+    ZTDSCallbackHandler,
+    ZTDSDocumentTransformer,
+    create_ztds_lcel_runnables,
+    LANGCHAIN_INSTALLED,
+)
+
+__all__ = [
+    "ZTDSCallbackHandler",
+    "ZTDSDocumentTransformer",
+    "create_ztds_lcel_runnables",
+    "LANGCHAIN_INSTALLED",
+]

package/examples/python-bridge/langchain_example.py

@@ -0,0 +1,126 @@
+"""
+PrivacyScrubber ZTDS - LangChain RAG & Callback Handler Example
+
+Demonstrates:
+1. ZTDSCallbackHandler: Automatic pre-LLM prompt tokenization and post-LLM response restoration.
+2. ZTDSDocumentTransformer: Sanitizing document page_content and metadata before vector embedding.
+3. LCEL (LangChain Expression Language) pipeline with create_ztds_lcel_runnables().
+4. Operates 100% in local memory with zero cloud network leakage.
+
+Run:
+  python3 langchain_example.py
+"""
+
+from __future__ import annotations
+
+import json
+from privacyscrubber import PrivacyScrubberClient
+from langchain_adapter import (
+    ZTDSCallbackHandler,
+    ZTDSDocumentTransformer,
+    create_ztds_lcel_runnables,
+    LANGCHAIN_INSTALLED
+)
+
+
+def run_document_transformer_demo(client: PrivacyScrubberClient):
+    print("--- 1. Vector RAG Document Pre-Ingestion Guard ---")
+
+    class SimpleDoc:
+        def __init__(self, page_content: str, metadata: dict):
+            self.page_content = page_content
+            self.metadata = metadata
+
+    raw_docs = [
+        SimpleDoc(
+            page_content="Lead Account Executive Bob Vance (bob.vance@vancerefrigeration.com, phone 570-555-0143) closed contract under EIN 12-3456789.",
+            metadata={"doc_id": "contract_901", "author": "bob.vance@vancerefrigeration.com", "source": "HubSpot"}
+        ),
+        SimpleDoc(
+            page_content="Customer escalation from Alice Morgan (amorgan@investcorp.com): wire transfer of $250,000 sent to IBAN GB29XAAA14151617181920.",
+            metadata={"doc_id": "wire_902", "author": "amorgan@investcorp.com", "source": "Zendesk"}
+        )
+    ]
+
+    transformer = ZTDSDocumentTransformer(
+        scrubber=client,
+        profile="Financial",
+        sensitive_metadata_keys=["author"]
+    )
+
+    sanitized_docs = transformer.transform_documents(raw_docs)
+
+    print("Sanitized Documents (Ready for Vector Embeddings):")
+    for doc in sanitized_docs:
+        print(f"  [ID: {doc.metadata['doc_id']}]")
+        print(f"  Content:  {doc.page_content}")
+        print(f"  Metadata: {doc.metadata}\n")
+
+
+def run_callback_handler_demo(client: PrivacyScrubberClient):
+    print("--- 2. ZTDS Callback Handler (Pre/Post LLM Interceptor) ---")
+
+    handler = ZTDSCallbackHandler(scrubber=client, profile="Financial", verbose=True)
+
+    # Simulated LangChain run:
+    # 1. Outgoing prompt before transmission
+    test_prompt = ["Analyze fraud risk for customer David Miller (SSN 987-65-4321, account # 4400-1122-3344-5566)."]
+    print(f"Prompt Before Interception:\n  \"{test_prompt[0]}\"")
+
+    handler.on_llm_start(serialized={}, prompts=test_prompt, run_id="run_abc123")
+    print(f"Prompt Sent to Cloud LLM:\n  \"{test_prompt[0]}\"")
+
+    # 2. Simulated LLM answer generated over tokens
+    class MockGeneration:
+        def __init__(self, text):
+            self.text = text
+
+    class MockLLMResult:
+        def __init__(self, text):
+            self.generations = [[MockGeneration(text)]]
+
+    simulated_cloud_ai_reply = (
+        "Fraud analysis for customer [NAME_1] (Tax ID [ID_1], account [ID_2]): "
+        "No anomalous velocity detected over the past 30 days."
+    )
+    mock_result = MockLLMResult(simulated_cloud_ai_reply)
+
+    print(f"\nRaw Cloud LLM Output:\n  \"{mock_result.generations[0][0].text}\"")
+
+    # 3. Intercept and restore cleartext in RAM
+    handler.on_llm_end(mock_result, run_id="run_abc123")
+    print(f"Restored Output in Local RAM:\n  \"{mock_result.generations[0][0].text}\"\n")
+
+
+def run_lcel_pipeline_demo(client: PrivacyScrubberClient):
+    print("--- 3. LCEL Pipeline Integration ---")
+    scrub_fn, restore_fn = create_ztds_lcel_runnables(client, profile="General")
+
+    user_query = "Please generate an introduction email for John Smith at john.smith@acme.com."
+    print(f"Input:    \"{user_query}\"")
+
+    # Step 1: Pre-scrub
+    sanitized_prompt = scrub_fn(user_query)
+    print(f"Sanitized: \"{sanitized_prompt}\"")
+
+    # Step 2: Simulated LLM
+    mock_ai_output = f"Subject: Welcome! Dear [NAME_1], we are thrilled to connect with you at [EMAIL_1]."
+    print(f"AI Output: \"{mock_ai_output}\"")
+
+    # Step 3: Post-restore
+    final_output = restore_fn(mock_ai_output)
+    print(f"Restored:  \"{final_output}\"\n")
+
+
+def main():
+    print("=== PrivacyScrubber ZTDS: LangChain Integration Suite ===\n")
+    with PrivacyScrubberClient(default_profile="Financial") as client:
+        run_document_transformer_demo(client)
+        run_callback_handler_demo(client)
+        run_lcel_pipeline_demo(client)
+
+    print("=== Zero Cleartext PII Egress Verified Across All Pipelines ===")
+
+
+if __name__ == "__main__":
+    main()

package/examples/python-bridge/llamaindex_example.py

@@ -0,0 +1,103 @@
+"""
+PrivacyScrubber ZTDS - LlamaIndex Node & RAG Transformation Example
+
+Demonstrates:
+1. Sanitizing text nodes before vector embedding (VectorStoreIndex).
+2. Preserving semantic search accuracy with deterministic surrogate tokens.
+3. In-memory response rehydration upon retrieval and answer synthesis.
+4. 100% in-memory RAM execution. Zero external egress.
+
+Run:
+  python3 llamaindex_example.py
+"""
+
+from __future__ import annotations
+
+import copy
+from typing import Any, Dict, List, Optional
+from privacyscrubber import PrivacyScrubberClient
+
+
+class ZTDSNodeTransformer:
+    """
+    Transforms LlamaIndex TextNodes or Document chunks before vector database insertion.
+    """
+
+    def __init__(
+        self,
+        scrubber: Optional[PrivacyScrubberClient] = None,
+        profile: str = "General"
+    ) -> None:
+        self.scrubber = scrubber or PrivacyScrubberClient(default_profile=profile)
+        self.profile = profile
+
+    def transform_nodes(self, nodes: List[Any]) -> List[Any]:
+        """Sanitizes text and metadata in place or creates clean copies."""
+        transformed: List[Any] = []
+        for node in nodes:
+            node_copy = copy.deepcopy(node)
+            text = getattr(node_copy, "text", "")
+            if text and isinstance(text, str):
+                res = self.scrubber.sanitize(text, profile=self.profile)
+                node_copy.text = res.sanitized
+
+            metadata = getattr(node_copy, "metadata", None)
+            if isinstance(metadata, dict):
+                for k, v in list(metadata.items()):
+                    if isinstance(v, str):
+                        res_m = self.scrubber.sanitize(v, profile=self.profile)
+                        metadata[k] = res_m.sanitized
+
+            transformed.append(node_copy)
+        return transformed
+
+
+def main():
+    print("=== PrivacyScrubber ZTDS: LlamaIndex Ingestion Demo ===\n")
+
+    class MockTextNode:
+        def __init__(self, node_id: str, text: str, metadata: Dict[str, Any]):
+            self.node_id = node_id
+            self.text = text
+            self.metadata = metadata
+
+    raw_nodes = [
+        MockTextNode(
+            node_id="chunk_001",
+            text="Employee review for Marcus Brody. Personal mobile is +1-202-555-0199, email mbrody@state.gov.",
+            metadata={"department": "Public Relations", "reviewer": "Marcus Brody"}
+        ),
+        MockTextNode(
+            node_id="chunk_002",
+            text="Compensation plan approved under Tax ID 99-8877665 for total salary $185,000.",
+            metadata={"department": "Executive Payroll", "approver": "Finance Board"}
+        )
+    ]
+
+    with PrivacyScrubberClient(default_profile="HR") as client:
+        transformer = ZTDSNodeTransformer(scrubber=client, profile="HR")
+
+        print("1. Raw LlamaIndex Chunks:")
+        for n in raw_nodes:
+            print(f"   [{n.node_id}] {n.text}")
+
+        sanitized_nodes = transformer.transform_nodes(raw_nodes)
+
+        print("\n2. Sanitized Chunks (Safe for Vector Store Ingestion):")
+        for n in sanitized_nodes:
+            print(f"   [{n.node_id}] {n.text}")
+            print(f"   Metadata: {n.metadata}")
+
+        # 3. Simulate Query Engine Synthesis
+        query_output = "Based on retrieved node [chunk_001], [NAME_1] ([EMAIL_1]) has verified contact info."
+        print(f"\n3. Query Engine Output (LLM generated over surrogate tokens):\n   \"{query_output}\"")
+
+        # 4. In-Memory Restoration
+        restored = client.restore(query_output)
+        print(f"\n4. Final Answer Restored in Local RAM:\n   \"{restored.restored_text}\"")
+
+    print("\n=== LlamaIndex RAG Pipeline Verification Complete ===")
+
+
+if __name__ == "__main__":
+    main()

package/examples/python-bridge/privacyscrubber/__init__.py

@@ -0,0 +1,42 @@
+"""
+PrivacyScrubber - Zero-Trust Data Sanitization & In-Memory PII Shield for Python.
+
+RFC v1.0 standard compliant.
+100% in-memory client-side RAM execution. Zero external network egress.
+Sub-millisecond latency (<1ms).
+"""
+
+from __future__ import annotations
+
+from privacyscrubber.client import (
+    PrivacyScrubberClient,
+    PrivacyScrubber,
+    AsyncPrivacyScrubberClient,
+    AsyncPrivacyScrubber,
+)
+from privacyscrubber.types import (
+    SanitizeResult,
+    RestoreResult,
+    ObjectSanitizeResult,
+)
+from privacyscrubber.exceptions import (
+    PrivacyScrubberError,
+    PrivacyScrubberLicenseError,
+)
+
+__version__ = "2.4.0"
+__author__ = "Ilya Sibiryakov (BrandMeWeb)"
+__license__ = "Proprietary"
+
+__all__ = [
+    "PrivacyScrubberClient",
+    "PrivacyScrubber",
+    "AsyncPrivacyScrubberClient",
+    "AsyncPrivacyScrubber",
+    "SanitizeResult",
+    "RestoreResult",
+    "ObjectSanitizeResult",
+    "PrivacyScrubberError",
+    "PrivacyScrubberLicenseError",
+    "__version__",
+]