ylemis 0.1.0__tar.gz

ylemis-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ylemis (Pranshu)
+
+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.

ylemis-0.1.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: ylemis
+Version: 0.1.0
+Summary: Official Python SDK for the Ylemis Trust Platform: PII Shield, Injection Guard, GroundCheck — one client, one integration.
+Author-email: Ylemis <pranshu.rs08@gmail.com>
+License: MIT
+Project-URL: Homepage, https://ylemis.com
+Project-URL: Documentation, https://ylemis.com/docs
+Keywords: pii,dpdp,guardrails,llm-security,india,aadhaar,prompt-injection,hallucination
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# ylemis — Python SDK for the Ylemis Trust Platform
+
+One integration for all Ylemis guardrails: **PII Shield** (India-tuned PII detection/redaction,
+98.68% F1, 0% false positives on the published benchmark), **Injection Guard**, and **GroundCheck**.
+Zero dependencies — stdlib only.
+
+```bash
+pip install ylemis
+```
+
+## 30-second DPDP fix
+
+You're piping customer data into an LLM. Aadhaar/PAN in a third-party model's logs is a
+₹250-crore DPDP exposure. One line stops it at the door:
+
+```python
+from ylemis import TrustEngine
+
+engine = TrustEngine(keys={"pii-shield": "sk_live_..."})
+
+safe_prompt = engine.check_input(user_text).redacted_text   # PII never leaves your app
+llm_response = call_your_llm(safe_prompt)
+```
+
+## The two hooks (full flow)
+
+Guardrails belong at two points in the LLM lifecycle — before the prompt goes out, and after
+the answer comes back:
+
+```python
+engine = TrustEngine(api_key="sk_live_...")    # one key everywhere (or keys={...} per product)
+
+inp = engine.check_input(prompt)                # PII + injection, PRE-LLM
+if inp.decision == "block":
+    ...                                         # your policy
+response = call_your_llm(inp.redacted_text)
+
+out = engine.check_output(response, docs=retrieved_docs)   # PII + groundedness, POST-LLM
+if out.decision == "allow":
+    return response
+```
+
+`engine.scan(prompt=..., response=..., docs=...)` is batch/audit sugar over both hooks.
+
+## Error handling — errors are honest
+
+The API never masks infra errors as billing errors. The SDK encodes that contract as types:
+
+```python
+from ylemis import QuotaExceeded, RateLimited, ServiceBusy, InvalidAPIKey
+
+try:
+    r = engine.pii.scan(text)
+except QuotaExceeded:   # 402 — genuinely out of quota, upgrade or wait for reset
+    ...
+except RateLimited:     # 429 — slow down (see .retry_after)
+    ...
+except ServiceBusy:     # 503 — transient; SDK already auto-retried per Retry-After
+    ...
+```
+
+Requests are metered only on success — a `ServiceBusy` retry never double-bills.
+
+## Per-product access
+
+```python
+engine.pii.scan(text, redaction_mode="mask")   # mask | replace | drop | hash
+engine.pii.redact(text)
+engine.pii.usage()
+engine.injection.score(text)
+engine.groundcheck.check(response, source=[...])
+engine.health()                                # no-auth liveness, all three services
+```
+
+Products without a configured key are skipped by `check_*` (listed in `report.skipped`)
+and raise `MissingKey` if called directly — so a PII-only key works fine today.
+
+## Development status
+
+All three adapters are exact, verified against the deployed services (2026-07-05),
+including a live end-to-end run with a single key across all three products.
+
+```bash
+python -m unittest discover -s tests -v    # offline, no keys needed
+```
+
+The SDK is MIT-licensed client code. API access requires a Ylemis subscription and
+key from [ylemis.com](https://ylemis.com).

ylemis-0.1.0/README.md

@@ -0,0 +1,88 @@
+# ylemis — Python SDK for the Ylemis Trust Platform
+
+One integration for all Ylemis guardrails: **PII Shield** (India-tuned PII detection/redaction,
+98.68% F1, 0% false positives on the published benchmark), **Injection Guard**, and **GroundCheck**.
+Zero dependencies — stdlib only.
+
+```bash
+pip install ylemis
+```
+
+## 30-second DPDP fix
+
+You're piping customer data into an LLM. Aadhaar/PAN in a third-party model's logs is a
+₹250-crore DPDP exposure. One line stops it at the door:
+
+```python
+from ylemis import TrustEngine
+
+engine = TrustEngine(keys={"pii-shield": "sk_live_..."})
+
+safe_prompt = engine.check_input(user_text).redacted_text   # PII never leaves your app
+llm_response = call_your_llm(safe_prompt)
+```
+
+## The two hooks (full flow)
+
+Guardrails belong at two points in the LLM lifecycle — before the prompt goes out, and after
+the answer comes back:
+
+```python
+engine = TrustEngine(api_key="sk_live_...")    # one key everywhere (or keys={...} per product)
+
+inp = engine.check_input(prompt)                # PII + injection, PRE-LLM
+if inp.decision == "block":
+    ...                                         # your policy
+response = call_your_llm(inp.redacted_text)
+
+out = engine.check_output(response, docs=retrieved_docs)   # PII + groundedness, POST-LLM
+if out.decision == "allow":
+    return response
+```
+
+`engine.scan(prompt=..., response=..., docs=...)` is batch/audit sugar over both hooks.
+
+## Error handling — errors are honest
+
+The API never masks infra errors as billing errors. The SDK encodes that contract as types:
+
+```python
+from ylemis import QuotaExceeded, RateLimited, ServiceBusy, InvalidAPIKey
+
+try:
+    r = engine.pii.scan(text)
+except QuotaExceeded:   # 402 — genuinely out of quota, upgrade or wait for reset
+    ...
+except RateLimited:     # 429 — slow down (see .retry_after)
+    ...
+except ServiceBusy:     # 503 — transient; SDK already auto-retried per Retry-After
+    ...
+```
+
+Requests are metered only on success — a `ServiceBusy` retry never double-bills.
+
+## Per-product access
+
+```python
+engine.pii.scan(text, redaction_mode="mask")   # mask | replace | drop | hash
+engine.pii.redact(text)
+engine.pii.usage()
+engine.injection.score(text)
+engine.groundcheck.check(response, source=[...])
+engine.health()                                # no-auth liveness, all three services
+```
+
+Products without a configured key are skipped by `check_*` (listed in `report.skipped`)
+and raise `MissingKey` if called directly — so a PII-only key works fine today.
+
+## Development status
+
+All three adapters are exact, verified against the deployed services (2026-07-05),
+including a live end-to-end run with a single key across all three products.
+
+```bash
+python -m unittest discover -s tests -v    # offline, no keys needed
+```
+
+The SDK is MIT-licensed client code. API access requires a Ylemis subscription and
+key from [ylemis.com](https://ylemis.com).

ylemis-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ylemis"
+version = "0.1.0"
+description = "Official Python SDK for the Ylemis Trust Platform: PII Shield, Injection Guard, GroundCheck — one client, one integration."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }  # client code only — models/services stay proprietary; access requires an API key
+authors = [{ name = "Ylemis", email = "pranshu.rs08@gmail.com" }]
+keywords = ["pii", "dpdp", "guardrails", "llm-security", "india", "aadhaar", "prompt-injection", "hallucination"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Topic :: Security",
+]
+# Zero runtime dependencies — stdlib only. This is deliberate: a guardrails SDK
+# should not widen a customer's supply-chain surface.
+dependencies = []
+
+[project.urls]
+Homepage = "https://ylemis.com"
+Documentation = "https://ylemis.com/docs"
+
+[tool.setuptools.packages.find]
+where = ["src"]

ylemis-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ylemis-0.1.0/src/ylemis/__init__.py

@@ -0,0 +1,20 @@
+"""Ylemis Trust Platform — official Python SDK (zero dependencies)."""
+
+from .client import (GroundCheckClient, InjectionGuardClient, PIIShieldClient,
+                     TrustEngine, DEFAULT_BASE_URL)
+from .exceptions import (APIError, InvalidAPIKey, MissingKey, PayloadTooLarge,
+                         QuotaExceeded, RateLimited, ServiceBusy, UpstreamTimeout,
+                         YlemisError)
+from .models import (CheckReport, Entity, GroundCheckResult, InjectionResult,
+                     PIIResult, RedactResult, Usage, merge_decisions)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "TrustEngine", "PIIShieldClient", "InjectionGuardClient", "GroundCheckClient",
+    "DEFAULT_BASE_URL",
+    "YlemisError", "MissingKey", "InvalidAPIKey", "QuotaExceeded", "PayloadTooLarge",
+    "RateLimited", "ServiceBusy", "UpstreamTimeout", "APIError",
+    "CheckReport", "PIIResult", "RedactResult", "Usage", "Entity",
+    "InjectionResult", "GroundCheckResult", "merge_decisions",
+]

