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/runtime	Focused generation, media, middleware, agent, and runtime helpers.
@zhivex-ai/sdk/workflows	Focused declarative workflow and state-service surface.
@zhivex-ai/sdk/ui	UI message parsing, serialization, and streaming response helpers.
@zhivex-ai/sdk/evals	Comparative model, agent, workflow, and provider-evidence evaluation contracts.
@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; local InMemory/SQLite persistence and application-owned catalogs; Meta Standard portable support; workflow graphs, stores, leases, migration, resume/fork/cancel; MCP, Gateway, core errors, HTTP, and SSE helpers.	Hosted tools, packaged skills, native media clients, native subagents, evaluation experiments, named external workflow-engine factories, 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 kept those Stable contracts while adding focused public entrypoints and explicit Beta capability profiles. Versions 1.8 through 1.13 add focused SDK entrypoints, Beta comparative model evaluation, an opt-in Beta model resolver, fail-closed provider tool-call diagnostics, current GLM/Qwen/Gemini/xAI/DeepSeek contracts, Beta provider-conformance evidence, and expanded Anthropic authentication without removing the package roots.

Python 0.19 promotes the narrow create_meta() Standard portable contract to Stable and introduces focused namespaces for new optional surfaces. Python 0.20 promotes the durable workflow core and checkpoint migration helpers to Stable while leaving named external-engine adapters Beta. Versions 0.21 and 0.22 keep the Gateway surface Stable while adding fail-closed per-model pricing, catalog-driven routing evidence, and deterministic terminal attempt telemetry.

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.

Upgrade to TypeScript 1.22

Update SDK to 1.22.0, Core to 1.19.1, Agents to 1.8.0, and the coordinated provider versions. React 0.6.0 is independently versioned. Gateway remains 1.3.0.

Existing public exports, persistence schemas, key formats, leases and approval contracts remain compatible. Core adds focused agent, generation, provider-helper and catalog entrypoints; use documented public exports instead of internal paths. The legacy Core model catalog remains frozen. Core 1.19.1 fixes regex backtracking in subagent tool-name generation for long underscore sequences.

Adopt media capability checks, execution panels and realtime voice explicitly. Verify attachment validation on the server, resumed approval rendering and the relay’s authentication/Origin boundary. Realtime interruption is optional and provider-dependent; Qwen implements cancellation. See React integration and multimodal.

Upgrade to TypeScript 1.21

The release history covers every release from 1.15 through 1.21. Review tool-history fallback and Vertex Claude configuration (1.15), stream cancellation and persisted compaction accounting (1.16), opt-in schema and unknown-tool recovery (1.17–1.18), and GPT-Live server sessions (1.19).

For 1.20, update exhaustive group-status handling for pending and cancelled members and reconcile legacy shared idempotency keys before replay. Adaptive routing, circuit breaking, and cost accounting require explicit adoption. React is versioned independently; use the release notes to select its matching integration features.

For 1.21, status: "completed" describes the agent loop, while optional taskOutcome distinguishes unresolved external effects. Historical states may omit this field. Adopt the Beta reconciliation API only with verified external evidence and supported stores; see agents and sessions. OpenAI and Anthropic native managed agents are separate Beta provider resources.

Upgrade to Python 0.25

Python 0.25.0 is published on PyPI. The versioned guides and wheel reference document the installable artifact; the 0.23.0 and 0.24.0 snapshots remain available for historical integrations.

InMemory/SQLite run, memory and checkpoint stores, AgentMemoryState, SummaryConfig, application-owned catalogs and their capability/pricing metadata are now Stable. InMemory remains process-local and SQLite single-host. Existing calls and persisted formats remain compatible. default_model_catalog, discovery, middleware, audio, CLI and the distribution remain Beta.

Install zhivex-ai-sdk[realtime] for the default WebSocket transport, which is now optional. Realtime remains Experimental. Durable approvals revalidate persisted Pydantic inputs on resume. Certification must match the exact wheel and source; a prior release’s evidence does not certify this release.

The accompanying dependency updates raise adapter runtime floors: @zhivex-ai/bedrock@2.0.0 requires Node.js 20+, and @zhivex-ai/vertex@1.0.0 requires Node.js 22+. Other packages retain their runtime requirements. MCP output schemas now enforce uniqueItems, property-count, and contains constraints; revalidate schemas previously accepted by older dependencies.

Python 0.25 adds Qwen3.8-Omni-Flash multimodal input, Beta OpenAI managed sessions and Anthropic compaction, and Experimental GPT-Live. Review the provider updates before adopting native features.