@privacyscrubber/sdk 2.3.7 → 2.4.0

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

@@ -0,0 +1,542 @@
+"""
+PrivacyScrubber ZTDS Client Implementation
+Synchronous and Asynchronous sidecar IPC over stdio NDJSON.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import subprocess
+import threading
+from typing import Any, Dict, List, Optional, Union
+
+from privacyscrubber.exceptions import PrivacyScrubberError, PrivacyScrubberLicenseError
+from privacyscrubber.types import SanitizeResult, RestoreResult, ObjectSanitizeResult
+
+
+def _find_daemon_path(explicit_path: Optional[str] = None) -> str:
+    """Resolves the absolute path to bridge_daemon.cjs across package and filesystem."""
+    if explicit_path and os.path.isfile(explicit_path):
+        return os.path.abspath(explicit_path)
+
+    env_path = os.environ.get("PRIVACYSCRUBBER_BRIDGE_DAEMON")
+    if env_path and os.path.isfile(env_path):
+        return os.path.abspath(env_path)
+
+    here = os.path.dirname(os.path.abspath(__file__))
+    candidates = [
+        # 1. Directly inside packaged directory
+        os.path.join(here, "bridge_daemon.cjs"),
+        # 2. Parent directory (for dev repository layouts)
+        os.path.join(here, "..", "bridge_daemon.cjs"),
+        # 3. Monorepo / relative to npm-sdk
+        os.path.join(here, "..", "..", "python-bridge", "bridge_daemon.cjs"),
+        os.path.join(here, "..", "..", "examples", "python-bridge", "bridge_daemon.cjs"),
+        # 4. Standard node_modules locations
+        os.path.join(here, "node_modules", "@privacyscrubber", "sdk", "examples", "python-bridge", "bridge_daemon.cjs"),
+        os.path.join(os.getcwd(), "node_modules", "@privacyscrubber", "sdk", "examples", "python-bridge", "bridge_daemon.cjs"),
+        os.path.join(os.getcwd(), "npm-sdk", "examples", "python-bridge", "bridge_daemon.cjs"),
+    ]
+
+    for cand in candidates:
+        if os.path.isfile(cand):
+            return os.path.abspath(cand)
+
+    raise FileNotFoundError(
+        "Could not locate bridge_daemon.cjs. "
+        "Please provide daemon_path or set PRIVACYSCRUBBER_BRIDGE_DAEMON environment variable."
+    )
+
+
+class PrivacyScrubberClient:
+    """
+    Synchronous PrivacyScrubber ZTDS client.
+    Manages a persistent, low-overhead Node.js sidecar daemon over stdio NDJSON.
+    """
+
+    def __init__(
+        self,
+        node_path: str = "node",
+        daemon_path: Optional[str] = None,
+        license_key: Optional[str] = None,
+        default_profile: str = "General",
+        detect_secrets: bool = False,
+        auto_start: bool = True
+    ) -> None:
+        self.node_path = os.environ.get("PRIVACYSCRUBBER_NODE_PATH", node_path)
+        self.daemon_path = _find_daemon_path(daemon_path)
+        self.license_key = license_key or os.environ.get("PRIVACYSCRUBBER_KEY") or os.environ.get("PRIVACYSCRUBBER_LICENSE_KEY") or ""
+        self.default_profile = default_profile
+        self.detect_secrets = detect_secrets
+
+        self._process: Optional[subprocess.Popen] = None
+        self._lock = threading.Lock()
+        self._req_id = 0
+
+        if auto_start:
+            self.start()
+
+    def start(self) -> None:
+        """Starts the persistent sidecar process."""
+        with self._lock:
+            if self._process and self._process.poll() is None:
+                return
+
+            cmd = [
+                self.node_path,
+                self.daemon_path,
+                "--profile", self.default_profile
+            ]
+            if self.license_key:
+                cmd.extend(["--license-key", self.license_key])
+
+            self._process = subprocess.Popen(
+                cmd,
+                stdin=subprocess.PIPE,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True,
+                bufsize=1
+            )
+
+    def close(self) -> None:
+        """Gracefully shuts down the sidecar process."""
+        with self._lock:
+            if not self._process:
+                return
+            try:
+                if self._process.poll() is None:
+                    if self._process.stdin:
+                        self._process.stdin.close()
+                    self._process.terminate()
+                    self._process.wait(timeout=2.0)
+            except Exception:
+                try:
+                    self._process.kill()
+                except Exception:
+                    pass
+            finally:
+                try:
+                    if self._process.stdout:
+                        self._process.stdout.close()
+                except Exception:
+                    pass
+                try:
+                    if self._process.stderr:
+                        self._process.stderr.close()
+                except Exception:
+                    pass
+                self._process = None
+
+    def __enter__(self) -> PrivacyScrubberClient:
+        self.start()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        self.close()
+
+    def _send_request(self, action: str, **kwargs: Any) -> Dict[str, Any]:
+        """Sends a JSON-RPC request to the sidecar and awaits single-line response."""
+        with self._lock:
+            if not self._process or self._process.poll() is not None:
+                self.start()
+
+            self._req_id += 1
+            req_id = self._req_id
+
+            payload = {
+                "id": req_id,
+                "action": action,
+                **kwargs
+            }
+
+            req_line = json.dumps(payload) + "\n"
+            try:
+                assert self._process.stdin is not None
+                assert self._process.stdout is not None
+                self._process.stdin.write(req_line)
+                self._process.stdin.flush()
+
+                resp_line = self._process.stdout.readline()
+                if not resp_line:
+                    stderr_output = self._process.stderr.read() if self._process.stderr else ""
+                    raise PrivacyScrubberError(f"Sidecar terminated unexpectedly: {stderr_output.strip()}")
+
+                res = json.loads(resp_line.strip())
+            except Exception as e:
+                if not isinstance(e, PrivacyScrubberError):
+                    raise PrivacyScrubberError(f"RPC communication failure: {str(e)}") from e
+                raise
+
+            if "error" in res and res["error"]:
+                err = res["error"]
+                msg = err.get("message", "Unknown error in PrivacyScrubber engine")
+                if err.get("name") == "PrivacyScrubberLicenseError":
+                    raise PrivacyScrubberLicenseError(
+                        msg,
+                        tier=err.get("tier", "FREE"),
+                        limit=err.get("limit", 15000),
+                        profile=err.get("profile", "General")
+                    )
+                raise PrivacyScrubberError(msg)
+
+            return res.get("result", {})
+
+    def ping(self) -> Dict[str, Any]:
+        """Verifies sidecar health, engine version, and process uptime."""
+        return self._send_request("ping")
+
+    def status(self) -> Dict[str, Any]:
+        """Queries engine status, memory footprint, and session size."""
+        return self._send_request("status")
+
+    def sanitize(
+        self,
+        text: str,
+        profile: Optional[str] = None,
+        detect_secrets: Optional[bool] = None,
+        license_key: Optional[str] = None,
+        persist_session: bool = True,
+        generate_receipt: bool = True,
+        ignore_list: Optional[List[str]] = None,
+        custom_rules: Optional[List[Dict[str, Any]]] = None,
+        throw_on_limit: bool = True
+    ) -> SanitizeResult:
+        """
+        Sanitizes text, replacing sensitive PII with cryptographic surrogate tokens.
+        Operates 100% in local process RAM with sub-millisecond latency.
+        """
+        res = self._send_request(
+            "sanitize",
+            text=text,
+            profile=profile or self.default_profile,
+            detect_secrets=self.detect_secrets if detect_secrets is None else detect_secrets,
+            license_key=license_key or self.license_key,
+            persist_session=persist_session,
+            generate_receipt=generate_receipt,
+            ignore_list=ignore_list,
+            custom_rules=custom_rules,
+            throw_on_limit=throw_on_limit
+        )
+
+        return SanitizeResult(
+            sanitized=res.get("sanitized", ""),
+            token_map=res.get("token_map", {}),
+            count=res.get("count", 0),
+            execution_ms=res.get("execution_ms", 0.0),
+            telemetry=res.get("telemetry"),
+            audit_receipt=res.get("audit_receipt"),
+            license=res.get("license"),
+            matches=res.get("matches")
+        )
+
+    def restore(
+        self,
+        text: str,
+        token_map: Optional[Dict[str, str]] = None
+    ) -> RestoreResult:
+        """
+        Replaces surrogate tokens in AI responses with their original values.
+        Uses in-memory engine session or the explicitly provided token_map.
+        """
+        res = self._send_request(
+            "restore",
+            text=text,
+            token_map=token_map
+        )
+        return RestoreResult(
+            restored_text=res.get("restored_text", ""),
+            restored_count=res.get("restored_count", 0)
+        )
+
+    def sanitize_object(
+        self,
+        data: Any,
+        profile: Optional[str] = None,
+        detect_secrets: Optional[bool] = None,
+        license_key: Optional[str] = None,
+        persist_session: bool = True,
+        throw_on_limit: bool = True
+    ) -> ObjectSanitizeResult:
+        """
+        Recursively sanitizes dictionary or list data structures.
+        Preserves original keys and non-string values intact.
+        """
+        res = self._send_request(
+            "sanitize_object",
+            data=data,
+            profile=profile or self.default_profile,
+            detect_secrets=self.detect_secrets if detect_secrets is None else detect_secrets,
+            license_key=license_key or self.license_key,
+            persist_session=persist_session,
+            throw_on_limit=throw_on_limit
+        )
+        return ObjectSanitizeResult(
+            sanitized=res.get("sanitized"),
+            token_map=res.get("token_map", {}),
+            count=res.get("count", 0),
+            execution_ms=res.get("execution_ms", 0.0),
+            telemetry=res.get("telemetry"),
+            audit_receipt=res.get("audit_receipt")
+        )
+
+    def restore_object(
+        self,
+        data: Any,
+        token_map: Optional[Dict[str, str]] = None
+    ) -> Any:
+        """Recursively restores tokenized dictionary or list structures."""
+        res = self._send_request(
+            "restore_object",
+            data=data,
+            token_map=token_map
+        )
+        return res.get("restored")
+
+    def reset_session(self) -> bool:
+        """Wipes the persistent in-memory session token map."""
+        res = self._send_request("reset_session")
+        return bool(res.get("success", False))
+
+    def mark_false_positive(self, token: str) -> Dict[str, Any]:
+        """
+        Excludes the plaintext value associated with a token from future sanitization.
+        """
+        return self._send_request("mark_false_positive", token=token)
+
+
+class AsyncPrivacyScrubberClient:
+    """
+    Asynchronous PrivacyScrubber ZTDS client for FastAPI and asyncio runtimes.
+    """
+
+    def __init__(
+        self,
+        node_path: str = "node",
+        daemon_path: Optional[str] = None,
+        license_key: Optional[str] = None,
+        default_profile: str = "General",
+        detect_secrets: bool = False
+    ) -> None:
+        self.node_path = os.environ.get("PRIVACYSCRUBBER_NODE_PATH", node_path)
+        self.daemon_path = _find_daemon_path(daemon_path)
+        self.license_key = license_key or os.environ.get("PRIVACYSCRUBBER_KEY") or os.environ.get("PRIVACYSCRUBBER_LICENSE_KEY") or ""
+        self.default_profile = default_profile
+        self.detect_secrets = detect_secrets
+
+        self._process: Optional[asyncio.subprocess.Process] = None
+        self._lock = asyncio.Lock()
+        self._req_id = 0
+
+    async def start(self) -> None:
+        """Starts the persistent asynchronous sidecar process."""
+        async with self._lock:
+            if self._process and self._process.returncode is None:
+                return
+
+            cmd = [
+                self.node_path,
+                self.daemon_path,
+                "--profile", self.default_profile
+            ]
+            if self.license_key:
+                cmd.extend(["--license-key", self.license_key])
+
+            self._process = await asyncio.create_subprocess_exec(
+                *cmd,
+                stdin=asyncio.subprocess.PIPE,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE
+            )
+
+    async def close(self) -> None:
+        """Gracefully closes the async sidecar process."""
+        async with self._lock:
+            if not self._process:
+                return
+            try:
+                if self._process.returncode is None:
+                    if self._process.stdin:
+                        self._process.stdin.close()
+                        await self._process.stdin.wait_closed()
+                    self._process.terminate()
+                    await asyncio.wait_for(self._process.wait(), timeout=2.0)
+            except Exception:
+                try:
+                    self._process.kill()
+                except Exception:
+                    pass
+            finally:
+                self._process = None
+
+    async def __aenter__(self) -> AsyncPrivacyScrubberClient:
+        await self.start()
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        await self.close()
+
+    async def _send_request(self, action: str, **kwargs: Any) -> Dict[str, Any]:
+        """Sends an async JSON-RPC request to the sidecar."""
+        async with self._lock:
+            if not self._process or self._process.returncode is not None:
+                cmd = [
+                    self.node_path,
+                    self.daemon_path,
+                    "--profile", self.default_profile
+                ]
+                if self.license_key:
+                    cmd.extend(["--license-key", self.license_key])
+                self._process = await asyncio.create_subprocess_exec(
+                    *cmd,
+                    stdin=asyncio.subprocess.PIPE,
+                    stdout=asyncio.subprocess.PIPE,
+                    stderr=asyncio.subprocess.PIPE
+                )
+
+            self._req_id += 1
+            req_id = self._req_id
+
+            payload = {
+                "id": req_id,
+                "action": action,
+                **kwargs
+            }
+
+            req_line = (json.dumps(payload) + "\n").encode("utf-8")
+            assert self._process.stdin is not None
+            assert self._process.stdout is not None
+
+            self._process.stdin.write(req_line)
+            await self._process.stdin.drain()
+
+            resp_bytes = await self._process.stdout.readline()
+            if not resp_bytes:
+                stderr_bytes = await self._process.stderr.read() if self._process.stderr else b""
+                raise PrivacyScrubberError(f"Async sidecar terminated: {stderr_bytes.decode('utf-8').strip()}")
+
+            res = json.loads(resp_bytes.decode("utf-8").strip())
+
+            if "error" in res and res["error"]:
+                err = res["error"]
+                msg = err.get("message", "Unknown error in PrivacyScrubber engine")
+                if err.get("name") == "PrivacyScrubberLicenseError":
+                    raise PrivacyScrubberLicenseError(
+                        msg,
+                        tier=err.get("tier", "FREE"),
+                        limit=err.get("limit", 15000),
+                        profile=err.get("profile", "General")
+                    )
+                raise PrivacyScrubberError(msg)
+
+            return res.get("result", {})
+
+    async def ping(self) -> Dict[str, Any]:
+        return await self._send_request("ping")
+
+    async def status(self) -> Dict[str, Any]:
+        return await self._send_request("status")
+
+    async def sanitize(
+        self,
+        text: str,
+        profile: Optional[str] = None,
+        detect_secrets: Optional[bool] = None,
+        license_key: Optional[str] = None,
+        persist_session: bool = True,
+        generate_receipt: bool = True,
+        ignore_list: Optional[List[str]] = None,
+        custom_rules: Optional[List[Dict[str, Any]]] = None,
+        throw_on_limit: bool = True
+    ) -> SanitizeResult:
+        res = await self._send_request(
+            "sanitize",
+            text=text,
+            profile=profile or self.default_profile,
+            detect_secrets=self.detect_secrets if detect_secrets is None else detect_secrets,
+            license_key=license_key or self.license_key,
+            persist_session=persist_session,
+            generate_receipt=generate_receipt,
+            ignore_list=ignore_list,
+            custom_rules=custom_rules,
+            throw_on_limit=throw_on_limit
+        )
+
+        return SanitizeResult(
+            sanitized=res.get("sanitized", ""),
+            token_map=res.get("token_map", {}),
+            count=res.get("count", 0),
+            execution_ms=res.get("execution_ms", 0.0),
+            telemetry=res.get("telemetry"),
+            audit_receipt=res.get("audit_receipt"),
+            license=res.get("license"),
+            matches=res.get("matches")
+        )
+
+    async def restore(
+        self,
+        text: str,
+        token_map: Optional[Dict[str, str]] = None
+    ) -> RestoreResult:
+        res = await self._send_request(
+            "restore",
+            text=text,
+            token_map=token_map
+        )
+        return RestoreResult(
+            restored_text=res.get("restored_text", ""),
+            restored_count=res.get("restored_count", 0)
+        )
+
+    async def sanitize_object(
+        self,
+        data: Any,
+        profile: Optional[str] = None,
+        detect_secrets: Optional[bool] = None,
+        license_key: Optional[str] = None,
+        persist_session: bool = True,
+        throw_on_limit: bool = True
+    ) -> ObjectSanitizeResult:
+        res = await self._send_request(
+            "sanitize_object",
+            data=data,
+            profile=profile or self.default_profile,
+            detect_secrets=self.detect_secrets if detect_secrets is None else detect_secrets,
+            license_key=license_key or self.license_key,
+            persist_session=persist_session,
+            throw_on_limit=throw_on_limit
+        )
+        return ObjectSanitizeResult(
+            sanitized=res.get("sanitized"),
+            token_map=res.get("token_map", {}),
+            count=res.get("count", 0),
+            execution_ms=res.get("execution_ms", 0.0),
+            telemetry=res.get("telemetry"),
+            audit_receipt=res.get("audit_receipt")
+        )
+
+    async def restore_object(
+        self,
+        data: Any,
+        token_map: Optional[Dict[str, str]] = None
+    ) -> Any:
+        res = await self._send_request(
+            "restore_object",
+            data=data,
+            token_map=token_map
+        )
+        return res.get("restored")
+
+    async def reset_session(self) -> bool:
+        res = await self._send_request("reset_session")
+        return bool(res.get("success", False))
+
+    async def mark_false_positive(self, token: str) -> Dict[str, Any]:
+        return await self._send_request("mark_false_positive", token=token)
+
+
+# Aliases
+PrivacyScrubber = PrivacyScrubberClient
+AsyncPrivacyScrubber = AsyncPrivacyScrubberClient

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

@@ -0,0 +1,26 @@
+"""
+PrivacyScrubber Exception Hierarchy
+"""
+
+from __future__ import annotations
+
+
+class PrivacyScrubberError(Exception):
+    """Base exception for all PrivacyScrubber errors."""
+    pass
+
+
+class PrivacyScrubberLicenseError(PrivacyScrubberError):
+    """Raised when Free tier quotas or license gates are exceeded."""
+    def __init__(
+        self,
+        message: str,
+        tier: str = "FREE",
+        limit: int = 15000,
+        profile: str = "General"
+    ) -> None:
+        super().__init__(message)
+        self.tier = tier
+        self.limit = limit
+        self.profile = profile
+        self.upgrade_url = "https://privacyscrubber.com/pricing?tier=sdk&src=python_sdk"