Registry / llm-agents / unitycatalog-openai

unitycatalog-openai

JSON →
library0.4.0pypypi✓ verified 26d ago

The `unitycatalog-openai` library provides support for integrating Databricks Unity Catalog functions as OpenAI tools. This allows large language models to discover and execute Unity Catalog registered functions. The current version is 0.2.0, and being an early-stage library, releases are currently irregular.

pip install unitycatalog-openai
INSTALL
IMPORT
SIG · UNITYCATALOG-OPENA
U
unitycatalog-openai
llm-agentspythonv0.4.0
Install
9.1s avg
Import
—
Disk
61MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v0.4.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 59.5MB
glibc
py 3.10–3.95 runs
installs and imports cleanly · install 9.1s · import 0.000s · 60MB
61MB installed
● package 61MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

UnityCatalogOpenAIToolFactory
✓ from unitycatalog.openai import UnityCatalogOpenAIToolFactory
✗ from unitycatalog.openai import UnityCatalogOpenAIToolFactory

This quickstart demonstrates how to initialize `UnityCatalogOpenAIToolFactory`, retrieve Unity Catalog functions as OpenAI-compatible tools, and pass them to an OpenAI chat completion call. It requires `OPENAI_API_KEY`, `DATABRICKS_HOST`, and `DATABRICKS_TOKEN` environment variables to be set. It then simulates a tool call by the LLM and demonstrates how to provide the tool's output back to the model.

import os from openai import OpenAI from unitycatalog_openai_tools import UnityCatalogOpenAIToolFactory # Ensure environment variables are set: # OPENAI_API_KEY # DATABRICKS_HOST (e.g., https://adb-XXXXXXXXXXXXXXXX.XX.databricks.com) # DATABRICKS_TOKEN (Databricks Personal Access Token) openai_api_key = os.environ.get('OPENAI_API_KEY', '') db_host = os.environ.get('DATABRICKS_HOST', '') db_token = os.environ.get('DATABRICKS_TOKEN', '') if not all([openai_api_key, db_host, db_token]): print("Please set OPENAI_API_KEY, DATABRICKS_HOST, and DATABRICKS_TOKEN environment variables.") exit(1) # Initialize OpenAI client client = OpenAI(api_key=openai_api_key) # Create the Unity Catalog tool factory # Specify desired catalog and schema tool_factory = UnityCatalogOpenAIToolFactory( databricks_host=db_host, databricks_token=db_token, catalog_name="main", # Replace with your catalog name schema_name="default" # Replace with your schema name ) # Get available tools uc_tools = tool_factory.get_tools() # Convert tools to OpenAI format openai_tools = [tool.openai_function for tool in uc_tools] # Example: Call OpenAI Chat Completion with tools messages = [{ "role": "user", "content": "What functions are available in Unity Catalog?" }] try: response = client.chat.completions.create( model="gpt-3.5-turbo", # or your preferred tool-calling model messages=messages, tools=openai_tools, tool_choice="auto" # Allow the model to choose if it needs a tool ) print("OpenAI API response (initial):") print(response.choices[0].message) # If the model requests a tool call, execute it message = response.choices[0].message if message.tool_calls: for tool_call in message.tool_calls: tool_name = tool_call.function.name tool_arguments = tool_call.function.arguments print(f"\nModel requested tool: {tool_name} with arguments: {tool_arguments}") # Find and execute the actual tool function for tool in uc_tools: if tool.name == tool_name: # In a real application, you'd parse arguments and call the tool's underlying function # For now, just acknowledge and print print(f"Executing mock call for {tool_name}...") # result = tool.execute(**json.loads(tool_arguments)) # print(f"Tool result: {result}") messages.append(message) messages.append({ "tool_call_id": tool_call.id, "role": "tool", "name": tool_name, "content": "{ 'status': 'success', 'message': 'Function discovery complete.' }" }) # Make another call to OpenAI with tool output second_response = client.chat.completions.create( model="gpt-3.5-turbo", messages=messages, ) print("\nOpenAI API response (after tool execution):") print(second_response.choices[0].message.content) break except Exception as e: print(f"An error occurred: {e}")
Debug
Known issues
breakingThe library explicitly requires `openai>=1.0.0` and `databricks-sdk>=0.20.0,<1.0.0`. Using older versions of these dependencies will lead to import errors or runtime issues due to API changes.
fix
Ensure your `openai` package is `1.0.0` or higher, and `databricks-sdk` is within `0.20.0` to `0.99.9` (e.g., `pip install 'openai>=1.0.0' 'databricks-sdk>=0.20.0,<1.0.0'`).
affects: <0.2.0
gotchaDatabricks authentication requires `DATABRICKS_HOST` and `DATABRICKS_TOKEN` to be set as environment variables. Without these, the `UnityCatalogOpenAIToolFactory` will fail to connect to your Databricks workspace.
fix
Set `DATABRICKS_HOST` to your workspace URL (e.g., `https://adb-XXXXXXXXXXXXXXXX.XX.databricks.com`) and `DATABRICKS_TOKEN` to a valid Databricks Personal Access Token with Unity Catalog permissions.
affects: All
gotchaThe Databricks Personal Access Token (PAT) used for `DATABRICKS_TOKEN` must have sufficient permissions to read Unity Catalog metadata (e.g., `USE CATALOG`, `USE SCHEMA`, `SELECT` on functions). Lack of permissions will result in errors when `get_tools()` attempts to list functions.
fix
Ensure the PAT has necessary Unity Catalog permissions. At a minimum, `USE CATALOG` on the specified catalog, `USE SCHEMA` on the specified schema, and `SELECT` on any functions you wish to expose.
affects: All
breakingAs a library in early development (v0.2.0), API surfaces, class names, and method signatures are subject to breaking changes even in minor version increments. Always consult the GitHub repository's README for the latest usage.
fix
Pin your `unitycatalog-openai` dependency to a specific minor version if stability is crucial (e.g., `unitycatalog-openai==0.2.0`) and carefully review changes when upgrading.
affects: All pre-1.0.0 versions
Upgrade
Version history
0.4.0latest on PyPI · released Apr 24, 2026
Audit
Dependencies
openairequiredRequired for interacting with the OpenAI API, specifically for tool calling functionality.
databricks-sdkrequiredRequired for authenticating and interacting with Databricks Unity Catalog to discover functions.
pydanticrequiredUsed for data validation and parsing, especially for function schemas.
Agent activity
45 hits · last 30 days
node
36
Perplexity
1
OpenAI (training)
1
Resources
unitycatalog-openai — pip install unitycatalog-openai · libregistry