Choose and configure a provider

Install the SDK once, then add only the provider adapters your application uses. Provider factories create model instances; generation, tools, agents, and workflows consume the shared model contract.

TypeScript adapters

bun add @zhivex-ai/sdk @zhivex-ai/openai
bun add @zhivex-ai/anthropic
bun add @zhivex-ai/gemini
bun add @zhivex-ai/openrouter
bun add @zhivex-ai/ollama

import { createOpenAI } from "@zhivex-ai/openai";
import { createAnthropic } from "@zhivex-ai/anthropic";
import { createGemini } from "@zhivex-ai/gemini";

const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });
const anthropic = createAnthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
const gemini = createGemini({ apiKey: process.env.GEMINI_API_KEY });

const model = openai("gpt-4o-mini");

The TypeScript packages also include Azure OpenAI, xAI, Meta, Vertex, Qwen, Kimi, DeepSeek, Z.AI, OpenRouter, Bedrock, Ollama, and a policy-based Gateway.

Python factories

The Python package exposes providers from the public zhivex_ai namespace:

from zhivex_ai import create_anthropic, create_gemini, create_openai

openai = create_openai()
anthropic = create_anthropic()
gemini = create_gemini()

Hosted-provider credentials are read from server environment variables unless explicitly passed to the factory.

Adapter availability

This is an adapter map, not a promise that every model supports every feature:

Provider	TypeScript	Python
OpenAI	@zhivex-ai/openai	create_openai()
Azure OpenAI	@zhivex-ai/azure-openai	create_azure_openai()
Anthropic	@zhivex-ai/anthropic	create_anthropic()
Gemini	@zhivex-ai/gemini	create_gemini()
Vertex AI	@zhivex-ai/vertex	create_vertex()
Qwen	@zhivex-ai/qwen	create_qwen()
Kimi / Moonshot	@zhivex-ai/kimi	create_kimi()
DeepSeek	@zhivex-ai/deepseek	create_deepseek()
vLLM	—	create_vllm()
xAI	@zhivex-ai/xai	—
Meta	@zhivex-ai/meta	—
Z.AI	@zhivex-ai/zai	—
Bedrock	@zhivex-ai/bedrock	create_bedrock() — experimental
Ollama	@zhivex-ai/ollama	create_ollama() — experimental
OpenRouter	@zhivex-ai/openrouter	create_openrouter() — experimental

An em dash means that the SDK does not document a corresponding public adapter. Do not substitute an undocumented deep import.

Compare capability surfaces

Surface	TypeScript shared contract	Python shared contract
Text and streaming	Stable	Stable
Structured output	Stable; enforcement depends on provider/model	Stable; enforcement depends on provider/model
Portable local tools	Stable	Stable
Embeddings	Stable	Stable
Audio and generative media	Stable high-level APIs; provider/model dependent	Native media clients are beta; provider/model dependent
Hosted tools and remote MCP	Mixed stable/experimental provider surfaces	Beta provider-data and hosted-tool surfaces
Realtime/live agents	Stable shared lifecycle; provider/model dependent	Experimental

Use the selected model’s runtime capabilities for a real decision. A provider name alone is too coarse: API mode, model family, region, deployment, and account access can all change the available surface. The Stable TypeScript realtime contract covers OpenAI, Azure OpenAI, Gemini, Vertex, and Qwen adapters, but it does not make any provider preview model permanently available.

TypeScript can render a matrix from the actual configured models:

import {
  createProviderSupportMatrix,
  renderProviderSupportMatrix
} from "@zhivex-ai/sdk";

const matrix = createProviderSupportMatrix([
  openai("gpt-4o-mini"),
  anthropic("claude-sonnet-4-5")
]);

console.log(renderProviderSupportMatrix(matrix));

Python exposes the selected model’s agent capability metadata:

from zhivex_ai import get_agent_capabilities, get_agent_support_tier

model = create_openai()(model_id)
capabilities = get_agent_capabilities(model)

print(get_agent_support_tier(model))
print(capabilities.remote_mcp, capabilities.hosted_web_search)

The TypeScript matrix helpers are stable. TypeScript 1.7 also introduces Beta discriminated capability profiles for provider authors who must distinguish native, prompted, model-dependent, and unsupported behavior while deriving the existing boolean capability shape. Python capability metadata is beta, so pin and review minor-version upgrades when automating policy from either Beta contract.

Pin model-catalog decisions

createModelCatalog() and defaultModelCatalog are Stable contracts for provider-scoped identity, aliases, recommendations, and optional versioned pricing metadata. TypeScript 1.7 moves ownership of the release-managed default inventory to the SDK:

import { defaultModelCatalog } from "@zhivex-ai/sdk/catalog";

const model = defaultModelCatalog.find("openai", "gpt-5.6-luna");

Import the default from @zhivex-ai/sdk or @zhivex-ai/sdk/catalog when you want future inventory updates. The deprecated @zhivex-ai/core copy is a frozen compatibility snapshot until the next major; createModelCatalog() remains available for application-owned data. A catalog snapshot is routing metadata, not authenticated capability or billing evidence.

Custom catalogs default to pinned data. Record the SDK version, catalog snapshot and pricing version with a run when reproducibility matters. Treat the built-in catalog as rolling only at package-release boundaries, and verify provider availability, entitlement, region, preview status, and current pricing before live routing or charging users.

Portable first, native when needed

Use the portable surface for messages, generation, streaming, structured output, tools, and normalized usage. Reach for a provider-native namespace or providerOptions only when the feature has no portable equivalent.

Keep that native code behind your own adapter so the rest of the product remains movable.

Capability checks matter

A published provider package does not imply identical support for every model or feature. Before shipping:

1. choose a model that advertises the required capability;
2. check the current provider matrix and stability level;
3. handle unsupported features explicitly;
4. run an authenticated smoke for the exact provider, model, operation, and release candidate you will deploy.

Offline tests establish contract behavior; they do not prove that credentials, quota, regional availability, or an upstream preview is working in production.

Keep four different statements separate:

• the adapter accepts a model id;
• the model advertises a capability in the SDK contract;
• deterministic tests cover request/response mapping;
• an authenticated smoke passed for the exact provider, model, operation, artifact, and commit.

Full provider references

• TypeScript provider packages
• TypeScript support contract
• Python provider guide
• Python parity matrix

Continue with Gateway routing, MCP and hosted tools, or multimodal features after choosing the portable provider boundary.