dbx-tools-model

Python contracts and runtime helpers for Databricks Model Serving. This package mirrors the reusable parts of @dbx-tools/shared-model and @dbx-tools/model without AppKit cache or Mastra dependencies.

Install from PyPI:

pip install dbx-tools-model

To install the current main branch directly from the repository instead:

pip install "dbx-tools-model @ git+https://github.com/reggie-db/dbx-tools.git@main#subdirectory=packages/py/model"

Key features:

• stable Pydantic endpoint, profile, query, and ranked-result models;
• live endpoint listing through a structural WorkspaceClient protocol;
• canonical first-party service model names exposed through a typed serviceNames map on library endpoint results;
• score-driven model classification with family fallbacks;
• reasoning-effort levels inferred from Databricks served-entity identity, with endpoint-family fallback for summaries that omit it;
• daily retirement-status discovery from the Databricks policy page, with a disk and memory cache plus a generated fallback, so endpoint listing excludes deprecated models even when the serving API reports them as ready;
• flexible family, version, and model parsing shared by classification, reasoning, sorting, and downstream integrations;
• exact and fuzzy endpoint resolution with deterministic class ordering;
• Databricks invocation URL and process-serialized per-request authentication helpers, so concurrent SDK refreshes converge;
• shared Responses-only endpoint policy, including Codex and GPT 5.4+ while excluding GPT-OSS;
• OpenAI chat request sanitization, assistant-prefill repair, and content extraction;
• embedding vector extraction with optional dimension validation.

from databricks.sdk import WorkspaceClient
from dbx_tools.model import ModelClass, list_serving_endpoints, resolve_model

endpoints = list_serving_endpoints(WorkspaceClient())
selection = resolve_model(endpoints, model_class=ModelClass.CHAT_BALANCED)
print(selection.model_id)
print(endpoints[0].service_names)
print(
    next(
        endpoint.reasoning_efforts for endpoint in endpoints if endpoint.name == selection.model_id
    )
)

The Python port intentionally omits AppKit CacheManager integration, Mastra-specific adapters, and browser-only schemas. Callers can cache the plain Pydantic results with their preferred Python cache.

Endpoint listing excludes deprecated models by default. Pass include_deprecated=True to include them alongside current endpoints. ModelQuery.include_deprecated defaults to False and applies the same behavior during model lookup through the includeDeprecated wire field. Every endpoint carries a status: ModelStatus field. model_status.get() resolves that dataclass from all known endpoint identities so additional status fields can be added in one place.

Model-name parsing produces provider-neutral components without maintaining a second family registry:

from dbx_tools.model.models import parse_model_name

parsed = parse_model_name("databricks-qwen35-122b-a10b")
assert parsed is not None
assert parsed.family == "qwen"
assert parsed.version == (3, 5)

Known first-party identities are keyed by ModelService, such as openai, anthropic, google, xai, deepseek, moonshot, alibaba, zhipu, and meta. A model without a canonical name on one of those services has no entry; the package does not invent names for third-party hosts.

Relationship to the Databricks SDK

Use the native SDK directly when an endpoint name is already known and its typed query method fits the request. Use this package when endpoint choice, stable cross-runtime models, OpenAI-shaped HTTP invocation, or provider-neutral chat and embedding normalization is the repetitive part.

Module map

• models — Pydantic wire contracts plus shared family/version/model parsing;
• reasoning — model-family and served-entity reasoning-level inference;
• classify, classes, fallback — model taxonomy and ordering;
• resolve — exact/fuzzy ranking and single-model selection;
• serving — structural WorkspaceClient endpoint listing;
• model_status - daily Databricks retirement-page refresh, parsing, caching, generated fallback selection, and centralized ModelStatus resolution;
• invoke - URLs, Responses-only policy, process-serialized SDK authentication headers, and JSON POST helpers;
• chat, embedding — request repair/sanitization and response extraction.