@privacyscrubber/sdk 2.3.9 → 2.4.0

package/examples/python-bridge/README.md

@@ -0,0 +1,265 @@
+# PrivacyScrubber Python Bridge (ZTDS Zero-Egress Sidecar)
+
+Sub-millisecond, zero-dependency Python adapter for **PrivacyScrubber SDK** (`@privacyscrubber/sdk`).
+
+Enforces **Zero-Trust Data Sanitization (ZTDS RFC v1.0)** across Python AI and data pipelines:
+- **FastAPI / Flask / Django**: Pre-LLM sanitization and post-LLM in-memory rehydration.
+- **LangChain**: `ZTDSCallbackHandler` and `ZTDSDocumentTransformer`.
+- **LlamaIndex**: Pre-embedding chunk and metadata sanitization.
+- **Raw OpenAI / Anthropic / Gemini SDKs**: Direct string and dictionary tokenization.
+
+---
+
+## Architectural Comparison: PrivacyScrubber vs. Microsoft Presidio
+
+| Metric | Microsoft Presidio | PrivacyScrubber ZTDS Bridge |
+| :--- | :--- | :--- |
+| **Inference Latency** | ~35ms – 65ms per request | **~0.15ms – 0.40ms per request (<1ms SLA)** |
+| **Memory Footprint** | 1.8 GB – 3.2 GB RAM (PyTorch / spaCy) | **< 25 MB RAM (Zero PyTorch / zero spaCy)** |
+| **Python Dependencies** | `presidio-analyzer`, `presidio-anonymizer`, `spacy`, `torch` | **0 Dependencies (Python Standard Library Only)** |
+| **Round-Trip Re-hydration** | Non-trivial (custom hash table mapping required) | **Native 100% Round-Trip (`client.restore()`)** |
+| **Pre-Configured Profiles** | Basic PII only (requires custom YAML recognizers) | **30 Built-in Industry Profiles (HIPAA, Financial, Legal, HR, etc.)** |
+| **Network Egress** | Potential telemetry unless air-gapped | **0.00 Bytes Network Egress (RAM-only volatile mapping)** |
+| **Container Startup** | 15 – 30 seconds model loading time | **< 100 milliseconds** |
+
+---
+
+---
+
+## Installation & Prerequisites
+
+1. Ensure **Node.js** (v18+) and **Python** (3.8+) are available on your system.
+2. Install `@privacyscrubber/sdk`:
+   ```bash
+   npm install @privacyscrubber/sdk
+   ```
+3. Install the Python package via `pip`:
+   ```bash
+   # Editable local development:
+   pip install -e npm-sdk/examples/python-bridge
+
+   # Or standard pip install:
+   pip install ./npm-sdk/examples/python-bridge
+   ```
+   *Note: Zero external Python dependencies are required.*
+
+---
+
+## Command Line Interface (CLI)
+
+The package bundles a terminal CLI utility `privacyscrubber` (alias: `ps-bridge`):
+
+```bash
+# Check ZTDS engine status and uptime
+privacyscrubber ping
+privacyscrubber status
+
+# Sanitize text directly
+privacyscrubber sanitize "Customer Alice Cooper (alice@hospital.org)" --profile Healthcare
+
+# Pipe text through standard input:
+echo "Analyze wire for John Doe john@corp.com" | privacyscrubber sanitize
+
+# Output structured JSON with tokens and compliance telemetry:
+privacyscrubber sanitize "Patient John Doe" --json
+
+# Restore surrogate tokens:
+privacyscrubber restore "Patient [NAME_1]" --token-map '{"[NAME_1]": "John Doe"}'
+```
+
+---
+
+## Quickstart
+
+### 1. Synchronous Client
+
+```python
+from privacyscrubber import PrivacyScrubber
+
+# Initialize sidecar in local RAM (auto-starts daemon)
+with PrivacyScrubber(default_profile="General") as ps:
+    # Sanitize prompt before sending to cloud LLM
+    result = ps.sanitize("Please review intake for patient John Doe (john@acme.com, phone +1-555-0199).")
+    
+    print("Sanitized Prompt:", result.sanitized)
+    # Output: Please review intake for patient [NAME_1] ([EMAIL_1], phone [PHONE_1]).
+    
+    # Simulate LLM operating strictly on tokens
+    ai_response = "I have noted records for [NAME_1] ([EMAIL_1])."
+    
+    # Restore cleartext tokens in local RAM
+    restored = ps.restore(ai_response)
+    print("Restored Answer:", restored.restored_text)
+    # Output: I have noted records for John Doe (john@acme.com).
+```
+
+### 2. Asynchronous Client (FastAPI / asyncio)
+
+```python
+import asyncio
+from privacyscrubber import AsyncPrivacyScrubber
+
+async def main():
+    async with AsyncPrivacyScrubber(default_profile="Healthcare") as ps:
+        res = await ps.sanitize("Patient Alice Cooper (DOB: 1984-05-12, SSN: 000-11-2222).")
+        print("Sanitized:", res.sanitized)
+        # Patient [NAME_1] (DOB: [DATE_1], SSN: [ID_1]).
+        
+        restored = await ps.restore("Prescription confirmed for [NAME_1].")
+        print("Restored:", restored.restored_text)
+
+asyncio.run(main())
+```
+
+---
+
+## Framework Integrations
+
+### FastAPI Zero-Egress Proxy (`fastapi_example.py`)
+
+Run an OpenAI-compatible proxy that guarantees no raw PII ever touches OpenAI or external model APIs:
+
+```python
+from fastapi import FastAPI
+from privacyscrubber import AsyncPrivacyScrubber
+
+app = FastAPI()
+scrubber = AsyncPrivacyScrubber()
+
+@app.on_event("startup")
+async def on_startup():
+    await scrubber.start()
+
+@app.on_event("shutdown")
+async def on_shutdown():
+    await scrubber.close()
+
+@app.post("/v1/chat/completions")
+async def chat_proxy(payload: dict):
+    # 1. Sanitize user prompt in client memory (<0.2ms)
+    messages = payload.get("messages", [])
+    user_prompt = messages[-1]["content"]
+    
+    sanitized = await scrubber.sanitize(user_prompt)
+    messages[-1]["content"] = sanitized.sanitized
+    
+    # 2. Forward sanitized payload to cloud LLM (httpx call)
+    # raw_llm_response = await client.post("https://api.openai.com/v1/chat/completions", json=payload)
+    mock_llm_reply = f"Acknowledged request for {sanitized.sanitized}"
+    
+    # 3. Restore cleartext in RAM before returning to end-user
+    restored = await scrubber.restore(mock_llm_reply, token_map=sanitized.token_map)
+    return {"choices": [{"message": {"role": "assistant", "content": restored.restored_text}}]}
+```
+
+### LangChain (`langchain_adapter.py`)
+
+#### Callback Handler (Transparent Pre/Post LLM Guard)
+```python
+from langchain_openai import ChatOpenAI
+from langchain_adapter import ZTDSCallbackHandler
+
+llm = ChatOpenAI(
+    model="gpt-4o",
+    callbacks=[ZTDSCallbackHandler(profile="Financial")]
+)
+
+# Prompts are automatically sanitized before leaving process memory;
+# LLM outputs are automatically restored before returning to your code.
+response = llm.invoke("What is the credit rating for customer David Miller (SSN 987-65-4321)?")
+print(response.content)
+```
+
+#### Vector Ingestion Guard (Pinecone, Chroma, Qdrant)
+```python
+from langchain_adapter import ZTDSDocumentTransformer
+
+transformer = ZTDSDocumentTransformer(
+    profile="Financial",
+    sensitive_metadata_keys=["customer_email", "account_id"]
+)
+
+# Sanitizes both page_content and sensitive metadata dictionaries
+safe_docs = transformer.transform_documents(raw_docs)
+vector_store.add_documents(safe_docs)
+```
+
+---
+
+## Nested Dictionary & JSON Sanitization
+
+Sanitize complex structured payloads (REST API payloads, MongoDB documents, JSON logs):
+
+```python
+payload = {
+    "user_id": 9012,
+    "customer": {
+        "name": "Sarah Connor",
+        "email": "sconnor@cyberdyne.org",
+        "phones": ["+1-555-0199", "+1-555-0188"]
+    },
+    "status": "active"
+}
+
+# Recursively sanitizes strings, preserving keys and types intact:
+result = ps.sanitize_object(payload)
+print(result.sanitized)
+# {
+#   "user_id": 9012,
+#   "customer": {
+#     "name": "[NAME_1]",
+#     "email": "[EMAIL_1]",
+#     "phones": ["[PHONE_1]", "[PHONE_2]"]
+#   },
+#   "status": "active"
+# }
+
+# Restore structure:
+restored = ps.restore_object(result.sanitized, token_map=result.token_map)
+```
+
+---
+
+## Production Docker Deployment
+
+Deploying Python applications alongside the PrivacyScrubber sidecar in a single multi-runtime container:
+
+```dockerfile
+FROM node:22-bookworm-slim AS node-base
+
+FROM python:3.11-slim-bookworm
+
+# Copy Node.js runtime into Python container
+COPY --from=node-base /usr/local/bin/node /usr/local/bin/node
+COPY --from=node-base /usr/local/lib/node_modules /usr/local/lib/node_modules
+
+WORKDIR /app
+
+# Install SDK bridge
+COPY package*.json ./
+RUN npm install @privacyscrubber/sdk --production
+
+# Install Python requirements
+COPY requirements.txt ./
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+CMD ["uvicorn", "fastapi_example:app", "--host", "0.0.0.0", "--port", "8000"]
+```
+
+---
+
+## Running the Verification Suite
+
+Run all tests, benchmarks, and concurrency assertions:
+
+```bash
+# Automated Test Suite (10 tests, 0.3s)
+python3 test_python_bridge.py
+
+# Interactive Examples
+python3 fastapi_example.py
+python3 langchain_example.py
+python3 llamaindex_example.py
+```