ylemis-0.1.0/src/ylemis/_http.py

@@ -0,0 +1,94 @@
+"""Stdlib-only HTTP transport with honest-error mapping and 503 auto-retry.
+
+Retry policy: ONLY network errors and 503 ServiceBusy are retried (the API
+guarantees 503 means the request was NOT metered — see store_pg.StoreUnavailable).
+402/401/429 are never retried: they are truthful, actionable answers.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.request
+
+from .exceptions import APIError, RateLimited, ServiceBusy, STATUS_MAP, YlemisError
+
+_USER_AGENT = "ylemis-python/0.1.0"
+
+
+def _parse_retry_after(value: str | None, default: float = 1.0) -> float:
+    if not value:
+        return default
+    try:
+        return max(0.0, min(float(value), 10.0))  # cap: never sleep >10s per hop
+    except ValueError:
+        return default
+
+
+class Transport:
+    def __init__(self, base_url: str, *, timeout: float = 15.0, max_retries: int = 2):
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max(0, int(max_retries))
+
+    # -- public ----------------------------------------------------------
+    def request(self, method: str, path: str, *, api_key: str | None = None,
+                payload: dict | None = None, product: str | None = None) -> dict:
+        attempt = 0
+        while True:
+            try:
+                return self._once(method, path, api_key=api_key, payload=payload,
+                                  product=product)
+            except ServiceBusy as exc:
+                if attempt >= self.max_retries:
+                    raise
+                time.sleep(exc.retry_after or 1.0)
+            except YlemisError:
+                raise
+            except OSError as exc:  # DNS/conn reset — one class of retryable
+                if attempt >= self.max_retries:
+                    raise APIError(f"network error: {exc}", product=product) from exc
+                time.sleep(0.5 * (attempt + 1))
+            attempt += 1
+
+    # -- internals ---------------------------------------------------------
+    def _once(self, method: str, path: str, *, api_key: str | None,
+              payload: dict | None, product: str | None) -> dict:
+        url = f"{self.base_url}{path}"
+        headers = {"Accept": "application/json", "User-Agent": _USER_AGENT}
+        body = None
+        if payload is not None:
+            body = json.dumps(payload).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+        if api_key:
+            headers["X-API-Key"] = api_key
+        req = urllib.request.Request(url, data=body, headers=headers, method=method)
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                return self._decode(resp.read())
+        except urllib.error.HTTPError as err:
+            raise self._to_error(err, product) from None
+
+    @staticmethod
+    def _decode(raw: bytes) -> dict:
+        try:
+            data = json.loads(raw.decode("utf-8"))
+        except (ValueError, UnicodeDecodeError):
+            raise APIError("non-JSON response from API")
+        return data if isinstance(data, dict) else {"data": data}
+
+    @staticmethod
+    def _to_error(err: urllib.error.HTTPError, product: str | None) -> YlemisError:
+        status = err.code
+        try:
+            detail = json.loads(err.read().decode("utf-8"))
+        except Exception:
+            detail = None
+        message = (detail or {}).get("detail") if isinstance(detail, dict) else None
+        message = message or f"HTTP {status}"
+        cls = STATUS_MAP.get(status, APIError)
+        kwargs = {"status": status, "product": product, "detail": detail}
+        if cls in (ServiceBusy, RateLimited):
+            kwargs["retry_after"] = _parse_retry_after(err.headers.get("Retry-After"))
+        return cls(message, **kwargs)

ylemis-0.1.0/src/ylemis/client.py

@@ -0,0 +1,217 @@
+"""Ylemis Trust Platform client.
+
+Two hook points match the real LLM request lifecycle (input checks run BEFORE
+the prompt reaches the model — that is the DPDP story), plus `.scan()` as
+batch/audit sugar:
+
+    from ylemis import TrustEngine
+    engine = TrustEngine(keys={"pii-shield": "sk_live_..."})   # or api_key="..." for all
+    inp = engine.check_input(prompt)              # PII + injection, pre-LLM
+    safe_prompt = inp.redacted_text               # send THIS to the LLM
+    out = engine.check_output(response, docs=docs)  # PII + groundedness, post-LLM
+
+Keys: pass `api_key=` to use one key everywhere (forward-compatible with the
+unified platform key), and/or `keys={product: key}` per product. Products with
+no key are skipped by check_* (reported in `.skipped`) and raise MissingKey if
+called directly.
+"""
+
+from __future__ import annotations
+
+from concurrent.futures import ThreadPoolExecutor
+from typing import Dict, Iterable, Optional, Sequence
+
+from ._http import Transport
+from .exceptions import MissingKey
+from .models import (CheckReport, GroundCheckResult, InjectionResult, PIIResult,
+                     RedactResult, Usage, merge_decisions)
+
+DEFAULT_BASE_URL = "https://api.ylemis.com"
+PII, INJECTION, GROUNDCHECK = "pii-shield", "injection-guard", "groundcheck"
+
+
+class _ProductClient:
+    slug: str = ""
+    _health_path: str = "/health"
+
+    def __init__(self, transport: Transport, key: Optional[str]):
+        self._transport = transport
+        self._key = key
+
+    def _require_key(self) -> str:
+        if not self._key:
+            raise MissingKey(f"no API key configured for {self.slug}", product=self.slug)
+        return self._key
+
+    def _post(self, path: str, payload: dict) -> dict:
+        return self._transport.request("POST", f"/{self.slug}{path}",
+                                       api_key=self._require_key(), payload=payload,
+                                       product=self.slug)
+
+    def _get(self, path: str, *, auth: bool = True) -> dict:
+        return self._transport.request("GET", f"/{self.slug}{path}",
+                                       api_key=self._require_key() if auth else None,
+                                       product=self.slug)
+
+    @property
+    def configured(self) -> bool:
+        return bool(self._key)
+
+    def health(self) -> dict:
+        """No-auth liveness check."""
+        return self._get(self._health_path, auth=False)
+
+
+class PIIShieldClient(_ProductClient):
+    """Exact contract, verified against the deployed service source."""
+
+    slug = PII
+
+    def scan(self, text: str, *, redaction_mode: str = "mask") -> PIIResult:
+        return PIIResult.from_dict(self._post("/v1/scan", {"text": text, "redaction_mode": redaction_mode}))
+
+    def redact(self, text: str, *, redaction_mode: str = "mask") -> RedactResult:
+        return RedactResult.from_dict(self._post("/v1/redact", {"text": text, "redaction_mode": redaction_mode}))
+
+    def usage(self) -> Usage:
+        return Usage.from_dict(self._get("/v1/usage"))
+
+
+class InjectionGuardClient(_ProductClient):
+    """Exact contract (locked from the deployed service's API.md, 2026-07-04).
+    Limits: 100k chars/text; batch = max 32 texts, 200k chars total, metered per text."""
+
+    slug = INJECTION
+
+    def score(self, text: str, *, payload: Optional[dict] = None) -> InjectionResult:
+        return InjectionResult.from_dict(self._post("/v1/score", payload or {"text": text}))
+
+    def score_batch(self, texts: Sequence[str]) -> list[InjectionResult]:
+        data = self._post("/v1/batch", {"texts": list(texts)})
+        return [InjectionResult.from_dict(r) for r in data.get("results", [])]
+
+    def usage(self) -> Usage:
+        return Usage.from_dict(self._get("/v1/usage"))
+
+
+class GroundCheckClient(_ProductClient):
+    """Exact contract (locked from the deployed service source, 2026-07-04).
+    Limits: source <=50k chars, answer <=10k, question <=2k; batch <=32 items."""
+
+    slug = GROUNDCHECK
+    _health_path = "/healthz"
+
+    def check(self, answer: str = "", source: "str | Sequence[str] | None" = None, *,
+              question: str = "", threshold: float = 0.5, granular: bool = False,
+              payload: Optional[dict] = None) -> GroundCheckResult:
+        """Is `answer` supported by `source`? `source` may be one string or a
+        list of retrieved docs (joined with blank lines)."""
+        if payload is None:
+            if source is None:
+                raise ValueError("check() needs source= (the grounding text/docs)")
+            src = source if isinstance(source, str) else "\n\n".join(source)
+            payload = {"source": src, "answer": answer, "question": question,
+                       "threshold": threshold, "granular": granular}
+        return GroundCheckResult.from_dict(self._post("/v1/check", payload))
+
+    def check_batch(self, items: Sequence[dict]) -> list[GroundCheckResult]:
+        """items = list of {source, answer, question?, threshold?, granular?} (max 32)."""
+        data = self._post("/v1/check/batch", {"items": list(items)})
+        return [GroundCheckResult.from_dict(r) for r in data.get("results", [])]
+
+    def usage(self) -> Usage:
+        return Usage.from_dict(self._get("/v1/usage"))
+
+
+class TrustEngine:
+    def __init__(self, api_key: Optional[str] = None, *,
+                 keys: Optional[Dict[str, str]] = None,
+                 base_url: str = DEFAULT_BASE_URL,
+                 timeout: float = 15.0, max_retries: int = 2):
+        resolved = {p: api_key for p in (PII, INJECTION, GROUNDCHECK)}
+        resolved.update(keys or {})
+        self._transport = Transport(base_url, timeout=timeout, max_retries=max_retries)
+        self.pii = PIIShieldClient(self._transport, resolved.get(PII))
+        self.injection = InjectionGuardClient(self._transport, resolved.get(INJECTION))
+        self.groundcheck = GroundCheckClient(self._transport, resolved.get(GROUNDCHECK))
+
+    def __repr__(self) -> str:  # never leak keys
+        configured = [c.slug for c in (self.pii, self.injection, self.groundcheck) if c.configured]
+        return f"TrustEngine(products={configured})"
+
+    # -- hooks -------------------------------------------------------------
+    def check_input(self, prompt: str, *, checks: Iterable[str] = (PII, INJECTION),
+                    redaction_mode: str = "mask") -> CheckReport:
+        """Run pre-LLM guardrails on the outbound prompt. Use `.redacted_text`
+        as the safe prompt to actually send."""
+        checks = set(checks)
+        pii = inj = None
+        skipped: list[str] = []
+        with ThreadPoolExecutor(max_workers=2) as pool:
+            futures = {}
+            if PII in checks:
+                if self.pii.configured:
+                    futures[PII] = pool.submit(self.pii.scan, prompt, redaction_mode=redaction_mode)
+                else:
+                    skipped.append(PII)
+            if INJECTION in checks:
+                if self.injection.configured:
+                    futures[INJECTION] = pool.submit(self.injection.score, prompt)
+                else:
+                    skipped.append(INJECTION)
+            pii = futures[PII].result() if PII in futures else None
+            inj = futures[INJECTION].result() if INJECTION in futures else None
+        decision = merge_decisions(pii.decision if pii else None, inj.decision if inj else None)
+        return CheckReport(decision=decision, pii=pii, injection=inj, skipped=skipped)
+
+    def check_output(self, response: str, docs: Optional[Sequence[str]] = None, *,
+                     checks: Iterable[str] = (PII, GROUNDCHECK),
+                     redaction_mode: str = "mask") -> CheckReport:
+        """Run post-LLM guardrails on the model's answer (PII in the output;
+        groundedness against `docs` when provided)."""
+        checks = set(checks)
+        if docs is None:
+            checks.discard(GROUNDCHECK)  # nothing to ground against
+        pii = gc = None
+        skipped: list[str] = []
+        with ThreadPoolExecutor(max_workers=2) as pool:
+            futures = {}
+            if PII in checks:
+                if self.pii.configured:
+                    futures[PII] = pool.submit(self.pii.scan, response, redaction_mode=redaction_mode)
+                else:
+                    skipped.append(PII)
+            if GROUNDCHECK in checks:
+                if self.groundcheck.configured:
+                    futures[GROUNDCHECK] = pool.submit(self.groundcheck.check, response, docs)
+                else:
+                    skipped.append(GROUNDCHECK)
+            pii = futures[PII].result() if PII in futures else None
+            gc = futures[GROUNDCHECK].result() if GROUNDCHECK in futures else None
+        decision = merge_decisions(pii.decision if pii else None, gc.decision if gc else None)
+        return CheckReport(decision=decision, pii=pii, groundcheck=gc, skipped=skipped)
+
+    # -- audit sugar ---------------------------------------------------------
+    def scan(self, *, prompt: Optional[str] = None, response: Optional[str] = None,
+             docs: Optional[Sequence[str]] = None) -> CheckReport:
+        """Offline/batch convenience: checks whatever you pass, merges decisions.
+        For live traffic prefer check_input()/check_output() at their hook points."""
+        reports = []
+        if prompt is not None:
+            reports.append(self.check_input(prompt))
+        if response is not None:
+            reports.append(self.check_output(response, docs))
+        if not reports:
+            raise ValueError("scan() needs prompt= and/or response=")
+        merged = CheckReport(
+            decision=merge_decisions(*(r.decision for r in reports)),
+            pii=next((r.pii for r in reports if r.pii), None),
+            injection=next((r.injection for r in reports if r.injection), None),
+            groundcheck=next((r.groundcheck for r in reports if r.groundcheck), None),
+            skipped=sorted({s for r in reports for s in r.skipped}),
+        )
+        return merged
+
+    def health(self) -> Dict[str, dict]:
+        """No-auth liveness of all three services."""
+        return {c.slug: c.health() for c in (self.pii, self.injection, self.groundcheck)}

ylemis-0.1.0/src/ylemis/exceptions.py

@@ -0,0 +1,73 @@
+"""Typed errors encoding the Ylemis API error semantics.
+
+Contract (NEXT_AGENT_HANDOFF_2026-07-04.md §5.6):
+  401 = bad/revoked key          -> InvalidAPIKey
+  402 = GENUINE quota exhaustion -> QuotaExceeded  (never masked infra errors)
+  413 = payload too large        -> PayloadTooLarge
+  429 = rate limit / lockout     -> RateLimited
+  503 = retryable infra hiccup   -> ServiceBusy    (transport auto-retries, honoring Retry-After)
+  504 = request timeout          -> UpstreamTimeout
+"""
+
+from __future__ import annotations
+
+
+class YlemisError(Exception):
+    """Base for all SDK errors."""
+
+    def __init__(self, message: str, *, status: int | None = None,
+                 product: str | None = None, detail: object = None):
+        super().__init__(message)
+        self.status = status
+        self.product = product
+        self.detail = detail
+
+
+class MissingKey(YlemisError):
+    """No API key configured for the product being called."""
+
+
+class InvalidAPIKey(YlemisError):
+    """401 — key is missing, malformed, revoked, or scoped to another product."""
+
+
+class QuotaExceeded(YlemisError):
+    """402 — the plan's quota for this billing period is genuinely exhausted."""
+
+
+class PayloadTooLarge(YlemisError):
+    """413 — request body exceeds the service limit."""
+
+
+class RateLimited(YlemisError):
+    """429 — per-key/per-IP rate limit or temporary auth-failure lockout."""
+
+    def __init__(self, message: str, *, retry_after: float | None = None, **kw):
+        super().__init__(message, **kw)
+        self.retry_after = retry_after
+
+
+class ServiceBusy(YlemisError):
+    """503 — transient infra/DB issue. The SDK already retried before raising this."""
+
+    def __init__(self, message: str, *, retry_after: float | None = None, **kw):
+        super().__init__(message, **kw)
+        self.retry_after = retry_after
+
+
+class UpstreamTimeout(YlemisError):
+    """504 — the service timed out processing the request."""
+
+
+class APIError(YlemisError):
+    """Any other non-2xx response."""
+
+
+STATUS_MAP = {
+    401: InvalidAPIKey,
+    402: QuotaExceeded,
+    413: PayloadTooLarge,
+    429: RateLimited,
+    503: ServiceBusy,
+    504: UpstreamTimeout,
+}

