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.4.0 accepts:

>=1.2.0 <2.0.0

On first use the client fetches discovery, selects a model whose contract this release supports, and fails fast with EngineCompatibilityError when there is none. That error always means: upgrade the SDK or 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.4.0 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, so the SDK verifies the release-pinned tokenizer's identity — repository, revision, and fingerprint — against what the Engine declares, and refuses to run on a mismatch rather than silently producing misaligned attributions.

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.