@zhivex-ai/sdk

Recommended entry point for Zhivex AI SDK. Re-exports the high-level public API for agents, sessions, text generation, streaming, structured output, tools, multimodal messages, embeddings, workflows, artifacts, and local CLI utilities.

Provider conformance reporting is available as a Beta surface from both the root package and @zhivex-ai/sdk/evals. Reports keep declared, offline, installed, and live evidence separate; skipped credentials do not certify support.

Install

bun add @zhivex-ai/sdk @zhivex-ai/openai

Install only the provider packages your application uses. Install @zhivex-ai/sdk from the npm latest tag, or pin an exact version. The next dist-tag can lag latest, so it does not track the newest stable release. Use a provider prerelease only when that provider was published in the same prerelease and the tag is newer than latest.

Quick Start

import { generateText } from "@zhivex-ai/sdk";
import { createOpenAI } from "@zhivex-ai/openai";

const openai = createOpenAI({
  apiKey: process.env.OPENAI_API_KEY
});

const result = await generateText({
  model: openai("gpt-4o-mini"),
  prompt: "Explain the unified SDK in one sentence."
});

console.log(result.text);

Use provider-backed models from Bun, Node.js, route handlers, workers, or other server runtimes. Keep provider credentials and effectful tools out of browser bundles.

Focused entrypoints are available for smaller and more explicit imports:

• @zhivex-ai/sdk/runtime for generation and runtime helpers
• @zhivex-ai/sdk/workflows for declarative workflows and state services
• @zhivex-ai/sdk/ui for UI message and SSE contracts
• @zhivex-ai/sdk/mcp-http for opt-in Stable MCP HTTP transport and OAuth with host-owned token storage
• @zhivex-ai/sdk/mcp-stdio for the opt-in Experimental Node/Bun stdio transport. Browser bundles resolve a stub that throws instead of spawning a process
• @zhivex-ai/sdk/mcp-server for the opt-in Experimental MCP server that exposes local tools and agents. @zhivex-ai/sdk/mcp-server-stdio binds it to process stdio; browser bundles resolve a stub that throws
• @zhivex-ai/sdk/a2a for the opt-in Experimental Agent2Agent 1.0 server and client. Browser bundles keep the client and throw from the server factory
• @zhivex-ai/sdk/evals for agent, workflow, and Beta comparative model evaluations
• @zhivex-ai/agents for the dedicated agent-first facade

The release-managed default model inventory is available from the SDK root or @zhivex-ai/sdk/catalog. @zhivex-ai/core keeps catalog contracts and the createModelCatalog mechanism plus a deprecated, frozen compatibility snapshot until the next major. Later inventory updates are shipped only by the SDK, so new applications should not import the core compatibility copy. Inject an application-owned catalog when model availability or pricing must be pinned independently from SDK releases.

The local zhivex-ai agents ledger command omits full output text by default; use --include-output-text only for a reviewed local export. zhivex-ai init agent creates a private .env with mode 0600 on POSIX systems, and doctor reports unsafe environment-file permissions.

Stability

The shared realtime session and streamLiveAgent lifecycle is Stable. Provider model IDs, provider-specific options, and upstream preview availability remain provider-scoped. The root export also contains Beta and Experimental surfaces; new code can make that risk explicit with @zhivex-ai/sdk/beta and @zhivex-ai/sdk/experimental. Existing root imports remain compatible. Check runtime symbols with getApiStability() and review https://github.com/Zhivex/zhivex-ai-sdk/blob/main/STABILITY.md before upgrading.

Start Here

• Quickstart: https://github.com/Zhivex/zhivex-ai-sdk/blob/main/docs/QUICKSTART.md
• Agents guide: https://github.com/Zhivex/zhivex-ai-sdk/blob/main/docs/AGENTS.md
• Next.js guide: https://github.com/Zhivex/zhivex-ai-sdk/blob/main/docs/NEXTJS.md
• Production guide: https://github.com/Zhivex/zhivex-ai-sdk/blob/main/docs/PRODUCTION.md
• Workflows guide: https://github.com/Zhivex/zhivex-ai-sdk/blob/main/docs/WORKFLOWS.md
• Artifact Service: https://github.com/Zhivex/zhivex-ai-sdk/blob/main/docs/ARTIFACTS.md
• Model Catalog: https://github.com/Zhivex/zhivex-ai-sdk/blob/main/docs/MODEL_CATALOG.md
• Optional Model Resolver: https://github.com/Zhivex/zhivex-ai-sdk/blob/main/docs/MODEL_RESOLVER.md
• Comparative model evaluations: https://github.com/Zhivex/zhivex-ai-sdk/blob/main/docs/MODEL_EVALUATIONS.md
• CLI contract: https://github.com/Zhivex/zhivex-ai-sdk/blob/main/docs/CLI.md
• Observability guide: https://github.com/Zhivex/zhivex-ai-sdk/blob/main/docs/OBSERVABILITY.md

Repository and full documentation:

• https://github.com/Zhivex/zhivex-ai-sdk

Reliable streaming

For long responses, opt into bounded tail replay:

const stream = streamText({
  model,
  prompt: "Explain the design in detail.",
  streamBuffer: { maxHistory: 4096, replayOverflow: "drop-oldest" }
});
for await (const text of stream.textStream) process.stdout.write(text);
const result = await stream.collect(); // Rejects on provider failure.

Import streamText from @zhivex-ai/sdk; model is your provider-backed model. Active consumers receive ordered events; late subscribers receive only the retained tail. The default replayOverflow: "error" preserves full replay and fails beyond 4,096 retained events. collect() returns the complete result in either mode. The same streamBuffer options apply to object generation and agents. maxSteps must be a positive safe integer and defaults to one.