Managing AI Services

8 Managing AI Services

Retail Analytics and Planning solutions leverage certain common AI services which need to be configured and maintained by customer administrators in order to enable them for business users. Review this chapter to understand the available services and manage their configurations.

Customer Documents for Retrieval-Augmented Generation

In the AI chat interfaces found throughout the Analytics and Planning applications, it is possible to ask general questions about application workflows, configurations, errors, and other details where the answers may be found somewhere in Oracle documentation. Retrieval-Augmented Generation (RAG) enhances AI answers to questions by retrieving relevant information before generating a response. In addition to the service’s shared knowledge base, you can provide your organization’s own documents so the AI can use them when answering your users’ questions. When users ask questions through the chat interface, the service searches your document content together with the shared documentation that applies to your service.

The workflow for leveraging this service has three main steps:

Upload PDF documents to your designated File Transfer Services (FTS) Object Storage path.
Monitor ingestion through the vectorization status REST API.
Test the new content in the chat interface once ingestion is complete.

The service handles security scanning, document processing, indexing, and retrieval automatically.

Upload Documents

File transfer services (FTS) are leveraged for document uploads through Object Storage. For a basic understanding of FTS, refer to the Managing File Transfers chapter of this document. Before you begin, obtain the following from your service administrator or implementation team:

Your Object Storage bucket and authorized FTS upload access
Your designated document path
The service host and tenant identifier for the status API
Access to the chat interface for your RAP application(s)

Your designated Object Storage path follows this format:

rais/vector_db/version/<version>/appl/<appCode>/module/<moduleCode>/tenant/<customerTenantId>/

Replace the placeholder values in the path with exact values provided for your environment. Uploading outside this path prevents the document from being picked up for your tenant’s RAG content. The paths are application and version-specific, which means you must upload your latest documentation set for each major product release that gets applied in your RAP environment (hot fixes do not affect this process). If you do not upload new documents after an upgrade, the chat interface will no longer return data from your documents and will default back to standard Oracle documentation.

Example path:

rais/vector_db/version/26.1.201.0/appl/ap/module/ap/tenant/fgta435gtc4590fn/

After upload, FTS automatically scans the document for security concerns. Because the RAG process requires PDF files, the primary purpose of the scan is to detect malware or other malicious content embedded inside the file. The scan may also fail if the file is corrupt and cannot be accessed, or if the file is password-protected. If anything is found, the file will fail the scan and cannot be loaded into the Oracle servers. Documents that pass the scan are transferred to the RAG ingestion area and prepared for search.

Monitor File Status

Once the files are accepted into the platform, they must be vectorized and added to the AI services database. Use the vectorization status REST API to check whether your uploaded documents are ready for RAG. The API format is:

POST
https://<host>/<tenant>/app/rgbucommongenai/retailaiservices/filesVectorizationStatus

Example API URL:

https://rgbu.gbua.eu-frankfurt-1.oci.oraclecloud.com/fgta435gtc4590fn/app/rgbucommongenai/retailaiservices/filesVectorizationStatus

Example payload for the message body:

{{
{"appName": "ap","module": "ap","version": "26.1.201.0"}
}}

Continue checking the status until it returns COMPLETED.

Status Message	Meaning	Next action
In progress or other non-completed status	The document is still being processed.	Wait and check again.
COMPLETED	The document has been indexed and is available to RAG.	Test it in the chat interface.

Processing includes breaking the document into searchable sections, creating embeddings, and updating the vector index. Completion time can vary based on scheduled processing intervals and document volume. The process to load files runs every 60 minutes so it is not expected to take more than 1 to 2 hours to load a document, unless the document is exceptionally large and then it may require more processing time.

Verify Chat Results

Once the documents have completed the upload process, you may begin asking questions about their content from the specific AI chat interface associated with the upload, such as the ones in AP or MFP applications. Follow these guidelines for verifying the document contents are correctly being used:

Ask a question whose answer is clearly contained in the uploaded document.
Use specific terminology, names, procedures, or values from the document.
Confirm that the response is accurate and useful for your intended audience.
Test a few alternative phrasings to ensure users can find the information naturally.
Start with a question that is not likely to be answered by the shared knowledge base alone.

Deleting Documents

There is a separate API available for removing documents from Object Storage. The API format is:

DELETE
https://<host>/<tenant>/app/rgbucommongenai/retailaiservices/deleteFilesInOS

Example API URL:

https://rgbu.gbua.eu-frankfurt-1.oci.oraclecloud.com/fgta435gtc4590fn/app/rgbucommongenai/retailaiservices/deleteFilesInOS

Example payload for the message body:

{{
{"appName": "ap","module": "ap","version": "26.1.201.0","fileName": "<filename to be deleted>"}
}}

Use your environment’s service host and tenant identifier. After deletion, confirm through your normal validation process that the document is no longer available through the chat interface. Only delete documents that your organization no longer wants available for RAG retrieval.

