Reasoning / Thinking

AI reasoning means that an AI system can work through a problem step by step. The model analyzes the information logically and reaches a conclusion by deliberate thought, and not only by a pattern match. The AI therefore solves a complex problem better, explains its decisions better, and handles a new situation that its training data does not hold.

Reasoning uses extra tokens. It is therefore much more expensive than standard text generation.

Provider Support

Each provider implements reasoning in its own way. UC AI therefore has provider-specific settings for the reasoning behavior. These provider pages describe how to configure reasoning:

Basic Usage

To enable reasoning, set the global flag uc_ai.g_enable_reasoning := true;. The AI can then reason during the generation of its answer.

A provider-specific parameter controls how much the AI reasons. More effort gives a more detailed thought process, but it also increases the response time and the token usage. The complexity of the task and the model also control this effect.

Example1: Reasoning with Google Gemini

DECLARE
  l_result json_object_t;
  l_final_message clob;
  l_messages json_array_t;
BEGIN
  -- Enable reasoning
  uc_ai.g_enable_reasoning := true;

  -- For Google models, set reasoning budget
  uc_ai_google.g_reasoning_budget := 512;

  l_result := uc_ai.generate_text(
    p_user_prompt => 'Answer in one sentence. If there is a great filter, are we before or after it and why?',
    p_provider => uc_ai.c_provider_google,
    p_model => uc_ai_google.c_model_gemini_3_7_flash
  );

  l_final_message := l_result.get_clob('final_message');
  dbms_output.put_line('Final Answer: ' || l_final_message);
END;
/

Example2: Reasoning with OpenAI

DECLARE
  l_result json_object_t;
  l_final_message clob;
  l_messages json_array_t;
BEGIN
  -- Enable reasoning
  uc_ai.g_enable_reasoning := true;
  -- Set reasoning effort
  uc_ai_openai.g_reasoning_effort := 'low'; -- low, medium, high

  l_result := uc_ai.GENERATE_TEXT(
    p_user_prompt => 'Answer in one sentence. If there is a great filter, are we before or after it and why.',
    p_provider => uc_ai.c_provider_openai,
    p_model => uc_ai_openai.c_model_gpt_5_6_terra
  );

  l_final_message := l_result.get_clob('final_message');
  dbms_output.put_line('Final Answer: ' || l_final_message);
END;
/

Generic Reasoning Settings

You can also choose one of three levels: low, medium, or high. A provider-specific setting is then not necessary. For a production system, test and tune the reasoning settings of your provider and model.

The g_reasoning_level variable of the uc_ai package holds this generic level.

DECLARE
  l_result json_object_t;
  l_final_message clob;
  l_messages json_array_t;
BEGIN
  -- Enable reasoning
  uc_ai.g_enable_reasoning := true;
  -- Set reasoning effort
  uc_ai.g_reasoning_level := uc_ai.c_reasoning_level_low; -- low, medium, high

  l_result := uc_ai.GENERATE_TEXT(
    p_user_prompt => 'Answer in one sentence. If there is a great filter, are we before or after it and why.',
    p_provider => uc_ai.c_provider_openai,
    p_model => uc_ai_openai.c_model_gpt_5_6_terra
  );

  l_final_message := l_result.get_clob('final_message');
  dbms_output.put_line('Final Answer: ' || l_final_message);
END;
/

Processing Reasoning Content

Message Structure with Reasoning

With reasoning enabled, the assistant message holds several content items:

{
  "role": "assistant",
  "content": [
    {
      "type": "reasoning",
      "text": "Let me think about this step by step. The Great Filter hypothesis suggests there's a barrier that prevents life from developing into advanced civilizations..."
    },
    {
      "type": "text",
      "text": "Based on current evidence, we are likely before the Great Filter, as we haven't yet achieved interstellar civilization or solved existential risks."
    }
  ]
}

The OpenAI Responses API returns the reasoning content only after you opt in. Reasoning content, storage, and encryption describes how g_store_responses, g_include_encrypted_reasoning, and g_reasoning_summary control the answer.

Extracting Reasoning Content

This block reads the reasoning content from the answer:

DECLARE
  l_result json_object_t;
  l_messages json_array_t;
  l_assistant_message json_object_t;
  l_content_array json_array_t;
  l_content_item json_object_t;
  l_reasoning_found boolean := false;
BEGIN
  uc_ai.g_enable_reasoning := true;
  uc_ai_google.g_reasoning_budget := 512;

  l_result := uc_ai.generate_text(
    p_user_prompt => 'Answer in one sentence. If there is a great filter, are we before or after it and why?',
    p_provider => uc_ai.c_provider_google,
    p_model => uc_ai_google.c_model_gemini_3_7_flash
  );

  l_messages := treat(l_result.get('messages') as json_array_t);

  -- Get the assistant message (the last one)
  l_assistant_message := treat(l_messages.get(l_messages.get_size - 1) as json_object_t);

  IF l_assistant_message.get_string('role') = 'assistant' THEN
    l_content_array := l_assistant_message.get_array('content');

    -- Loop through content items
    FOR i IN 0 .. l_content_array.get_size - 1 LOOP
      l_content_item := treat(l_content_array.get(i) as json_object_t);

      IF l_content_item.get_string('type') = 'reasoning' THEN
        dbms_output.put_line('Reasoning: ' || l_content_item.get_clob('text'));
      END IF;
    END LOOP;

    IF NOT l_reasoning_found THEN
      dbms_output.put_line('No reasoning content found (may not be supported by this provider/model)');
    END IF;
  ELSE
    raise_application_error(-20001, 'Did not find expected assistant message structure');
  END IF;
END;
/

Best Practices

These provider guides give the best practices for reasoning: