@privacyscrubber/sdk 2.3.9 → 2.4.1

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

@@ -0,0 +1,161 @@
+"""
+PrivacyScrubber LangChain Adapter
+"""
+
+from __future__ import annotations
+
+import copy
+from typing import Any, Dict, List, Optional, Sequence, Union
+
+from privacyscrubber.client import PrivacyScrubberClient
+
+
+try:
+    from langchain_core.callbacks.base import BaseCallbackHandler
+    from langchain_core.documents import Document
+    from langchain_core.outputs import LLMResult
+    from langchain_core.runnables import RunnableLambda
+    LANGCHAIN_INSTALLED = True
+except ImportError:
+    LANGCHAIN_INSTALLED = False
+    BaseCallbackHandler = object  # type: ignore
+    Document = object  # type: ignore
+    LLMResult = object  # type: ignore
+    RunnableLambda = object  # type: ignore
+
+
+class ZTDSCallbackHandler(BaseCallbackHandler):
+    """
+    LangChain Callback Handler enforcing Zero-Trust Data Sanitization.
+    
+    1. Intercepts outgoing prompts in on_llm_start -> replaces raw PII with surrogate tokens.
+    2. Stores ephemeral token mappings in RAM only (no disk, no network).
+    3. Intercepts incoming responses in on_llm_end -> restores cleartext values in RAM.
+    """
+
+    def __init__(
+        self,
+        scrubber: Optional[PrivacyScrubberClient] = None,
+        profile: str = "General",
+        detect_secrets: bool = False,
+        verbose: bool = False
+    ) -> None:
+        self.scrubber = scrubber or PrivacyScrubberClient(default_profile=profile)
+        self.profile = profile
+        self.detect_secrets = detect_secrets
+        self.verbose = verbose
+        self._session_token_maps: Dict[str, Dict[str, str]] = {}
+
+    def on_llm_start(
+        self,
+        serialized: Dict[str, Any],
+        prompts: List[str],
+        *,
+        run_id: Optional[Any] = None,
+        parent_run_id: Optional[Any] = None,
+        tags: Optional[List[str]] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        **kwargs: Any
+    ) -> Any:
+        """Sanitizes prompts in place before they are dispatched to the cloud LLM."""
+        key = str(run_id) if run_id else "default"
+        combined_token_map: Dict[str, str] = {}
+
+        for i, prompt in enumerate(prompts):
+            res = self.scrubber.sanitize(
+                prompt,
+                profile=self.profile,
+                detect_secrets=self.detect_secrets,
+                persist_session=True
+            )
+            prompts[i] = res.sanitized
+            combined_token_map.update(res.token_map)
+            if self.verbose and res.count > 0:
+                print(f"[ZTDS Guard] Sanitized {res.count} PII tokens for run {key}")
+
+        self._session_token_maps[key] = combined_token_map
+
+    def on_llm_end(
+        self,
+        response: Any,
+        *,
+        run_id: Optional[Any] = None,
+        parent_run_id: Optional[Any] = None,
+        tags: Optional[List[str]] = None,
+        **kwargs: Any
+    ) -> Any:
+        """Restores cleartext tokens in LLM output before reaching the user."""
+        key = str(run_id) if run_id else "default"
+        token_map = self._session_token_maps.pop(key, None)
+
+        generations = getattr(response, "generations", None)
+        if generations and isinstance(generations, list):
+            for gen_list in generations:
+                for gen in gen_list:
+                    if hasattr(gen, "text") and gen.text:
+                        restored = self.scrubber.restore(gen.text, token_map=token_map)
+                        gen.text = restored.restored_text
+                    elif hasattr(gen, "message") and hasattr(gen.message, "content"):
+                        if isinstance(gen.message.content, str):
+                            restored = self.scrubber.restore(gen.message.content, token_map=token_map)
+                            gen.message.content = restored.restored_text
+
+        return response
+
+
+class ZTDSDocumentTransformer:
+    """
+    Sanitizes LangChain Documents before vector database ingestion (Pinecone, Qdrant, Chroma).
+    Guarantees no raw PII enters embeddings or persistent vector storage.
+    """
+
+    def __init__(
+        self,
+        scrubber: Optional[PrivacyScrubberClient] = None,
+        profile: str = "General",
+        sensitive_metadata_keys: Optional[Sequence[str]] = None
+    ) -> None:
+        self.scrubber = scrubber or PrivacyScrubberClient(default_profile=profile)
+        self.profile = profile
+        self.sensitive_metadata_keys = list(sensitive_metadata_keys or [])
+
+    def transform_documents(self, documents: Sequence[Any]) -> List[Any]:
+        """Transforms documents, sanitizing page_content and sensitive metadata keys."""
+        transformed: List[Any] = []
+        for doc in documents:
+            doc_copy = copy.deepcopy(doc)
+            content = getattr(doc_copy, "page_content", "")
+            if isinstance(content, str) and content:
+                res = self.scrubber.sanitize(content, profile=self.profile)
+                doc_copy.page_content = res.sanitized
+
+            metadata = getattr(doc_copy, "metadata", None)
+            if isinstance(metadata, dict):
+                for k in self.sensitive_metadata_keys:
+                    if k in metadata and isinstance(metadata[k], str):
+                        res_meta = self.scrubber.sanitize(metadata[k], profile=self.profile)
+                        metadata[k] = res_meta.sanitized
+
+            transformed.append(doc_copy)
+        return transformed
+
+
+def create_ztds_lcel_runnables(
+    scrubber: Optional[PrivacyScrubberClient] = None,
+    profile: str = "General"
+):
+    """
+    Creates pre-scrub and post-restore runnables for LCEL pipelines:
+    chain = scrub_runnable | prompt | model | parser | restore_runnable
+    """
+    client = scrubber or PrivacyScrubberClient(default_profile=profile)
+
+    def scrub_func(input_text: str) -> str:
+        res = client.sanitize(str(input_text), profile=profile)
+        return res.sanitized
+
+    def restore_func(output_text: str) -> str:
+        restored = client.restore(str(output_text))
+        return restored.restored_text
+
+    return scrub_func, restore_func

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

