Add Oracle database tools for the agent framework, enabling LLM agents to query and discover Oracle database schemas

[Viphava280444]

Key changes

New files:

• oracle_connection.py — Manages Oracle DB connections. Handles DSN, credentials from .env, schema
  allowlists, timeouts, and thick mode for CERN NNE.
• oracle_query.py — Two LangChain tools: query_oracle_db (read-only SQL with safety checks) and
  describe_oracle_schema (list databases/tables/columns). Includes error hints for common Oracle errors so
  the LLM can self-correct.
• oracle_safety.py — SQL validation: blocks non-SELECT statements, enforces schema allowlists, injects
  row limits.

Modified files:

• cms_comp_ops_agent.py — Wires up Oracle tools when services.chat_app.tools.oracle_databases is
  configured.
• tools/init.py — Exports Oracle tool factories.
• Dockerfile-chat — Installs oracledb and Oracle Instant Client when INSTALL_ORACLE=true.
• templates_manager.py — Auto-detects Oracle config to set the build arg.
• base-config.yaml — Oracle config passes through via {{ services.chat_app.tools | tojson }}.
• pyproject.toml — Adds oracledb as optional dependency.

Oracle databases are configured under services.chat_app.tools.oracle_databases

services:
 chat_app:
   tools:
     oracle_databases:
       tier0_replay2:
         dsn: "int2r-s.cern.ch:10121/int2r_nolb.cern.ch"
         user: "CMS_T0AST_REPLAY2"                         # TODO: replace with real user
         password_secret: "ORACLE_T0_PASSWORD"     # env var or Docker secret
         description: "Tier-0 replay database"
         allowed_schemas:
           - CMS_T0AST_REPLAY2
         max_rows: 200
         query_timeout_seconds: 30

       tier0_replay3:
         dsn: "int2r-s.cern.ch:10121/int2r_nolb.cern.ch"
         user: "CMS_T0AST_REPLAY3"                         # TODO: replace with real user
         password_secret: "ORACLE_T0_PASSWORD"     # env var or Docker secret
         description: "Tier-0 replay database"
         allowed_schemas:
           - CMS_T0AST_REPLAY3
         max_rows: 200
         query_timeout_seconds: 30

       tier0_replay1:
         dsn: "int2r-s.cern.ch:10121/int2r_nolb.cern.ch"
         user: "CMS_T0AST_REPLAY1"                         # TODO: replace with real user
         password_secret: "ORACLE_T0_PASSWORD"     # env var or Docker secret
         description: "Tier-0 replay database"
         allowed_schemas:
           - CMS_T0AST_REPLAY1
         max_rows: 200
         query_timeout_seconds: 30

Examples

Example 1

Example 2

Example 3

Example 4

[lucalavezzo]

why do we need this outside the container?

[Viphava280444]

You're right, no need for it outside the chat container. I'll remove it.

[lucalavezzo]

tools are determined via the agents.md now, so i think this wouldn't work.

but I agree with your concern about installing oracle in the docker even if you don't want it. How large / slow is this?

another option would be to set up an external MCP server, and ping it?

[Viphava280444]

My thinking was to install oracledb only when it's needed to keep the container lightweight. I use thick mode by default because the CERN Oracle databases require it and it will cover everything if we use this mode(thin mode). So the size of package is about 145 MB.
I haven't looked into the MCP server approach yet, but I'll have a look.

[haozturk]

@LinaresToine can you please take a look at this from the Tier0 angle? I'm curious what you think about this

[LinaresToine]

Thanks for pinging me @haozturk. I really like this feature, I can see it being of great use for Tier-0 day to day operations. Thank you @Viphava280444.

What is the cost of this tool? I mean, would it require heavy use of the higher-end models?

[LinaresToine]

@haozturk @Viphava280444 I would also like to point out that this tool is not to be used blindly. There are cases in which the operator needs to be very critical of what is going on. One example is for data invalidation whenever we must reprocess something. Although this is unlikely now with the Run3 coming to an end, I think it is valuable to keep such cases in mind.

[haozturk]

Why have you added these host_mode conditionals? How are they relevant to the purpose of this PR?

[Viphava280444]

Hi Hasan, No, it's not directly relevant to this PR. I added it in the build section as an ad hoc solution because when I tried to install Archi on a Tier 0 machine, it couldn't build the image. Somehow, Docker's network on the Tier 0 machine behaves differently and needs host mode to reach the network to install packages (pip install, apt install, etc.).

[Viphava280444]

I can remove them once I finish development on this PR, since I still need to deploy it on Tier 0 for testing the Oracle tool.

[Viphava280444]

Thanks for pinging me @haozturk. I really like this feature, I can see it being of great use for Tier-0 day to day operations. Thank you @Viphava280444.

What is the cost of this tool? I mean, would it require heavy use of the higher-end models?

Hi @LinaresToine, No, it doesn't require heavy use of a higher-end model. It just needs the same model to call this tool as it does for the other tools.

[Viphava280444]

@haozturk @Viphava280444 I would also like to point out that this tool is not to be used blindly. There are cases in which the operator needs to be very critical of what is going on. One example is for data invalidation whenever we must reprocess something. Although this is unlikely now with the Run3 coming to an end, I think it is valuable to keep such cases in mind.

@LinaresToine Thank you for pointing this out Antonio. Yesterday, I modified the output of the tool to also show the query that the AI uses, so that people can validate it for correctness.