SDKs

SDKs

A TypeScript package, a Python package and the dm1 command line tool. Your labels become your result types.

Three clients call decision-machine-1. They share one idea: the names you pass in come back as the types you read.

npm i @cloudraker/milliseconds     # pnpm add, bun add, yarn add
export MS_API_KEY=test_sk-...

Both packages are at version 0.1.0. Get a key in the console. Both clients read MS_API_KEY from the environment.

Your labels become types

You describe a decision in your own vocabulary. You pass label names, statements, scale levels, entity types or a JSON Schema. The SDK carries those names into the result type. In TypeScript, r.label is the union of the label names you passed, so a typo is a compile error. In Python, one annotation on your constant solves the same TypeVar, so r.label is your Literal and a match over it is exhaustive. No code generator can do this, because the names live in your call, not in the API spec. Both packages are therefore hand written.

TypeScript

Inferred unions, tuple batching, extraction from a schema literal, zod and arktype.

Python

Sync and async clients, annotated constants, TypedDict and pydantic extraction.

dm1 CLI

Every capability from a shell. Tables, JSON, JSONL and exit codes.

What the SDK changes

The SDK keeps the wire. It unwraps three envelopes, merges two mutually exclusive body keys into one argument, and moves the headers off the result.

WireSDKWhy
{ "results": [...] }a plain array or listone envelope less. The order is already guaranteed.
{ "entities": [...] }a plain array or listthe same
{ "data": {...} }the object itselfthe same
text / textsone positional inputthe mutual exclusion becomes impossible
statement / statementsone positional argumentthe same
question / questionsone positional argumentthe same
x-* headerswithUsage() in TypeScript, .usage in Pythonthe headers stay reachable, the results stay clean

Every other field keeps its exact wire name, snake_case included: when_true, input_chars, inference_ms, probability, scores, start, end.

What the SDK adds

  • Argument checks before the call. Label, statement, scale and text limits fail locally. Nothing is sent, so nothing is billed.
  • Retries on the right failures. 429 rate_limit_exceeded, 502 runner_error, 529 overloaded, and transport failures and timeouts. Every capability is a pure function, so a retry is always safe.
  • One error type. Catch by class in Python, switch on code in TypeScript.
  • An escape hatch. post() sends an untouched body to any path, including a path shipped after the package.

What the SDK never does

It never chunks a batch for you. Chunking costs money and changes failure modes, so the caller decides. The limits stay the API limits: 32 texts per call, 20,000 characters per text. See Batching and Limits. The dm1 --lines flag chunks, and says so.

It never estimates a price. It reports x-input-tokens. See Pricing.