@@ -0,0 +1,52 @@
+"""
+PrivacyScrubber Data Types & Response Models
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class SanitizeResult:
+    """Result of a text sanitization operation."""
+    sanitized: str
+    token_map: Dict[str, str]
+    count: int = 0
+    execution_ms: float = 0.0
+    telemetry: Optional[Dict[str, Any]] = None
+    audit_receipt: Optional[str] = None
+    license: Optional[Dict[str, Any]] = None
+    matches: Optional[List[Dict[str, Any]]] = None
+
+    def __str__(self) -> str:
+        """Allow direct string usage in prompts and string formatting."""
+        return self.sanitized
+
+    @property
+    def scrubbed_text(self) -> str:
+        """Alias for sanitized text."""
+        return self.sanitized
+
+
+@dataclass
+class RestoreResult:
+    """Result of a token restoration operation."""
+    restored_text: str
+    restored_count: int = 0
+
+    def __str__(self) -> str:
+        """Allow direct string usage in final responses."""
+        return self.restored_text
+
+
+@dataclass
+class ObjectSanitizeResult:
+    """Result of a structured dictionary or list sanitization operation."""
+    sanitized: Any
+    token_map: Dict[str, str]
+    count: int = 0
+    execution_ms: float = 0.0
+    telemetry: Optional[Dict[str, Any]] = None
+    audit_receipt: Optional[str] = None

package/examples/python-bridge/privacyscrubber.py

@@ -0,0 +1,36 @@
+"""
+PrivacyScrubber ZTDS Client for Python
+Zero-Trust Data Sanitization & Local PII Shield for LLM / AI Pipelines.
+
+100% in-memory client-side execution. Zero cloud egress. Sub-millisecond latency.
+RFC v1.0 standard-compliant Zero-Trust Data Sanitization engine.
+"""
+
+from __future__ import annotations
+
+from privacyscrubber import (
+    PrivacyScrubberClient,
+    PrivacyScrubber,
+    AsyncPrivacyScrubberClient,
+    AsyncPrivacyScrubber,
+    SanitizeResult,
+    RestoreResult,
+    ObjectSanitizeResult,
+    PrivacyScrubberError,
+    PrivacyScrubberLicenseError,
+    __version__,
+)
+from privacyscrubber.client import _find_daemon_path
+
+__all__ = [
+    "PrivacyScrubberClient",
+    "PrivacyScrubber",
+    "AsyncPrivacyScrubberClient",
+    "AsyncPrivacyScrubber",
+    "SanitizeResult",
+    "RestoreResult",
+    "ObjectSanitizeResult",
+    "PrivacyScrubberError",
+    "PrivacyScrubberLicenseError",
+    "__version__",
+]

package/examples/python-bridge/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "privacyscrubber"
+version = "2.4.1"
+description = "Zero-Trust Data Sanitization & In-Memory PII Shield for Python AI Pipelines (ZTDS RFC v1.0)"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "Commercial / Proprietary" }
+authors = [
+    { name = "Ilya Sibiryakov (BrandMeWeb)", email = "contact@privacyscrubber.com" }
+]
+keywords = [
+    "pii", "redaction", "sanitization", "zero-trust", "ztds", "langchain",
+    "fastapi", "presidio", "llm-security", "gdpr", "hipaa", "ai-guardrail"
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Information Technology",
+    "Topic :: Security",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://privacyscrubber.com"
+Documentation = "https://privacyscrubber.com/sdk/"
+Repository = "https://github.com/moxno/privacyscrubber-mcp"
+Standard = "https://datatracker.ietf.org/doc/draft-sibiryakov-ztds-protocol/"
+
+[project.optional-dependencies]
+fastapi = ["fastapi>=0.100.0", "uvicorn>=0.20.0", "pydantic>=2.0.0"]
+langchain = ["langchain-core>=0.1.0"]
+llamaindex = ["llama-index-core>=0.10.0"]
+all = [
+    "fastapi>=0.100.0",
+    "uvicorn>=0.20.0",
+    "pydantic>=2.0.0",
+    "langchain-core>=0.1.0",
+    "llama-index-core>=0.10.0"
+]
+
+[project.scripts]
+privacyscrubber = "privacyscrubber.cli:main"
+ps-bridge = "privacyscrubber.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["privacyscrubber*"]
+
+[tool.setuptools.package-data]
+privacyscrubber = ["*.cjs", "bridge_daemon.cjs"]

package/examples/python-bridge/setup.py

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+"""
+Setup script for privacyscrubber Python package.
+"""
+
+from setuptools import setup, find_packages
+import os
+
+here = os.path.abspath(os.path.dirname(__file__))
+
+with open(os.path.join(here, "README.md"), encoding="utf-8") as f:
+    long_description = f.read()
+
+setup(
+    name="privacyscrubber",
+    version="2.4.1",
+    description="Zero-Trust Data Sanitization & In-Memory PII Shield for Python AI Pipelines (ZTDS RFC v1.0)",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    author="Ilya Sibiryakov (BrandMeWeb)",
+    author_email="contact@privacyscrubber.com",
+    url="https://privacyscrubber.com",
+    project_urls={
+        "Documentation": "https://privacyscrubber.com/sdk/",
+        "Source": "https://github.com/moxno/privacyscrubber-mcp",
+        "ZTDS Standard": "https://datatracker.ietf.org/doc/draft-sibiryakov-ztds-protocol/",
+    },
+    packages=find_packages(),
+    package_data={
+        "privacyscrubber": ["*.cjs", "bridge_daemon.cjs"],
+    },
+    include_package_data=True,
+    python_requires=">=3.8",
+    install_requires=[],
+    extras_require={
+        "fastapi": ["fastapi>=0.100.0", "uvicorn>=0.20.0", "pydantic>=2.0.0"],
+        "langchain": ["langchain-core>=0.1.0"],
+        "llamaindex": ["llama-index-core>=0.10.0"],
+        "all": [
+            "fastapi>=0.100.0",
+            "uvicorn>=0.20.0",
+            "pydantic>=2.0.0",
+            "langchain-core>=0.1.0",
+            "llama-index-core>=0.10.0",
+        ],
+    },
+    entry_points={
+        "console_scripts": [
+            "privacyscrubber=privacyscrubber.cli:main",
+            "ps-bridge=privacyscrubber.cli:main",
+        ],
+    },
+    classifiers=[
+        "Development Status :: 5 - Production/Stable",
+        "Intended Audience :: Developers",
+        "Topic :: Security",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",
+        "Programming Language :: Python :: 3.13",
+        "Operating System :: OS Independent",
+    ],
+)