> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokz.si/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript SDK

> @tokz/sdk — typed decisions about text over HTTP, and your fine tunes on your own machine.

```bash theme={null}
npm install @tokz/sdk
```

Works in Node 20+, Bun, and Deno, with no dependencies. Only `decideLocal` needs more: it
runs on Node.js and takes two more packages.

## `new Tokz(options)`

```ts theme={null}
import { Tokz } from "@tokz/sdk";

const tokz = new Tokz({
  apiKey: process.env.TOKZ_API_KEY!,
  baseUrl: "https://api.tokz.si", // optional
});
```

**apiKey** `string` *required*

Your key, `tokz_live_<id>_<secret>`.

**baseUrl** `string` (default: [https://api.tokz.si](https://api.tokz.si))

Override for a private endpoint or local development.

**fetch** `function` (default: globalThis.fetch)

Inject your own `fetch` for proxies, instrumentation, or tests.

## `tokz.decide(request, options?)`

Typed decisions about text with the OpenDecision models. See [Decisions API](https://docs.tokz.si/decisions.md).

```ts theme={null}
import { Tokz } from "@tokz/sdk";

const tokz = new Tokz({ apiKey: process.env.TOKZ_API_KEY! });

const out = await tokz.decide({
  inputs: ["I was charged twice.", "How do I export my data?"],
  decisions: {
    queue: { type: "choice", options: ["billing", "technical", "account"] },
    urgent: { type: "bool" },
  },
  model: "opendecision-small", // optional; the default is opendecision-large-packed
});

for (const r of out.results) console.log(r.queue.best, r.urgent.best);
console.log(out.usage.billed_tokens, out.usage.cost_usd);
```

```ts no-check theme={null}
decide(request: { inputs: string | string[]; decisions: Record<string, Decision>; model?: string },
       options?: { signal?: AbortSignal; timeout?: number }): Promise<DecideResponse>
```

`timeout` defaults to 60000 ms. `decide` is never retried, because a retry could bill twice.

## `tokz.decide(model, inputs, options?)`

Calls a [fine tune](https://docs.tokz.si/fine-tune.md) on our servers by name. Needs 0.7+.

```ts theme={null}
import { Tokz } from "@tokz/sdk";

const tokz = new Tokz({ apiKey: process.env.TOKZ_API_KEY! });

const { results, usage } = await tokz.decide("support-triage", ["I was charged twice.", "How do I export my data?"]);

for (const r of results) console.log(r.decision.best, r.decision.selected);
console.log(usage.billed_tokens);
```

```ts no-check theme={null}
decide(model: string, inputs: string | string[],
       options?: { signal?: AbortSignal; timeout?: number }): Promise<FineTuneResponse>
```

Up to 16 texts. The answer is always under `decision`. For a multi-label model read `selected`,
because `best` names a label even when `selected` is empty.

## `tokz.decideLocal(model, inputs, options?)`

The same model and the same result shape, run on this machine for free. Needs 0.7+ and two
more packages, about 320 MB on Linux. The flag skips a GPU library it does not use.

```bash theme={null}
npm i onnxruntime-node@1.26.0 tokenizers@0.23.2 --onnxruntime-node-install=skip
```

```ts theme={null}
import { Tokz } from "@tokz/sdk";

const tokz = new Tokz({ apiKey: process.env.TOKZ_API_KEY! });

const { results } = await tokz.decideLocal("support-triage", "I was charged twice.");
console.log(results[0].decision.best);
```

```ts no-check theme={null}
decideLocal(model: string, inputs: string | string[],
            options?: { signal?: AbortSignal }): Promise<FineTuneResponse>
```

The first call downloads the model into `~/.cache/tokz` and verifies its hashes. `TOKZ_CACHE_DIR`
moves the cache. After that it works offline, and asks the server about once an hour whether the
model still exists. See [Fine Tune](https://docs.tokz.si/fine-tune.md#run-it-on-your-machine). A bundler cannot see these
two packages, so name them yourself if a tool such as Next's standalone output copies only what
it traces.

## `tokz.listDecisionModels(signal?)`

The public model catalog, prices and request limits (`GET /v1/decide/models`). No key
is sent.

## `tokz.health()`

Resolves `{ ok, latency }` and never throws, so it is safe in a readiness probe.

## Errors

| Class | When |
| - | - |
| `TokzError` | Any failure; `.status` carries the HTTP status when there was one, `.retryAfter` the seconds from `Retry-After` |
| `TokzInsufficientCreditsError` | HTTP 402; `.balanceCents` carries the reported balance |

```ts theme={null}
import { Tokz, TokzError, TokzInsufficientCreditsError } from "@tokz/sdk";

const tokz = new Tokz({ apiKey: process.env.TOKZ_API_KEY! });

try {
  await tokz.decide({ inputs: "charged twice", decisions: { urgent: { type: "bool" } } });
} catch (err) {
  if (err instanceof TokzInsufficientCreditsError) console.warn("out of credit", err.balanceCents);
  else if (err instanceof TokzError) console.error(err.status, err.message);
  else throw err;
}
```

Using Python? The [Python SDK](https://docs.tokz.si/sdk/python.md) has the same methods and errors.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.