Skip to main content
Version: 0.7.3

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.