sovergate 0.1.0a1__tar.gz

sovergate-0.1.0a1/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+dist/
+build/
+*.egg-info/
+.coverage
+.DS_Store

sovergate-0.1.0a1/LICENSE

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

sovergate-0.1.0a1/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.5
+Name: sovergate
+Version: 0.1.0a1
+Summary: EU AI Act compliance SDK — automatic, non-invasive audit logging for LLM calls
+Project-URL: Homepage, https://sovergate.com
+Project-URL: Repository, https://github.com/Sovergate/sdk-python
+Project-URL: Issues, https://github.com/Sovergate/sdk-python/issues
+Author: Roberto Postolovski
+License-Expression: MIT
+License-File: LICENSE
+Keywords: anthropic,audit,compliance,eu-ai-act,gdpr,llm,observability,openai,pii
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Logging
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: anthropic>=2.0; extra == 'dev'
+Requires-Dist: httpx2; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: openai>=1.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# sovergate
+
+Python SDK for [Sovergate](https://sovergate.com): EU AI Act Article 12 audit
+logging for LLM calls, with PII scrubbed inside your own infrastructure.
+
+> **Early access.** The SDK is published as an alpha and the hosted ingest
+> service is not generally available yet. APIs may change before 1.0.
+
+## How it works
+
+Your app keeps calling OpenAI or Anthropic directly. Sovergate does not proxy
+or intercept the request. After a call completes, the SDK takes a copy,
+scrubs personal data **locally**, and sends the scrubbed copy to Sovergate
+from a background thread.
+
+```
+Your app ─────────────────────────────► OpenAI / Anthropic
+              │
+              └──► scrub PII locally ──► Sovergate (background, fire and forget)
+```
+
+## Install
+
+```bash
+pip install --pre sovergate
+```
+
+`--pre` is needed while the SDK is in alpha. Requires Python 3.10+. No runtime
+dependencies.
+
+## Quick start
+
+```python
+import openai
+import sovergate
+
+sovergate.init(api_key="sov_prod_xxxx")
+sovergate.instrument(openai)
+
+# Your existing code is unchanged
+response = openai.chat.completions.create(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "Hello"}],
+)
+# The response is returned immediately; logging happens in the background
+```
+
+You can also instrument a client instance, sync or async:
+
+```python
+from openai import AsyncOpenAI
+
+client = AsyncOpenAI()
+sovergate.instrument(client)
+```
+
+### Anthropic
+
+Pass a client instance (the `anthropic` module itself has no client to patch):
+
+```python
+import anthropic
+import sovergate
+
+client = anthropic.Anthropic()        # or anthropic.AsyncAnthropic()
+sovergate.init(api_key="sov_prod_xxxx")
+sovergate.instrument(client)
+```
+
+## Stable PII tokens (recommended)
+
+By default, detected PII is replaced with positional placeholders
+(`[EMAIL_REDACTED_1]`), which are not correlatable between logs. Pass a
+`pii_key` to replace values with deterministic, irreversible HMAC-SHA256 tokens
+instead. The same value always maps to the same token, so Sovergate can count
+unique people, IBANs and so on without ever receiving the raw values.
+
+```python
+sovergate.init(api_key="sov_prod_xxxx", pii_key="<your-secret>")
+```
+
+The `pii_key` is your secret. Keep it stable, and never send it to us: it stays
+on your infrastructure, and without it the tokens cannot be reversed.
+
+## Options
+
+```python
+sovergate.init(
+    api_key="sov_prod_xxxx",           # required
+    base_url="https://...",            # default: https://api.sovergate.com
+    pii_key="<your-secret>",           # optional, see above
+    debug=True,                        # verbose output from the "sovergate" logger only
+)
+```
+
+## What is sent to Sovergate
+
+For each completed call, one JSON record:
+
+| Field | Content |
+|---|---|
+| `model` | Model name returned by the provider |
+| `messages` | Your prompt messages (and Anthropic `system` prompt), **after** PII scrubbing |
+| `response` | The model's text output, **after** PII scrubbing |
+| `prompt_tokens`, `completion_tokens` | Token counts from the provider |
+| `latency_ms`, `timestamp` | Call duration and start time |
+| `finish_reason` | Why the model stopped |
+| `pii_detections` | Category and placeholder of each scrubbed item, never the original value |
+
+Never sent: the raw prompt or response, your `pii_key`, your LLM provider API
+key, or request headers.
+
+### What the scrubber detects
+
+Regex-based, applied to every text part of the prompt and response: email
+addresses, IP addresses, IBANs (including the spaced format), card numbers,
+phone numbers, dates of birth, ID numbers, and names that follow a title (Mr,
+Mrs, Ms, Dr, Prof). Other personal data, such as names without a title, is
+**not** detected yet, so keep data minimisation in mind when you build prompts.
+The code is in [`sovergate/scrubber.py`](sovergate/scrubber.py).
+
+## Guarantees
+
+- Never blocks your call: logging runs in a background daemon thread
+- Never raises: if setup fails, the SDK logs a warning on the `sovergate`
+  logger and stays out of the way
+- Returns the provider's response unchanged; `with_raw_response` keeps working
+- Never changes your app's logging configuration, even with `debug=True`
+- 2 second timeout on every HTTP call to Sovergate
+- If Sovergate is unreachable, records are queued in memory (up to 10,000) and
+  retried with exponential backoff
+
+## Current limitations
+
+- Streaming calls (`stream=True`) are passed through untouched but not logged yet.
+- Calls made through `with_raw_response` are not logged.
+- The retry queue is in memory, so queued records are lost if the process exits.
+
+## Development
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## Security
+
+Please report vulnerabilities privately. See [SECURITY.md](SECURITY.md).
+
+## License
+
+[MIT](LICENSE)

sovergate-0.1.0a1/README.md

@@ -0,0 +1,153 @@
+# sovergate
+
+Python SDK for [Sovergate](https://sovergate.com): EU AI Act Article 12 audit
+logging for LLM calls, with PII scrubbed inside your own infrastructure.
+
+> **Early access.** The SDK is published as an alpha and the hosted ingest
+> service is not generally available yet. APIs may change before 1.0.
+
+## How it works
+
+Your app keeps calling OpenAI or Anthropic directly. Sovergate does not proxy
+or intercept the request. After a call completes, the SDK takes a copy,
+scrubs personal data **locally**, and sends the scrubbed copy to Sovergate
+from a background thread.
+
+```
+Your app ─────────────────────────────► OpenAI / Anthropic
+              │
+              └──► scrub PII locally ──► Sovergate (background, fire and forget)
+```
+
+## Install
+
+```bash
+pip install --pre sovergate
+```
+
+`--pre` is needed while the SDK is in alpha. Requires Python 3.10+. No runtime
+dependencies.
+
+## Quick start
+
+```python
+import openai
+import sovergate
+
+sovergate.init(api_key="sov_prod_xxxx")
+sovergate.instrument(openai)
+
+# Your existing code is unchanged
+response = openai.chat.completions.create(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "Hello"}],
+)
+# The response is returned immediately; logging happens in the background
+```
+
+You can also instrument a client instance, sync or async:
+
+```python
+from openai import AsyncOpenAI
+
+client = AsyncOpenAI()
+sovergate.instrument(client)
+```
+
+### Anthropic
+
+Pass a client instance (the `anthropic` module itself has no client to patch):
+
+```python
+import anthropic
+import sovergate
+
+client = anthropic.Anthropic()        # or anthropic.AsyncAnthropic()
+sovergate.init(api_key="sov_prod_xxxx")
+sovergate.instrument(client)
+```
+
+## Stable PII tokens (recommended)
+
+By default, detected PII is replaced with positional placeholders
+(`[EMAIL_REDACTED_1]`), which are not correlatable between logs. Pass a
+`pii_key` to replace values with deterministic, irreversible HMAC-SHA256 tokens
+instead. The same value always maps to the same token, so Sovergate can count
+unique people, IBANs and so on without ever receiving the raw values.
+
+```python
+sovergate.init(api_key="sov_prod_xxxx", pii_key="<your-secret>")
+```
+
+The `pii_key` is your secret. Keep it stable, and never send it to us: it stays
+on your infrastructure, and without it the tokens cannot be reversed.
+
+## Options
+
+```python
+sovergate.init(
+    api_key="sov_prod_xxxx",           # required
+    base_url="https://...",            # default: https://api.sovergate.com
+    pii_key="<your-secret>",           # optional, see above
+    debug=True,                        # verbose output from the "sovergate" logger only
+)
+```
+
+## What is sent to Sovergate
+
+For each completed call, one JSON record:
+
+| Field | Content |
+|---|---|
+| `model` | Model name returned by the provider |
+| `messages` | Your prompt messages (and Anthropic `system` prompt), **after** PII scrubbing |
+| `response` | The model's text output, **after** PII scrubbing |
+| `prompt_tokens`, `completion_tokens` | Token counts from the provider |
+| `latency_ms`, `timestamp` | Call duration and start time |
+| `finish_reason` | Why the model stopped |
+| `pii_detections` | Category and placeholder of each scrubbed item, never the original value |
+
+Never sent: the raw prompt or response, your `pii_key`, your LLM provider API
+key, or request headers.
+
+### What the scrubber detects
+
+Regex-based, applied to every text part of the prompt and response: email
+addresses, IP addresses, IBANs (including the spaced format), card numbers,
+phone numbers, dates of birth, ID numbers, and names that follow a title (Mr,
+Mrs, Ms, Dr, Prof). Other personal data, such as names without a title, is
+**not** detected yet, so keep data minimisation in mind when you build prompts.
+The code is in [`sovergate/scrubber.py`](sovergate/scrubber.py).
+
+## Guarantees
+
+- Never blocks your call: logging runs in a background daemon thread
+- Never raises: if setup fails, the SDK logs a warning on the `sovergate`
+  logger and stays out of the way
+- Returns the provider's response unchanged; `with_raw_response` keeps working
+- Never changes your app's logging configuration, even with `debug=True`
+- 2 second timeout on every HTTP call to Sovergate
+- If Sovergate is unreachable, records are queued in memory (up to 10,000) and
+  retried with exponential backoff
+
+## Current limitations
+
+- Streaming calls (`stream=True`) are passed through untouched but not logged yet.
+- Calls made through `with_raw_response` are not logged.
+- The retry queue is in memory, so queued records are lost if the process exits.
+
+## Development
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## Security
+
+Please report vulnerabilities privately. See [SECURITY.md](SECURITY.md).
+
+## License
+
+[MIT](LICENSE)

sovergate-0.1.0a1/SECURITY.md

@@ -0,0 +1,21 @@
+# Security policy
+
+This SDK runs inside your infrastructure and sees prompts before PII is
+scrubbed, so we take reports seriously.
+
+## Reporting a vulnerability
+
+Please **do not open a public issue**. Instead, report it privately through
+GitHub: open the **Security** tab of this repository and choose
+**Report a vulnerability**.
+
+If you cannot use GitHub, email **hello@sovergate.com** with the subject
+"Security report".
+
+We aim to acknowledge reports within 3 business days and will keep you updated
+until the issue is resolved.
+
+## Supported versions
+
+The SDK is in early access. Security fixes are released on the latest version
+only.

sovergate-0.1.0a1/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sovergate"
+dynamic = ["version"]
+description = "EU AI Act compliance SDK — automatic, non-invasive audit logging for LLM calls"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+dependencies = []
+authors = [{ name = "Roberto Postolovski" }]
+keywords = ["eu-ai-act", "compliance", "gdpr", "llm", "audit", "openai", "anthropic", "pii", "observability"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Security",
+  "Topic :: System :: Logging",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://sovergate.com"
+Repository = "https://github.com/Sovergate/sdk-python"
+Issues = "https://github.com/Sovergate/sdk-python/issues"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "openai>=1.0",
+  "anthropic>=2.0",
+  "httpx>=0.27",
+  "httpx2",
+]
+
+[tool.hatch.version]
+path = "sovergate/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["sovergate"]
+
+[tool.hatch.build.targets.sdist]
+include = ["sovergate", "tests", "README.md", "LICENSE", "SECURITY.md"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

sovergate-0.1.0a1/sovergate/__init__.py

@@ -0,0 +1,4 @@
+from .client import init, instrument, shutdown
+
+__all__ = ["init", "instrument", "shutdown"]
+__version__ = "0.1.0a1"

sovergate-0.1.0a1/sovergate/client.py

@@ -0,0 +1,138 @@
+"""Public entry point — init() and instrument()."""
+
+import logging
+from typing import Any, Optional
+
+from .sender import send
+from .queue import LogQueue
+
+logger = logging.getLogger("sovergate")
+
+_state: dict = {
+    "api_key": None,
+    "base_url": "https://api.sovergate.com",
+    "pii_key": None,
+    "queue": None,
+}
+
+
+def init(
+    api_key: str,
+    base_url: str = "https://api.sovergate.com",
+    pii_key: Optional[str] = None,
+    debug: bool = False,
+) -> None:
+    """
+    Call once at app startup before any LLM calls.
+
+    Args:
+        api_key:  Your sovergate SDK key (starts with sov_).
+        base_url: Override API endpoint (useful for self-hosted or local dev).
+        pii_key:  Secret used to derive deterministic, irreversible PII tokens.
+                  The same value always maps to the same token, so the platform
+                  can count unique entities without ever holding raw PII. Keep it
+                  secret and stable — it NEVER leaves your infrastructure. If
+                  omitted, tokens are positional and not correlatable across logs.
+        debug:    Enable verbose logging from the SDK.
+    """
+    try:
+        if debug:
+            _enable_debug_logging()
+
+        _state["api_key"] = api_key
+        _state["base_url"] = base_url.rstrip("/")
+        _state["pii_key"] = pii_key.encode("utf-8") if pii_key else None
+        if _state["pii_key"] is None:
+            logger.debug(
+                "sovergate: no pii_key set — PII tokens will be positional and not "
+                "correlatable across logs (unique-entity metrics unavailable)."
+            )
+
+        def _send(payload: dict) -> bool:
+            return send(api_key, payload, base_url=_state["base_url"])
+
+        q = LogQueue(send_fn=_send)
+        q.start()
+        _state["queue"] = q
+
+        logger.debug("sovergate initialised (base_url=%s)", _state["base_url"])
+    except Exception as e:
+        # Never let SDK setup break the host app; logging just stays disabled.
+        _state["queue"] = None
+        logger.warning("sovergate: init failed, logging disabled: %s", e)
+
+
+def _enable_debug_logging() -> None:
+    """Verbose output for the SDK's own loggers only — never the app's root logger."""
+    logger.setLevel(logging.DEBUG)
+    if not logger.handlers:
+        handler = logging.StreamHandler()
+        handler.setFormatter(logging.Formatter("%(name)s %(levelname)s %(message)s"))
+        logger.addHandler(handler)
+
+
+def instrument(library: Any) -> None:
+    """
+    Patch an LLM client library so all calls are automatically logged.
+
+    Supported:
+        - the openai module, or an OpenAI / AsyncOpenAI client   (chat.completions.create)
+        - an Anthropic / AsyncAnthropic client                     (messages.create)
+
+    Usage:
+        import openai
+        sovergate.instrument(openai)
+
+        import anthropic
+        client = anthropic.Anthropic()
+        sovergate.instrument(client)
+
+    The original library and its responses are completely unchanged.
+    Never raises: if instrumentation isn't possible, a warning is logged and
+    the library is left untouched.
+    """
+    if _state["queue"] is None:
+        logger.warning(
+            "sovergate: instrument() called before init(api_key=...) — LLM calls will not be logged."
+        )
+        return
+
+    try:
+        enqueue = _state["queue"].enqueue
+        pii_key = _state["pii_key"]
+        module_name = getattr(library, "__name__", "") or getattr(library, "__class__", type(library)).__name__
+
+        if module_name == "openai" or hasattr(library, "chat"):
+            from .patcher import patch_openai
+            patch_openai(library, enqueue, pii_key)
+            return
+
+        if module_name == "anthropic" and not hasattr(library, "messages"):
+            logger.warning(
+                "sovergate: pass an Anthropic client instance, not the anthropic module — "
+                "e.g. sovergate.instrument(anthropic.Anthropic()). LLM calls will not be logged."
+            )
+            return
+
+        if hasattr(library, "messages"):
+            from .patcher import patch_anthropic
+            patch_anthropic(library, enqueue, pii_key)
+            return
+
+        logger.warning(
+            "sovergate: unsupported library '%s' — LLM calls will not be logged. "
+            "Supported: openai, anthropic. Open an issue at "
+            "https://github.com/sovergate/sdk-python/issues",
+            module_name,
+        )
+    except Exception as e:
+        logger.warning("sovergate: instrument() failed, LLM calls will not be logged: %s", e)
+
+
+def shutdown() -> None:
+    """Stop the background sender thread. Records still queued at that point are discarded."""
+    try:
+        if _state["queue"]:
+            _state["queue"].stop()
+    except Exception as e:
+        logger.debug("sovergate: shutdown error: %s", e)