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 |
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, and the consumer package is a final release.
convilyn ships on the 3.x line, so pip install convilyn needs no
--pre. The author and edge packages are still on beta lines
(convilyn-author, convilyn-edge), and those two do need --pre. The
exported public surface is covered by the SemVer promise above; pin an exact
version in production and read the CHANGELOG before bumping.
The SDKs are Python. If you work in another language, call the REST API directly — it is the same surface the SDKs wrap, and it carries the same stability promise.
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.