Compatibility
SDK releases and Engine deployments evolve independently. Compatibility is governed by one explicit, machine-checked contract instead of by hope.
The Engine contract
The Engine publishes a SemVer contract version in its discovery document. Each SDK release accepts a pinned range — SDK 0.7.3 accepts:
>=1.3.1 <2.0.0
On first use the client fetches discovery and uses the one model the Engine
endpoint reports. It fails fast with EngineCompatibilityError when the
contract or the model's capabilities are not supported, or when discovery
lists no model or several models: an Engine endpoint serves exactly one
model, and the SDK never asks it for a particular one. That error always
means: upgrade the SDK or change the Engine deployment — it is never
transient.
Pre-release contract versions are rejected by default and require the
explicit allowPrereleaseContract / allow_prerelease_contract opt-in.
The client also checks attribution_convention. SDK 0.7.3 requires
emitted, which guarantees that every streamed row explains the token carried
by that row; a deployment configured for next-token rows is rejected before
generation instead of producing shifted word mappings.
Tokenizer identity
The contract makes the SDK the owner of tokenization and tool-call parsing. For that to be sound, both sides must use the exact same tokenizer.
The Engine supplies the locator and the expected identity: the Hugging Face
repository, an immutable commit revision, and a SHA-256 fingerprint. The SDK
loads exactly that revision and accepts it only after the fingerprint it
computes locally matches. A missing, mutable, or mismatching identity is
rejected before any token ids are sent, rather than silently producing
misaligned attributions. Because the identity comes from discovery, a new
model or tokenizer revision on the Engine needs no SDK upgrade. A tokenizer
you supply through createClientWithTokenizer /
create_client_with_tokenizer must report the same identity.
Model capabilities
The SDK does not keep a list of supported models. It checks only what
changes its behavior: the tokenizer must have a chat template, discovery
must report EOS and special token ids, and the Engine's recommended tool
parser must be one the SDK implements (SUPPORTED_TOOL_PARSERS):
qwen_json_tool_call (JSON inside <tool_call>, Qwen2.5/Qwen3/QwQ) or
qwen_xml_tool_call (XML per parameter, Qwen3.5 and later). A model without a recommended tool parser streams
text completions; requests with tools are rejected for it.
Deprecation notices
The Engine can announce upcoming changes per model. The SDK surfaces every
notice exactly once per client, including its severity, effective date, and
migration URL, through the overridable warn hook. Treat warnings as a
scheduled migration task, not as noise to suppress.
Versioned documentation
This site is generated from the SDK sources of each release; use the version dropdown in the navigation bar to read the documentation matching the SDK version you have pinned. The central version and contract range live in one release manifest that all published packages are synchronized from.