letscomplai 0.1.0__tar.gz

letscomplai-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AKVentures.ai, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

letscomplai-0.1.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: letscomplai
+Version: 0.1.0
+Summary: Python SDK for LetsComplai PII/PHI redaction and compliance gateway
+License-Expression: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25.0
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: responses>=0.18.0; extra == "dev"
+Requires-Dist: build>=1.2.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+Dynamic: license-file
+
+# LetsComplai Python SDK
+
+Python SDK for the LetsCompl.ai PII/PHI redaction engine and compliance API gateway.
+
+## Installation
+
+```bash
+pip install letscomplai
+```
+
+## Usage
+
+### Local Redaction
+
+```python
+from letscomplai import redact
+
+payload = {
+    "name": "The patient John Doe was diagnosed.",
+    "email": "test@example.com",
+    "ssn": "000-12-3456",
+}
+
+result = redact(payload)
+print(result["redacted"])
+# {
+#     "name": "patient [REDACTED_NAME] was diagnosed.",
+#     "email": "[REDACTED_EMAIL]",
+#     "ssn": "[REDACTED_SSN]"
+# }
+print(result["hits"])  # ['SSN', 'EMAIL', 'NAME']
+```
+
+### Remote Evaluation
+
+```python
+from letscomplai import LetsComplaiClient
+
+client = LetsComplaiClient(api_key="your-api-key")
+
+result = client.evaluate({
+    "patient_notes": "Mr. John Smith has a history of asthma.",
+})
+print(result)
+```
+
+By default, `evaluate()` redacts PII/PHI **locally, before the payload is sent to the gateway** — raw sensitive data never leaves your process. Pass `redact=False` as an explicit opt-out to send the raw, unredacted payload:
+
+```python
+client.evaluate(payload, redact=False)  # explicit opt-out — sends the raw payload
+```
+
+`evaluate()` also accepts `rules` (a list of rule keys to restrict evaluation to a subset instead of the full workspace policy) and `pinned_versions` (a dict mapping ruleset key to a historical version number, for audit replay):
+
+```python
+client.evaluate(payload, rules=["ftc_budget_cap"], pinned_versions={"ftc_budget_cap": 2})
+```
+
+Passing `rules` makes the response's `policyScope` `"filtered"` instead of `"full"`, with `evaluatedRules` listing exactly which rule keys ran. **A `"filtered"` response is not a complete compliance decision** — it only reflects the requested subset, not the workspace's full active policy. Omit `rules` to evaluate everything.
+
+### Guarding an action
+
+```python
+from letscomplai import LetsComplaiClient
+
+client = LetsComplaiClient(api_key="your-api-key")
+result = client.guard_action(
+    {"action": "payout", "amount": 1200},
+    lambda: payments.create_payout(amount=1200),
+)
+```
+
+`guard_action` raises `ComplianceBlockedError` if the verdict is `blocked`, and (by default) `ComplianceUnavailableError` if the gateway is unreachable, before the action callable runs.
+
+### Async client
+
+```python
+from letscomplai import AsyncLetsComplaiClient
+
+client = AsyncLetsComplaiClient(api_key="your-api-key")
+result = await client.evaluate({"action": "payout", "amount": 1200})
+await client.aclose()
+```
+
+`AsyncLetsComplaiClient` mirrors `LetsComplaiClient`'s `evaluate`/`guard_action`/`redact_local` methods for asyncio applications.
+
+> LetsCompl.ai is a technical enforcement tool, not a legal compliance service. Verdicts do not constitute legal advice.
+
+For timeout, fail-open/fail-closed, retry, SLA, and local-enforcement behavior, see [docs/operations/client-availability.md](https://github.com/akventures-ai/letscomplai/blob/main/docs/operations/client-availability.md).

letscomplai-0.1.0/README.md

@@ -0,0 +1,89 @@
+# LetsComplai Python SDK
+
+Python SDK for the LetsCompl.ai PII/PHI redaction engine and compliance API gateway.
+
+## Installation
+
+```bash
+pip install letscomplai
+```
+
+## Usage
+
+### Local Redaction
+
+```python
+from letscomplai import redact
+
+payload = {
+    "name": "The patient John Doe was diagnosed.",
+    "email": "test@example.com",
+    "ssn": "000-12-3456",
+}
+
+result = redact(payload)
+print(result["redacted"])
+# {
+#     "name": "patient [REDACTED_NAME] was diagnosed.",
+#     "email": "[REDACTED_EMAIL]",
+#     "ssn": "[REDACTED_SSN]"
+# }
+print(result["hits"])  # ['SSN', 'EMAIL', 'NAME']
+```
+
+### Remote Evaluation
+
+```python
+from letscomplai import LetsComplaiClient
+
+client = LetsComplaiClient(api_key="your-api-key")
+
+result = client.evaluate({
+    "patient_notes": "Mr. John Smith has a history of asthma.",
+})
+print(result)
+```
+
+By default, `evaluate()` redacts PII/PHI **locally, before the payload is sent to the gateway** — raw sensitive data never leaves your process. Pass `redact=False` as an explicit opt-out to send the raw, unredacted payload:
+
+```python
+client.evaluate(payload, redact=False)  # explicit opt-out — sends the raw payload
+```
+
+`evaluate()` also accepts `rules` (a list of rule keys to restrict evaluation to a subset instead of the full workspace policy) and `pinned_versions` (a dict mapping ruleset key to a historical version number, for audit replay):
+
+```python
+client.evaluate(payload, rules=["ftc_budget_cap"], pinned_versions={"ftc_budget_cap": 2})
+```
+
+Passing `rules` makes the response's `policyScope` `"filtered"` instead of `"full"`, with `evaluatedRules` listing exactly which rule keys ran. **A `"filtered"` response is not a complete compliance decision** — it only reflects the requested subset, not the workspace's full active policy. Omit `rules` to evaluate everything.
+
+### Guarding an action
+
+```python
+from letscomplai import LetsComplaiClient
+
+client = LetsComplaiClient(api_key="your-api-key")
+result = client.guard_action(
+    {"action": "payout", "amount": 1200},
+    lambda: payments.create_payout(amount=1200),
+)
+```
+
+`guard_action` raises `ComplianceBlockedError` if the verdict is `blocked`, and (by default) `ComplianceUnavailableError` if the gateway is unreachable, before the action callable runs.
+
+### Async client
+
+```python
+from letscomplai import AsyncLetsComplaiClient
+
+client = AsyncLetsComplaiClient(api_key="your-api-key")
+result = await client.evaluate({"action": "payout", "amount": 1200})
+await client.aclose()
+```
+
+`AsyncLetsComplaiClient` mirrors `LetsComplaiClient`'s `evaluate`/`guard_action`/`redact_local` methods for asyncio applications.
+
+> LetsCompl.ai is a technical enforcement tool, not a legal compliance service. Verdicts do not constitute legal advice.
+
+For timeout, fail-open/fail-closed, retry, SLA, and local-enforcement behavior, see [docs/operations/client-availability.md](https://github.com/akventures-ai/letscomplai/blob/main/docs/operations/client-availability.md).

letscomplai-0.1.0/letscomplai/__init__.py

@@ -0,0 +1,22 @@
+from letscomplai.client import LetsComplaiClient
+from letscomplai.async_client import AsyncLetsComplaiClient
+from letscomplai.errors import (
+    ComplianceBlockedError,
+    ComplianceUnavailableError,
+    LetsComplaiTransportError,
+)
+from letscomplai.guard import GuardedActionResult
+from letscomplai.redactor import redact, RedactResult
+from letscomplai.validation import require_json_object
+
+__all__ = [
+    "LetsComplaiClient",
+    "AsyncLetsComplaiClient",
+    "ComplianceBlockedError",
+    "ComplianceUnavailableError",
+    "LetsComplaiTransportError",
+    "GuardedActionResult",
+    "redact",
+    "RedactResult",
+    "require_json_object",
+]

letscomplai-0.1.0/letscomplai/async_client.py

@@ -0,0 +1,130 @@
+import inspect
+from typing import Any, Awaitable, Callable, Dict, List, Optional, Union
+import httpx
+
+from letscomplai.errors import (
+    ComplianceBlockedError,
+    ComplianceUnavailableError,
+    LetsComplaiTransportError,
+)
+from letscomplai.guard import GuardedActionResult
+from letscomplai.redactor import redact as redact_fn, RedactResult
+from letscomplai.validation import require_json_object
+
+
+class AsyncLetsComplaiClient:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://api.letscompl.ai",
+        timeout_seconds: float = 10.0,
+        transport_errors: str = "return",
+    ):
+        if not api_key:
+            raise ValueError("LetsComplai API key is required.")
+        if timeout_seconds <= 0:
+            raise ValueError("timeout_seconds must be positive")
+        if transport_errors not in ("return", "raise"):
+            raise ValueError('transport_errors must be "return" or "raise"')
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout_seconds = timeout_seconds
+        self.transport_errors = transport_errors
+        self._client = httpx.AsyncClient()
+
+    def redact_local(self, payload: Dict[str, Any]) -> RedactResult:
+        return redact_fn(payload)
+
+    async def aclose(self):
+        await self._client.aclose()
+
+    def _error_result(
+        self,
+        code: str,
+        outgoing_payload: Dict[str, Any],
+        redact: bool,
+    ) -> Dict[str, Any]:
+        return {
+            "verdict": "error",
+            "citation": None,
+            "redactedPayload": outgoing_payload,
+            "latencyMs": 0,
+            "llmUsed": False,
+            "piiRedacted": redact,
+            "evaluations": [],
+            "unsupportedRules": [],
+            "policyScope": "full",
+            "evaluatedRules": [],
+            "disclaimer": "",
+            "error": code,
+        }
+
+    async def evaluate(
+        self,
+        payload: Dict[str, Any],
+        rules: Optional[List[str]] = None,
+        pinned_versions: Optional[Dict[str, int]] = None,
+        redact: bool = True,
+        timeout_seconds: Optional[float] = None,
+    ) -> Dict[str, Any]:
+        url = f"{self.base_url}/api/v1/evaluate"
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+        payload = require_json_object(payload)
+        outgoing_payload = redact_fn(payload)["redacted"] if redact else payload
+        body: Dict[str, Any] = {"payload": outgoing_payload}
+        if rules is not None:
+            body["rules"] = rules
+        if pinned_versions is not None:
+            body["pinnedVersions"] = pinned_versions
+
+        timeout = timeout_seconds if timeout_seconds is not None else self.timeout_seconds
+
+        try:
+            response = await self._client.post(
+                url, json=body, headers=headers, timeout=timeout
+            )
+        except Exception as e:
+            if self.transport_errors == "raise":
+                raise LetsComplaiTransportError("network_error", str(e))
+            return self._error_result("network_error", outgoing_payload, redact)
+
+        if not response.is_success:
+            if self.transport_errors == "raise":
+                raise LetsComplaiTransportError(
+                    "gateway_error", "Gateway request failed.", response.status_code
+                )
+            return self._error_result("gateway_error", outgoing_payload, redact)
+
+        try:
+            return response.json()
+        except Exception as e:
+            if self.transport_errors == "raise":
+                raise LetsComplaiTransportError("network_error", str(e))
+            return self._error_result("network_error", outgoing_payload, redact)
+
+    async def guard_action(
+        self,
+        payload: Dict[str, Any],
+        action: Callable[[], Union[Any, Awaitable[Any]]],
+        unavailable: str = "deny",
+        **evaluate_options: Any,
+    ) -> GuardedActionResult:
+        if unavailable not in ("deny", "allow"):
+            raise ValueError('unavailable must be "deny" or "allow"')
+        redact = evaluate_options.get("redact", True)
+        try:
+            evaluation = await self.evaluate(payload, **evaluate_options)
+        except LetsComplaiTransportError as exc:
+            outgoing_payload = redact_fn(payload)["redacted"] if redact else payload
+            evaluation = self._error_result(exc.code, outgoing_payload, redact)
+        if evaluation.get("verdict") == "blocked":
+            raise ComplianceBlockedError(evaluation)
+        if evaluation.get("verdict") == "error" and unavailable == "deny":
+            raise ComplianceUnavailableError(evaluation)
+        result = action()
+        if inspect.isawaitable(result):
+            result = await result
+        return GuardedActionResult(evaluation=evaluation, value=result)

letscomplai-0.1.0/letscomplai/client.py

@@ -0,0 +1,131 @@
+from typing import Any, Callable, Dict, List, Optional
+import requests
+
+from letscomplai.errors import (
+    ComplianceBlockedError,
+    ComplianceUnavailableError,
+    LetsComplaiTransportError,
+)
+from letscomplai.guard import GuardedActionResult
+from letscomplai.redactor import redact as redact_fn, RedactResult
+from letscomplai.validation import require_json_object
+
+
+class LetsComplaiClient:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://api.letscompl.ai",
+        timeout_seconds: float = 10.0,
+        transport_errors: str = "return",
+    ):
+        if not api_key:
+            raise ValueError("LetsComplai API key is required.")
+        if timeout_seconds <= 0:
+            raise ValueError("timeout_seconds must be positive")
+        if transport_errors not in ("return", "raise"):
+            raise ValueError('transport_errors must be "return" or "raise"')
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout_seconds = timeout_seconds
+        self.transport_errors = transport_errors
+
+    def redact_local(self, payload: Dict[str, Any]) -> RedactResult:
+        """
+        Sanitizes PII/PHI in a payload locally before making any network requests.
+        Useful for keeping sensitive data completely local.
+        """
+        return redact_fn(payload)
+
+    def _error_result(
+        self,
+        code: str,
+        outgoing_payload: Dict[str, Any],
+        redact: bool,
+    ) -> Dict[str, Any]:
+        return {
+            "verdict": "error",
+            "citation": None,
+            "redactedPayload": outgoing_payload,
+            "latencyMs": 0,
+            "llmUsed": False,
+            "piiRedacted": redact,
+            "evaluations": [],
+            "unsupportedRules": [],
+            "policyScope": "full",
+            "evaluatedRules": [],
+            "disclaimer": "",
+            "error": code,
+        }
+
+    def evaluate(
+        self,
+        payload: Dict[str, Any],
+        rules: Optional[List[str]] = None,
+        pinned_versions: Optional[Dict[str, int]] = None,
+        redact: bool = True,
+        timeout_seconds: Optional[float] = None,
+    ) -> Dict[str, Any]:
+        """
+        Submits a payload to the LetsComplai gateway for compliance checks,
+        applying active rulesets and returning the verdict/citations.
+
+        By default, PII/PHI is redacted locally before transmission. Pass
+        redact=False as an explicit sensitive-data opt-out to send the raw payload.
+        """
+        url = f"{self.base_url}/api/v1/evaluate"
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+        payload = require_json_object(payload)
+        outgoing_payload = redact_fn(payload)["redacted"] if redact else payload
+        body: Dict[str, Any] = {"payload": outgoing_payload}
+        if rules is not None:
+            body["rules"] = rules
+        if pinned_versions is not None:
+            body["pinnedVersions"] = pinned_versions
+
+        timeout = timeout_seconds if timeout_seconds is not None else self.timeout_seconds
+
+        try:
+            response = requests.post(url, json=body, headers=headers, timeout=timeout)
+        except Exception as e:
+            if self.transport_errors == "raise":
+                raise LetsComplaiTransportError("network_error", str(e))
+            return self._error_result("network_error", outgoing_payload, redact)
+
+        if not response.ok:
+            if self.transport_errors == "raise":
+                raise LetsComplaiTransportError(
+                    "gateway_error", "Gateway request failed.", response.status_code
+                )
+            return self._error_result("gateway_error", outgoing_payload, redact)
+
+        try:
+            return response.json()
+        except Exception as e:
+            if self.transport_errors == "raise":
+                raise LetsComplaiTransportError("network_error", str(e))
+            return self._error_result("network_error", outgoing_payload, redact)
+
+    def guard_action(
+        self,
+        payload: Dict[str, Any],
+        action: Callable[[], Any],
+        unavailable: str = "deny",
+        **evaluate_options: Any,
+    ) -> GuardedActionResult:
+        if unavailable not in ("deny", "allow"):
+            raise ValueError('unavailable must be "deny" or "allow"')
+        redact = evaluate_options.get("redact", True)
+        try:
+            evaluation = self.evaluate(payload, **evaluate_options)
+        except LetsComplaiTransportError as exc:
+            outgoing_payload = redact_fn(payload)["redacted"] if redact else payload
+            evaluation = self._error_result(exc.code, outgoing_payload, redact)
+        if evaluation.get("verdict") == "blocked":
+            raise ComplianceBlockedError(evaluation)
+        if evaluation.get("verdict") == "error" and unavailable == "deny":
+            raise ComplianceUnavailableError(evaluation)
+        return GuardedActionResult(evaluation=evaluation, value=action())