ylemis-0.1.0/src/ylemis/models.py

@@ -0,0 +1,197 @@
+"""Result types. Every wrapper keeps the full server payload in `.raw`.
+
+PII Shield shapes are exact (verified against the deployed service source).
+Injection Guard / GroundCheck payloads are PROVISIONAL passthroughs until one
+live probe locks their field names — decisions for them are derived defensively.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+Decision = str  # "allow" | "review" | "block"
+_DECISION_RANK = {"allow": 0, "review": 1, "block": 2}
+
+
+def merge_decisions(*decisions: Optional[Decision]) -> Decision:
+    """Most-restrictive-wins merge; unknown/None values are ignored."""
+    best = "allow"
+    for d in decisions:
+        if d in _DECISION_RANK and _DECISION_RANK[d] > _DECISION_RANK[best]:
+            best = d
+    return best
+
+
+@dataclass(frozen=True)
+class Entity:
+    """One detected PII span (positions refer to the original text)."""
+
+    type: str
+    start: int
+    end: int
+    text_preview: str
+    confidence: float
+    severity: str
+    source: str = ""
+    method: str = ""
+    recognizer: str = ""
+    format_validated: bool = False
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "Entity":
+        return cls(
+            type=d.get("type", ""), start=int(d.get("start", 0)), end=int(d.get("end", 0)),
+            text_preview=d.get("text_preview", ""), confidence=float(d.get("confidence", 0.0)),
+            severity=str(d.get("severity", "")), source=d.get("source", ""),
+            method=d.get("method", ""), recognizer=d.get("recognizer", ""),
+            format_validated=bool(d.get("format_validated", False)),
+        )
+
+
+@dataclass(frozen=True)
+class PIIResult:
+    decision: Decision
+    risk_level: str
+    entities: List[Entity]
+    redacted_text: str
+    counts: Dict[str, int]
+    latency_ms: float
+    model_version: str
+    quota_remaining: Optional[int]
+    raw: Dict[str, Any] = field(repr=False, default_factory=dict)
+
+    @property
+    def has_pii(self) -> bool:
+        return bool(self.entities)
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "PIIResult":
+        return cls(
+            decision=d.get("decision", "allow"),
+            risk_level=d.get("risk_level", ""),
+            entities=[Entity.from_dict(e) for e in d.get("entities", [])],
+            redacted_text=d.get("redacted_text", ""),
+            counts=dict(d.get("counts", {})),
+            latency_ms=float(d.get("latency_ms", 0.0)),
+            model_version=str(d.get("model_version", "")),
+            quota_remaining=d.get("quota_remaining"),
+            raw=d,
+        )
+
+
+@dataclass(frozen=True)
+class RedactResult:
+    redacted_text: str
+    counts: Dict[str, int]
+    risk_level: str
+    quota_remaining: Optional[int]
+    model_version: str
+    raw: Dict[str, Any] = field(repr=False, default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "RedactResult":
+        return cls(
+            redacted_text=d.get("redacted_text", ""), counts=dict(d.get("counts", {})),
+            risk_level=d.get("risk_level", ""), quota_remaining=d.get("quota_remaining"),
+            model_version=str(d.get("model_version", "")), raw=d,
+        )
+
+
+@dataclass(frozen=True)
+class Usage:
+    plan: str
+    quota: int          # -1 = unlimited
+    used: int
+    unlimited: bool
+    raw: Dict[str, Any] = field(repr=False, default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "Usage":
+        return cls(plan=d.get("plan", ""), quota=int(d.get("quota", 0)),
+                   used=int(d.get("used", 0)), unlimited=bool(d.get("unlimited", False)), raw=d)
+
+
+def _derive_decision(raw: Dict[str, Any]) -> Decision:
+    """Defensive decision extraction for services whose schema isn't locked yet.
+
+    Order: explicit `decision` field > boolean block-ish flags > allow.
+    Deliberately does NOT invent numeric thresholds — that's server/policy work.
+    """
+    d = raw.get("decision")
+    if d in _DECISION_RANK:
+        return d
+    for flag in ("blocked", "block", "flagged", "injection_detected", "is_injection"):
+        v = raw.get(flag)
+        if isinstance(v, bool):
+            return "block" if v else "allow"
+    verdict = raw.get("verdict") or raw.get("label")
+    if isinstance(verdict, str) and verdict.lower() in ("malicious", "injection", "unsafe", "ungrounded", "hallucinated"):
+        return "review"
+    return "allow"
+
+
+@dataclass(frozen=True)
+class InjectionResult:
+    """LOCKED to the deployed Injection Guard schema (verified against the
+    service's API.md pulled from the VPS, 2026-07-04)."""
+
+    decision: Decision          # "allow" | "review" | "block" (server-native)
+    score: float = 0.0          # 0-1 probability of injection
+    reason: str = ""            # "model" | "trivial_safe"
+    obfuscation: bool = False   # homoglyph/base64/zero-width evasion detected
+    quota_remaining: Optional[int] = None
+    raw: Dict[str, Any] = field(repr=False, default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "InjectionResult":
+        return cls(decision=_derive_decision(d), score=float(d.get("score", 0.0)),
+                   reason=str(d.get("reason", "")),
+                   obfuscation=bool(d.get("obfuscation", False)),
+                   quota_remaining=d.get("quota_remaining"), raw=d)
+
+
+@dataclass(frozen=True)
+class GroundCheckResult:
+    """LOCKED to the deployed GroundCheck Pro schema (app/schemas.py + engine.py,
+    verified 2026-07-04). `decision` is SDK-derived: hallucinated -> "review"
+    (grounding failure is a review signal, not a hard block, by default)."""
+
+    decision: Decision
+    label: str = ""             # "grounded" | "hallucinated"
+    p_grounded: float = 0.0     # 0-1 probability the answer is supported
+    threshold: float = 0.5
+    engine: str = ""            # "model" | "lexical" (degraded mode)
+    sentences: List[Dict[str, Any]] = field(default_factory=list)  # granular=True only
+    quota_remaining: Optional[int] = None
+    raw: Dict[str, Any] = field(repr=False, default_factory=dict)
+
+    @property
+    def grounded(self) -> bool:
+        return self.label == "grounded"
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "GroundCheckResult":
+        label = str(d.get("label", ""))
+        return cls(decision="review" if label == "hallucinated" else "allow",
+                   label=label, p_grounded=float(d.get("p_grounded", 0.0)),
+                   threshold=float(d.get("threshold", 0.5)), engine=str(d.get("engine", "")),
+                   sentences=list(d.get("sentences", [])),
+                   quota_remaining=d.get("quota_remaining"), raw=d)
+
+
+@dataclass(frozen=True)
+class CheckReport:
+    """Combined result of a multi-product check. `skipped` lists products that
+    had no API key configured and were therefore not consulted."""
+
+    decision: Decision
+    pii: Optional[PIIResult] = None
+    injection: Optional[InjectionResult] = None
+    groundcheck: Optional[GroundCheckResult] = None
+    skipped: List[str] = field(default_factory=list)
+
+    @property
+    def redacted_text(self) -> Optional[str]:
+        """The PII-safe text (None if PII check was skipped)."""
+        return self.pii.redacted_text if self.pii else None

ylemis-0.1.0/src/ylemis.egg-info/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: ylemis
+Version: 0.1.0
+Summary: Official Python SDK for the Ylemis Trust Platform: PII Shield, Injection Guard, GroundCheck — one client, one integration.
+Author-email: Ylemis <pranshu.rs08@gmail.com>
+License: MIT
+Project-URL: Homepage, https://ylemis.com
+Project-URL: Documentation, https://ylemis.com/docs
+Keywords: pii,dpdp,guardrails,llm-security,india,aadhaar,prompt-injection,hallucination
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# ylemis — Python SDK for the Ylemis Trust Platform
+
+One integration for all Ylemis guardrails: **PII Shield** (India-tuned PII detection/redaction,
+98.68% F1, 0% false positives on the published benchmark), **Injection Guard**, and **GroundCheck**.
+Zero dependencies — stdlib only.
+
+```bash
+pip install ylemis
+```
+
+## 30-second DPDP fix
+
+You're piping customer data into an LLM. Aadhaar/PAN in a third-party model's logs is a
+₹250-crore DPDP exposure. One line stops it at the door:
+
+```python
+from ylemis import TrustEngine
+
+engine = TrustEngine(keys={"pii-shield": "sk_live_..."})
+
+safe_prompt = engine.check_input(user_text).redacted_text   # PII never leaves your app
+llm_response = call_your_llm(safe_prompt)
+```
+
+## The two hooks (full flow)
+
+Guardrails belong at two points in the LLM lifecycle — before the prompt goes out, and after
+the answer comes back:
+
+```python
+engine = TrustEngine(api_key="sk_live_...")    # one key everywhere (or keys={...} per product)
+
+inp = engine.check_input(prompt)                # PII + injection, PRE-LLM
+if inp.decision == "block":
+    ...                                         # your policy
+response = call_your_llm(inp.redacted_text)
+
+out = engine.check_output(response, docs=retrieved_docs)   # PII + groundedness, POST-LLM
+if out.decision == "allow":
+    return response
+```
+
+`engine.scan(prompt=..., response=..., docs=...)` is batch/audit sugar over both hooks.
+
+## Error handling — errors are honest
+
+The API never masks infra errors as billing errors. The SDK encodes that contract as types:
+
+```python
+from ylemis import QuotaExceeded, RateLimited, ServiceBusy, InvalidAPIKey
+
+try:
+    r = engine.pii.scan(text)
+except QuotaExceeded:   # 402 — genuinely out of quota, upgrade or wait for reset
+    ...
+except RateLimited:     # 429 — slow down (see .retry_after)
+    ...
+except ServiceBusy:     # 503 — transient; SDK already auto-retried per Retry-After
+    ...
+```
+
+Requests are metered only on success — a `ServiceBusy` retry never double-bills.
+
+## Per-product access
+
+```python
+engine.pii.scan(text, redaction_mode="mask")   # mask | replace | drop | hash
+engine.pii.redact(text)
+engine.pii.usage()
+engine.injection.score(text)
+engine.groundcheck.check(response, source=[...])
+engine.health()                                # no-auth liveness, all three services
+```
+
+Products without a configured key are skipped by `check_*` (listed in `report.skipped`)
+and raise `MissingKey` if called directly — so a PII-only key works fine today.
+
+## Development status
+
+All three adapters are exact, verified against the deployed services (2026-07-05),
+including a live end-to-end run with a single key across all three products.
+
+```bash
+python -m unittest discover -s tests -v    # offline, no keys needed
+```
+
+The SDK is MIT-licensed client code. API access requires a Ylemis subscription and
+key from [ylemis.com](https://ylemis.com).

ylemis-0.1.0/src/ylemis.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/ylemis/__init__.py
+src/ylemis/_http.py
+src/ylemis/client.py
+src/ylemis/exceptions.py
+src/ylemis/models.py
+src/ylemis.egg-info/PKG-INFO
+src/ylemis.egg-info/SOURCES.txt
+src/ylemis.egg-info/dependency_links.txt
+src/ylemis.egg-info/top_level.txt
+tests/test_sdk.py

ylemis-0.1.0/src/ylemis.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ylemis-0.1.0/src/ylemis.egg-info/top_level.txt

@@ -0,0 +1 @@
+ylemis

ylemis-0.1.0/tests/test_sdk.py

@@ -0,0 +1,178 @@
+"""Offline unit tests — a fake Transport is injected; no network, no keys."""
+
+from __future__ import annotations
+
+import sys
+import unittest
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+from ylemis import (InvalidAPIKey, MissingKey, QuotaExceeded, ServiceBusy,
+                    TrustEngine, merge_decisions)
+from ylemis._http import Transport
+from ylemis.exceptions import STATUS_MAP
+
+
+PII_SCAN_RESPONSE = {
+    "decision": "block",
+    "risk_level": "critical",
+    "entities": [{
+        "type": "AADHAAR", "start": 20, "end": 34, "text_preview": "XXXX-…-9012",
+        "confidence": 1.0, "source": "deterministic", "method": "deterministic",
+        "recognizer": "aadhaar", "format_validated": True, "severity": "critical",
+    }],
+    "redacted_text": "my aadhaar card is [AADHAAR]",
+    "counts": {"AADHAAR": 1},
+    "latency_ms": 9.4,
+    "model_version": "1.0",
+    "hybrid": True,
+    "quota_remaining": 41,
+}
+
+
+class FakeTransport(Transport):
+    """Records requests; replays canned responses/exceptions per (method, path)."""
+
+    def __init__(self):
+        super().__init__("https://api.test")
+        self.calls = []
+        self.responses = {}
+
+    def request(self, method, path, *, api_key=None, payload=None, product=None):
+        self.calls.append({"method": method, "path": path, "api_key": api_key,
+                           "payload": payload, "product": product})
+        result = self.responses[(method, path)]
+        if isinstance(result, Exception):
+            raise result
+        return result
+
+
+def engine_with_fake(**kw) -> tuple[TrustEngine, FakeTransport]:
+    engine = TrustEngine(**kw)
+    fake = FakeTransport()
+    engine._transport = fake
+    for client in (engine.pii, engine.injection, engine.groundcheck):
+        client._transport = fake
+    return engine, fake
+
+
+class TestKeyRouting(unittest.TestCase):
+    def test_single_key_used_for_all_products(self):
+        engine, fake = engine_with_fake(api_key="sk_live_one")
+        fake.responses[("POST", "/pii-shield/v1/scan")] = PII_SCAN_RESPONSE
+        fake.responses[("POST", "/injection-guard/v1/score")] = {"decision": "allow"}
+        engine.check_input("hello")
+        self.assertEqual({c["api_key"] for c in fake.calls}, {"sk_live_one"})
+
+    def test_per_product_keys_override(self):
+        engine, fake = engine_with_fake(api_key="sk_live_default",
+                                        keys={"injection-guard": "sk_live_inj"})
+        fake.responses[("POST", "/injection-guard/v1/score")] = {"decision": "allow"}
+        engine.injection.score("hi")
+        self.assertEqual(fake.calls[0]["api_key"], "sk_live_inj")
+
+    def test_missing_key_raises_and_check_skips(self):
+        engine, fake = engine_with_fake(keys={"pii-shield": "sk_live_p"})
+        with self.assertRaises(MissingKey):
+            engine.injection.score("hi")
+        fake.responses[("POST", "/pii-shield/v1/scan")] = PII_SCAN_RESPONSE
+        report = engine.check_input("hi")   # injection not configured -> skipped
+        self.assertEqual(report.skipped, ["injection-guard"])
+        self.assertEqual(report.decision, "block")  # PII decision still applies
+
+    def test_repr_never_leaks_keys(self):
+        engine, _ = engine_with_fake(api_key="sk_live_secret")
+        self.assertNotIn("sk_live_secret", repr(engine))
+
+
+class TestPIIContract(unittest.TestCase):
+    def test_scan_parses_exact_shape(self):
+        engine, fake = engine_with_fake(api_key="k")
+        fake.responses[("POST", "/pii-shield/v1/scan")] = PII_SCAN_RESPONSE
+        r = engine.pii.scan("my aadhaar card is 2345 6789 9012")
+        self.assertTrue(r.has_pii)
+        self.assertEqual(r.entities[0].type, "AADHAAR")
+        self.assertTrue(r.entities[0].format_validated)
+        self.assertEqual(r.quota_remaining, 41)
+        self.assertEqual(r.raw["hybrid"], True)
+        self.assertEqual(fake.calls[0]["payload"],
+                         {"text": "my aadhaar card is 2345 6789 9012", "redaction_mode": "mask"})
+
+    def test_usage(self):
+        engine, fake = engine_with_fake(api_key="k")
+        fake.responses[("GET", "/pii-shield/v1/usage")] = {
+            "plan": "pro", "quota": 100000, "used": 1234, "unlimited": False}
+        u = engine.pii.usage()
+        self.assertEqual((u.plan, u.used), ("pro", 1234))
+
+
+class TestDecisions(unittest.TestCase):
+    def test_merge_most_restrictive_wins(self):
+        self.assertEqual(merge_decisions("allow", "review", "block"), "block")
+        self.assertEqual(merge_decisions("allow", None, "review"), "review")
+        self.assertEqual(merge_decisions(), "allow")
+
+    def test_check_output_skips_groundcheck_without_docs(self):
+        engine, fake = engine_with_fake(api_key="k")
+        fake.responses[("POST", "/pii-shield/v1/scan")] = PII_SCAN_RESPONSE
+        report = engine.check_output("some model answer")   # no docs
+        self.assertIsNone(report.groundcheck)
+        self.assertNotIn("groundcheck", report.skipped)     # not skipped-for-key; simply N/A
+
+    def test_scan_sugar_merges_both_hooks(self):
+        engine, fake = engine_with_fake(api_key="k")
+        fake.responses[("POST", "/pii-shield/v1/scan")] = PII_SCAN_RESPONSE
+        fake.responses[("POST", "/injection-guard/v1/score")] = {"decision": "allow", "score": 0.01}
+        fake.responses[("POST", "/groundcheck/v1/check")] = {"label": "hallucinated", "p_grounded": 0.2}
+        report = engine.scan(prompt="p", response="r", docs=["d"])
+        self.assertEqual(report.decision, "block")
+        self.assertIsNotNone(report.groundcheck)
+        self.assertEqual(report.groundcheck.decision, "review")
+
+    def test_groundcheck_locked_request_shape(self):
+        engine, fake = engine_with_fake(api_key="k")
+        fake.responses[("POST", "/groundcheck/v1/check")] = {
+            "label": "grounded", "p_grounded": 0.97, "threshold": 0.5,
+            "engine": "model", "latency_ms": 12.0, "quota_remaining": 99}
+        r = engine.groundcheck.check("Paris is the capital.", ["Paris is the capital of France."])
+        self.assertTrue(r.grounded)
+        self.assertEqual(r.decision, "allow")
+        self.assertEqual(fake.calls[0]["payload"], {
+            "source": "Paris is the capital of France.", "answer": "Paris is the capital.",
+            "question": "", "threshold": 0.5, "granular": False})
+
+
+class TestErrorMapping(unittest.TestCase):
+    def test_status_map_covers_contract(self):
+        self.assertIs(STATUS_MAP[401], InvalidAPIKey)
+        self.assertIs(STATUS_MAP[402], QuotaExceeded)
+        self.assertIs(STATUS_MAP[503], ServiceBusy)
+
+    def test_quota_exceeded_surfaces(self):
+        engine, fake = engine_with_fake(api_key="k")
+        fake.responses[("POST", "/pii-shield/v1/scan")] = QuotaExceeded(
+            "quota exceeded", status=402, product="pii-shield")
+        with self.assertRaises(QuotaExceeded):
+            engine.pii.scan("text")
+
+
+class TestProvisionalAdapters(unittest.TestCase):
+    def test_injection_decision_derivation(self):
+        engine, fake = engine_with_fake(api_key="k")
+        for raw, expected in [({"decision": "block"}, "block"),
+                              ({"blocked": True}, "block"),
+                              ({"label": "malicious"}, "review"),
+                              ({"score": 0.1}, "allow")]:
+            fake.responses[("POST", "/injection-guard/v1/score")] = raw
+            self.assertEqual(engine.injection.score("x").decision, expected, raw)
+
+    def test_groundcheck_payload_override(self):
+        engine, fake = engine_with_fake(api_key="k")
+        fake.responses[("POST", "/groundcheck/v1/check")] = {"decision": "allow"}
+        engine.groundcheck.check("ans", payload={"custom": "shape"})
+        self.assertEqual(fake.calls[0]["payload"], {"custom": "shape"})
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)