Versioning & stability
Every Convilyn SDK follows Semantic Versioning. This page is the contract: what counts as the public surface, what's stable vs beta, and how deprecations are handled — so you can pin and upgrade with confidence.
The SemVer contract = the package's public exports
The SemVer promise covers exactly the names exported from each package root — nothing more. For each SDK that means:
| SDK | The covered surface |
|---|---|
| Python | convilyn.__all__ / convilyn_author.__all__ + the CLI + the auth / manifest wire shapes |
| TypeScript (pre-release) | the names exported from the package root + the VERSION constant |
| Go (coming soon) | the exported identifiers of the module's root package |
Anything not exported there — the HTTP transport, the auth strategy, parsers,
the concrete WebSocket adapter — is internal and may change in any release.
The packaging enforces this: Python keeps internals under _internal/, the
TypeScript package.json exports map blocks deep imports, and a packaging test
in each SDK pins the public surface so it cannot grow by accident.
Release status per language
Python is the supported SDK. The packages currently ship as beta
pre-releases (convilyn on the 1.2.x line, convilyn-author on 2.1.x),
so pip installs them only with --pre. The exported public surface is stable
and covered by the SemVer promise above; the beta tag reflects that a few newer
surfaces (see below) are still settling. Pin an exact version in production and
read the CHANGELOG before bumping.
TypeScript is a pre-release. The SDKs are on npm at pre-1.0 (0.x), which
under SemVer means the surface may change in any release — the promise above
starts applying at 1.0. They are installable and their reference pages are
accurate, so they are a fine way to try the shape of the API; they are not the
path to build a product on yet. Pin exact versions if you use them.
Go is coming soon — no public release.
Stable vs beta endpoints
The wire contract tags each surface with a stability tier:
| Tier | Promise |
|---|---|
| stable | Shape is frozen; a breaking change ships only after a ≥ 6-month deprecation notice. |
| beta | Wired and usable, but the shape may still evolve within a minor SDK release. |
The live WebSocket goal-event stream is the headline beta surface today — it's
implemented in every SDK but gated on a backend dependency (the gateway does not
yet accept ck_ keys for the stream). Prefer polling with goals.wait until that
lands.
What's deliberately not in the SDK contract
Some platform endpoints are intentionally excluded from the SDK surface — they're internal, admin, or auth-flow concerns, not data-plane operations:
/api/v1/chat/*and/api/v1/user_workflows/*(console-internal)/api/v1/admin/*- OAuth / OIDC sign-in flows and notification plumbing
Need one of these? Use the convilyn CLI's api escape hatch or call the
endpoint directly — but know it carries no stability promise.
Deprecation policy
When a stable name must change, the old name keeps working for the full notice
window and emits a deprecation warning pointing at the replacement. Each SDK
maintains a deprecation register in its STABILITY doc listing the name, the
version it was deprecated in, and the version it will be removed in.