Frequently Asked Questions

Question: How does the model used for the chat interface resolve differences between the Oracle and customer-provided documentation?

Answer: The customer’s documentation, once transformed and loaded into our database, is combined with the base documentation’s data. At this point there is no functional difference between base and custom documents, all information is retrieved based on standard LLM techniques for identifying the most relevant information for the user’s question and forming a natural-language response. The response may contain data from multiple sources, and it cannot verify the accuracy of the response if two documents provide conflicting answers to a question.

Question: How do I know which document was used to answer a question?

Answer: In the current implementation, the model can return details on the base Oracle Retail document that was used in a response, but not the custom documents.

Question: Can I control who can see data from certain documents, or who can see information on certain topics such as a specific UI screen or workflow that not all users can access?

Answer: No, the documentation uploaded to the RAG database becomes available to all users who have access to the chat interface. Do not upload sensitive or restricted information that should not be available to all users of the application.

Question: What are the customer’s responsibilities for maintaining this feature after they begin using one or more Retail applications?

Answer: The customer is responsible for uploading documents for each product release, verifying the quality of chat responses on their documentation, and deleting old documents if they become outdated or irrelevant.

Question: What suggestions can be given for managing this process in a live production environment?

Answer: Both document uploads and deletion can be automated from the customer’s own servers by incorporating the Rest API calls into scripts, AI tools, or other integration software. The customer could place new documents into a shared location, periodically poll that location for changes, and upload the documents to Oracle. For chat validation, prepare a standard set of questions which can be asked after every major update and log the responses for future reference, so quality and accuracy can be monitored over longer periods of time and applied back into the custom documents.

Access Retail AI Services MCP Server

Use the Retail AI Services (RAIS) MCP Server to access selected Retail AI Services capabilities from an AI client. Model Context Protocol provides a standard interface through which the client discovers available tools, determines their input requirements, and requests execution.

RAIS MCP Server provides tools for generating retail content, extracting product attributes and document information, translating text, summarizing information, and retrieving application knowledge. It also provides natural-language analytics capabilities when the required data and services are configured.

For example, you can ask an AI client with a connection to the MCP server to:

Generate an item description from product attributes.
Extract attributes from a supplier’s product description.
Translate product content into another language.
Summarize information about an item.
Draft a customer follow-up message for a store associate.
Retrieve information about a configured retail application.

The AI client selects an appropriate tool and supplies the information required for the request. Tool availability and successful execution depend on the deployed server version and the configuration of the services used by each tool. Clients connect over HTTPS using Streamable HTTP. You do not need to install or start a Retail AI Services server on your computer.

The endpoint has the following format:

https://<oracle-regional-domain>/<tenant-id>/app/rgbucommongenai/retailaiservices/mcp/

An example of a regional domain name is rgbu.gbua.us-ashburn-1.oci.oraclecloud.com. The tenant ID will be the same one used for other Retail services such as Application Express (APEX). Obtain the complete endpoint from your administrator. The domain and tenant identifier are specific to your environment. Use the full published endpoint, including its server name and trailing slash. Access to the deployed endpoint is authenticated through the tenant’s Oracle Cloud Infrastructure (OCI) IAM Identity Domain or Oracle Identity Cloud Service (IDCS), using the single-sign-on authentication integration. The permissions associated with the authenticated user determine access to the services.

Before connecting, confirm that your organization permits the selected AI client to process the information used in your requests and returned by the tools. Review generated content and analytical results before using them in business processes.

Tools Available with Retail AI Services MCP Server

The following table describes the tools in the standard Retail AI Services MCP implementation. Use tool discovery in your connected client to determine which tools are available in your environment and their current input requirements.

Tool	What the Tool Does	Information to Provide
attribute_extraction_tool	Extracts and normalizes retail product attributes from text, category information, or product-image evidence.	A product description, category, or supported Object Storage image URL.
clientelling_tool	Generates customer follow-up messages for retail associates.	An item status or description. Include customer, associate, event, or follow-up context when relevant.
document_understanding_tool	Extracts document fields and line items, such as information from an invoice.	A supported document URL that the server can access.
item_description_tool	Generates retail item descriptions, including primary, short, secondary, or long descriptions.	Item identifier, description, parent hierarchies, and item attributes, as required by the discovered schema.
nl2sql_tool	Processes natural-language analytics questions through the configured Retail AI Services analytics runtime.	A clear business question, including relevant metrics, filters, and time period.
note_generation_tool	Generates or refines retail notes.	Source text, an existing note, or instructions describing the note to generate.
rag_search_tool	Retrieves information from configured Retail AI Services application knowledge.	A question and the valid application code for the target knowledge source.
summary_tool	Summarizes structured entity information.	Entity type and the information to summarize. Include a length limit when needed.
translation_tool	Translates retail field content.	Source text, source language, and one or more target languages. Use full language names, such as English and Spanish.

