ciphyrs 1.1.0__py3-none-any.whl

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/_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/_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"),
+        )

ciphyrs/client.py

@@ -0,0 +1,313 @@
+"""Ciphyrs PII Shield API client (sync and async)."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Any
+
+from ._http import AsyncHTTPClient, SyncHTTPClient
+from ._types import AsyncMaskResult, JobResult, MaskResult, RestoreResult
+from .errors import CiphyrsJobTimeoutError
+
+_DEFAULT_BASE_URL = "https://www.ciphyrs.com"
+
+
+def _build_mask_payload(
+    text: str,
+    session_id: str | None,
+    source: str,
+    surface: str,
+    entities: list[str] | None,
+    llm_provider: str | None,
+) -> dict[str, Any]:
+    payload: dict[str, Any] = {
+        "text": text,
+        "source": source,
+        "surface": surface,
+    }
+    if session_id is not None:
+        payload["session_id"] = session_id
+    if entities is not None:
+        payload["entities"] = entities
+    if llm_provider is not None:
+        payload["llm_provider"] = llm_provider
+    return payload
+
+
+class CiphyrsClient:
+    """Synchronous client for the Ciphyrs PII Shield API.
+
+    Usage::
+
+        client = CiphyrsClient(api_key="cprs_...")
+        result = client.mask("My SSN is 123-45-6789")
+        print(result.masked_text)
+        client.close()
+
+    Can also be used as a context manager::
+
+        with CiphyrsClient(api_key="cprs_...") as client:
+            result = client.mask("My SSN is 123-45-6789")
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout: float = 10.0,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key must be a non-empty string")
+        self._http = SyncHTTPClient(base_url=base_url, api_key=api_key, timeout=timeout)
+
+    def __enter__(self) -> CiphyrsClient:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        self._http.close()
+
+    # ── Mask ──────────────────────────────────────────────────────────
+
+    def mask(
+        self,
+        text: str,
+        session_id: str | None = None,
+        source: str = "PROMPT",
+        surface: str = "sdk",
+        entities: list[str] | None = None,
+        llm_provider: str | None = None,
+    ) -> MaskResult:
+        """Mask PII in text synchronously.
+
+        Args:
+            text: The text to scan and mask.
+            session_id: Optional session identifier for grouping related requests.
+            source: Origin label (e.g. ``"PROMPT"``, ``"RESPONSE"``).
+            surface: Integration surface (default ``"sdk"``).
+            entities: Optional list of entity types to detect.
+            llm_provider: Optional LLM provider hint.
+
+        Returns:
+            A :class:`MaskResult` with the masked text and metadata.
+        """
+        payload = _build_mask_payload(text, session_id, source, surface, entities, llm_provider)
+        data = self._http.request("POST", "/v1/scan/mask", json=payload)
+        return MaskResult.from_dict(data)
+
+    # ── Async Mask ────────────────────────────────────────────────────
+
+    def mask_async(
+        self,
+        text: str,
+        session_id: str | None = None,
+        source: str = "PROMPT",
+        surface: str = "sdk",
+        entities: list[str] | None = None,
+        llm_provider: str | None = None,
+    ) -> AsyncMaskResult:
+        """Submit an asynchronous mask job.
+
+        Returns immediately with a job ID that can be polled via
+        :meth:`get_job` or awaited via :meth:`wait_for_job`.
+        """
+        payload = _build_mask_payload(text, session_id, source, surface, entities, llm_provider)
+        data = self._http.request("POST", "/v1/scan/mask/async", json=payload)
+        return AsyncMaskResult.from_dict(data)
+
+    # ── Restore ───────────────────────────────────────────────────────
+
+    def restore(self, masked_text: str, session_id: str, *, purge: bool = False) -> RestoreResult:
+        """Restore previously masked text back to its original form.
+
+        Args:
+            masked_text: The masked text containing placeholder tokens.
+            session_id: The session ID returned from the original mask call.
+            purge: If True, delete tokens from the vault after restore.
+
+        Returns:
+            A :class:`RestoreResult` with the restored text.
+        """
+        payload: dict[str, Any] = {"text": masked_text, "session_id": session_id, "purge": purge}
+        data = self._http.request("POST", "/v1/scan/restore", json=payload)
+        return RestoreResult.from_dict(data)
+
+    # ── Jobs ──────────────────────────────────────────────────────────
+
+    def get_job(self, job_id: str) -> JobResult:
+        """Get the current status and result of an async job."""
+        data = self._http.request("GET", f"/v1/scan/jobs/{job_id}")
+        return JobResult.from_dict(data)
+
+    def wait_for_job(
+        self,
+        job_id: str,
+        poll_interval: float = 0.5,
+        timeout: float = 60.0,
+    ) -> JobResult:
+        """Poll an async job until it completes or the timeout is reached.
+
+        Args:
+            job_id: The job ID to poll.
+            poll_interval: Seconds between poll requests.
+            timeout: Maximum seconds to wait before raising :class:`CiphyrsJobTimeoutError`.
+
+        Returns:
+            The final :class:`JobResult`.
+
+        Raises:
+            CiphyrsJobTimeoutError: If the job does not complete within *timeout* seconds.
+        """
+        deadline = time.monotonic() + timeout
+        while True:
+            result = self.get_job(job_id)
+            if result.is_complete or result.is_failed:
+                return result
+            if time.monotonic() >= deadline:
+                raise CiphyrsJobTimeoutError(job_id, timeout)
+            time.sleep(min(poll_interval, max(0, deadline - time.monotonic())))
+
+    # ── API Keys ──────────────────────────────────────────────────────
+
+    def create_key(
+        self,
+        name: str | None = None,
+        scopes: list[str] | None = None,
+    ) -> dict[str, Any]:
+        """Create a new API key.
+
+        Args:
+            name: Optional human-readable name for the key.
+            scopes: Optional list of permission scopes.
+
+        Returns:
+            A dict containing the new key details.
+        """
+        payload: dict[str, Any] = {}
+        if name is not None:
+            payload["name"] = name
+        if scopes is not None:
+            payload["scopes"] = scopes
+        return self._http.request("POST", "/v1/auth/api-keys", json=payload)
+
+    def list_keys(self) -> dict[str, Any]:
+        """List all API keys associated with the account."""
+        return self._http.request("GET", "/v1/auth/api-keys")
+
+
+class AsyncCiphyrsClient:
+    """Asynchronous client for the Ciphyrs PII Shield API.
+
+    Usage::
+
+        async with AsyncCiphyrsClient(api_key="cprs_...") as client:
+            result = await client.mask("My SSN is 123-45-6789")
+            print(result.masked_text)
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout: float = 10.0,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key must be a non-empty string")
+        self._http = AsyncHTTPClient(base_url=base_url, api_key=api_key, timeout=timeout)
+
+    async def __aenter__(self) -> AsyncCiphyrsClient:
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        await self._http.close()
+
+    # ── Mask ──────────────────────────────────────────────────────────
+
+    async def mask(
+        self,
+        text: str,
+        session_id: str | None = None,
+        source: str = "PROMPT",
+        surface: str = "sdk",
+        entities: list[str] | None = None,
+        llm_provider: str | None = None,
+    ) -> MaskResult:
+        """Mask PII in text asynchronously."""
+        payload = _build_mask_payload(text, session_id, source, surface, entities, llm_provider)
+        data = await self._http.request("POST", "/v1/scan/mask", json=payload)
+        return MaskResult.from_dict(data)
+
+    # ── Async Mask ────────────────────────────────────────────────────
+
+    async def mask_async(
+        self,
+        text: str,
+        session_id: str | None = None,
+        source: str = "PROMPT",
+        surface: str = "sdk",
+        entities: list[str] | None = None,
+        llm_provider: str | None = None,
+    ) -> AsyncMaskResult:
+        """Submit an asynchronous mask job."""
+        payload = _build_mask_payload(text, session_id, source, surface, entities, llm_provider)
+        data = await self._http.request("POST", "/v1/scan/mask/async", json=payload)
+        return AsyncMaskResult.from_dict(data)
+
+    # ── Restore ───────────────────────────────────────────────────────
+
+    async def restore(self, masked_text: str, session_id: str, *, purge: bool = False) -> RestoreResult:
+        """Restore previously masked text back to its original form."""
+        payload: dict[str, Any] = {"text": masked_text, "session_id": session_id, "purge": purge}
+        data = await self._http.request("POST", "/v1/scan/restore", json=payload)
+        return RestoreResult.from_dict(data)
+
+    # ── Jobs ──────────────────────────────────────────────────────────
+
+    async def get_job(self, job_id: str) -> JobResult:
+        """Get the current status and result of an async job."""
+        data = await self._http.request("GET", f"/v1/scan/jobs/{job_id}")
+        return JobResult.from_dict(data)
+
+    async def wait_for_job(
+        self,
+        job_id: str,
+        poll_interval: float = 0.5,
+        timeout: float = 60.0,
+    ) -> JobResult:
+        """Poll an async job until it completes or the timeout is reached."""
+        deadline = asyncio.get_event_loop().time() + timeout
+        while True:
+            result = await self.get_job(job_id)
+            if result.is_complete or result.is_failed:
+                return result
+            remaining = deadline - asyncio.get_event_loop().time()
+            if remaining <= 0:
+                raise CiphyrsJobTimeoutError(job_id, timeout)
+            await asyncio.sleep(min(poll_interval, remaining))
+
+    # ── API Keys ──────────────────────────────────────────────────────
+
+    async def create_key(
+        self,
+        name: str | None = None,
+        scopes: list[str] | None = None,
+    ) -> dict[str, Any]:
+        """Create a new API key."""
+        payload: dict[str, Any] = {}
+        if name is not None:
+            payload["name"] = name
+        if scopes is not None:
+            payload["scopes"] = scopes
+        return await self._http.request("POST", "/v1/auth/api-keys", json=payload)
+
+    async def list_keys(self) -> dict[str, Any]:
+        """List all API keys associated with the account."""
+        return await self._http.request("GET", "/v1/auth/api-keys")