truerecord-sdk 0.1.2__tar.gz

truerecord_sdk-0.1.2/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.

truerecord_sdk-0.1.2/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,112 @@
+# 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/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "truerecord-sdk"
+version = "0.1.2"
+description = "Python SDK for the TrueRecord LLM Governance Platform"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Exploring Data B.V.", email = "support@truerecord.eu" }]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.24.0",
+    "cryptography>=41.0.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "pytest-asyncio>=0.21"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/truerecord_sdk"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

truerecord_sdk-0.1.2/src/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-0.1.2/src/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-0.1.2/src/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-0.1.2/src/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/tests/test_client.py

@@ -0,0 +1,307 @@
+import base64
+import json
+from datetime import datetime
+
+import httpx
+import pytest
+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 import (
+    APIError,
+    AuthenticationError,
+    EncryptionError,
+    NetworkError,
+    TrueRecordClient,
+    ValidationError,
+)
+from truerecord_sdk import client as client_module
+from truerecord_sdk.client import API_URL
+
+OAEP = padding.OAEP(mgf=padding.MGF1(hashes.SHA256()), algorithm=hashes.SHA256(), label=None)
+
+
+@pytest.fixture(scope="module")
+def private_key():
+    return rsa.generate_private_key(public_exponent=65537, key_size=2048)
+
+
+@pytest.fixture(scope="module")
+def pem(private_key):
+    return private_key.public_key().public_bytes(
+        serialization.Encoding.PEM, serialization.PublicFormat.SubjectPublicKeyInfo
+    ).decode()
+
+
+@pytest.fixture
+def client(pem):
+    return TrueRecordClient(
+        api_key="tr_sk_test", public_key=pem,
+        application_guid="app-1", interaction_guid="int-1",
+    )
+
+
+def fake_server(monkeypatch, *responses):
+    """Route every httpx request to a scripted sequence of responses.
+
+    Each entry is an httpx.Response or an exception to raise.
+    The last entry repeats. Returns captured requests and sleep durations."""
+    responses = list(responses) or [httpx.Response(200, json={"ok": True})]
+    captured = {"requests": [], "sleeps": []}
+
+    def handler(request):
+        captured["requests"].append(request)
+        item = responses[min(len(captured["requests"]) - 1, len(responses) - 1)]
+        if isinstance(item, Exception):
+            raise item
+        return item
+
+    transport = httpx.MockTransport(handler)
+    real_client, real_async = httpx.Client, httpx.AsyncClient
+    monkeypatch.setattr(httpx, "Client", lambda **kw: real_client(transport=transport, **kw))
+    monkeypatch.setattr(httpx, "AsyncClient", lambda **kw: real_async(transport=transport, **kw))
+    monkeypatch.setattr(client_module.time, "sleep", lambda s: captured["sleeps"].append(s))
+
+    async def fake_async_sleep(s):
+        captured["sleeps"].append(s)
+
+    monkeypatch.setattr(client_module.asyncio, "sleep", fake_async_sleep)
+    return captured
+
+
+def decrypt(private_key, body):
+    key = private_key.decrypt(base64.b64decode(body["record"]["encryption_key"]), OAEP)
+    raw = base64.b64decode(body["record"]["content"])
+    return json.loads(AESGCM(key).decrypt(raw[:12], raw[12:], None))
+
+
+# -- constructor --------------------------------------------------------------
+
+@pytest.mark.parametrize("missing", ["api_key", "public_key", "application_guid", "interaction_guid"])
+def test_init_requires_args(pem, missing):
+    kwargs = {"api_key": "k", "public_key": pem, "application_guid": "app-1", "interaction_guid": "int-1", missing: ""}
+    with pytest.raises(ValidationError, match=missing):
+        TrueRecordClient(**kwargs)
+
+
+def test_init_rejects_bad_key():
+    with pytest.raises(EncryptionError):
+        TrueRecordClient(api_key="k", public_key="bad", application_guid="app-1", interaction_guid="int-1")
+
+
+# -- send ---------------------------------------------------------------------
+
+def test_send_user_message(client, private_key, monkeypatch):
+    captured = fake_server(monkeypatch, httpx.Response(200, json={"id": "rec-1"}))
+
+    result = client.send(
+        {"prompt": "héllo 🎉"}, "user",
+        message_datetime="2026-09-17T10:00:00Z",
+        conversation_ref="conv-1",
+    )
+
+    assert result == {"id": "rec-1"}
+    [req] = captured["requests"]
+    assert req.method == "POST"
+    assert str(req.url) == API_URL
+    assert req.headers["Authorization"] == "Bearer tr_sk_test"
+    assert req.headers["User-Agent"].startswith("truerecord-sdk/")
+
+    body = json.loads(req.content)
+    assert body["application_guid"] == "app-1"
+    assert body["interaction_guid"] == "int-1"
+    assert body["conversation_ref"] == "conv-1"
+    datetime.fromisoformat(body["sent_at_datetime"])
+    assert body["record"]["type"] == "user"
+    assert body["record"]["occurred_at"] == "2026-09-17T10:00:00Z"
+    assert "prompt" not in body["record"]["content"]
+    assert decrypt(private_key, body) == {"prompt": "héllo 🎉"}
+
+
+def test_send_llm_message(client, private_key, monkeypatch):
+    captured = fake_server(monkeypatch, httpx.Response(200, json={"id": "rec-2"}))
+
+    result = client.send(
+        {"text": "world"}, "llm",
+        message_datetime="2026-09-17T10:00:01Z",
+    )
+
+    assert result == {"id": "rec-2"}
+    body = json.loads(captured["requests"][0].content)
+    assert body["record"]["type"] == "llm"
+    assert body["record"]["occurred_at"] == "2026-09-17T10:00:01Z"
+    assert decrypt(private_key, body) == {"text": "world"}
+
+
+def test_send_defaults_message_datetime(client, monkeypatch):
+    captured = fake_server(monkeypatch)
+    client.send("just a string", "user")
+    body = json.loads(captured["requests"][0].content)
+    assert body["conversation_ref"] is None
+    datetime.fromisoformat(body["record"]["occurred_at"])
+
+
+def test_send_agent_message(client, monkeypatch):
+    captured = fake_server(monkeypatch)
+    client.send("from an agent", "agent")
+    body = json.loads(captured["requests"][0].content)
+    assert body["record"]["type"] == "agent"
+
+
+def test_send_requires_message(client):
+    with pytest.raises(ValidationError, match="message is required"):
+        client.send(None, "user")
+
+
+def test_send_requires_valid_origin(client):
+    with pytest.raises(ValidationError, match="origin"):
+        client.send({}, "invalid")
+    with pytest.raises(ValidationError, match="origin"):
+        client.send({}, None)
+
+
+def test_send_rejects_unserialisable(client):
+    with pytest.raises(ValidationError, match="not JSON-serialisable"):
+        client.send({"when": datetime.now()}, "user")
+
+
+# -- errors -------------------------------------------------------------------
+
+@pytest.mark.parametrize("status", [401, 403])
+def test_auth_error_not_retried(client, monkeypatch, status):
+    captured = fake_server(monkeypatch, httpx.Response(status))
+    with pytest.raises(AuthenticationError):
+        client.send({}, "user")
+    assert len(captured["requests"]) == 1
+
+
+def test_api_error_with_detail(client, monkeypatch):
+    fake_server(monkeypatch, httpx.Response(422, json={"detail": "bad guid"}))
+    with pytest.raises(APIError, match="HTTP 422: bad guid") as exc:
+        client.send({}, "user")
+    assert exc.value.status_code == 422
+    assert exc.value.detail == "bad guid"
+
+
+def test_api_error_non_json_body(client, monkeypatch):
+    fake_server(monkeypatch, httpx.Response(400, text="<html>Bad Request</html>"))
+    with pytest.raises(APIError, match="400.*Bad Request"):
+        client.send({}, "user")
+
+
+def test_success_non_json_body(client, monkeypatch):
+    fake_server(monkeypatch, httpx.Response(200, text="OK"))
+    with pytest.raises(APIError, match="Expected JSON object"):
+        client.send({}, "user")
+
+
+def test_redirect_is_an_error_not_a_success(client, monkeypatch):
+    redirect = httpx.Response(302, headers={"Location": "https://elsewhere.example/"}, json={"ok": True})
+    captured = fake_server(monkeypatch, redirect)
+    with pytest.raises(APIError) as exc:
+        client.send({}, "user")
+    assert exc.value.status_code == 302
+    assert len(captured["requests"]) == 1
+
+
+def test_error_detail_is_truncated(client, monkeypatch):
+    fake_server(monkeypatch, httpx.Response(400, text="x" * 5000))
+    with pytest.raises(APIError) as exc:
+        client.send({}, "user")
+    assert len(exc.value.detail) == client_module.DETAIL_MAX
+
+
+# -- retries ------------------------------------------------------------------
+
+def test_retries_then_succeeds(client, monkeypatch):
+    captured = fake_server(
+        monkeypatch,
+        httpx.Response(503), httpx.Response(503), httpx.Response(200, json={"ok": True}),
+    )
+    assert client.send({}, "user") == {"ok": True}
+    assert len(captured["requests"]) == 3
+    first, second = captured["sleeps"]
+    assert 0.5 <= first <= 0.75
+    assert 1.0 <= second <= 1.5
+
+
+def test_gives_up_after_retries(client, monkeypatch):
+    captured = fake_server(monkeypatch, httpx.Response(503, json={"detail": "busy"}))
+    with pytest.raises(APIError, match="HTTP 503: busy"):
+        client.send({}, "user")
+    assert len(captured["requests"]) == 3  # 1 + 2 retries
+
+
+def test_client_error_not_retried(client, monkeypatch):
+    captured = fake_server(monkeypatch, httpx.Response(422, json={"detail": "nope"}))
+    with pytest.raises(APIError):
+        client.send({}, "user")
+    assert len(captured["requests"]) == 1
+    assert captured["sleeps"] == []
+
+
+def test_retry_after_header_honoured(client, monkeypatch):
+    captured = fake_server(
+        monkeypatch,
+        httpx.Response(429, headers={"Retry-After": "3"}), httpx.Response(200, json={}),
+    )
+    client.send({}, "user")
+    assert captured["sleeps"] == [3.0]
+
+
+def test_retry_after_is_capped(client, monkeypatch):
+    captured = fake_server(
+        monkeypatch,
+        httpx.Response(503, headers={"Retry-After": "1e9"}), httpx.Response(200, json={}),
+    )
+    client.send({}, "user")
+    assert captured["sleeps"] == [client_module.RETRY_AFTER_CAP]
+
+
+@pytest.mark.parametrize("value", ["inf", "nan", "soon"])
+def test_retry_after_garbage_falls_back_to_backoff(client, monkeypatch, value):
+    captured = fake_server(
+        monkeypatch,
+        httpx.Response(503, headers={"Retry-After": value}), httpx.Response(200, json={}),
+    )
+    client.send({}, "user")
+    assert 0.5 <= captured["sleeps"][0] <= 0.75
+
+
+@pytest.mark.parametrize("error", [httpx.ConnectError("refused"), httpx.ReadTimeout("slow")])
+def test_network_error_retried_then_raised(client, monkeypatch, error):
+    captured = fake_server(monkeypatch, error)
+    with pytest.raises(NetworkError):
+        client.send({}, "user")
+    assert len(captured["requests"]) == 3
+
+
+# -- asend --------------------------------------------------------------------
+
+async def test_asend_user_message(client, private_key, monkeypatch):
+    captured = fake_server(monkeypatch, httpx.Response(200, json={"id": "rec-2"}))
+    result = await client.asend({"q": 1}, "user")
+    assert result == {"id": "rec-2"}
+    body = json.loads(captured["requests"][0].content)
+    assert decrypt(private_key, body) == {"q": 1}
+
+
+async def test_asend_retries_then_succeeds(client, monkeypatch):
+    captured = fake_server(monkeypatch, httpx.Response(503), httpx.Response(200, json={}))
+    await client.asend({}, "user")
+    assert len(captured["requests"]) == 2
+    assert 0.5 <= captured["sleeps"][0] <= 0.75
+
+
+async def test_asend_errors(client, monkeypatch):
+    fake_server(monkeypatch, httpx.Response(401))
+    with pytest.raises(AuthenticationError):
+        await client.asend({}, "user")
+
+
+async def test_asend_redirect_is_an_error(client, monkeypatch):
+    fake_server(monkeypatch, httpx.Response(307, headers={"Location": "https://elsewhere.example/"}))
+    with pytest.raises(APIError) as exc:
+        await client.asend({}, "user")
+    assert exc.value.status_code == 307

