peyeeye 1.0.0__tar.gz

peyeeye-1.0.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+.tox/
+.env
+.DS_Store

peyeeye-1.0.0/LICENSE

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

peyeeye-1.0.0/PKG-INFO

@@ -0,0 +1,280 @@
+Metadata-Version: 2.4
+Name: peyeeye
+Version: 1.0.0
+Summary: Official Python client for peyeeye.ai — PII redaction & rehydration for LLM prompts.
+Project-URL: Homepage, https://peyeeye.ai
+Project-URL: Documentation, https://peyeeye.ai/docs
+Author-email: "peyeeye.ai" <support@peyeeye.ai>
+License: MIT
+License-File: LICENSE
+Keywords: ai,ai-safety,anonymization,anthropic,claude,compliance,data-masking,data-privacy,data-protection,gdpr,hipaa,llm,openai,peyeeye,pii,pii-detection,privacy,prompt-engineering,rag,redaction,rehydrate,security,sensitive-data,tokenization
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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 :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# peyeeye
+
+[![PyPI version](https://img.shields.io/pypi/v/peyeeye.svg)](https://pypi.org/project/peyeeye/)
+[![Python versions](https://img.shields.io/pypi/pyversions/peyeeye.svg)](https://pypi.org/project/peyeeye/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+Official Python client for [**peyeeye.ai**](https://peyeeye.ai) — redact PII on
+the way _into_ your LLM prompts and rehydrate it on the way out.
+
+- **Homepage**: <https://peyeeye.ai>
+- **API reference**: <https://peyeeye.ai/docs>
+- **PyPI**: <https://pypi.org/project/peyeeye/>
+
+```bash
+pip install peyeeye
+```
+
+Python 3.9+. Single runtime dependency: `httpx`. Fully type-hinted (`py.typed`).
+
+## Quickstart
+
+```python
+import os
+from peyeeye import Peyeeye
+from anthropic import Anthropic
+
+peyeeye = Peyeeye(api_key=os.environ["PEYEEYE_KEY"])
+claude = Anthropic()
+
+with peyeeye.shield() as shield:
+    safe = shield.redact("Hi, I'm Ada, ada@a-e.com")
+    reply = claude.messages.create(
+        model="claude-sonnet-*",
+        max_tokens=256,
+        messages=[{"role": "user", "content": safe}],
+    )
+    print(shield.rehydrate(reply.content[0].text))
+```
+
+`shield()` opens a session, redacts, and cleans up on exit. Inside the block,
+the same real value always maps to the same token — `Ada Lovelace` is always
+`[PERSON_1]` — and tokens never leak across sessions.
+
+## Low-level calls
+
+Skip the `shield` helper when you need more control:
+
+```python
+r = peyeeye.redact("Card: 4242 4242 4242 4242")
+# r.redacted    → "Card: [CARD_1]"
+# r.session     → "ses_…"
+# r.entities    → [DetectedEntity(token="[CARD_1]", type="CARD", span=(6, 25), confidence=0.99)]
+
+clean = peyeeye.rehydrate("Confirmation for [CARD_1].", session=r.session)
+# clean.text → "Confirmation for 4242 4242 4242 4242."
+```
+
+## Stateless sealed mode
+
+Pass `stateless=True` and peyeeye never stores the mapping — the redact
+response carries a sealed `skey_…` blob you hand back to rehydrate. Nothing
+lives on the server between calls.
+
+```python
+with peyeeye.shield(stateless=True) as shield:
+    safe = shield.redact("Email ada@a-e.com")
+    clean = shield.rehydrate("Reply: [EMAIL_1]")
+    # shield.rehydration_key is the skey_... blob, if you need to persist it
+```
+
+Or with raw calls:
+
+```python
+r = peyeeye.redact("Email ada@a-e.com", session="stateless")
+# r.rehydration_key → "skey_…"
+clean = peyeeye.rehydrate("[EMAIL_1] received.", session=r.rehydration_key)
+```
+
+## Streaming rehydration
+
+When piping an LLM token stream straight to a user, naive rehydration breaks
+on mid-token boundaries. `rehydrate_chunk()` buffers partial tokens across
+chunks; call `flush()` once upstream closes.
+
+```python
+with peyeeye.shield() as shield:
+    safe = shield.redact(prompt)
+    for chunk in your_llm_stream(safe):
+        sys.stdout.write(shield.rehydrate_chunk(chunk))
+    sys.stdout.write(shield.flush())
+```
+
+Never call `flush()` while the stream is still delivering chunks — you'll emit
+a half-formed placeholder.
+
+## Streaming redact (SSE)
+
+For the `/v1/redact/stream` endpoint (Build plan and higher):
+
+```python
+for event in peyeeye.redact_stream(["Hi, I'm Ada", " — card 4242 4242 4242 4242"]):
+    if event.event == "session":
+        session_id = event.data["session"]
+    elif event.event == "redacted":
+        print(event.data["text"])
+    elif event.event == "done":
+        print("chars:", event.data["chars"])
+```
+
+## Custom detectors
+
+```python
+peyeeye.create_entity(
+    id="ORDER_ID",
+    kind="regex",
+    pattern=r"#A-\d{6,}",
+    examples=["#A-884217", "#A-007431"],
+    confidence_floor=0.9,
+)
+
+# dry-run a pattern before saving
+peyeeye.test_pattern(pattern=r"#A-\d{6,}", text="ref #A-884217 and #A-1")
+#   → TestPatternResponse(count=1, matches=[PatternMatch(value="#A-884217", ...)])
+
+# inspect / update / retire
+peyeeye.list_entities()
+peyeeye.update_entity("ORDER_ID", enabled=False)
+peyeeye.delete_entity("ORDER_ID")
+
+# starter templates (Twilio SIDs, Stripe keys, AWS access keys, etc.)
+for tpl in peyeeye.entity_templates():
+    print(tpl.id, tpl.pattern)
+```
+
+## Sessions
+
+```python
+peyeeye.get_session("ses_…")       # SessionInfo
+peyeeye.delete_session("ses_…")    # drop immediately
+```
+
+## Errors
+
+Every non-2xx response raises `PeyeeyeError` with `.code`, `.status`,
+`.message`, and `.request_id`. 429 and 5xx responses are retried with
+exponential backoff (`Retry-After` honoured); terminal errors raise
+immediately.
+
+```python
+from peyeeye import PeyeeyeError
+
+try:
+    peyeeye.redact("…")
+except PeyeeyeError as e:
+    if e.code == "rate_limited":
+        ...
+    elif e.code == "forbidden":
+        ...
+    else:
+        raise
+```
+
+## Configuration
+
+```python
+Peyeeye(
+    api_key="pk_live_…",
+    base_url="https://api.peyeeye.ai",
+    timeout=30.0,
+    max_retries=3,
+)
+```
+
+For CI / air-gapped use, `Peyeeye(transport=httpx.MockTransport(handler))`
+lets you mount a mock transport without monkey-patching.
+
+## Method reference
+
+| Method | HTTP | Purpose |
+| --- | --- | --- |
+| `peyeeye.redact(text, ...)` | `POST /v1/redact` | Redact PII; returns token stream + session. |
+| `peyeeye.rehydrate(text, session=...)` | `POST /v1/rehydrate` | Substitute tokens back. Accepts `ses_…` or `skey_…`. |
+| `peyeeye.redact_stream(chunks, ...)` | `POST /v1/redact/stream` (SSE) | Stream-safe redact. |
+| `peyeeye.get_session(id)` | `GET /v1/sessions/{id}` | Inspect mapping metadata. |
+| `peyeeye.delete_session(id)` | `DELETE /v1/sessions/{id}` | Evict a session. |
+| `peyeeye.list_entities()` | `GET /v1/entities` | Built-ins + your custom detectors. |
+| `peyeeye.create_entity(...)` | `POST /v1/entities` | Custom detector. |
+| `peyeeye.update_entity(id, ...)` | `PATCH /v1/entities/{id}` | Toggle / tweak. |
+| `peyeeye.delete_entity(id)` | `DELETE /v1/entities/{id}` | Retire. |
+| `peyeeye.test_pattern(pattern, text)` | `POST /v1/entities/test` | Dry-run a regex. |
+| `peyeeye.entity_templates()` | `GET /v1/entities/templates` | Starter patterns. |
+
+Full request / response schemas: <https://peyeeye.ai/docs>.
+
+## Using this SDK from an AI coding assistant
+
+Drop these into your agent's context. Each snippet is self-contained and
+compiles as-is.
+
+```python
+# Install
+# pip install peyeeye
+
+from peyeeye import Peyeeye, PeyeeyeError
+import os
+
+client = Peyeeye(api_key=os.environ["PEYEEYE_KEY"])  # or explicit base_url
+
+# Round-trip: redact → call LLM → rehydrate (session-scoped)
+with client.shield() as shield:
+    safe = shield.redact("Hi, I'm Ada, ada@a-e.com")
+    # ... send `safe` to the LLM, get `reply` back ...
+    out = shield.rehydrate(reply)
+
+# Stateless (zero server-side state; key is yours to persist)
+with client.shield(stateless=True) as shield:
+    safe = shield.redact("...")
+    key = shield.rehydration_key  # skey_...
+    clean = shield.rehydrate("[EMAIL_1] confirmed.")
+
+# Low-level one-shot
+r = client.redact("Card 4242 4242 4242 4242")
+clean = client.rehydrate("Receipt: [CARD_1].", session=r.session)
+
+# Error handling
+try:
+    client.redact(text)
+except PeyeeyeError as e:
+    # e.code ∈ {"rate_limited","forbidden","invalid_request","server_error", ...}
+    # e.status, e.message, e.request_id
+    raise
+```
+
+**Endpoint envelope**: all requests use `Authorization: Bearer <api_key>` against
+`https://api.peyeeye.ai/v1/*`. Errors follow `{code, message, request_id}`
+and surface as `PeyeeyeError`. Responses are plain JSON (dataclasses via
+`from_dict`).
+
+**Do**: reuse one `Peyeeye(...)` per process; call `.close()` or use it as a
+context manager at shutdown.
+**Don't**: open a new client per request, call `flush()` mid-stream, or parse
+`skey_` blobs yourself — the API opens them.
+
+## License
+
+MIT.

peyeeye-1.0.0/README.md

@@ -0,0 +1,246 @@
+# peyeeye
+
+[![PyPI version](https://img.shields.io/pypi/v/peyeeye.svg)](https://pypi.org/project/peyeeye/)
+[![Python versions](https://img.shields.io/pypi/pyversions/peyeeye.svg)](https://pypi.org/project/peyeeye/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+Official Python client for [**peyeeye.ai**](https://peyeeye.ai) — redact PII on
+the way _into_ your LLM prompts and rehydrate it on the way out.
+
+- **Homepage**: <https://peyeeye.ai>
+- **API reference**: <https://peyeeye.ai/docs>
+- **PyPI**: <https://pypi.org/project/peyeeye/>
+
+```bash
+pip install peyeeye
+```
+
+Python 3.9+. Single runtime dependency: `httpx`. Fully type-hinted (`py.typed`).
+
+## Quickstart
+
+```python
+import os
+from peyeeye import Peyeeye
+from anthropic import Anthropic
+
+peyeeye = Peyeeye(api_key=os.environ["PEYEEYE_KEY"])
+claude = Anthropic()
+
+with peyeeye.shield() as shield:
+    safe = shield.redact("Hi, I'm Ada, ada@a-e.com")
+    reply = claude.messages.create(
+        model="claude-sonnet-*",
+        max_tokens=256,
+        messages=[{"role": "user", "content": safe}],
+    )
+    print(shield.rehydrate(reply.content[0].text))
+```
+
+`shield()` opens a session, redacts, and cleans up on exit. Inside the block,
+the same real value always maps to the same token — `Ada Lovelace` is always
+`[PERSON_1]` — and tokens never leak across sessions.
+
+## Low-level calls
+
+Skip the `shield` helper when you need more control:
+
+```python
+r = peyeeye.redact("Card: 4242 4242 4242 4242")
+# r.redacted    → "Card: [CARD_1]"
+# r.session     → "ses_…"
+# r.entities    → [DetectedEntity(token="[CARD_1]", type="CARD", span=(6, 25), confidence=0.99)]
+
+clean = peyeeye.rehydrate("Confirmation for [CARD_1].", session=r.session)
+# clean.text → "Confirmation for 4242 4242 4242 4242."
+```
+
+## Stateless sealed mode
+
+Pass `stateless=True` and peyeeye never stores the mapping — the redact
+response carries a sealed `skey_…` blob you hand back to rehydrate. Nothing
+lives on the server between calls.
+
+```python
+with peyeeye.shield(stateless=True) as shield:
+    safe = shield.redact("Email ada@a-e.com")
+    clean = shield.rehydrate("Reply: [EMAIL_1]")
+    # shield.rehydration_key is the skey_... blob, if you need to persist it
+```
+
+Or with raw calls:
+
+```python
+r = peyeeye.redact("Email ada@a-e.com", session="stateless")
+# r.rehydration_key → "skey_…"
+clean = peyeeye.rehydrate("[EMAIL_1] received.", session=r.rehydration_key)
+```
+
+## Streaming rehydration
+
+When piping an LLM token stream straight to a user, naive rehydration breaks
+on mid-token boundaries. `rehydrate_chunk()` buffers partial tokens across
+chunks; call `flush()` once upstream closes.
+
+```python
+with peyeeye.shield() as shield:
+    safe = shield.redact(prompt)
+    for chunk in your_llm_stream(safe):
+        sys.stdout.write(shield.rehydrate_chunk(chunk))
+    sys.stdout.write(shield.flush())
+```
+
+Never call `flush()` while the stream is still delivering chunks — you'll emit
+a half-formed placeholder.
+
+## Streaming redact (SSE)
+
+For the `/v1/redact/stream` endpoint (Build plan and higher):
+
+```python
+for event in peyeeye.redact_stream(["Hi, I'm Ada", " — card 4242 4242 4242 4242"]):
+    if event.event == "session":
+        session_id = event.data["session"]
+    elif event.event == "redacted":
+        print(event.data["text"])
+    elif event.event == "done":
+        print("chars:", event.data["chars"])
+```
+
+## Custom detectors
+
+```python
+peyeeye.create_entity(
+    id="ORDER_ID",
+    kind="regex",
+    pattern=r"#A-\d{6,}",
+    examples=["#A-884217", "#A-007431"],
+    confidence_floor=0.9,
+)
+
+# dry-run a pattern before saving
+peyeeye.test_pattern(pattern=r"#A-\d{6,}", text="ref #A-884217 and #A-1")
+#   → TestPatternResponse(count=1, matches=[PatternMatch(value="#A-884217", ...)])
+
+# inspect / update / retire
+peyeeye.list_entities()
+peyeeye.update_entity("ORDER_ID", enabled=False)
+peyeeye.delete_entity("ORDER_ID")
+
+# starter templates (Twilio SIDs, Stripe keys, AWS access keys, etc.)
+for tpl in peyeeye.entity_templates():
+    print(tpl.id, tpl.pattern)
+```
+
+## Sessions
+
+```python
+peyeeye.get_session("ses_…")       # SessionInfo
+peyeeye.delete_session("ses_…")    # drop immediately
+```
+
+## Errors
+
+Every non-2xx response raises `PeyeeyeError` with `.code`, `.status`,
+`.message`, and `.request_id`. 429 and 5xx responses are retried with
+exponential backoff (`Retry-After` honoured); terminal errors raise
+immediately.
+
+```python
+from peyeeye import PeyeeyeError
+
+try:
+    peyeeye.redact("…")
+except PeyeeyeError as e:
+    if e.code == "rate_limited":
+        ...
+    elif e.code == "forbidden":
+        ...
+    else:
+        raise
+```
+
+## Configuration
+
+```python
+Peyeeye(
+    api_key="pk_live_…",
+    base_url="https://api.peyeeye.ai",
+    timeout=30.0,
+    max_retries=3,
+)
+```
+
+For CI / air-gapped use, `Peyeeye(transport=httpx.MockTransport(handler))`
+lets you mount a mock transport without monkey-patching.
+
+## Method reference
+
+| Method | HTTP | Purpose |
+| --- | --- | --- |
+| `peyeeye.redact(text, ...)` | `POST /v1/redact` | Redact PII; returns token stream + session. |
+| `peyeeye.rehydrate(text, session=...)` | `POST /v1/rehydrate` | Substitute tokens back. Accepts `ses_…` or `skey_…`. |
+| `peyeeye.redact_stream(chunks, ...)` | `POST /v1/redact/stream` (SSE) | Stream-safe redact. |
+| `peyeeye.get_session(id)` | `GET /v1/sessions/{id}` | Inspect mapping metadata. |
+| `peyeeye.delete_session(id)` | `DELETE /v1/sessions/{id}` | Evict a session. |
+| `peyeeye.list_entities()` | `GET /v1/entities` | Built-ins + your custom detectors. |
+| `peyeeye.create_entity(...)` | `POST /v1/entities` | Custom detector. |
+| `peyeeye.update_entity(id, ...)` | `PATCH /v1/entities/{id}` | Toggle / tweak. |
+| `peyeeye.delete_entity(id)` | `DELETE /v1/entities/{id}` | Retire. |
+| `peyeeye.test_pattern(pattern, text)` | `POST /v1/entities/test` | Dry-run a regex. |
+| `peyeeye.entity_templates()` | `GET /v1/entities/templates` | Starter patterns. |
+
+Full request / response schemas: <https://peyeeye.ai/docs>.
+
+## Using this SDK from an AI coding assistant
+
+Drop these into your agent's context. Each snippet is self-contained and
+compiles as-is.
+
+```python
+# Install
+# pip install peyeeye
+
+from peyeeye import Peyeeye, PeyeeyeError
+import os
+
+client = Peyeeye(api_key=os.environ["PEYEEYE_KEY"])  # or explicit base_url
+
+# Round-trip: redact → call LLM → rehydrate (session-scoped)
+with client.shield() as shield:
+    safe = shield.redact("Hi, I'm Ada, ada@a-e.com")
+    # ... send `safe` to the LLM, get `reply` back ...
+    out = shield.rehydrate(reply)
+
+# Stateless (zero server-side state; key is yours to persist)
+with client.shield(stateless=True) as shield:
+    safe = shield.redact("...")
+    key = shield.rehydration_key  # skey_...
+    clean = shield.rehydrate("[EMAIL_1] confirmed.")
+
+# Low-level one-shot
+r = client.redact("Card 4242 4242 4242 4242")
+clean = client.rehydrate("Receipt: [CARD_1].", session=r.session)
+
+# Error handling
+try:
+    client.redact(text)
+except PeyeeyeError as e:
+    # e.code ∈ {"rate_limited","forbidden","invalid_request","server_error", ...}
+    # e.status, e.message, e.request_id
+    raise
+```
+
+**Endpoint envelope**: all requests use `Authorization: Bearer <api_key>` against
+`https://api.peyeeye.ai/v1/*`. Errors follow `{code, message, request_id}`
+and surface as `PeyeeyeError`. Responses are plain JSON (dataclasses via
+`from_dict`).
+
+**Do**: reuse one `Peyeeye(...)` per process; call `.close()` or use it as a
+context manager at shutdown.
+**Don't**: open a new client per request, call `flush()` mid-stream, or parse
+`skey_` blobs yourself — the API opens them.
+
+## License
+
+MIT.

peyeeye-1.0.0/peyeeye/__init__.py

@@ -0,0 +1,41 @@
+"""peyeeye — PII redaction & rehydration client.
+
+    from peyeeye import Peyeeye
+
+    pe = Peyeeye(api_key="pk_live_...")
+    with pe.shield() as shield:
+        safe = shield.redact("Hi, I'm Ada, ada@a-e.com")
+        reply = call_your_model(safe)
+        print(shield.rehydrate(reply))
+"""
+
+from .client import Peyeeye, Shield
+from .errors import PeyeeyeError
+from .models import (
+    CustomDetector,
+    DetectedEntity,
+    EntitiesList,
+    EntityTemplate,
+    RedactResponse,
+    RehydrateResponse,
+    SessionInfo,
+    StreamEvent,
+    TestPatternResponse,
+)
+
+__all__ = [
+    "Peyeeye",
+    "PeyeeyeError",
+    "Shield",
+    "DetectedEntity",
+    "RedactResponse",
+    "RehydrateResponse",
+    "SessionInfo",
+    "CustomDetector",
+    "EntitiesList",
+    "EntityTemplate",
+    "TestPatternResponse",
+    "StreamEvent",
+]
+
+__version__ = "1.0.0"