privaro 0.1.0__tar.gz

privaro-0.1.0/PKG-INFO

@@ -0,0 +1,232 @@
+Metadata-Version: 2.4
+Name: privaro
+Version: 0.1.0
+Summary: Privacy Infrastructure for Enterprise AI — Official Python SDK
+Author-email: iCommunity Labs <hello@icommunity.io>
+License: MIT
+Project-URL: Homepage, https://privaro.io
+Project-URL: Documentation, https://privaro.io/docs
+Project-URL: Repository, https://github.com/icommunity-labs/privaro-python-sdk
+Project-URL: Bug Tracker, https://github.com/icommunity-labs/privaro-python-sdk/issues
+Keywords: privacy,pii,gdpr,ai,llm,compliance,blockchain
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: async
+Requires-Dist: aiohttp>=3.9; extra == "async"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: aiohttp>=3.9; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+
+# Privaro Python SDK
+
+**Privacy Infrastructure for Enterprise AI** — Official Python SDK by [iCommunity Labs](https://privaro.io)
+
+Protect PII in AI prompts with one line of code. Every interaction is tokenized, audited, and blockchain-certified.
+
+---
+
+## Installation
+
+```bash
+pip install privaro
+```
+
+No required dependencies — uses Python stdlib only.
+
+```bash
+# Optional: async support
+pip install privaro[async]
+```
+
+---
+
+## Quick Start
+
+```python
+import privaro
+
+# Initialize once (e.g., at app startup)
+privaro.init(
+    api_key="prvr_your_api_key",
+    pipeline_id="your-pipeline-uuid",
+)
+
+# Protect a prompt before sending to any LLM
+result = privaro.protect("Patient: María García, DNI 34521789X, IBAN ES91 2100...")
+
+print(result.protected)      # "Patient: [NM-0001], DNI [ID-0001], IBAN [BK-0001]..."
+print(result.risk_score)     # 0.847
+print(result.risk_level)     # "high"
+print(result.gdpr_compliant) # True
+
+# Send protected prompt to your LLM — no PII ever reaches the model
+response = openai.chat.completions.create(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": result.protected}]
+)
+```
+
+---
+
+## Usage Patterns
+
+### Protect + LLM (full pipeline)
+
+```python
+import privaro
+import openai
+
+privaro.init(api_key="prvr_xxx", pipeline_id="uuid")
+
+def ask_ai(user_input: str) -> str:
+    # 1. Protect PII
+    protected = privaro.protect(user_input)
+
+    if not protected.is_safe:
+        raise ValueError(f"PII leak detected: {protected.leaked} entities exposed")
+
+    # 2. Call LLM with protected prompt
+    response = openai.chat.completions.create(
+        model="gpt-4o",
+        messages=[{"role": "user", "content": protected.protected}]
+    )
+
+    return response.choices[0].message.content
+```
+
+### Detect only (analysis mode)
+
+```python
+result = privaro.detect("Call me at 612 345 678, email: user@company.es")
+
+for detection in result.detections:
+    print(f"{detection.type}: {detection.severity} ({detection.detector})")
+# phone: high (regex)
+# email: high (regex)
+```
+
+### Agent mode (stricter policies)
+
+```python
+result = privaro.protect(
+    prompt=agent_input,
+    agent_mode=True,   # Applies stricter policy preset
+)
+```
+
+### Multiple clients (multiple pipelines)
+
+```python
+from privaro import PrivaroClient
+
+legal_client = PrivaroClient(api_key="prvr_xxx", pipeline_id="legal-pipeline-uuid")
+hr_client = PrivaroClient(api_key="prvr_xxx", pipeline_id="hr-pipeline-uuid")
+
+legal_result = legal_client.protect(contract_text)
+hr_result = hr_client.protect(employee_record)
+```
+
+### Async support
+
+```python
+from privaro.async_client import AsyncPrivaroClient
+
+client = AsyncPrivaroClient(api_key="prvr_xxx", pipeline_id="uuid")
+
+async def process(prompt: str):
+    result = await client.protect(prompt)
+    return result.protected
+```
+
+### Error handling
+
+```python
+from privaro.exceptions import AuthError, PolicyBlockError, ProxyUnavailableError
+
+try:
+    result = privaro.protect(prompt)
+except PolicyBlockError as e:
+    # Request blocked by policy (e.g., health data on non-approved provider)
+    logger.warning(f"Request blocked: {e}")
+    return "Request cannot be processed — sensitive data detected."
+except ProxyUnavailableError:
+    # Fallback: log and fail safely
+    logger.error("Privaro proxy unavailable")
+    raise
+except AuthError:
+    logger.error("Invalid Privaro API key")
+    raise
+```
+
+---
+
+## ProtectResult Reference
+
+| Property | Type | Description |
+|---|---|---|
+| `result.protected` | str | Prompt with PII replaced by tokens |
+| `result.original` | str | Original prompt (local only) |
+| `result.risk_score` | float | 0.0–1.0 composite risk score |
+| `result.risk_level` | str | "high" / "medium" / "low" |
+| `result.gdpr_compliant` | bool | True if no PII leaked |
+| `result.is_safe` | bool | True if all PII masked |
+| `result.has_pii` | bool | True if any entities detected |
+| `result.total_detected` | int | Total PII entities found |
+| `result.total_masked` | int | Entities successfully masked |
+| `result.leaked` | int | Entities that passed through |
+| `result.detections` | list[Detection] | Per-entity details |
+| `result.audit_log_id` | str | Supabase audit log UUID |
+| `result.processing_ms` | int | Proxy latency in ms |
+| `result.summary()` | str | One-line log summary |
+
+---
+
+## Detection Reference
+
+| Property | Values |
+|---|---|
+| `detection.type` | `dni` `iban` `email` `full_name` `phone` `health_record` `credit_card` `ip_address` `date_of_birth` |
+| `detection.severity` | `critical` `high` `medium` `low` |
+| `detection.action` | `tokenised` `anonymised` `blocked` |
+| `detection.detector` | `regex` `presidio` |
+| `detection.confidence` | 0.0–1.0 |
+| `detection.is_high_risk` | bool |
+
+---
+
+## Blockchain Verification
+
+Every `protect()` call creates an immutable audit entry certified on **Fantom Opera Mainnet** via iBS. Verify any event at:
+
+```
+https://checker.icommunitylabs.com/check/fantom_opera_mainnet/{tx_hash}
+```
+
+Access the TX hash from your Privaro dashboard → Audit Logs → ⛓️ badge.
+
+---
+
+## Requirements
+
+- Python 3.9+
+- Zero required dependencies (uses `urllib` from stdlib)
+- Optional: `aiohttp>=3.9` for async support
+
+---
+
+## License
+
+MIT — © 2026 iCommunity Labs · [privaro.io](https://privaro.io)

privaro-0.1.0/README.md

@@ -0,0 +1,200 @@
+# Privaro Python SDK
+
+**Privacy Infrastructure for Enterprise AI** — Official Python SDK by [iCommunity Labs](https://privaro.io)
+
+Protect PII in AI prompts with one line of code. Every interaction is tokenized, audited, and blockchain-certified.
+
+---
+
+## Installation
+
+```bash
+pip install privaro
+```
+
+No required dependencies — uses Python stdlib only.
+
+```bash
+# Optional: async support
+pip install privaro[async]
+```
+
+---
+
+## Quick Start
+
+```python
+import privaro
+
+# Initialize once (e.g., at app startup)
+privaro.init(
+    api_key="prvr_your_api_key",
+    pipeline_id="your-pipeline-uuid",
+)
+
+# Protect a prompt before sending to any LLM
+result = privaro.protect("Patient: María García, DNI 34521789X, IBAN ES91 2100...")
+
+print(result.protected)      # "Patient: [NM-0001], DNI [ID-0001], IBAN [BK-0001]..."
+print(result.risk_score)     # 0.847
+print(result.risk_level)     # "high"
+print(result.gdpr_compliant) # True
+
+# Send protected prompt to your LLM — no PII ever reaches the model
+response = openai.chat.completions.create(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": result.protected}]
+)
+```
+
+---
+
+## Usage Patterns
+
+### Protect + LLM (full pipeline)
+
+```python
+import privaro
+import openai
+
+privaro.init(api_key="prvr_xxx", pipeline_id="uuid")
+
+def ask_ai(user_input: str) -> str:
+    # 1. Protect PII
+    protected = privaro.protect(user_input)
+
+    if not protected.is_safe:
+        raise ValueError(f"PII leak detected: {protected.leaked} entities exposed")
+
+    # 2. Call LLM with protected prompt
+    response = openai.chat.completions.create(
+        model="gpt-4o",
+        messages=[{"role": "user", "content": protected.protected}]
+    )
+
+    return response.choices[0].message.content
+```
+
+### Detect only (analysis mode)
+
+```python
+result = privaro.detect("Call me at 612 345 678, email: user@company.es")
+
+for detection in result.detections:
+    print(f"{detection.type}: {detection.severity} ({detection.detector})")
+# phone: high (regex)
+# email: high (regex)
+```
+
+### Agent mode (stricter policies)
+
+```python
+result = privaro.protect(
+    prompt=agent_input,
+    agent_mode=True,   # Applies stricter policy preset
+)
+```
+
+### Multiple clients (multiple pipelines)
+
+```python
+from privaro import PrivaroClient
+
+legal_client = PrivaroClient(api_key="prvr_xxx", pipeline_id="legal-pipeline-uuid")
+hr_client = PrivaroClient(api_key="prvr_xxx", pipeline_id="hr-pipeline-uuid")
+
+legal_result = legal_client.protect(contract_text)
+hr_result = hr_client.protect(employee_record)
+```
+
+### Async support
+
+```python
+from privaro.async_client import AsyncPrivaroClient
+
+client = AsyncPrivaroClient(api_key="prvr_xxx", pipeline_id="uuid")
+
+async def process(prompt: str):
+    result = await client.protect(prompt)
+    return result.protected
+```
+
+### Error handling
+
+```python
+from privaro.exceptions import AuthError, PolicyBlockError, ProxyUnavailableError
+
+try:
+    result = privaro.protect(prompt)
+except PolicyBlockError as e:
+    # Request blocked by policy (e.g., health data on non-approved provider)
+    logger.warning(f"Request blocked: {e}")
+    return "Request cannot be processed — sensitive data detected."
+except ProxyUnavailableError:
+    # Fallback: log and fail safely
+    logger.error("Privaro proxy unavailable")
+    raise
+except AuthError:
+    logger.error("Invalid Privaro API key")
+    raise
+```
+
+---
+
+## ProtectResult Reference
+
+| Property | Type | Description |
+|---|---|---|
+| `result.protected` | str | Prompt with PII replaced by tokens |
+| `result.original` | str | Original prompt (local only) |
+| `result.risk_score` | float | 0.0–1.0 composite risk score |
+| `result.risk_level` | str | "high" / "medium" / "low" |
+| `result.gdpr_compliant` | bool | True if no PII leaked |
+| `result.is_safe` | bool | True if all PII masked |
+| `result.has_pii` | bool | True if any entities detected |
+| `result.total_detected` | int | Total PII entities found |
+| `result.total_masked` | int | Entities successfully masked |
+| `result.leaked` | int | Entities that passed through |
+| `result.detections` | list[Detection] | Per-entity details |
+| `result.audit_log_id` | str | Supabase audit log UUID |
+| `result.processing_ms` | int | Proxy latency in ms |
+| `result.summary()` | str | One-line log summary |
+
+---
+
+## Detection Reference
+
+| Property | Values |
+|---|---|
+| `detection.type` | `dni` `iban` `email` `full_name` `phone` `health_record` `credit_card` `ip_address` `date_of_birth` |
+| `detection.severity` | `critical` `high` `medium` `low` |
+| `detection.action` | `tokenised` `anonymised` `blocked` |
+| `detection.detector` | `regex` `presidio` |
+| `detection.confidence` | 0.0–1.0 |
+| `detection.is_high_risk` | bool |
+
+---
+
+## Blockchain Verification
+
+Every `protect()` call creates an immutable audit entry certified on **Fantom Opera Mainnet** via iBS. Verify any event at:
+
+```
+https://checker.icommunitylabs.com/check/fantom_opera_mainnet/{tx_hash}
+```
+
+Access the TX hash from your Privaro dashboard → Audit Logs → ⛓️ badge.
+
+---
+
+## Requirements
+
+- Python 3.9+
+- Zero required dependencies (uses `urllib` from stdlib)
+- Optional: `aiohttp>=3.9` for async support
+
+---
+
+## License
+
+MIT — © 2026 iCommunity Labs · [privaro.io](https://privaro.io)

privaro-0.1.0/privaro/__init__.py

@@ -0,0 +1,122 @@
+"""
+Privaro Python SDK
+Privacy Infrastructure for Enterprise AI — iCommunity Labs
+
+Usage:
+    import privaro
+
+    privaro.init(api_key="prvr_xxx", pipeline_id="uuid")
+    result = privaro.protect("Patient: María García, DNI 34521789X")
+
+    print(result.protected)      # "Patient: [NM-0001], DNI [ID-0001]"
+    print(result.risk_score)     # 0.847
+    print(result.gdpr_compliant) # True
+"""
+
+from .client import PrivaroClient
+from .models import ProtectResult, Detection
+from .exceptions import PrivaroError, AuthError, PipelineNotFoundError
+
+__version__ = "0.1.0"
+__all__ = [
+    "PrivaroClient",
+    "ProtectResult",
+    "Detection",
+    "PrivaroError",
+    "AuthError",
+    "PipelineNotFoundError",
+    "init",
+    "protect",
+    "detect",
+]
+
+# ── Module-level default client ───────────────────────────────────────────────
+_default_client: "PrivaroClient | None" = None
+
+
+def init(
+    api_key: str,
+    pipeline_id: str,
+    base_url: str = "https://privaro-proxy-production.up.railway.app/v1",
+    timeout: float = 10.0,
+) -> PrivaroClient:
+    """
+    Initialize the default Privaro client.
+
+    Args:
+        api_key:     Your Privaro API key (starts with prvr_)
+        pipeline_id: UUID of your active pipeline
+        base_url:    Proxy URL (default: production)
+        timeout:     Request timeout in seconds
+
+    Returns:
+        PrivaroClient instance (also set as module default)
+
+    Example:
+        privaro.init(
+            api_key="prvr_abc123",
+            pipeline_id="c93aed87-b440-4de0-bb21-54a938e475f2"
+        )
+    """
+    global _default_client
+    _default_client = PrivaroClient(
+        api_key=api_key,
+        pipeline_id=pipeline_id,
+        base_url=base_url,
+        timeout=timeout,
+    )
+    return _default_client
+
+
+def _require_client() -> "PrivaroClient":
+    if _default_client is None:
+        raise PrivaroError(
+            "Privaro not initialized. Call privaro.init(api_key=..., pipeline_id=...) first."
+        )
+    return _default_client
+
+
+def protect(
+    prompt: str,
+    mode: str = "tokenise",
+    reversible: bool = True,
+    agent_mode: bool = False,
+    include_detections: bool = True,
+) -> "ProtectResult":
+    """
+    Detect and tokenize PII in a prompt.
+
+    Args:
+        prompt:             Text to protect
+        mode:               tokenise | anonymise | block
+        reversible:         Store reversible tokens in vault
+        agent_mode:         Apply stricter policies for agent pipelines
+        include_detections: Include detection details in response
+
+    Returns:
+        ProtectResult with .protected, .risk_score, .detections, etc.
+
+    Example:
+        result = privaro.protect("Patient: María García, DNI 34521789X")
+        llm_response = your_llm.complete(result.protected)
+    """
+    return _require_client().protect(
+        prompt=prompt,
+        mode=mode,
+        reversible=reversible,
+        agent_mode=agent_mode,
+        include_detections=include_detections,
+    )
+
+
+def detect(prompt: str) -> "ProtectResult":
+    """
+    Detect PII without masking (analysis mode).
+    Does not store audit logs or tokens.
+
+    Example:
+        result = privaro.detect("Call me at 612 345 678")
+        for d in result.detections:
+            print(d.type, d.confidence)
+    """
+    return _require_client().detect(prompt=prompt)

privaro-0.1.0/privaro/async_client.py

@@ -0,0 +1,110 @@
+"""
+Privaro SDK — Async Client (optional, requires Python 3.11+)
+
+Usage:
+    from privaro.async_client import AsyncPrivaroClient
+
+    client = AsyncPrivaroClient(api_key="prvr_xxx", pipeline_id="uuid")
+
+    async with client:
+        result = await client.protect("María García, DNI 34521789X")
+"""
+import json
+from typing import Optional
+from .client import PrivaroClient
+from .models import ProtectResult
+from .exceptions import (
+    AuthError, PipelineNotFoundError, PolicyBlockError,
+    RateLimitError, ProxyUnavailableError, PrivaroError,
+)
+
+
+class AsyncPrivaroClient(PrivaroClient):
+    """
+    Async version of PrivaroClient using aiohttp (optional dependency).
+
+    Install with: pip install privaro[async]
+    """
+
+    async def _request_async(self, method: str, path: str, payload: dict) -> dict:
+        try:
+            import aiohttp
+        except ImportError:
+            raise PrivaroError(
+                "aiohttp is required for async support. "
+                "Install with: pip install privaro[async]"
+            )
+
+        url = f"{self.base_url}{path}"
+
+        async with aiohttp.ClientSession() as session:
+            try:
+                async with session.request(
+                    method, url,
+                    json=payload,
+                    headers=self._headers(),
+                    timeout=aiohttp.ClientTimeout(total=self.timeout),
+                ) as resp:
+                    body = await resp.json()
+
+                    if resp.status == 401:
+                        raise AuthError("Invalid API key.")
+                    if resp.status == 404:
+                        raise PipelineNotFoundError(f"Pipeline '{self.pipeline_id}' not found.")
+                    if resp.status == 429:
+                        raise RateLimitError("Rate limit exceeded.")
+                    if resp.status >= 400:
+                        raise PrivaroError(f"HTTP {resp.status}: {body}")
+
+                    return body
+
+            except aiohttp.ClientConnectorError as e:
+                raise ProxyUnavailableError(f"Cannot reach proxy: {e}")
+
+    async def protect(
+        self,
+        prompt: str,
+        mode: str = "tokenise",
+        reversible: bool = True,
+        agent_mode: bool = False,
+        include_detections: bool = True,
+    ) -> ProtectResult:
+        """Async version of protect()."""
+        if not prompt or not prompt.strip():
+            return ProtectResult(protected="", original="", request_id="",
+                                 audit_log_id=None, gdpr_compliant=True)
+
+        raw = await self._request_async("POST", "/proxy/protect", {
+            "pipeline_id": self.pipeline_id,
+            "prompt": prompt,
+            "options": {
+                "mode": mode,
+                "reversible": reversible,
+                "agent_mode": agent_mode,
+                "include_detections": include_detections,
+            },
+        })
+        return self._parse_result(raw, original=prompt)
+
+    async def detect(self, prompt: str) -> ProtectResult:
+        """Async version of detect()."""
+        if not prompt or not prompt.strip():
+            return ProtectResult(protected=prompt, original=prompt, request_id="",
+                                 audit_log_id=None, gdpr_compliant=True)
+
+        raw = await self._request_async("POST", "/proxy/detect", {
+            "pipeline_id": self.pipeline_id,
+            "prompt": prompt,
+        })
+        result = self._parse_result(
+            {**raw, "protected_prompt": prompt, "gdpr_compliant": True},
+            original=prompt,
+        )
+        result.protected = prompt
+        return result
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *args):
+        pass