`dbx-tools-litellm`

Thin routing and discovery around LiteLLM's native Databricks provider.

The package resolves live Databricks endpoints, injects Rust-managed credentials and the correct Unity Gateway URL, and publishes model discovery routes. LiteLLM owns request conversion, transport, tools, streaming, and retries.

Key features

Uses litellm[proxy] 1.99.0 and Python 3.11 or newer.
Resolves exact or fuzzy model names against the selected workspace.
Routes Chat, Responses, and embeddings through LiteLLM's native Databricks and OpenAI providers.
Selects /ai-gateway/codex/v1 for OpenAI GPT Responses, /ai-gateway/mlflow/v1 for other foundation model services and embeddings, and /serving-endpoints for custom endpoints.
Exposes live /v1/models and package-specific /lookup routes without LiteLLM's hardcoded model catalogue.
Preserves native Databricks Responses tools and hosted-tool output.
Learns optional parameters rejected by each model, retries the active call, and caches the result for one day.
Records requested model, resolved model, requesting IP, latency, token usage, cache usage, and streaming mode.

Install

uv add dbx-tools-litellm

The package supports Python 3.11 through 3.13.

Run

uv run dbx-litellm --port 4000

The proxy listens on 127.0.0.1 by default. Any additional arguments are forwarded to LiteLLM.

An explicit profile is optional:

uv run dbx-litellm --profile my-workspace --port 4000

dbx_tools.client owns profile selection, U2M, M2M, and PAT authentication, storage, locking, and token refresh. The proxy reads the resolved profile and host from that package rather than invoking the Databricks CLI itself. Explicit PAT profiles are supported. Automatic profile resolution ignores PAT configuration inside a Databricks App so ambient app credentials remain in use.

Request routing

The model routing hook changes only LiteLLM routing fields:

Resolve the requested model against the five-minute live endpoint cache.
Select the endpoint's system.ai.* model-service identity when available.
Set LiteLLM's native databricks provider and the matching Databricks base URL.
Inject the Rust-managed bearer token.
Forward a Codex originator header when present.

The routing hook leaves messages, tools, images, and provider parameters unchanged. LiteLLM's native bridge converts Responses requests and Chat responses for model services without native OpenAI Responses support. Bridged requests use LiteLLM's native parameter dropping and omit reasoning only when the cached endpoint record exposes no reasoning efforts.

Foundation model Chat and embedding calls use the OpenAI-compatible Unity Gateway:

<workspace>/ai-gateway/mlflow/v1/chat/completions
<workspace>/ai-gateway/mlflow/v1/embeddings

Codex OpenAI GPT Responses use:

<workspace>/ai-gateway/codex/v1/responses

Custom serving endpoints retain LiteLLM's native Databricks serving URL.

Models

GET /v1/models is the standard OpenAI model-list route. It is built only from the live workspace catalogue and excludes deprecated endpoints.

Standard OpenAI clients receive the data envelope with exact endpoint IDs. Requests whose originator begins with codex also receive the Codex models extension. Codex entries use databricks/system.ai.* model-service IDs and include:

supported_reasoning_levels from endpoint metadata, using the required empty list when the endpoint exposes none;
default_reasoning_level, preferring medium;
visibility, priority, shell, truncation, and base-instruction metadata required by Codex.

OpenAI GPT model services use LiteLLM's native OpenAI Responses provider against the Codex-compatible gateway. Other text-model families use LiteLLM's native Responses-to-Chat bridge against the MLflow-compatible gateway. The Codex catalogue uses an exclusion policy for Claude, Gemini, Inkling, and embedding families, so newly recognized text-model families are eligible by default.

List the same catalogue without starting the proxy:

uv run dbx-litellm models
uv run dbx-litellm models --extended
uv run dbx-litellm models --output json

Lookup

GET /lookup ranks the live catalogue using dbx-tools-model. It exposes the ModelQuery fields as query parameters and returns complete RankedModel records. An omitted search returns every eligible model.

curl 'http://127.0.0.1:4000/lookup?search=gpt&limit=5'
uv run dbx-litellm lookup gpt
uv run dbx-litellm lookup gpt --output json

Codex

Point Codex at the local proxy:

[model_providers.dbx]
name = "dbx-tools LiteLLM"
base_url = "http://127.0.0.1:4000/v1"
wire_api = "responses"
requires_openai_auth = false

Codex reads /v1/models, selects a databricks/system.ai.* model, and sends its originator header with Responses requests.

Databricks Responses tools

