Cheatsheet

A reference for day-to-day work. For full parameter details see generate_text and generate_embeddings.

Core functions

-- Text from a prompt
uc_ai.generate_text(
  p_user_prompt          => 'clob',
  p_system_prompt        => 'clob',            -- optional
  p_provider             => uc_ai.c_provider_openai,
  p_model                => uc_ai_openai.c_model_gpt_5_6_luna,
  p_max_tool_calls       => 6,                 -- optional
  p_response_json_schema => l_schema           -- optional: structured output
) return json_object_t;

-- Text from a full message array (needed for file/image input & history)
uc_ai.generate_text(
  p_messages       => l_messages,
  p_provider       => ...,
  p_model          => ...
) return json_object_t;

-- Embeddings (vectors) for an array of strings
uc_ai.generate_embeddings(
  p_input    => json_array_t('["text one", "text two"]'),
  p_provider => uc_ai.c_provider_openai,
  p_model    => uc_ai_openai.c_model_text_embedding_3_small
) return json_array_t;   -- array of vectors, one per input

The next call reads a PDF or an image. See OCR.

-- OCR: text, pages and boxes of a PDF or an image
uc_ai.ocr(
  p_document   => l_blob,
  p_media_type => 'application/pdf',
  p_provider   => uc_ai.c_provider_mistral,   -- or c_provider_oci, c_provider_ollama
  p_model      => null,                       -- optional. Ollama requires a vision model
  p_options    => json_object_t('{"tables":true}')  -- optional
) return json_object_t;   -- markdown, pages, usage, model, warnings, raw

-- Mistral only: a document behind a URL
uc_ai.ocr(p_url => 'https://...', p_provider => uc_ai.c_provider_mistral) return json_object_t;

-- Only the text (result.markdown)
uc_ai.ocr_text(l_blob, 'application/pdf', uc_ai.c_provider_mistral) return clob;

The next call is experimental. It answers questions about a text with choices, scores, and probabilities. See Decide.

-- Decide: typed answers with probabilities (OpenAI, TypeSafe and OpenRouter only)
uc_ai.decide(
  p_state     => 'I was charged twice for my order.',
  p_questions => json_object_t('{
    "department": {"type": "choice", "instructions": "Which team handles this?",
                   "criteria": {"billing": "Payments", "support": "Technical problems"}},
    "severity":   {"type": "score", "instructions": "How severe is it?",
                   "criteria": ["Cosmetic", "Workaround exists", "Blocking"]},
    "refund":     {"type": "boolean", "instructions": "Does the customer ask for money back?"}
  }'),
  p_provider  => uc_ai.c_provider_openai,   -- or c_provider_typesafe, c_provider_openrouter
  p_model     => null,                      -- optional. The provider default is used
  p_files     => null,                      -- optional. Images, OpenAI only
  p_options   => null                       -- optional. safety_identifier, extra_body
) return json_object_t;   -- answers, usage, model, provider_metadata, warnings, raw

Both generate_text and generate_embeddings also have a config-driven overload with an extra p_config json_object_t parameter — see Config vs globals below.

Reading the result

generate_text returns a json_object_t. Common keys:

Key	Type	Description
final_message	CLOB	The AI’s final text answer. Use .get_clob('final_message').
finish_reason	string	Why generation stopped (see constants below).
messages	array	Full conversation incl. tool calls and results.

dbms_output.put_line( l_result.get_clob('final_message') );

Reading an OCR result

uc_ai.ocr returns a json_object_t. Keys:

Key	Type	Description
markdown	CLOB	The text of all pages, joined with a blank line.
pages	array	index (from 0), markdown, and optional blocks, dimensions, confidence.
usage	object	pages and bytes (Mistral), pages (OCI), input_tokens and output_tokens (Ollama).
warnings	array	Problems that did not stop the call.
raw	object	The response of the provider.

Reading a decision result

uc_ai.decide returns a json_object_t. Keys:

Key	Type	Description
answers	object	One answer for each question id. type is boolean, choice, score or refused.
usage	object	input_tokens, output_tokens and total_tokens, where the provider reports them.
model	string	The model that answered. TypeSafe reports the specific model version that answered.
provider_metadata	object	confidence for choice and score questions, and usage.
warnings	array	Problems that did not stop the call.
raw	object	The response of the provider.

Read type before you read choice, score or probability. A refused answer has none of them.

A decision agent runs uc_ai.decide as an agent. Create it with p_agent_type => uc_ai_agents_api.c_type_decision and p_decision_config (provider, model, state_template, questions, options, model_config). The final_message of execute_agent is the same object without raw.