package/examples/python-bridge/bridge_daemon.cjs

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+/**
+ * PrivacyScrubber ZTDS Python Bridge Daemon
+ * 
+ * Provides a low-latency, zero-network-egress stdio NDJSON RPC daemon
+ * for Python, FastAPI, LangChain, and LlamaIndex environments.
+ * 
+ * Communication protocol:
+ * - Request (stdin): Single-line JSON {"id": number|string, "action": string, ...}\n
+ * - Response (stdout): Single-line JSON {"id": number|string, "result": {...}}\n
+ *   or {"id": number|string, "error": {"message": string, ...}}\n
+ * 
+ * Zero external network egress. 100% in-memory RAM execution.
+ */
+
+'use strict';
+
+const readline = require('readline');
+const path = require('path');
+
+// Resolve @privacyscrubber/sdk across local monorepo, parent dirs, cwd, and node_modules
+let sdk;
+const candidatePaths = [
+    process.env.PRIVACYSCRUBBER_SDK_PATH,
+    path.resolve(process.cwd(), 'npm-sdk/index.cjs'),
+    path.resolve(process.cwd(), 'node_modules/@privacyscrubber/sdk'),
+    path.resolve(__dirname, '../../index.cjs'),
+    path.resolve(__dirname, '../index.cjs'),
+    path.resolve(__dirname, './index.cjs'),
+    '@privacyscrubber/sdk'
+];
+
+for (const p of candidatePaths) {
+    if (!p) continue;
+    try {
+        sdk = require(p);
+        break;
+    } catch (e) {
+        // try next candidate
+    }
+}
+
+if (!sdk) {
+    try {
+        const resolved = require.resolve('@privacyscrubber/sdk', { paths: [process.cwd(), __dirname] });
+        sdk = require(resolved);
+    } catch (e2) {}
+}
+
+if (!sdk) {
+    process.stderr.write('Fatal: Could not load @privacyscrubber/sdk or index.cjs\n');
+    process.exit(1);
+}
+
+// Parse initial CLI options
+const args = process.argv.slice(2);
+let initialProfile = process.env.PRIVACYSCRUBBER_PROFILE || 'General';
+let licenseKey = process.env.PRIVACYSCRUBBER_KEY || process.env.PRIVACYSCRUBBER_LICENSE_KEY || '';
+
+for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--profile' && args[i + 1]) {
+        initialProfile = args[++i];
+    } else if (args[i] === '--license-key' && args[i + 1]) {
+        licenseKey = args[++i];
+    }
+}
+
+// Instantiate long-lived engine in local RAM
+const engine = new sdk.PrivacyScrubberEngine({
+    licenseKey,
+    defaultProfile: initialProfile,
+    generateReceipt: true
+});
+
+function sendResponse(id, result, error = null) {
+    const payload = { id };
+    if (error) {
+        payload.error = {
+            message: error.message || String(error),
+            name: error.name || 'Error',
+            tier: error.tier,
+            limit: error.limit,
+            profile: error.profile
+        };
+    } else {
+        payload.result = result;
+    }
+    process.stdout.write(JSON.stringify(payload) + '\n');
+}
+
+// Setup readline interface on stdin
+const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    terminal: false
+});
+
+rl.on('line', (line) => {
+    const trimmed = line.trim();
+    if (!trimmed) return;
+
+    let req;
+    try {
+        req = JSON.parse(trimmed);
+    } catch (parseErr) {
+        sendResponse(null, null, new Error(`Invalid JSON request: ${parseErr.message}`));
+        return;
+    }
+
+    const { id, action } = req;
+
+    try {
+        switch (action) {
+            case 'ping': {
+                sendResponse(id, {
+                    pong: true,
+                    engine: 'PrivacyScrubber ZTDS',
+                    version: '2.4.0',
+                    uptime: process.uptime()
+                });
+                break;
+            }
+
+            case 'sanitize': {
+                const text = req.text || '';
+                const options = {
+                    profile: req.profile || engine.defaultProfile,
+                    detectSecrets: req.detect_secrets ?? req.detectSecrets ?? false,
+                    licenseKey: req.license_key || req.licenseKey || engine.licenseKey,
+                    persistSession: req.persist_session ?? req.persistSession ?? true,
+                    generateReceipt: req.generate_receipt ?? req.generateReceipt ?? true,
+                    customRules: req.custom_rules || req.customRules || [],
+                    ignoreList: req.ignore_list || req.ignoreList || null,
+                    throwOnLimit: req.throw_on_limit ?? req.throwOnLimit ?? true
+                };
+
+                const res = engine.sanitize(text, options);
+                sendResponse(id, {
+                    sanitized: res.scrubbedText,
+                    scrubbed_text: res.scrubbedText,
+                    token_map: res.tokenMap,
+                    matches: res.matches,
+                    count: res.count,
+                    execution_ms: res.executionMs,
+                    telemetry: res.telemetry,
+                    audit_receipt: res.auditReceipt,
+                    license: res.license
+                });
+                break;
+            }
+
+            case 'restore': {
+                const text = req.text || '';
+                const tokenMap = req.token_map || req.tokenMap || null;
+                const res = engine.restore(text, tokenMap);
+                sendResponse(id, {
+                    restored_text: res.restoredText,
+                    restored_count: res.restoredCount
+                });
+                break;
+            }
+
+            case 'sanitize_object': {
+                const data = req.data ?? {};
+                const options = {
+                    profile: req.profile || engine.defaultProfile,
+                    detectSecrets: req.detect_secrets ?? req.detectSecrets ?? false,
+                    licenseKey: req.license_key || req.licenseKey || engine.licenseKey,
+                    customRules: req.custom_rules || req.customRules || [],
+                    throwOnLimit: req.throw_on_limit ?? req.throwOnLimit ?? true
+                };
+
+                const res = sdk.sanitizeObject(data, options);
+                // Also merge into engine sessionMap if requested
+                if (req.persist_session !== false && res.tokenMap) {
+                    Object.assign(engine.sessionMap, res.tokenMap);
+                }
+                sendResponse(id, {
+                    sanitized: res.sanitized,
+                    token_map: res.tokenMap,
+                    count: res.count,
+                    execution_ms: res.executionMs,
+                    telemetry: res.telemetry,
+                    audit_receipt: res.auditReceipt
+                });
+                break;
+            }
+
+            case 'restore_object': {
+                const data = req.data ?? {};
+                const tokenMap = req.token_map || req.tokenMap || engine.sessionMap;
+                const restored = sdk.restoreObject(data, tokenMap);
+                sendResponse(id, {
+                    restored
+                });
+                break;
+            }
+
+            case 'reset_session': {
+                engine.resetSession();
+                sendResponse(id, { success: true });
+                break;
+            }
+
+            case 'mark_false_positive': {
+                const token = req.token;
+                if (!token) {
+                    throw new Error('Missing token argument for mark_false_positive');
+                }
+                const fpRes = engine.markFalsePositive(token);
+                sendResponse(id, fpRes);
+                break;
+            }
+
+            case 'status': {
+                sendResponse(id, {
+                    profile: engine.defaultProfile,
+                    license_tier: engine.license?.tier || 'FREE',
+                    is_pro: engine.license?.isPro || false,
+                    session_tokens_count: Object.keys(engine.sessionMap).length,
+                    ignore_list_size: engine.ignoreList.size,
+                    memory_usage: process.memoryUsage()
+                });
+                break;
+            }
+
+            default:
+                sendResponse(id, null, new Error(`Unknown action: ${action}`));
+                break;
+        }
+    } catch (err) {
+        sendResponse(id, null, err);
+    }
+});
+
+rl.on('close', () => {
+    process.exit(0);
+});
+
+process.on('SIGINT', () => process.exit(0));
+process.on('SIGTERM', () => process.exit(0));