Install and configure

The configured clients in this documentation are unreleased. Use this checkout to try them. The earlier registry release candidate does not contain these APIs.

Python

From the repository root:

python -m pip install "./sdk/python[openai]"

The OpenAI extra installs the provider integration. The instrumentation core has no runtime dependencies. Python 3.10 or newer is required.

TypeScript

The following commands use Node 24 to run TypeScript directly. Start at the repository root, build the package, and prepare a small backend application:

cd sdk/ts
npm ci
npm run build
npm pack
cd ../..
mkdir -p test-results/sdk-example-app
cd test-results/sdk-example-app
npm init -y
npm pkg set type=module
npm install ../../sdk/ts/tokentriage-1.0.0-rc.2.tgz [email protected]
cp ../../sdk/examples/first_request.ts first_request.ts
cd ../..

PowerShell:

Set-Location sdk/ts
npm.cmd ci
npm.cmd run build
npm.cmd pack
Set-Location ../..
New-Item -ItemType Directory -Force test-results/sdk-example-app | Out-Null
Set-Location test-results/sdk-example-app
npm.cmd init -y
npm.cmd pkg set type=module
npm.cmd install ../../sdk/ts/tokentriage-1.0.0-rc.2.tgz [email protected]
Copy-Item ../../sdk/examples/first_request.ts first_request.ts
Set-Location ../..

Both sequences return to the repository root. The installed tarball contains the local SDK; the application also has the official OpenAI package. Existing Node 22 applications can use their TypeScript compiler or runner. The instrumentation core supports Node 18 or newer.

Set your managed connection

Your TokenTriage account key belongs in X-Tokentriage-Key. Your provider key stays in its provider credential slot. The configured client supplies both at request time.

Replace these values with your assigned URL, keys and enabled model:

export TOKENTRIAGE_BASE_URL='your-assigned-gateway-url'
export TOKENTRIAGE_API_KEY='your-account-key'
export OPENAI_API_KEY='your-provider-key'
export TOKENTRIAGE_MODEL='your-enabled-model'

$env:TOKENTRIAGE_BASE_URL = 'your-assigned-gateway-url'
$env:TOKENTRIAGE_API_KEY = 'your-account-key'
$env:OPENAI_API_KEY = 'your-provider-key'
$env:TOKENTRIAGE_MODEL = 'your-enabled-model'

Keep credentials in your backend. From the repository root, run the example for your language:

python sdk/examples/first_request.py

node test-results/sdk-example-app/first_request.ts

Each prints the answer and request ID. See the first-request code and failure guidance.

Self-hosted configuration

Use your deployment’s URL, including any path prefix, and select mode="self_hosted" in Python or mode: "self_hosted" in TypeScript. Unset TOKENTRIAGE_API_KEY if your gateway does not require it. Supply the upstream credential required by your own deployment.

Verify before you spend

Onboarding may supply a health_url. A GET to that exact URL checks gateway reachability without inference. It does not verify provider credentials or models.

The legacy check() helper probes an admin endpoint. It is useful for self-hosted administration and is not required for a managed first request.