Stability and upgrades

Zhivex classifies public surfaces as Stable, Beta, or Experimental. The labels apply to individual APIs, not automatically to every capability in a package or provider.

Level	Compatibility expectation	Adoption guidance
Stable	Supported public contract; meaningful behavior changes require release communication.	Appropriate for production with normal integration tests.
Beta	Documented and supported for early adoption, but may change between minor releases.	Put behind an application-owned abstraction and review every upgrade.
Experimental	Evaluation surface without a long-term compatibility guarantee.	Isolate aggressively and expect redesign or removal.

Language boundaries

The two SDKs are at different release boundaries.

Area	TypeScript	Python
Package release stance	Stable packages are published on latest; next is for prerelease validation.	The package is still published as Beta, while a documented subset of top-level APIs is Stable.
Primary public import	Published @zhivex-ai/* package entrypoints; use @zhivex-ai/sdk for most applications.	Top-level imports from zhivex_ai.
Machine-readable contract	API_STABILITY_MANIFEST, getApiStability(), and listApiStability().	Repository manifest in src/zhivex_ai/api_stability.py, enforced against zhivex_ai.__all__.
Version policy	Semantic package bumps coordinated with Changesets across the monorepo.	Strict compatibility policy for Stable APIs even while versions remain in the 0.x line.

Deep imports from internal source files are not part of either stable contract.

TypeScript 1.7 adds supported focused entrypoints without removing the package roots:

Entry point	Intended boundary
@zhivex-ai/core/contracts	Provider-neutral TypeScript contracts; no runtime module.
@zhivex-ai/core/runtime	Adapter, message, tool, media, retrieval, and realtime primitives.
@zhivex-ai/core/workflows	Portable workflow orchestration and evaluation contracts.
@zhivex-ai/core/ui	UI messages, request parsing, and response streams.
@zhivex-ai/core/node	Complete server surface, including file-backed stores and middleware.
@zhivex-ai/core/testing	Evaluation harnesses and deterministic test doubles.
@zhivex-ai/sdk/catalog	Release-managed default model inventory and catalog exports.
@zhivex-ai/sdk/beta	Explicit opt-in to documented Beta runtime APIs.
@zhivex-ai/sdk/experimental	Explicit opt-in to Experimental runtime APIs.

These are published package entrypoints, not deep imports. The root exports remain backward compatible.

Current high-level classification

Language	Stable examples	Beta examples	Experimental examples
TypeScript	Generation, media, portable agents, realtime, sessions, workflows and every built-in workflow state service; workflow evaluation gates; artifacts; model catalogs; OpenTelemetry adapters; CLI; Agent Control Plane; safety, replay, MCP, and Gateway contracts.	Provider-native resource helpers, file workflow-state pruning, agent telemetry event details, hosted-tool classification, and some Gateway policy ergonomics.	Provider-native hosted-tool escape hatches, advanced tool registries, and undocumented provider options.
Python	Portable generation and embeddings; the main agent runtime; tools, sessions, durable Postgres run state and approvals; MCP, Gateway, core errors, HTTP, and SSE helpers.	Hosted tools, packaged skills, native media clients, native subagents, evaluation experiments, workflow graphs and stores, A2A/AG-UI/Responses hosting, CLI, and playground.	Realtime/live voice, raw provider payload escape hatches, and compatibility/native-only create_bedrock, create_openrouter, and create_ollama factories.

This table is an adoption map, not a substitute for checking a specific symbol. Provider support also varies by model and operation; review the provider guide separately.

Inspect a TypeScript symbol

import { getApiStability, listApiStability } from "@zhivex-ai/sdk";

console.log(getApiStability("createWorkflow")?.stability);
console.log(listApiStability("beta"));

The runtime manifest covers runtime exports. Public TypeScript declaration snapshots separately guard type-only exports. An exported symbol being present does not make an undocumented deep import stable.

The Stable realtime classification applies to the shared session and live-agent lifecycle, including CallbackRealtimeSession, streamLiveAgent(), browser-safe frame encoders, and default WebSocket transport helpers. Provider model IDs, regional access, and upstream preview status remain provider-scoped and require live verification.

TypeScript 1.5 promoted SQLite/Postgres workflow state, workflow evaluation baselines and gates, and the focused @zhivex-ai/agents/control-plane contract. TypeScript 1.6 promoted the Artifact Service, Model Catalog, OpenTelemetry adapters, and zhivex-ai CLI. TypeScript 1.7 keeps those Stable contracts while adding focused public entrypoints and explicit Beta capability profiles, provider-resource dispatch, callable adapters, and abort cleanup.

The release-managed defaultModelCatalog now belongs to @zhivex-ai/sdk; the deprecated Core copy is frozen for compatibility until the next major. Stability covers the versioned SDK contract, while applications still own database operations, authorization, retention, telemetry destinations, catalog provenance, and live-provider certification.

Upgrade checklist

1. Read the release notes and linked package changelogs for every version crossed.
2. Inventory the APIs your application uses and record their stability level.
3. Remove deep imports and import only from published package entrypoints or zhivex_ai.
4. Review provider packages when shared generation, tool, streaming, or message contracts change.
5. Rebuild and run offline contract, type, and integration tests.
6. Run authenticated smokes for each production provider, model, and operation.
7. Validate durable session, agent, workflow, and artifact records against a copy of production-shaped data.
8. Deploy progressively with rollback, cost, latency, and error monitoring.

For TypeScript, a change in @zhivex-ai/core can require coordinated updates to @zhivex-ai/sdk, provider adapters, React, and Gateway packages. For Python, Beta protocol and workflow schemas may version independently from the package; reconstruct the same workflow definition and test existing checkpoints before rollout.

Deprecations and durable data

Stable APIs should follow a documented deprecation path before removal. Beta APIs can move sooner, but visible changes should still have changelog coverage.

Do not assume a package upgrade migrates application data automatically. Preserve schema versions, test old fixtures with the new reader, and fail closed on an unknown durable schema or workflow definition digest. Keep source history and lineage when an application performs its own migration.

Finally, keep these decisions separate: source compatibility, passing offline tests, authenticated provider certification, package publication, and application deployment. A green build proves only the boundary it actually exercised. Continue with errors and troubleshooting and production architecture.