Provide enough business context for the client to prepare a useful request. For example, specify the desired description length, translation languages, target application, or analytics time period. The following examples illustrate requests you can adapt:

“Extract the product attributes from this description: women’s blue cotton shirt with long sleeves.”
“Generate a short item description using the following item attributes.”
“Translate this product description from English into Spanish and French.”
“Draft a customer follow-up message about this item that is back in stock.”
“Summarize the following item information in 100 words or less.”
“Use the application code supplied by my administrator to find guidance about this retail process.”

Some tools require information beyond the text of your question. Product-image inputs must use the supported Object Storage URL format; local image paths and raw base64 images are not supported by the attribute extraction tool. Document URLs must be accessible from the server. Uploading a file to the AI client does not, by itself, make that file available to the Retail AI Services runtime. Do not guess application codes or other environment identifiers. Obtain them from your administrator. The tool descriptions and schemas returned by the deployed server are authoritative.

Connecting with Codex

Configure Codex to connect to the Retail AI Services HTTPS endpoint. The following procedure applies to a local Codex client.

Before You Begin

Obtain the following information from your administrator:

Required Information	Description
MCP endpoint	The complete Retail AI Services MCP URL for your environment.
Authentication method	Whether the endpoint supports a compatible interactive OAuth connection or requires an administrator-provided bearer token.
Authorized identity	The user identity or registered application permitted to access the endpoint.
OAuth scope	The exact resource scope configured for this environment, when required for OAuth setup.
Token renewal procedure	How replacement tokens are obtained, or how renewal is managed for the connection, if using bearer tokens.
Application identifiers	Valid application codes and other context required by the tools you intend to use.
AI Client Setup	Install an organization-approved version of Codex that supports Streamable HTTP MCP connections. Confirm that your computer can reach the endpoint through the required network or VPN.

Configure the Server

Open the Codex configuration file, config.toml. The default user location is:

Windows: %USERPROFILE%\.codex\config.toml

macOS/Linux: ~/.codex/config.toml

Add a server entry and replace the endpoint placeholders with the values supplied by your administrator:

[mcp_servers.rais]
url = "https://<oracle-regional-domain>/<tenant-id>/app/rgbucommongenai/retailaiservices/mcp/"
startup_timeout_sec = 20
tool_timeout_sec = 60

Complete the applicable authentication procedure from the following sections.

Connect Using a Bearer Token

Use this procedure when your administrator supplies an access token or an approved method for obtaining one.

Make the access token available to the Codex process through the environment variable RAIS_MCP_ACCESS_TOKEN, using your organization’s approved credential-handling procedure.

Add the following setting to the server entry:

bearer_token_env_var = "RAIS_MCP_ACCESS_TOKEN"

Save the configuration and restart Codex from an environment containing the token.

An access token expires according to the lifetime returned by the identity service, typically 1 hour by default. The environment-variable setting supplies a token to Codex. It does not acquire or renew tokens. Updating a variable in another terminal does not update the environment of an already-running Codex process. Follow your administrator’s replacement and restart procedure when the token expires. For continuous use, your administrator must provide a supported connection that manages token renewal. Do not assume that a manually supplied token will remain valid throughout a long-running session.

Obtaining bearer tokens will follow the standard process for OCI IAM OAuth 2.0 authentication. You will need to call the OCI token API using the appropriate client credentials and retain the returned token for use with all subsequent calls to the MCP server. The scope for the client must follow the format rgbu:rais:RAIS-<environment><index>. For a typical production environment, this will be rgbu:rais:RAIS-PRD1. Creation of the client and management of credentials should be coordinated with your identity domain administrator.

Verify the Connection

Restart Codex if you have not done so after applying configuration changes, then enter /mcp to inspect the connection. Ask:

“List the tools available from the Retail AI Services MCP server and describe their required inputs.”

Confirm that the server returns a tool list. Then test an available tool with a simple request, such as:

“Use the Retail AI Services translation tool to translate ‘Blue cotton shirt’ from English into Spanish.”

Approve the tool request when prompted. Successful discovery confirms access to the MCP interface; successful execution also confirms that the selected tool’s dependencies are working.

Resolve Common Errors

Failure Type	Recommended Actions
Connection timeout	Check network access, VPN requirements, and the published endpoint URL.
HTTP 401	Check whether the token is missing, expired, or invalid. Follow the renewal procedure.
HTTP 403	Ask your administrator to verify the identity’s permissions, granted scopes, and expected token audience.
HTTP 404	Verify the domain, tenant identifier, server name, and trailing slash. Ask your administrator to confirm the deployed route.
Browser request returns 406	Test through Codex. Opening an MCP URL as a web page does not perform an MCP connection.
Tools are listed, but a request fails validation	Use the discovered tool requirements and provide any missing information.
A tool fails after discovery succeeds	Check the tool’s input, application context, and configured service dependencies with your administrator.