Extract standalone TRACE Python SDK

Create the dedicated latence-trace-python SDK repo that publishes the existing latence package with a thin TRACE-first client, session storage, contract checks, and PyPI trusted publishing setup.

Author: ddickmann

.github/workflows/publish.yml

@@ -0,0 +1,33 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tooling
+        run: python -m pip install --upgrade build twine
+
+      - name: Build
+        run: python -m build
+
+      - name: Check distributions
+        run: python -m twine check dist/*
+
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

.github/workflows/test.yml

@@ -0,0 +1,32 @@
+name: Test
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install
+        run: python -m pip install -e ".[dev]"
+
+      - name: Lint
+        run: python -m ruff check .
+
+      - name: Test
+        run: python -m pytest

.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.venv/
+dist/
+build/
+*.egg-info/
+.trace-sessions/
+.env
+.env.*
+!.env.example

LICENSE

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

README.md

@@ -0,0 +1,81 @@
+# Latence Python SDK
+
+Thin Python SDK for Latence TRACE.
+
+```bash
+pip install latence
+```
+
+```python
+from latence import Latence
+
+client = Latence(api_key="lat_...")
+
+result = client.grounding.rag(
+    query="When will this customer be refunded?",
+    response_text="The customer will be refunded within 48 hours.",
+    raw_context="Refunds are reviewed manually after finance approval.",
+)
+
+print(result.risk_band)
+```
+
+## Surface
+
+The SDK maps 1:1 to the TRACE product API:
+
+- `client.privacy.redact(...)`
+- `client.grounding.rag(...)`
+- `client.grounding.code(...)`
+- `client.compression.text(...)`
+- `client.compression.messages(...)`
+- `client.memory.step(...)`
+- `client.rollup(...)`
+- `client.session(...)`
+
+`Latence` is the sync client. `AsyncLatence` exposes the same product namespaces for asyncio apps.
+
+## Sessions
+
+TRACE deployments are stateless by default. The SDK owns caller-carried session state for agent workflows that need memory continuity, rollups, idempotency, and local persistence.
+
+```python
+from latence import FileSessionStorage, Latence
+
+client = Latence(api_key="lat_...")
+session = client.session(
+    session_id="support-run-42",
+    storage=FileSessionStorage(".trace-sessions"),
+)
+
+session.event("tool", "loaded refund policy")
+session.memory_step(turn_text="Keep finance approval as required context.")
+score = session.rag(
+    query="Can I promise the refund?",
+    response_text="Yes, the refund is guaranteed in 48 hours.",
+    raw_context="Refunds require manual finance approval.",
+)
+session.save()
+```
+
+## Compatibility
+
+The primary import is:
+
+```python
+from latence import Latence, AsyncLatence
+```
+
+For migration from the TRACE preview SDK, `LatenceTraceClient` and `AsyncLatenceTraceClient` remain aliases.
+
+## Development
+
+```bash
+python -m pip install -e ".[dev]"
+python -m pytest
+python -m ruff check .
+python -m build
+python -m twine check dist/*
+```
+
+Set `LATENCE_TRACE_RUNTIME_REPO=/path/to/latence-trace` when running contract tests from a non-sibling checkout.

docs/errors.md

@@ -0,0 +1,13 @@
+# Errors
+
+All SDK exceptions inherit from `LatenceTraceAPIError`.
+
+Common subclasses:
+
+- `LatenceTraceAuthError` for invalid or missing credentials.
+- `LatenceTraceRateLimited` for HTTP 429 responses. The `retry_after` attribute is set when the server provides it.
+- `LatenceTraceTimeout` for client-side timeouts.
+- `LatenceTraceValidationError` for request validation errors.
+- `LatenceTraceServerError` for malformed or failed server responses.
+
+The SDK retries transient `408`, `409`, `425`, `429`, and `5xx` responses according to `RetryPolicy`.

docs/integrations.md

@@ -0,0 +1,26 @@
+# Integrations
+
+The core SDK has only `httpx` and `pydantic` runtime dependencies.
+
+Optional integration helpers live under `latence.integrations` and are activated through extras:
+
+```bash
+pip install "latence[langchain]"
+pip install "latence[llama_index]"
+pip install "latence[openai]"
+```
+
+The recommended baseline for frameworks such as LangChain, LangGraph, LlamaIndex, n8n, Cursor, Claude Code, and Codex is to call the explicit product methods directly:
+
+```python
+from latence import Latence
+
+trace = Latence()
+decision = trace.grounding.rag(
+    query=user_question,
+    response_text=agent_answer,
+    raw_context=retrieved_context,
+)
+```
+
+This keeps the integration thin and makes TRACE decisions easy to log, replay, and route.

docs/publishing.md

@@ -0,0 +1,20 @@
+# PyPI Publishing
+
+PyPI project: `latence`
+
+Trusted Publisher settings:
+
+- Publisher: GitHub
+- Owner: `latenceainew`
+- Repository: `latence-trace-python`
+- Workflow filename: `publish.yml`
+- Environment name: `pypi`
+
+No PyPI API token is required when Trusted Publishing is enabled.
+
+Release flow:
+
+1. Confirm the version in `pyproject.toml` has not been uploaded before.
+2. Run `python -m pytest`, `python -m ruff check .`, `python -m build`, and `python -m twine check dist/*`.
+3. Create and push a release tag, for example `v1.0.0`.
+4. Publish through the protected `pypi` GitHub environment.

docs/quickstart.md

@@ -0,0 +1,23 @@
+# Quickstart
+
+Install:
+
+```bash
+pip install latence
+```
+
+Score a RAG response:
+
+```python
+from latence import Latence
+
+client = Latence(api_key="lat_...")
+score = client.grounding.rag(
+    query="Can this invoice be refunded?",
+    response_text="Yes, it will be refunded within 48 hours.",
+    raw_context="Refunds require manual finance approval.",
+)
+print(score.risk_band)
+```
+
+Use `AsyncLatence` for asyncio services. The async surface mirrors the sync client.

docs/sessions.md

@@ -0,0 +1,24 @@
+# Sessions
+
+TRACE compute deployments are stateless. The Python SDK carries optional session state on the caller side so agent runs can preserve memory state, idempotency keys, events, and rollup inputs without requiring shared server storage.
+
+```python
+from latence import FileSessionStorage, Latence
+
+client = Latence()
+session = client.session(
+    session_id="agent-run-1",
+    storage=FileSessionStorage(".trace-sessions"),
+)
+
+session.event("tool", "loaded customer policy")
+session.memory_step(turn_text="Keep the manual approval rule active.")
+score = session.rag(
+    query="Can we promise a refund?",
+    response_text="The refund is guaranteed.",
+    raw_context="Refunds require finance approval.",
+)
+session.save()
+```
+
+Use `InMemorySessionStorage` for tests and short-lived processes. Use `FileSessionStorage` for local agents and CLI workflows.