Installation

Prerequisites

• Oracle Database 12.2 or later
• Oracle APEX (older versions are fine, this project uses some of the APIs)

Installing UC AI

UC logs some debug relevant information. If you don’t have Logger installed it will log via the apex_debug package.

Option 1: GitHub release scripts

For each new release of UC AI the release page in GitHub will contain scripts to install the UC AI package and its dependencies.

• install_uc_ai_complete.sql installs all UC AI objects
• install_uc_ai_complete_with_logger.sql installs all UC AI objects and the Logger package
• upgrade_packages.sql upgrades the UC AI packages. Most of the time only packages get modified. So for most releases you just need to run this script to upgrade to a newer version. Please still keep an eye on the release notes to see if there are any changes that require you to run the complete installation script.

Just run the necessary script in your SQL client to install the UC AI package and its dependencies.

Option 2: Install GitHub repository

Either download the source code of the latest release from the GitHub releases page or clone the GitHub repository:

Run this script to install the UC AI with any SQL client:

# inside the uc_ai directory
sql ./install_uc_ai.sql

There is also a install_with_logger.sql script that installs the UC AI with the Logger package.

# inside the uc_ai directory
sql ./install_with_logger.sql

Alternatively if you don’t want the logger installed you can install it’s “no op” (no operation) version which installs the necessary objects so that the packages compile but does not log anything.

# inside the uc_ai directory
cd ./src/dependencies/logger_3.1.1
sql ./logger_install_no_op.sql

Set up API Keys

There are two ways to manage your API keys for the AI providers: Key function or APEX Web Credentials.

Option 1: Key function

The installation script created the following function. Modify it to return your API keys for the AI providers you want to use.

create or replace function uc_ai_get_key (
  p_provider in uc_ai.provider_type
)
  return varchar2
as
  e_unhandled_provider exception;
begin
  -- retrieve and return your keys from a secure location the way you prefer
  case p_provider
    when uc_ai.c_provider_openai then
      return 'change_me';
    when uc_ai.c_provider_anthropic then
      return '...';
    when uc_ai.c_provider_google then
      return '...';
    else
      raise e_unhandled_provider;
  end case;
exception
  when e_unhandled_provider then
    raise_application_error(-20001, 'No key defined for provider: ' || p_provider);
  when others then
    raise;
end uc_ai_get_key;
/

Option 2: APEX Web Credentials

You can also store your secret API keys with APEX Web Credentials. For this you have to have an APEX Workspace for the schema where UC AI is installed. Log in there and head to Workspace Utilities → Web Credentials (guide with screenshots). Check out the following guides on how to set up the web credentials:

• Anthropic
• Google
• OCI
• OpenAI

Now before calling any UC AI functions you have to set the package variable for the provider you want to use to the static ID of your web credential. For example if you created a web credential with the static ID OPENAI for OpenAI you would run this code:

uc_ai_openai.g_apex_web_credential := 'OPENAI';

Test if it is working

DECLARE
  l_result JSON_OBJECT_T;
BEGIN
  -- If you are using APEX Web Credentials set it here
  -- uc_ai_openai.g_apex_web_credential := 'OPENAI';

  l_result := uc_ai.generate_text(
    p_user_prompt => 'What is APEX Office Print?',
    p_provider => uc_ai.c_provider_openai, -- change to your preferred provider
    p_model => uc_ai_openai.c_model_gpt_4o_mini -- change to your preferred model
  );

  -- Get the AI's response
  DBMS_OUTPUT.PUT_LINE('AI Response: ' || l_result.get_string('final_message'));
END;
/

Upgrades

Most of the time you just need to run the upgrade_packages.sql script to upgrade to a newer version of UC AI. This script will only upgrade the packages that have changed since the last version.

Please still keep an eye on the release notes to see if there are any changes that require you to run the complete installation script.