Metadata-Version: 2.4
Name: trinitite
Version: 0.0.3
Summary: The Trinitite SDK for Python — the control plane for AI. One universal execution layer for governing, observing, and auditing every AI call.
Project-URL: Homepage, https://trinitite.ai
Author-email: Trinitite <dev@trinitite.ai>
License: Apache-2.0
License-File: LICENSE
Keywords: ai-governance,audit,compliance,sdk,trinitite
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: jsonschema>=4.21
Requires-Dist: pydantic>=2.6
Requires-Dist: python-dotenv>=1.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: datamodel-code-generator[http]>=0.28; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: stream
Requires-Dist: python-socketio>=5.11; extra == 'stream'
Description-Content-Type: text/markdown

# trinitite — Python SDK

The Trinitite SDK for Python — the control plane for AI. One universal execution layer for governing, observing, and auditing every AI call. Sync-first (httpx) with a keyword-sugar entry point: `Trinitite(api_key="trnt_live_…", env="prod")`.

**Status (this checkout):** the runtime SDK is **live** — the hero entry point plus all 43 `tr.*` foreground namespaces, contract-first against `sdk/contract/schemas/`. Every `tr.<name>` property returns a typed handle.

- **Typed result + instance handles** mirroring `GovernanceResult` — `RiskHandle`, `GateReceiptHandle`, `TraceHandle`, `ThreatHandle` + typed accessors on the existing instance handles (`ServedModelAssetHandle`, `TrainingJobHandle`, `EvalRunHandle`, `VendorHandle`). Each carries per-field typed properties + chained accessors (`.replay()`, `.verify()`, `.export()`, …).
- **`Trinitite.from_posture(source, opts=...)`** — posture-as-code. Load a `trinitite.yaml`, apply the baseline via `govern()`, each scope via `scope()`/`agent()`, each scope's assets via the `ScopeHandle` sub-handles. Idempotent (GitOps-safe). Returns a `Posture` (`{ baseline, scopes, raw }`).
- **`tr.status` / `tr.health`** — the operational one-pager. Tries the designed `GET /v1/status` / `GET /v1/health`; on 404 composes a `PlatformStatus` / `PlatformHealth` client-side from the live endpoints. Works today; ready when the backend ships the composed route.
- **`tr.on(...) / tr.events`** — the unified typed-event surface. External webhook registration (`POST /v1/webhooks`), typed pull (`GET /v1/events` with `GET /v1/audit/logs` fallback → `TrinititeEvent[]`), and an SSE stream (`GET /v1/events/stream`). See `docs/sdk/reference/events.md`.
- **`tr.dashboard.embed(...)`** — the buyer-side admin UI. Mints a scoped, time-bound, iframe-able embed token via `POST /v1/dashboard/embed` → `DashboardEmbedHandle` (`url`, `embed_id`, `expires_at`, `.revoke()`). See `docs/sdk/reference/dashboard.md`.
- **The surface-diff parity gate** — `npm run parity:check -w sdk/contract` walks every public class + method/field in both SDKs and fails on any cross-language drift.

Every foreground's `.get()`/`.create()`/`.build()`/`.ingest()`/`.recommend()`/`.evaluate()` returns a typed handle (snake_case accessors + chained methods) instead of raw `Response`. The dev writes `r.frameworks` / `r.coverage` / `r.accept()` instead of `tr.compliance.snapshot(...).body['frameworks']`.

The contract types are generated into `src/trinitite/_generated/` by the shared contract package (`sdk/contract`); the runtime classes live in the `_*` modules. Never hand-edit `_generated/` — change the schema, re-run codegen.

## Build

```bash
# 1. Generate the contract mirror (from the repo root):
( cd sdk/contract && python scripts/codegen-py.py )

# 2. Install the package (editable, with dev extras):
( cd sdk/python && pip install -e '.[dev]' )

# 3. Run the test suite:
( cd sdk/python && pytest )

# 4. The drift gate (full surface-diff vs the TypeScript SDK):
npm run parity:check -w sdk/contract
```

## Live SDK tests

An opt-in live-backend smoke suite sits beside the mock suite at
`tests/live/test_smoke.py`. It routes **real calls** through the SDK hero entry
+ foregrounds against the same deployed control plane the REST
`proxy-testing/` harness drives, proving the transport, boot, and typed-handle
unwrap layer work against the real wire (the mock suite stays the green gate —
it is **not** touched by the live run).

The `live` marker is default-deselected (`addopts = "-m 'not live'"` in
`pyproject.toml`), so bare `pytest` never touches the network. The live
fixtures + the collection-time self-skip hook live in `tests/conftest.py` (a
second `conftest.py` under `tests/live/` would shadow the bare
`from conftest import ...` imports the mock suite relies on).

```bash
# Run the live smoke (reuses proxy-testing/.env automatically — no extra config):
( cd sdk/python && pytest -m live -v )

# Or with explicit env (wins over the file):
TRINITITE_API_KEY=trnt_live_… TRINITITE_BASE_URL=https://… \
    ( cd sdk/python && pytest -m live -v )

# Bare pytest is unchanged — live tests deselected, mock suite is the green gate:
( cd sdk/python && pytest )
```

`pytest -m live` without credentials self-skips at collection time (no network,
no failures). TLS verification defaults to off (`TRINITITE_VERIFY_TLS=0`) for
the internal nip.io dev cert; set `TRINITITE_VERIFY_TLS=1` for a
publicly-trusted endpoint. Findings (SDK-vs-wire drift, backend defects) are
recorded as in-test `xfail` regression records + in
`tests/live/RUN_RESULTS_*.md` (mirroring `proxy-testing`'s BUG-N/DOC-N
discipline). See `tests/live/RUN_RESULTS_2026-07-19.md` for the inaugural run
(10 PASS, 2 xfailed: SDK-BUG-1 + BACKEND-BUG-1).

### Full SDK parity harness (`proxy-testing --sdk`)

For the **full** 92-scenario parity run, the `proxy-testing/` harness has a
`--sdk` mode that re-runs its entire scenario matrix through the real
`trinitite` SDK instead of the raw REST adapters. Two layers: Layer 2 (foreground
parity — `sdk_shim/mappers/*.py` dispatches to `tr.<foreground>.<method>(**kw)`)
+ Layer 1 (transport parity — unmapped actions route through the real
`trinitite._client.TrinititeClient` transport). The composite LLM track routes
through the SDK transport via the `sdk_proxy_chat_completions` interceptor.

```bash
# Install the SDK into the proxy-testing venv (editable):
( cd sdk/python && pip install -e '.' )

# Run the full 92-scenario matrix through the SDK:
cd proxy-testing
ANTHROPIC_API_KEY=dummy python run_matrix.py --sdk --json results_sdk_parity.json -v
```

Findings are recorded in
`proxy-testing/docs/RUN_RESULTS_sdk_parity_2026-07-20.md` (8 batches, ~259
Layer 2 entries, 5 SDK bugs caught: SDK-BUG-1 through SDK-BUG-5). See the
`--sdk` mode section in `proxy-testing/README.md` for the full guide.

[FEATURE] Origin: live SDK smoke harness, 2026-07-16 (chat thread: test that the
SDK works against the live backend like proxy-testing does).
