ciphyrs 1.1.0__tar.gz

ciphyrs-1.1.0/.gitignore

@@ -0,0 +1,16 @@
+node_modules/
+__pycache__/
+*.pyc
+.env
+.env.*
+!.env.example
+*.tfstate
+*.tfstate.*
+.terraform/
+.terraform.lock.hcl
+dist/
+build/
+*.log
+.DS_Store
+extensions/vscode/*.vsix
+extensions/vscode/out/

ciphyrs-1.1.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: ciphyrs
+Version: 1.1.0
+Summary: Python SDK for the Ciphyrs PII Shield API
+Project-URL: Homepage, https://www.ciphyrs.com
+Project-URL: Documentation, https://www.ciphyrs.com/docs
+Project-URL: Repository, https://github.com/praveen190/Ciphyrs
+Project-URL: Changelog, https://github.com/praveen190/Ciphyrs/releases
+Author-email: Ciphyrs <support@ciphyrs.com>
+License-Expression: MIT
+Keywords: ciphyrs,masking,pii,privacy
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.25.0
+Provides-Extra: all
+Requires-Dist: crewai>=0.41.0; extra == 'all'
+Requires-Dist: langchain-core>=0.2.0; extra == 'all'
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.41.0; extra == 'crewai'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.2.0; extra == 'langchain'
+Description-Content-Type: text/markdown
+
+# Ciphyrs — PII Shield for AI Workflows
+
+[![PyPI](https://img.shields.io/pypi/v/ciphyrs)](https://pypi.org/project/ciphyrs/)
+[![Python](https://img.shields.io/pypi/pyversions/ciphyrs)](https://pypi.org/project/ciphyrs/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+Intercept, mask, and restore PII before it reaches any LLM. Works with LangChain, CrewAI, or any Python application.
+
+## Install
+
+```bash
+pip install ciphyrs                  # core SDK
+pip install 'ciphyrs[langchain]'     # + LangChain integration
+pip install 'ciphyrs[crewai]'        # + CrewAI integration
+pip install 'ciphyrs[all]'           # everything
+```
+
+## Quick Start
+
+```python
+from ciphyrs import CiphyrsClient
+
+client = CiphyrsClient(
+    api_key="cyp_live_...",
+    base_url="https://www.ciphyrs.com"
+)
+
+# Mask PII
+result = client.mask("Contact Praveen at 9876125640 and praveen@acme.com")
+print(result.masked_text)
+# "Contact XXXX_a1b2c3 at XXXX_d4e5f6 and XXXX_g7h8i9"
+
+# Restore PII
+restored = client.restore(result.masked_text, result.session_id)
+print(restored.restored_text)
+# "Contact Praveen at 9876125640 and praveen@acme.com"
+```
+
+## Authentication
+
+All API calls require an `x-api-key` header. Get your API key from the [Ciphyrs Dashboard](https://www.ciphyrs.com/dashboard).
+
+1. Register at [ciphyrs.com/register](https://www.ciphyrs.com/register)
+2. Go to **Settings > API Keys**
+3. Click **Generate API Key**
+4. Copy the key (starts with `cyp_live_`)
+
+## LangChain Integration
+
+### Option 1: Callback Handler (auto-masks all LLM calls)
+
+```python
+from langchain_openai import ChatOpenAI
+from ciphyrs.integrations.langchain import CiphyrsPIICallback
+
+callback = CiphyrsPIICallback(api_key="cyp_live_...")
+llm = ChatOpenAI(model="gpt-4o", callbacks=[callback])
+
+# PII is automatically masked before reaching OpenAI
+# and restored in the response
+result = llm.invoke("Hi, I'm Praveen Kumar, my phone is 9876125640")
+```
+
+### Option 2: LCEL Runnables (pipe operator)
+
+```python
+from ciphyrs.integrations.langchain import CiphyrsMaskRunnable, CiphyrsRestoreRunnable
+
+session = {}
+mask = CiphyrsMaskRunnable(api_key="cyp_live_...", session_store=session)
+restore = CiphyrsRestoreRunnable(api_key="cyp_live_...", session_store=session)
+
+# Build pipeline: mask -> prompt -> llm -> restore
+chain = mask | prompt_template | llm | restore
+result = chain.invoke({"input": "Call Praveen at 9876125640"})
+```
+
+### Option 3: Shield Wrapper (wrap any chain)
+
+```python
+from ciphyrs.integrations.langchain import CiphyrsShield
+
+shield = CiphyrsShield(api_key="cyp_live_...")
+safe_chain = shield.wrap(my_existing_chain)
+result = safe_chain.invoke({"input": "Praveen's email is praveen@acme.com"})
+```
+
+## Async Support
+
+```python
+from ciphyrs import AsyncCiphyrsClient
+
+async with AsyncCiphyrsClient(api_key="cyp_live_...") as client:
+    result = await client.mask("Contact Praveen at praveen@acme.com")
+    restored = await client.restore(result.masked_text, result.session_id)
+```
+
+## Detected Entity Types
+
+| Entity | Example |
+|--------|---------|
+| PERSON | Praveen Kumar |
+| EMAIL | praveen@acme.com |
+| PHONE | 9876125640 |
+| IN_AADHAAR | 2345 6789 0123 |
+| IN_PAN | ABCDE1234F |
+| CREDIT_CARD | 4111-1111-1111-1111 |
+| IP_ADDRESS | 192.168.1.1 |
+| DATE_OF_BIRTH | 15/03/1990 |
+| LOCATION | Mumbai |
+| ORGANIZATION | Acme Corp |
+| API_KEY | sk-abc123... |
+
+## Links
+
+- [Website](https://www.ciphyrs.com)
+- [Documentation](https://www.ciphyrs.com/docs)
+- [Dashboard](https://www.ciphyrs.com/dashboard)

ciphyrs-1.1.0/README.md

@@ -0,0 +1,118 @@
+# Ciphyrs — PII Shield for AI Workflows
+
+[![PyPI](https://img.shields.io/pypi/v/ciphyrs)](https://pypi.org/project/ciphyrs/)
+[![Python](https://img.shields.io/pypi/pyversions/ciphyrs)](https://pypi.org/project/ciphyrs/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+Intercept, mask, and restore PII before it reaches any LLM. Works with LangChain, CrewAI, or any Python application.
+
+## Install
+
+```bash
+pip install ciphyrs                  # core SDK
+pip install 'ciphyrs[langchain]'     # + LangChain integration
+pip install 'ciphyrs[crewai]'        # + CrewAI integration
+pip install 'ciphyrs[all]'           # everything
+```
+
+## Quick Start
+
+```python
+from ciphyrs import CiphyrsClient
+
+client = CiphyrsClient(
+    api_key="cyp_live_...",
+    base_url="https://www.ciphyrs.com"
+)
+
+# Mask PII
+result = client.mask("Contact Praveen at 9876125640 and praveen@acme.com")
+print(result.masked_text)
+# "Contact XXXX_a1b2c3 at XXXX_d4e5f6 and XXXX_g7h8i9"
+
+# Restore PII
+restored = client.restore(result.masked_text, result.session_id)
+print(restored.restored_text)
+# "Contact Praveen at 9876125640 and praveen@acme.com"
+```
+
+## Authentication
+
+All API calls require an `x-api-key` header. Get your API key from the [Ciphyrs Dashboard](https://www.ciphyrs.com/dashboard).
+
+1. Register at [ciphyrs.com/register](https://www.ciphyrs.com/register)
+2. Go to **Settings > API Keys**
+3. Click **Generate API Key**
+4. Copy the key (starts with `cyp_live_`)
+
+## LangChain Integration
+
+### Option 1: Callback Handler (auto-masks all LLM calls)
+
+```python
+from langchain_openai import ChatOpenAI
+from ciphyrs.integrations.langchain import CiphyrsPIICallback
+
+callback = CiphyrsPIICallback(api_key="cyp_live_...")
+llm = ChatOpenAI(model="gpt-4o", callbacks=[callback])
+
+# PII is automatically masked before reaching OpenAI
+# and restored in the response
+result = llm.invoke("Hi, I'm Praveen Kumar, my phone is 9876125640")
+```
+
+### Option 2: LCEL Runnables (pipe operator)
+
+```python
+from ciphyrs.integrations.langchain import CiphyrsMaskRunnable, CiphyrsRestoreRunnable
+
+session = {}
+mask = CiphyrsMaskRunnable(api_key="cyp_live_...", session_store=session)
+restore = CiphyrsRestoreRunnable(api_key="cyp_live_...", session_store=session)
+
+# Build pipeline: mask -> prompt -> llm -> restore
+chain = mask | prompt_template | llm | restore
+result = chain.invoke({"input": "Call Praveen at 9876125640"})
+```
+
+### Option 3: Shield Wrapper (wrap any chain)
+
+```python
+from ciphyrs.integrations.langchain import CiphyrsShield
+
+shield = CiphyrsShield(api_key="cyp_live_...")
+safe_chain = shield.wrap(my_existing_chain)
+result = safe_chain.invoke({"input": "Praveen's email is praveen@acme.com"})
+```
+
+## Async Support
+
+```python
+from ciphyrs import AsyncCiphyrsClient
+
+async with AsyncCiphyrsClient(api_key="cyp_live_...") as client:
+    result = await client.mask("Contact Praveen at praveen@acme.com")
+    restored = await client.restore(result.masked_text, result.session_id)
+```
+
+## Detected Entity Types
+
+| Entity | Example |
+|--------|---------|
+| PERSON | Praveen Kumar |
+| EMAIL | praveen@acme.com |
+| PHONE | 9876125640 |
+| IN_AADHAAR | 2345 6789 0123 |
+| IN_PAN | ABCDE1234F |
+| CREDIT_CARD | 4111-1111-1111-1111 |
+| IP_ADDRESS | 192.168.1.1 |
+| DATE_OF_BIRTH | 15/03/1990 |
+| LOCATION | Mumbai |
+| ORGANIZATION | Acme Corp |
+| API_KEY | sk-abc123... |
+
+## Links
+
+- [Website](https://www.ciphyrs.com)
+- [Documentation](https://www.ciphyrs.com/docs)
+- [Dashboard](https://www.ciphyrs.com/dashboard)

ciphyrs-1.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ciphyrs"
+version = "1.1.0"
+description = "Python SDK for the Ciphyrs PII Shield API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [
+    { name = "Ciphyrs", email = "support@ciphyrs.com" },
+]
+keywords = ["pii", "privacy", "masking", "ciphyrs"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "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",
+    "Topic :: Security",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.25.0",
+]
+
+[project.optional-dependencies]
+langchain = [
+    "langchain-core>=0.2.0",
+]
+crewai = [
+    "crewai>=0.41.0",
+]
+all = [
+    "langchain-core>=0.2.0",
+    "crewai>=0.41.0",
+]
+
+[project.urls]
+Homepage = "https://www.ciphyrs.com"
+Documentation = "https://www.ciphyrs.com/docs"
+Repository = "https://github.com/praveen190/Ciphyrs"
+Changelog = "https://github.com/praveen190/Ciphyrs/releases"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ciphyrs"]

ciphyrs-1.1.0/src/ciphyrs/__init__.py

@@ -0,0 +1,31 @@
+"""Ciphyrs PII Shield Python SDK."""
+
+from .client import AsyncCiphyrsClient, CiphyrsClient
+from .errors import (
+    CiphyrsAuthError,
+    CiphyrsError,
+    CiphyrsJobTimeoutError,
+    CiphyrsNotFoundError,
+    CiphyrsPermissionError,
+    CiphyrsRateLimitError,
+    CiphyrsTimeoutError,
+)
+from ._types import AsyncMaskResult, JobResult, MaskResult, RestoreResult
+
+__all__ = [
+    "CiphyrsClient",
+    "AsyncCiphyrsClient",
+    "CiphyrsError",
+    "CiphyrsAuthError",
+    "CiphyrsPermissionError",
+    "CiphyrsNotFoundError",
+    "CiphyrsRateLimitError",
+    "CiphyrsTimeoutError",
+    "CiphyrsJobTimeoutError",
+    "MaskResult",
+    "RestoreResult",
+    "AsyncMaskResult",
+    "JobResult",
+]
+
+__version__ = "1.1.0"

ciphyrs-1.1.0/src/ciphyrs/_http.py

@@ -0,0 +1,183 @@
+"""Internal HTTP transport with retry logic for the Ciphyrs SDK."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Any
+
+import httpx
+
+from .errors import (
+    CiphyrsAuthError,
+    CiphyrsError,
+    CiphyrsNotFoundError,
+    CiphyrsPermissionError,
+    CiphyrsRateLimitError,
+    CiphyrsTimeoutError,
+)
+
+_MAX_RETRIES = 3
+_BACKOFF_BASE = 0.5
+_BACKOFF_FACTOR = 2.0
+_RETRYABLE_STATUS_CODES = frozenset({429, 500, 502, 503, 504})
+
+
+def _parse_error_body(response: httpx.Response) -> tuple[str, str | None]:
+    """Extract message and error code from an error response body."""
+    try:
+        body = response.json()
+        message = body.get("error", body.get("message", response.reason_phrase or "Unknown error"))
+        code = body.get("code")
+    except Exception:
+        message = response.reason_phrase or "Unknown error"
+        code = None
+    return message, code
+
+
+def _raise_for_status(response: httpx.Response) -> None:
+    """Map HTTP status codes to typed SDK exceptions."""
+    if response.is_success:
+        return
+
+    status = response.status_code
+    message, code = _parse_error_body(response)
+
+    if status == 401:
+        raise CiphyrsAuthError(message=message, code=code)
+    if status == 403:
+        raise CiphyrsPermissionError(message=message, code=code)
+    if status == 404:
+        raise CiphyrsNotFoundError(message=message, code=code)
+    if status == 429:
+        retry_after_raw = response.headers.get("retry-after")
+        retry_after: float | None = None
+        if retry_after_raw is not None:
+            try:
+                retry_after = float(retry_after_raw)
+            except (ValueError, TypeError):
+                retry_after = None
+        raise CiphyrsRateLimitError(message=message, retry_after=retry_after, code=code)
+
+    raise CiphyrsError(message=message, status=status, code=code)
+
+
+def _backoff_delay(attempt: int, retry_after: float | None = None) -> float:
+    """Calculate delay for the given retry attempt, respecting Retry-After if present."""
+    base_delay = _BACKOFF_BASE * (_BACKOFF_FACTOR ** attempt)
+    if retry_after is not None and retry_after > base_delay:
+        return retry_after
+    return base_delay
+
+
+class SyncHTTPClient:
+    """Synchronous HTTP client with automatic retries."""
+
+    def __init__(self, base_url: str, api_key: str, timeout: float) -> None:
+        self._client = httpx.Client(
+            base_url=base_url,
+            headers={
+                "x-api-key": api_key,
+                "Content-Type": "application/json",
+                "User-Agent": "ciphyrs-python/1.0.0",
+            },
+            timeout=httpx.Timeout(timeout),
+        )
+
+    def request(self, method: str, path: str, **kwargs: Any) -> dict[str, Any]:
+        last_exc: Exception | None = None
+
+        for attempt in range(_MAX_RETRIES + 1):
+            try:
+                response = self._client.request(method, path, **kwargs)
+            except httpx.TimeoutException as exc:
+                if attempt < _MAX_RETRIES:
+                    time.sleep(_backoff_delay(attempt))
+                    last_exc = exc
+                    continue
+                raise CiphyrsTimeoutError() from exc
+            except httpx.HTTPError as exc:
+                raise CiphyrsError(str(exc)) from exc
+
+            if response.status_code in _RETRYABLE_STATUS_CODES and attempt < _MAX_RETRIES:
+                retry_after: float | None = None
+                if response.status_code == 429:
+                    raw = response.headers.get("retry-after")
+                    if raw is not None:
+                        try:
+                            retry_after = float(raw)
+                        except (ValueError, TypeError):
+                            pass
+                time.sleep(_backoff_delay(attempt, retry_after))
+                last_exc = None
+                continue
+
+            _raise_for_status(response)
+
+            if response.status_code == 204:
+                return {}
+            return response.json()  # type: ignore[no-any-return]
+
+        # Should not reach here, but just in case
+        if last_exc is not None:
+            raise CiphyrsTimeoutError() from last_exc
+        raise CiphyrsError("Max retries exceeded")
+
+    def close(self) -> None:
+        self._client.close()
+
+
+class AsyncHTTPClient:
+    """Asynchronous HTTP client with automatic retries."""
+
+    def __init__(self, base_url: str, api_key: str, timeout: float) -> None:
+        self._client = httpx.AsyncClient(
+            base_url=base_url,
+            headers={
+                "x-api-key": api_key,
+                "Content-Type": "application/json",
+                "User-Agent": "ciphyrs-python/1.0.0",
+            },
+            timeout=httpx.Timeout(timeout),
+        )
+
+    async def request(self, method: str, path: str, **kwargs: Any) -> dict[str, Any]:
+        last_exc: Exception | None = None
+
+        for attempt in range(_MAX_RETRIES + 1):
+            try:
+                response = await self._client.request(method, path, **kwargs)
+            except httpx.TimeoutException as exc:
+                if attempt < _MAX_RETRIES:
+                    await asyncio.sleep(_backoff_delay(attempt))
+                    last_exc = exc
+                    continue
+                raise CiphyrsTimeoutError() from exc
+            except httpx.HTTPError as exc:
+                raise CiphyrsError(str(exc)) from exc
+
+            if response.status_code in _RETRYABLE_STATUS_CODES and attempt < _MAX_RETRIES:
+                retry_after: float | None = None
+                if response.status_code == 429:
+                    raw = response.headers.get("retry-after")
+                    if raw is not None:
+                        try:
+                            retry_after = float(raw)
+                        except (ValueError, TypeError):
+                            pass
+                await asyncio.sleep(_backoff_delay(attempt, retry_after))
+                last_exc = None
+                continue
+
+            _raise_for_status(response)
+
+            if response.status_code == 204:
+                return {}
+            return response.json()  # type: ignore[no-any-return]
+
+        if last_exc is not None:
+            raise CiphyrsTimeoutError() from last_exc
+        raise CiphyrsError("Max retries exceeded")
+
+    async def close(self) -> None:
+        await self._client.aclose()

ciphyrs-1.1.0/src/ciphyrs/_types.py

@@ -0,0 +1,94 @@
+"""Data classes for Ciphyrs API responses."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class MaskResult:
+    """Result of a synchronous mask operation."""
+
+    masked_text: str
+    session_id: str
+    entities_found: list[str] = field(default_factory=list)
+    entity_summary: dict[str, int] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> MaskResult:
+        return cls(
+            masked_text=data["masked_text"],
+            session_id=data["session_id"],
+            entities_found=data.get("entities_found", []),
+            entity_summary=data.get("entity_summary", {}),
+        )
+
+
+@dataclass(frozen=True)
+class RestoreResult:
+    """Result of a restore operation."""
+
+    restored_text: str
+    tokens_restored: int
+    purged: bool = False
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> RestoreResult:
+        return cls(
+            restored_text=data["restored_text"],
+            tokens_restored=data.get("tokens_restored", 0),
+            purged=data.get("purged", False),
+        )
+
+
+@dataclass(frozen=True)
+class AsyncMaskResult:
+    """Result of submitting an async mask job."""
+
+    job_id: str
+    session_id: str
+    status: str
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> AsyncMaskResult:
+        return cls(
+            job_id=data["job_id"],
+            session_id=data["session_id"],
+            status=data.get("status", "pending"),
+        )
+
+
+@dataclass(frozen=True)
+class JobResult:
+    """Result of polling a job."""
+
+    job_id: str
+    status: str
+    session_id: str | None = None
+    masked_text: str | None = None
+    entities_found: list[str] = field(default_factory=list)
+    entity_summary: dict[str, int] = field(default_factory=dict)
+    latency_ms: float | None = None
+    error: str | None = None
+
+    @property
+    def is_complete(self) -> bool:
+        return self.status == "completed"
+
+    @property
+    def is_failed(self) -> bool:
+        return self.status == "failed"
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> JobResult:
+        return cls(
+            job_id=data["job_id"],
+            status=data["status"],
+            session_id=data.get("session_id"),
+            masked_text=data.get("masked_text"),
+            entities_found=data.get("entities_found", []),
+            entity_summary=data.get("entity_summary", {}),
+            latency_ms=data.get("latency_ms"),
+            error=data.get("error"),
+        )