Native GPT Responses preserve function, custom, apply_patch, shell, image_generation, mcp, and web_search, plus tool_choice, parallel_tool_calls, max_tool_calls, and include.

OpenAI models use {"type":"web_search"}. Gemini web search uses google_search through Chat or the Gemini API. Claude web search requires an MCP search server.

Responses-only hosted tools are not available on the Chat bridge. LiteLLM drops those unsupported parameters while preserving function tools accepted by the Chat model.

Adaptive parameter support

Model-specific Open Responses support is not present in the serving-endpoint API. The proxy therefore learns from structured gateway rejections. When a model rejects an optional top-level parameter, the HTTP transport extracts the field name, retries without it, and caches the rejection by gateway route and resolved model for one day. The cache expires so newly enabled model capabilities are tried again. Required protocol fields such as model, input, messages, and stream are never removed. When a replayed function-call item uses its call_ value as the item id, the transport preserves call_id, removes the invalid item id, and retries after the gateway reports the fc_ namespace requirement.

Response annotations and access logs

Non-streaming Chat and Responses JSON includes:

requestedModel: the value supplied by the client;
model: the resolved Databricks endpoint or model service;
requestEndpoint: the exact upstream URL.

The dbx-access logger writes one structured line per request to stderr. It includes model identity, requesting IP, timing, token counts, cache counts, and whether streaming was native or emulated.

Modules

backend - live catalogue cache and fuzzy resolution.
capabilities - adaptive parameter cache and HTTP retry transport.
credentials - Rust-backed credentials and Databricks base URLs.
routing - native provider and originator routing.
models - dynamic native-streaming registration.
models_api - /v1/models, /lookup, and response annotations.
originator - Codex originator extraction and forwarding.
access_log - request telemetry.
cli - proxy launcher and model inspection commands.

Metadata

Release files for dbx-tools-litellm 0.6.183

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for dbx-tools-litellm 0.6.183
File	Size	Uploaded
dbx_tools_litellm-0.6.183.tar.gz	20.0 kB	Sep 8, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for dbx-tools-litellm 0.6.183
File	Interpreter	ABI	Platform	Reset
dbx_tools_litellm-0.6.183-py3-none-any.whl 25.8 kB Sep 8, 2026	Python 3	none	any	Details

Total release size: 45.7 kB

Release files / dbx_tools_litellm-0.6.183.tar.gz

Download URL	dbx_tools_litellm-0.6.183.tar.gz
Size	20.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`f4bf50ca6475359b621f0a30a5778683be05bc69af7f64b870df6625fe065c40`
BLAKE2b-256 checksum How to use checksums	`c28ed6a8c5b07ff1cc48c8effcded99831c8110b19aac1dfc16bef88e614b558`
Upload date	Sep 8, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/reggie-db/dbx-tools
Publishing commit: github.com/reggie-db/dbx-tools/tree/9bb6a4fe7dc52d13cde4ce03f1689081c4690d3a

Workflow

Publishing configuration: github.com/reggie-db/dbx-tools/blob/9bb6a4fe7dc52d13cde4ce03f1689081c4690d3a/.github/workflows/release.yml
Publishing logs: github.com/reggie-db/dbx-tools/actions/runs/34273490161/attempts/1

Artifact

Subject: dbx_tools_litellm-0.6.183.tar.gz
SHA-256 checksum: f4bf50ca6475359b621f0a30a5778683be05bc69af7f64b870df6625fe065c40 Verifying attestations

Release files / dbx_tools_litellm-0.6.183-py3-none-any.whl

Download URL	dbx_tools_litellm-0.6.183-py3-none-any.whl
Size	25.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`3fc2eefe3c8eeb45379139d83434d44f52570a53ee122a922744df0f57a1361a`
BLAKE2b-256 checksum How to use checksums	`94e3d663b90640fcf458d259ab6846cee32d9e97e93da8b1e5e06f461700f925`
Upload date	Sep 8, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/reggie-db/dbx-tools
Publishing commit: github.com/reggie-db/dbx-tools/tree/9bb6a4fe7dc52d13cde4ce03f1689081c4690d3a

Workflow

Publishing configuration: github.com/reggie-db/dbx-tools/blob/9bb6a4fe7dc52d13cde4ce03f1689081c4690d3a/.github/workflows/release.yml
Publishing logs: github.com/reggie-db/dbx-tools/actions/runs/34273490161/attempts/1

Artifact

Subject: dbx_tools_litellm-0.6.183-py3-none-any.whl
SHA-256 checksum: 3fc2eefe3c8eeb45379139d83434d44f52570a53ee122a922744df0f57a1361a Verifying attestations