truerecord-sdk 0.1.2__py3-none-any.whl

truerecord_sdk/__init__.py

@@ -0,0 +1,20 @@
+from truerecord_sdk.client import TrueRecordClient, __version__
+from truerecord_sdk.exceptions import (
+    APIError,
+    AuthenticationError,
+    EncryptionError,
+    NetworkError,
+    TrueRecordError,
+    ValidationError,
+)
+
+__all__ = [
+    "TrueRecordClient",
+    "TrueRecordError",
+    "APIError",
+    "AuthenticationError",
+    "EncryptionError",
+    "NetworkError",
+    "ValidationError",
+    "__version__",
+]

truerecord_sdk/client.py

@@ -0,0 +1,220 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import math
+import random
+import time
+import uuid
+from datetime import datetime, timezone
+from importlib.metadata import PackageNotFoundError, version
+from typing import Any, Literal
+
+import httpx
+
+from truerecord_sdk.encryption import Encryptor, load_public_key
+from truerecord_sdk.exceptions import (
+    APIError,
+    AuthenticationError,
+    NetworkError,
+    ValidationError,
+)
+
+try:
+    __version__ = version("truerecord-sdk")
+except PackageNotFoundError:  # running from source, not installed
+    __version__ = "0.0.0"
+
+API_URL = "https://api.truerecord.eu/evaluate"
+
+# Responses worth retrying: the API is busy, restarting, or asked us to wait.
+RETRY_STATUSES = frozenset({408, 409, 429, 500, 502, 503, 504})
+TIMEOUT = 15.0  # seconds per attempt
+RETRIES = 2  # attempts after the first
+BACKOFF_BASE = 0.5  # seconds; doubles each retry
+BACKOFF_CAP = 10.0  # seconds
+RETRY_AFTER_CAP = 30.0  # seconds; the longest Retry-After we honour
+DETAIL_MAX = 200  # characters of a response body quoted in an error
+
+Origin = Literal["user", "llm", "agent"]
+
+
+class TrueRecordClient:
+    """Sends encrypted LLM interaction records to TrueRecord.
+
+        client = TrueRecordClient(api_key, public_key, application_guid, interaction_guid)
+        client.send({"prompt": "hello"}, "user")
+        client.send({"text": "hi there"}, "llm")
+
+    Every method raises only subclasses of `TrueRecordError`.
+
+    Retries: a send that fails because the API is unreachable, times out, or
+    answers 408/409/429/5xx is retried twice with exponential
+    backoff and jitter (about 0.5s, then 1s, then 2s...). A `Retry-After`
+    header from the API overrides the wait, up to 30s. Other 4xx responses
+    are not retried. Redirects are not followed: anything but a 2xx is an error.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        public_key: str,
+        application_guid: str,
+        interaction_guid: str,
+    ) -> None:
+        """
+        Args:
+            api_key: Your TrueRecord API key. Sent as a bearer token.
+            public_key: Your TrueRecord RSA public key, as a PEM string or
+                base64-encoded DER. Messages are encrypted with it before
+                leaving your process.
+            application_guid: Identifies the application the records belong to.
+            interaction_guid: Identifies the specific interaction within the application.
+
+        Raises:
+            ValidationError: An argument is empty.
+            EncryptionError: The public key is not a valid RSA key of at least 2048 bits.
+        """
+        if not api_key:
+            raise ValidationError("api_key is required")
+        if not public_key:
+            raise ValidationError("public_key is required")
+        if not application_guid:
+            raise ValidationError("application_guid is required")
+        if not interaction_guid:
+            raise ValidationError("interaction_guid is required")
+
+        self._public_key = load_public_key(public_key)
+        self._application_guid = application_guid
+        self._interaction_guid = interaction_guid
+        self._headers = {
+            "Authorization": f"Bearer {api_key}",
+            "User-Agent": f"truerecord-sdk/{__version__}",
+        }
+
+    def send(
+        self,
+        message: Any,
+        origin: Origin,
+        message_datetime: str | None = None,
+        conversation_ref: str | None = None,
+    ) -> dict[str, Any]:
+        """Encrypt an LLM message and send it to TrueRecord.
+
+        Args:
+            message: The message content. Any JSON-serialisable value. Encrypted.
+            origin: ``"user"`` for a user message, ``"llm"`` for the LLM's
+                response, ``"agent"`` for a message from an agent.
+            message_datetime: When the message occurred, ISO 8601.
+                Defaults to now. Not encrypted.
+            conversation_ref: Optional ID linking interactions in one conversation.
+
+        Returns:
+            The server's JSON response as a dict.
+
+        Raises:
+            ValidationError: A required argument is missing or a value is not JSON-serialisable.
+            NetworkError: The server could not be reached or timed out, after all retries.
+            AuthenticationError: The API key was rejected.
+            APIError: The server returned any other error, after all retries where applicable.
+        """
+        body = self._prepare(message, origin, message_datetime, conversation_ref)
+        with httpx.Client(headers=self._headers, timeout=TIMEOUT) as http:
+            for attempt in range(RETRIES + 1):
+                last = attempt == RETRIES
+                try:
+                    result = http.post(API_URL, json=body)
+                except httpx.HTTPError as exc:
+                    if last:
+                        raise NetworkError(str(exc)) from exc
+                    time.sleep(_backoff(attempt, None))
+                    continue
+                if result.status_code in RETRY_STATUSES and not last:
+                    time.sleep(_backoff(attempt, result.headers.get("Retry-After")))
+                    continue
+                return _parse(result.status_code, result.text)
+        raise AssertionError("unreachable")
+
+    async def asend(
+        self,
+        message: Any,
+        origin: Origin,
+        message_datetime: str | None = None,
+        conversation_ref: str | None = None,
+    ) -> dict[str, Any]:
+        """Async version of `send`. Same arguments, return value, retries and errors."""
+        body = self._prepare(message, origin, message_datetime, conversation_ref)
+        async with httpx.AsyncClient(headers=self._headers, timeout=TIMEOUT) as http:
+            for attempt in range(RETRIES + 1):
+                last = attempt == RETRIES
+                try:
+                    result = await http.post(API_URL, json=body)
+                except httpx.HTTPError as exc:
+                    if last:
+                        raise NetworkError(str(exc)) from exc
+                    await asyncio.sleep(_backoff(attempt, None))
+                    continue
+                if result.status_code in RETRY_STATUSES and not last:
+                    await asyncio.sleep(_backoff(attempt, result.headers.get("Retry-After")))
+                    continue
+                return _parse(result.status_code, result.text)
+        raise AssertionError("unreachable")
+
+    def _prepare(
+        self,
+        message: Any,
+        origin: Origin,
+        message_datetime: str | None,
+        conversation_ref: str | None,
+    ) -> dict[str, Any]:
+        if message is None:
+            raise ValidationError("message is required")
+        if origin not in ("user", "llm", "agent"):
+            raise ValidationError("origin must be 'user', 'llm' or 'agent'")
+
+        enc = Encryptor(self._public_key)
+        try:
+            encrypted = enc.encrypt(message)
+        except (TypeError, ValueError) as exc:
+            raise ValidationError(f"message is not JSON-serialisable: {exc}") from exc
+
+        return {
+            "idempotency_key": str(uuid.uuid4()),
+            "interaction_guid": self._interaction_guid,
+            "application_guid": self._application_guid,
+            "conversation_ref": conversation_ref,
+            "sent_at_datetime": datetime.now(timezone.utc).isoformat(),
+            "record": {
+                "encryption_key": enc.wrapped_key,
+                "content": encrypted,
+                "type": origin,
+                "occurred_at": message_datetime or datetime.now(timezone.utc).isoformat(),
+            },
+        }
+
+
+def _backoff(attempt: int, retry_after: str | None) -> float:
+    if retry_after:
+        try:
+            seconds = float(retry_after)
+            if math.isfinite(seconds):
+                return min(max(0.0, seconds), RETRY_AFTER_CAP)
+        except ValueError:
+            pass
+    return min(BACKOFF_BASE * 2**attempt, BACKOFF_CAP) * random.uniform(1.0, 1.5)
+
+
+def _parse(status_code: int, text: str) -> dict[str, Any]:
+    if status_code in (401, 403):
+        raise AuthenticationError("API key rejected")
+    try:
+        body = json.loads(text)
+    except (ValueError, RecursionError):
+        body = None
+    # Only 2xx means the record landed. A 3xx is not followed and not a success.
+    if not 200 <= status_code < 300:
+        detail = body.get("detail") if isinstance(body, dict) else None
+        raise APIError(status_code, str(detail or text or "Unexpected status")[:DETAIL_MAX])
+    if not isinstance(body, dict):
+        raise APIError(status_code, f"Expected JSON object, got: {text[:DETAIL_MAX]}")
+    return body

truerecord_sdk/encryption.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import base64
+import json
+import os
+from typing import Any
+
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import padding, rsa
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+from truerecord_sdk.exceptions import EncryptionError
+
+_OAEP = padding.OAEP(
+    mgf=padding.MGF1(algorithm=hashes.SHA256()),
+    algorithm=hashes.SHA256(),
+    label=None,
+)
+
+
+def load_public_key(key_string: str) -> rsa.RSAPublicKey:
+    try:
+        if "-----BEGIN" in key_string:
+            key = serialization.load_pem_public_key(key_string.encode())
+        else:
+            key = serialization.load_der_public_key(base64.b64decode(key_string))
+    except (ValueError, TypeError) as exc:
+        raise EncryptionError(f"Invalid public key: {exc}") from exc
+    if not isinstance(key, rsa.RSAPublicKey):
+        raise EncryptionError(f"Expected an RSA public key, got {type(key).__name__}")
+    if key.key_size < 2048:
+        raise EncryptionError(f"RSA key is {key.key_size} bits, need at least 2048")
+    return key
+
+
+class Encryptor:
+    """One fresh AES-256 key. `wrapped_key` is that key encrypted with the RSA public key."""
+
+    def __init__(self, public_key: rsa.RSAPublicKey) -> None:
+        key = AESGCM.generate_key(bit_length=256)
+        self._aes = AESGCM(key)
+        self.wrapped_key = _b64(public_key.encrypt(key, _OAEP))
+
+    def encrypt(self, value: Any) -> str:
+        """JSON-encode `value`, encrypt with AES-GCM. Returns base64(nonce + ciphertext)."""
+        nonce = os.urandom(12)
+        plaintext = json.dumps(value, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+        return _b64(nonce + self._aes.encrypt(nonce, plaintext, None))
+
+
+def _b64(raw: bytes) -> str:
+    return base64.b64encode(raw).decode("ascii")

truerecord_sdk/exceptions.py

@@ -0,0 +1,27 @@
+class TrueRecordError(Exception):
+    """Base class for every error raised by this SDK."""
+
+
+class ValidationError(TrueRecordError):
+    """A required argument was missing or invalid. No request was sent."""
+
+
+class EncryptionError(TrueRecordError):
+    """The public key could not be loaded or the record could not be encrypted."""
+
+
+class NetworkError(TrueRecordError):
+    """The server could not be reached, or the request timed out."""
+
+
+class AuthenticationError(TrueRecordError):
+    """The server rejected the API key (HTTP 401 or 403)."""
+
+
+class APIError(TrueRecordError):
+    """The server returned an error. Check `status_code` and `detail`."""
+
+    def __init__(self, status_code: int, detail: str) -> None:
+        self.status_code = status_code
+        self.detail = detail
+        super().__init__(f"HTTP {status_code}: {detail}")

truerecord_sdk-0.1.2.dist-info/METADATA

@@ -0,0 +1,132 @@
+Metadata-Version: 2.5
+Name: truerecord-sdk
+Version: 0.1.2
+Summary: Python SDK for the TrueRecord LLM Governance Platform
+Author-email: "Exploring Data B.V." <support@truerecord.eu>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: cryptography>=41.0.0
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# TrueRecord SDK for Python
+
+[TrueRecord](https://truerecord.eu) keeps a record of every interaction with an AI system in your app. This SDK sends those records. Each message is encrypted before it leaves your process, so only TrueRecord can process it. See the [TrueRecord SDK docs](https://truerecord.eu/docs/sdk) for setup and guides.
+
+Requires Python 3.9+.
+
+## Install
+
+```
+pip install truerecord-sdk
+```
+
+## Quick start
+
+```python
+from truerecord_sdk import TrueRecordClient, TrueRecordError
+
+client = TrueRecordClient(
+    api_key="tr_sk_...",
+    public_key=open("truerecord_public.pem").read(),
+    application_guid="...",
+    interaction_guid="...",
+)
+
+try:
+    # Send the message your user sends to the LLM
+    client.send(user_message, "user", conversation_ref="session-42")
+
+    # Send a message from the LLM to the user
+    client.send(llm_message, "llm", conversation_ref="session-42")
+except TrueRecordError as e:
+    print(e)
+```
+
+## What to send
+
+Each call to `send` creates a record of one message, either what the user sent (`"user"`) or what the LLM sent (`"llm"`). Use the same `conversation_ref` for both so TrueRecord can pair them.
+
+```python
+client.send(message, origin, message_datetime=None, conversation_ref=None)
+```
+
+| Argument | Required | Description |
+|---|---|---|
+| `message` | Yes | The message a user sent to the AI or the AI sent to the user. Can be any value that converts to JSON (string, dict, list, etc.). |
+| `origin` | Yes | `"user"` if this is a message sent to the LLM, `"llm"` if it's the LLM's response, `"agent"` if it comes from an agent. |
+| `message_datetime` | No | When the message happened, as an ISO 8601 string (e.g. `"2025-01-15T10:30:00Z"`). When not set defaults to the current time. |
+| `conversation_ref` | No | A reference you choose (like a session ID or chat ID) to link related messages together. Pass the same value for a user message and its AI response so TrueRecord can pair them. |
+
+## Implementation details
+
+### Non-blocking (recommended)
+
+Sending data to TrueRecord runs in the background so the rest of your code continues without waiting for TrueRecord to respond.
+
+#### Synchronous apps
+
+For apps using Flask, Django or scripts and CLI tools. Use a thread pool to send in the background.
+
+```python
+from concurrent.futures import ThreadPoolExecutor
+
+executor = ThreadPoolExecutor(max_workers=4)
+
+executor.submit(client.send, user_message, "user", conversation_ref="session-42")
+executor.submit(client.send, llm_message, "llm", conversation_ref="session-42")
+```
+
+#### Asynchronous apps
+
+For apps using FastAPI, Starlette, aiohttp or functions defined with `async`. Use `asyncio.create_task` to send in the background.
+
+```python
+import asyncio
+
+asyncio.create_task(client.asend(user_message, "user", conversation_ref="session-42"))
+asyncio.create_task(client.asend(llm_message, "llm", conversation_ref="session-42"))
+```
+
+### Blocking
+
+Sending data to TrueRecord waits for TrueRecord to respond before the rest of your code continues.
+
+#### Synchronous apps
+
+```python
+client.send(user_message, "user", conversation_ref="session-42")
+client.send(llm_message, "llm", conversation_ref="session-42")
+```
+
+#### Asynchronous apps
+
+```python
+await client.asend(user_message, "user", conversation_ref="session-42")
+await client.asend(llm_message, "llm", conversation_ref="session-42")
+```
+
+## Errors
+
+All errors extend `TrueRecordError`, so you can catch them in one place.
+
+| Error | When |
+|---|---|
+| `ValidationError` | A required argument is missing or the message can't be serialised to JSON. |
+| `EncryptionError` | The public key isn't a valid RSA key. |
+| `NetworkError` | TrueRecord couldn't be reached after retries. |
+| `AuthenticationError` | The API key was rejected. |
+| `APIError` | Any other server error. Has `status_code` and `detail`. |
+
+## License
+
+MIT

truerecord_sdk-0.1.2.dist-info/RECORD

@@ -0,0 +1,9 @@
+truerecord_sdk/__init__.py,sha256=P-m8dT9wbsbcPHjSqgtAZbwCC3RaVFsPSwPOvT92vr4,416
+truerecord_sdk/client.py,sha256=HxLIYOnxOV_0ofchOFfLyZYCjkkkIUoTPag4eaSn0F8,8642
+truerecord_sdk/encryption.py,sha256=yF9W_b8onjLA5ftgog3Y3ZfxAe-CJ9Xrzuhs_MyeQzw,1854
+truerecord_sdk/exceptions.py,sha256=ERSoDEcjFGaMIRA_pjaStc-jwnFAa87EnKu-NktW7Kc,847
+truerecord_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+truerecord_sdk-0.1.2.dist-info/METADATA,sha256=DQcd_HrpR3XIP2xBa_Hz_ZRLCSsLL58mm4aCpBlpaDo,4530
+truerecord_sdk-0.1.2.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+truerecord_sdk-0.1.2.dist-info/licenses/LICENSE,sha256=Ctuhvjdl88HD9HbJ5ukS-bPr_bDPqSoEh3uyqJCtApc,1076
+truerecord_sdk-0.1.2.dist-info/RECORD,,

truerecord_sdk-0.1.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

truerecord_sdk-0.1.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Exploring Data B.V.
+
+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.