Skip to main content

Get started

Put one governed model call on the wire. You will get a clear result that your app can use right away.

Status: Beta · Python 0.0.3 · TypeScript 0.0.3 Companion docs: Authentication · Language compatibility · Result

1. Install​

Pick your language:

pip install trinitite==0.0.3
npm install @trinitite/sdk@0.0.3

Terminal running.

The example ends with an explicit verdict and a govern receipt ID.

2. Choose an environment​

Set TRINITITE_API_KEY. The key prefix must match the environment:

export TRINITITE_API_KEY="trnt_test_..."
export TRINITITE_ENV="test"

Environment keyring

The key prefix must match the environment

Key prefix
trnt_test_...
Use
Forced verdicts and CI

prod is the default. A mismatched key and environment stops at startup with EnvironmentMismatchError. This keeps a development key from reaching the production endpoint by mistake.

Create the SDK client. The empty constructor reads the environment:

from trinitite import Trinitite

tr = Trinitite()
import { Trinitite } from "@trinitite/sdk";

const tr = new Trinitite();

Python calls use snake case. TypeScript calls use camel case and promises.

3. Make the call​

Use the provider and model you already chose. The wrapped call returns a response. Turn that response into a GovernanceResult with tr.result(...).

response = tr.client(
    "openai",
    credential="cred_openai_prod",
).chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Refund order 4821."}],
)

result = tr.result(response)
const response = await tr.client("openai", {
  credential: "cred_openai_prod",
}).chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Refund order 4821." }],
});

const result = tr.result(response);

Guarded request route

Current step: dlir_ receipt. Records the decision.

  1. 1Your codeThe request you already make
  2. 2SDKRoutes the call
  3. 3GuardianChecks the request
  4. 4Model or toolHandles the allowed call
  5. 5Result: passedNames the outcome
  6. 6dlir_ receiptRecords the decision

You can call tr.govern(...) first when you want to set a baseline. In TypeScript, await it:

await tr.govern({ frameworks: ["soc2"], mode: "enforce" });

The wrapped client accepts provider request fields, but it returns a fully materialized response. This guide does not treat provider token streaming as a supported response contract.

4. Read the result​

Branch on the lowercase wire verdict:

if result.verdict == "passed":
    print(result.body)
elif result.verdict == "corrected":
    print(result.diff)
elif result.verdict == "blocked":
    show_safe_fallback()
elif result.verdict == "masked":
    keep_tokens_outside_the_trust_boundary()
elif result.verdict == "hitl":
    queue_for_review()
else:  # failed
    follow_error_policy()
First result
GovernanceResult
passed
verdict
passed
violations
[]
receipt
dlir_01J7FIRSTCALL

The verdict drives the app path. The receipt records the decision.

Fields such as risk, flow_id, and receipt are optional. Check them before use. A receipt is a handle, not a receipt_id field on every result:

if result.receipt and result.receipt.get("id"):
    verification = result.receipt.verify()

TypeScript uses optional chaining and awaits follow-up network calls:

const receiptId = result.receipt?.get("id");
const verification = result.receipt
  ? await result.receipt.verify()
  : null;

For the structured trace, call the method:

trace_response = result.explain()
const traceResponse = await result.explain();

5. Test every branch​

force_verdict is a development and test control on wrapped calls. The SDK rejects it in prod before network I/O.

test_tr = Trinitite(env="test")

response = test_tr.client("openai").chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Test the blocked path."}],
    force_verdict="blocked",
)
result = test_tr.result(response)

Verdict test bench

Choose a synthetic verdict to exercise that Result branch with a trnt_test_ key.

Selected verdict: Blocked

The request did not pass the check.

Handle the blocked branch in your app.

Result {
  verdict: "blocked"
  forced: true
  output
  diff
  violations
  compliance
  risk
  receipt_id: "dlir_…"
}
Test keySynthetic Result, no billing
Live keyForcedVerdictInProdError, request refused
Keep test controls out of production

A production client raises ForcedVerdictInProdError when a wrapped call sets force_verdict. Test mode does not bypass authentication, permissions, or server-side capability checks.

Where to go next​

Last updated on