truerecord_sdk-0.1.2/tests/test_encryption.py

@@ -0,0 +1,75 @@
+import base64
+import json
+
+import pytest
+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.encryption import Encryptor, load_public_key
+from truerecord_sdk.exceptions import EncryptionError
+
+OAEP = padding.OAEP(mgf=padding.MGF1(hashes.SHA256()), algorithm=hashes.SHA256(), label=None)
+
+
+def pem_for(private_key):
+    return private_key.public_key().public_bytes(
+        serialization.Encoding.PEM, serialization.PublicFormat.SubjectPublicKeyInfo
+    ).decode()
+
+
+def der_b64_for(private_key):
+    return base64.b64encode(private_key.public_key().public_bytes(
+        serialization.Encoding.DER, serialization.PublicFormat.SubjectPublicKeyInfo
+    )).decode()
+
+
+@pytest.fixture(scope="module")
+def private_key():
+    return rsa.generate_private_key(public_exponent=65537, key_size=2048)
+
+
+@pytest.fixture(scope="module")
+def public_key(private_key):
+    return load_public_key(pem_for(private_key))
+
+
+def decrypt(private_key, wrapped_key: str, blob: str):
+    key = private_key.decrypt(base64.b64decode(wrapped_key), OAEP)
+    raw = base64.b64decode(blob)
+    return json.loads(AESGCM(key).decrypt(raw[:12], raw[12:], None))
+
+
+def test_rejects_garbage():
+    with pytest.raises(EncryptionError, match="Invalid public key"):
+        load_public_key("not a valid key")
+
+
+def test_rejects_small_key():
+    small = rsa.generate_private_key(public_exponent=65537, key_size=1024)
+    with pytest.raises(EncryptionError, match="at least 2048"):
+        load_public_key(pem_for(small))
+
+
+def test_round_trip(private_key, public_key):
+    value = {"text": "héllo 日本 🎉 \"quotes\" \\ \x00\n", "n": [1, 2.5, None, True]}
+    enc = Encryptor(public_key)
+    assert decrypt(private_key, enc.wrapped_key, enc.encrypt(value)) == value
+
+
+def test_round_trip_der_b64(private_key):
+    public_key = load_public_key(der_b64_for(private_key))
+    value = {"msg": "hello from DER"}
+    enc = Encryptor(public_key)
+    assert decrypt(private_key, enc.wrapped_key, enc.encrypt(value)) == value
+
+
+def test_same_key_different_nonce(private_key, public_key):
+    enc = Encryptor(public_key)
+    a, b = enc.encrypt("x"), enc.encrypt("x")
+    assert a != b
+    assert decrypt(private_key, enc.wrapped_key, a) == decrypt(private_key, enc.wrapped_key, b) == "x"
+
+
+def test_fresh_key_per_encryptor(public_key):
+    assert Encryptor(public_key).wrapped_key != Encryptor(public_key).wrapped_key