letscomplai-0.1.0/letscomplai/errors.py

@@ -0,0 +1,20 @@
+from typing import Optional
+
+
+class LetsComplaiTransportError(Exception):
+    def __init__(self, code: str, message: str, status: Optional[int] = None):
+        super().__init__(message)
+        self.code = code
+        self.status = status
+
+
+class ComplianceBlockedError(Exception):
+    def __init__(self, evaluation):
+        super().__init__((evaluation.get("citation") or {}).get("ruleName", "Action blocked"))
+        self.evaluation = evaluation
+
+
+class ComplianceUnavailableError(Exception):
+    def __init__(self, evaluation):
+        super().__init__(evaluation.get("error", "Compliance evaluation unavailable"))
+        self.evaluation = evaluation

letscomplai-0.1.0/letscomplai/guard.py

@@ -0,0 +1,10 @@
+from dataclasses import dataclass
+from typing import Any, Dict, Generic, TypeVar
+
+T = TypeVar("T")
+
+
+@dataclass(frozen=True)
+class GuardedActionResult(Generic[T]):
+    evaluation: Dict[str, Any]
+    value: T

letscomplai-0.1.0/letscomplai/redactor.py

@@ -0,0 +1,101 @@
+import re
+from typing import Any, Dict, List, TypedDict, Union
+
+from letscomplai.validation import require_json_object
+
+# Compiled regex patterns matching those in typescript SDK
+PATTERNS = [
+    {
+        "name": "SSN",
+        "re": re.compile(r"\b\d{3}-\d{2}-\d{4}\b"),
+        "token": "[REDACTED_SSN]",
+    },
+    {
+        "name": "CARD",
+        "re": re.compile(r"\b(?:\d[ -]*?){13,16}\b"),
+        "token": "[REDACTED_CARD]",
+    },
+    {
+        "name": "MRN",
+        "re": re.compile(r"\bMRN:?\s*\d{6,10}\b", re.IGNORECASE),
+        "token": "[REDACTED_MRN]",
+    },
+    {
+        "name": "EMAIL",
+        "re": re.compile(r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b"),
+        "token": "[REDACTED_EMAIL]",
+    },
+    {
+        "name": "PHONE",
+        "re": re.compile(r"(\+?\d{1,2}[ .-]?)?\(?\d{3}\)?[ .-]?\d{3}[ .-]?\d{4}\b"),
+        "token": "[REDACTED_PHONE]",
+    },
+    {
+        "name": "ICD_CODE",
+        "re": re.compile(
+            r"\b(?:ICD-(?:9|10)(?:-CM)?:?\s*)?[A-Z]\d{2,3}(?:\.\d{1,4})?\b",
+            re.IGNORECASE,
+        ),
+        "token": "[REDACTED_ICD]",
+    },
+    {
+        "name": "CLINICAL_TERM",
+        "re": re.compile(
+            r"\b(cancer|diabetes|hypertension|asthma|depression|anxiety|leukemia|arthritis|dementia|covid(?:-19)?|influenza|schizophrenia|bipolar|stroke|hiv|aids)\b",
+            re.IGNORECASE,
+        ),
+        "token": "[REDACTED_CLINICAL]",
+    },
+]
+
+NAME_PATTERN = re.compile(
+    r"\b(patient|Mr\.?|Ms\.?|Mrs\.?|Dr\.?)\s+[A-Z][a-z]+\s+[A-Z][a-z]+\b"
+)
+
+
+class RedactResult(TypedDict):
+    redacted: Dict[str, Any]
+    hits: List[str]
+
+
+def scrub_string(s: str, hits: List[str]) -> str:
+    out = s
+    # CARD before PHONE to avoid the phone regex eating card digits
+    for p in PATTERNS:
+
+        def repl(match: re.Match) -> str:
+            hits.append(p["name"])
+            return p["token"]
+
+        out = p["re"].sub(repl, out)
+
+    def repl_name(match: re.Match) -> str:
+        hits.append("NAME")
+        prefix = match.group(1)
+        return f"{prefix} [REDACTED_NAME]"
+
+    out = NAME_PATTERN.sub(repl_name, out)
+    return out
+
+
+def walk(v: Any, hits: List[str]) -> Any:
+    if isinstance(v, str):
+        return scrub_string(v, hits)
+    elif isinstance(v, list):
+        return [walk(x, hits) for x in v]
+    elif isinstance(v, dict):
+        return {k: walk(val, hits) for k, val in v.items()}
+    return v
+
+
+def redact(payload: Dict[str, Any]) -> RedactResult:
+    """
+    Scrubs PII/PHI in a JSON payload dict locally.
+    Returns a dict with:
+      - 'redacted': the modified payload
+      - 'hits': list of names of patterns that matched (e.g. 'SSN', 'NAME')
+    """
+    payload = require_json_object(payload)
+    hits: List[str] = []
+    redacted = walk(payload, hits)
+    return {"redacted": redacted, "hits": hits}

letscomplai-0.1.0/letscomplai/validation.py

@@ -0,0 +1,7 @@
+from typing import Any, Dict
+
+
+def require_json_object(value: Any, label: str = "payload") -> Dict[str, Any]:
+    if not isinstance(value, dict):
+        raise TypeError(f"{label} must be a JSON object")
+    return value