{"id":4834,"library":"unitycatalog-openai","title":"Unity Catalog OpenAI Tools","description":"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.","status":"active","version":"0.2.0","language":"en","source_language":"en","source_url":"https://github.com/databricks-partners/unitycatalog-openai-tools","tags":["databricks","unity catalog","openai","tools","ai","llm","functions"],"install":[{"cmd":"pip install unitycatalog-openai","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required for interacting with the OpenAI API, specifically for tool calling functionality.","package":"openai","optional":false},{"reason":"Required for authenticating and interacting with Databricks Unity Catalog to discover functions.","package":"databricks-sdk","optional":false},{"reason":"Used for data validation and parsing, especially for function schemas.","package":"pydantic","optional":false}],"imports":[{"symbol":"UnityCatalogOpenAIToolFactory","correct":"from unitycatalog_openai_tools import UnityCatalogOpenAIToolFactory"}],"quickstart":{"code":"import os\nfrom openai import OpenAI\nfrom unitycatalog_openai_tools import UnityCatalogOpenAIToolFactory\n\n# Ensure environment variables are set:\n# OPENAI_API_KEY\n# DATABRICKS_HOST (e.g., https://adb-XXXXXXXXXXXXXXXX.XX.databricks.com)\n# DATABRICKS_TOKEN (Databricks Personal Access Token)\n\nopenai_api_key = os.environ.get('OPENAI_API_KEY', '')\ndb_host = os.environ.get('DATABRICKS_HOST', '')\ndb_token = os.environ.get('DATABRICKS_TOKEN', '')\n\nif not all([openai_api_key, db_host, db_token]):\n    print(\"Please set OPENAI_API_KEY, DATABRICKS_HOST, and DATABRICKS_TOKEN environment variables.\")\n    exit(1)\n\n# Initialize OpenAI client\nclient = OpenAI(api_key=openai_api_key)\n\n# Create the Unity Catalog tool factory\n# Specify desired catalog and schema\ntool_factory = UnityCatalogOpenAIToolFactory(\n    databricks_host=db_host,\n    databricks_token=db_token,\n    catalog_name=\"main\", # Replace with your catalog name\n    schema_name=\"default\" # Replace with your schema name\n)\n\n# Get available tools\nuc_tools = tool_factory.get_tools()\n\n# Convert tools to OpenAI format\nopenai_tools = [tool.openai_function for tool in uc_tools]\n\n# Example: Call OpenAI Chat Completion with tools\nmessages = [{\n    \"role\": \"user\",\n    \"content\": \"What functions are available in Unity Catalog?\"\n}]\n\ntry:\n    response = client.chat.completions.create(\n        model=\"gpt-3.5-turbo\", # or your preferred tool-calling model\n        messages=messages,\n        tools=openai_tools,\n        tool_choice=\"auto\" # Allow the model to choose if it needs a tool\n    )\n    print(\"OpenAI API response (initial):\")\n    print(response.choices[0].message)\n\n    # If the model requests a tool call, execute it\n    message = response.choices[0].message\n    if message.tool_calls:\n        for tool_call in message.tool_calls:\n            tool_name = tool_call.function.name\n            tool_arguments = tool_call.function.arguments\n            print(f\"\\nModel requested tool: {tool_name} with arguments: {tool_arguments}\")\n\n            # Find and execute the actual tool function\n            for tool in uc_tools:\n                if tool.name == tool_name:\n                    # In a real application, you'd parse arguments and call the tool's underlying function\n                    # For now, just acknowledge and print\n                    print(f\"Executing mock call for {tool_name}...\")\n                    # result = tool.execute(**json.loads(tool_arguments))\n                    # print(f\"Tool result: {result}\")\n                    messages.append(message)\n                    messages.append({\n                        \"tool_call_id\": tool_call.id,\n                        \"role\": \"tool\",\n                        \"name\": tool_name,\n                        \"content\": \"{ 'status': 'success', 'message': 'Function discovery complete.' }\"\n                    })\n                    \n                    # Make another call to OpenAI with tool output\n                    second_response = client.chat.completions.create(\n                        model=\"gpt-3.5-turbo\",\n                        messages=messages,\n                    )\n                    print(\"\\nOpenAI API response (after tool execution):\")\n                    print(second_response.choices[0].message.content)\n                    break\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"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'`).","message":"The 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.","severity":"breaking","affected_versions":"<0.2.0"},{"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.","message":"Databricks 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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"As 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.","severity":"breaking","affected_versions":"All pre-1.0.0 versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}