Providers

uc_ai.c_provider_openai       uc_ai.c_provider_anthropic
uc_ai.c_provider_google       uc_ai.c_provider_ollama
uc_ai.c_provider_oci          uc_ai.c_provider_xai
uc_ai.c_provider_mistral      uc_ai.c_provider_openrouter
uc_ai.c_provider_typesafe     -- decide only, no chat and no embeddings

Model constants live in each provider package, e.g. uc_ai_openai.c_model_gpt_5_6_luna, uc_ai_anthropic.c_model_claude_5_5_haiku, uc_ai_google.c_model_gemini_3_8_flash. See each provider page for the full list, or use the utility functions to list them at runtime.

Global configuration

Set these before calling generate_text (they default to off). Call uc_ai.reset_globals to restore defaults.

-- Tools
uc_ai.g_enable_tools := true;
uc_ai.g_tool_tags    := apex_t_varchar2('weather', 'users');  -- restrict to tags
uc_ai.g_max_tool_calls := 6;

-- Reasoning / thinking
uc_ai.g_enable_reasoning := true;
uc_ai.g_reasoning_level  := uc_ai.c_reasoning_level_medium;  -- low | medium | high
-- (some providers have their own, e.g. uc_ai_openai.g_reasoning_effort)

-- Connection & auth
uc_ai.g_base_url := 'host.containers.internal:11434/api';    -- e.g. Ollama
uc_ai.g_apex_web_credential := 'OPENAI';                     -- APEX Web Credential static id
uc_ai_openai.g_apex_web_credential := 'OPENAI';              -- or per-provider

-- HTTP timeout in seconds for each provider request (default 180; 300 for OCR and decide)
uc_ai.g_transfer_timeout := 600;

-- Extra HTTP headers on every request
uc_ai.g_extra_headers('X-Tenant-Id') := 'acme';

uc_ai.reset_globals;  -- restore all globals to defaults

Finish reason constants

uc_ai.c_finish_reason_stop            -- completed normally
uc_ai.c_finish_reason_tool_calls      -- paused to call a tool
uc_ai.c_finish_reason_length          -- hit token limit (truncated)
uc_ai.c_finish_reason_content_filter  -- blocked by content filter

Registering a tool

uc_ai_tools_api.create_tool_from_schema(   -- create-only (errors if exists)
  p_tool_code     => 'GET_WEATHER',
  p_description   => 'Get the current weather for a city',
  p_function_call => 'return my_pkg.get_weather(:parameters);',
  p_json_schema   => l_schema,             -- null if no parameters
  p_tags          => apex_t_varchar2('weather')
);

uc_ai_tools_api.merge_tool_from_schema( ... );  -- upsert (idempotent deploys)

Building messages (for files, images, history)

uc_ai_message_api.create_system_message('You are ...')
uc_ai_message_api.create_user_message(l_content_array)
uc_ai_message_api.create_text_content('a question')
uc_ai_message_api.create_file_content(
  p_media_type => 'application/pdf',  -- or image/png, image/webp, ...
  p_data_blob  => l_blob,
  p_filename   => 'doc.pdf'
)

Publishing an agent over A2A

uc_ai_a2a.install_ords_module;                          -- once per schema
uc_ai_a2a.expose_agent('support', 'support_bot');       -- endpoint code, agent code
dbms_output.put_line(uc_ai_a2a.create_api_key('support', 'crm_system'));
commit;                                                  -- ORDS reads committed rows

The card is at <ords>/<schema>/a2a/support/.well-known/agent-card.json. See the A2A server guide.

Config-driven calls vs globals

There are two ways to configure a call:

	Package globals	p_config overload
How	Set uc_ai.g_* before the call	Pass a JSON config object as p_config
State	Reads & mutates shared session globals	Reads neither; nothing is mutated
Best for	Interactive / app code you control end-to-end	Libraries, concurrent or re-entrant calls, self-contained requests
Defaults	Uses current global values	Absent keys fall back to framework defaults (as reset_globals restores)

l_result := uc_ai.generate_text(
  p_user_prompt => 'How is the weather in Paris?',
  p_provider    => uc_ai.c_provider_openai,
  p_model       => uc_ai_openai.c_model_gpt_5_6_luna,
  p_config      => json_object_t('{
    "g_enable_tools": true,
    "g_tool_tags": ["weather"],
    "openai": {"g_use_responses_api": false}
  }')
);

Tip

Use p_config when a library must not depend on or disturb the caller’s globals. Use globals when a single application session owns the configuration.