Skip to content

Commit 2df0fca

Browse files
jpmc-githubjpmc-github
authored
Merge pull request #75 from sandeepkhot/DATABASE_INSPECT_V2
Database inspect v2
2 parents d65271e + ab3e90a commit 2df0fca

File tree

3 files changed

+1679
-530
lines changed

3 files changed

+1679
-530
lines changed

‎autonomous-ai-agents/database_inspect/README.md‎

Lines changed: 140 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Select AI Inspect - Database Inspection Tool Built Using Select AI Agent (26ai)
1+
# Select AI Inspect - Database Inspection Tool Built Using Select AI Agent
22

33
## Overview
44

@@ -11,7 +11,7 @@ For definitions of **Tool**, **Task**, **Agent**, and **Agent Team**, see the to
1111

1212
Instead of manually reviewing tables, searching through PL/SQL files, or examining function and procedure metadata, users can simply ask the Select AI Inspect agent natural language questions such as:
1313

14-
* How are these tables related?
14+
* Which objects reference this table?
1515
* Why am I receiving this error from a function call?
1616
* What is this function used for?
1717
* What objects will be impacted if I modify this package?
@@ -36,6 +36,7 @@ Select AI Inspect supports the following database object types:
3636
* Tables
3737
* Views
3838
* Types
39+
* Type Bodies
3940
* Triggers
4041
* Functions
4142
* Procedures
@@ -49,10 +50,12 @@ Users may define the inspection scope either at the individual object level or a
4950

5051
## Prerequisites
5152

52-
- Oracle Database 26ai (Autonomous AI Database supported)
53+
- Oracle Autonomous AI Database (26ai)
5354
- Select AI and `DBMS_CLOUD_AI_AGENT` enabled
5455
- `ADMIN` or equivalent privileged user for installation
5556
- A Select AI profile created with `DBMS_CLOUD_AI.CREATE_PROFILE`
57+
- The Select AI profile used for inspection must include an `embedding_model` attribute
58+
- If the Select AI profile uses an OCI Generative AI model/provider, it must also include `oci_compartment_id`
5659

5760
---
5861

@@ -64,7 +67,7 @@ Before running installation commands:
6467
2. Open a terminal and change directory to `autonomous-ai-agents/database_inspect`.
6568
3. Choose one execution mode:
6669
- SQL*Plus/SQLcl: run script files directly with `@script_name`.
67-
- SQL Worksheet (Database Actions or other SQL IDE): open the `.sql` file and run/paste its contents.
70+
- SQL Developer or another SQL IDE: run the file in script mode so interactive prompts are shown.
6871
4. Uploading scripts to `DATA_PUMP_DIR` is not required for these methods.
6972

7073
Run as `ADMIN` (or another privileged user):
@@ -74,43 +77,134 @@ sqlplus admin@<adb_connect_string> @database_inspect_tool.sql
7477
sqlplus admin@<adb_connect_string> @database_inspect_agent.sql
7578
```
7679

77-
You can also execute the contents of `database_inspect_tool.sql` and `database_inspect_agent.sql` in SQL Worksheet.
80+
`database_inspect_agent.sql` uses interactive prompts, so run it as a script instead of copy/pasting individual statements into a worksheet.
81+
82+
### Step 1: Install `DATABASE_INSPECT` Package and Tool Framework
83+
84+
Run `database_inspect_tool.sql` first.
85+
86+
The script prompts for:
87+
88+
- `SCHEMA_NAME`: target schema where `DATABASE_INSPECT` is compiled
89+
90+
What the tools installer does:
91+
92+
- Grants required execute privileges to the target schema
93+
- Switches `CURRENT_SCHEMA` to the target schema
94+
- Compiles the `DATABASE_INSPECT` package specification and body inline
95+
- Is safe to rerun
96+
97+
Notes:
98+
99+
- The tools installer no longer executes `DATABASE_INSPECT.setup` directly from an `ADMIN` anonymous block. This avoids `ORA-06598` when the package is `AUTHID CURRENT_USER`.
100+
- Internal `DATABASE_INSPECT` tables are initialized from the target-schema execution path when the package is invoked by the agent installer or by direct package usage in the target schema.
101+
102+
### Step 2: Create or Recreate the Inspect Agent Team
103+
104+
Run `database_inspect_agent.sql` after the package is installed.
105+
106+
The script prompts for:
107+
108+
- `INSTALL_SCHEMA_NAME`: schema where the team is created
109+
- `AI_PROFILE_NAME`: profile used for reasoning and embeddings
110+
- `AGENT_TEAM_NAME`: team name to create
111+
- `RECREATE_EXISTING`: `Y` to drop and recreate an existing team, otherwise `N`
112+
- `SCOPE_MODE`: guided scope mode; supported values are `SCHEMA`, `TABLE`, `PACKAGE`, and `JSON`
113+
- `SCOPE_OWNERS`: use this for `SCHEMA` mode; enter one or more schema owners separated by commas, or leave blank to use `INSTALL_SCHEMA_NAME`
114+
- `OBJECT_OWNER`: use this for `TABLE` or `PACKAGE` mode; enter the owner/schema of the listed objects, or leave blank to use `INSTALL_SCHEMA_NAME`
115+
- `OBJECT_NAMES`: use this for `TABLE` or `PACKAGE` mode; enter one or more object names separated by commas
116+
- `MATCH_LIMIT`: optional
117+
- `TEAM_ATTRIBUTES_JSON`: use this for `JSON` mode
118+
119+
The script now shows one simple input section for these values. Enter only the fields that apply to the selected `SCOPE_MODE` and leave the others blank.
120+
121+
Guided input examples:
122+
123+
- Single schema scope:
124+
`SCOPE_MODE = SCHEMA`
125+
`SCOPE_OWNERS = <INSTALL_SCHEMA_NAME>`
126+
- Multiple schema owners:
127+
`SCOPE_MODE = SCHEMA`
128+
`SCOPE_OWNERS = SH,HR`
129+
- Multiple tables in one schema:
130+
`SCOPE_MODE = TABLE`
131+
`OBJECT_OWNER = SH`
132+
`OBJECT_NAMES = SALES,CUSTOMERS,PRODUCTS`
133+
- Multiple packages in one schema:
134+
`SCOPE_MODE = PACKAGE`
135+
`OBJECT_OWNER = HR`
136+
`OBJECT_NAMES = EMP_PKG,PAYROLL_PKG`
137+
138+
Advanced `TEAM_ATTRIBUTES_JSON` example for JSON mode:
139+
140+
```json
141+
{"object_list":[
142+
{"owner":"SH","type":"TABLE","name":"SALES"},
143+
{"owner":"SH","type":"TABLE","name":"CUSTOMERS"},
144+
{"owner":"SH","type":"TABLE","name":"PRODUCTS"}
145+
]}
146+
```
147+
148+
What the agent installer does:
149+
150+
- Grants required privileges for agent creation and background jobs, including `CREATE JOB`, `CREATE SEQUENCE`, `CREATE PROCEDURE`, and `CREATE VIEW`
151+
- Creates `DATABASE_INSPECT_AGENT_JOB_LOG$` in the target schema
152+
- Creates submitter and worker procedures in the target schema
153+
- Validates that `AI_PROFILE_NAME` has a non-null `embedding_model`
154+
- Requires `AI_PROFILE_NAME` to include `oci_compartment_id` when the profile uses an OCI Generative AI model/provider
155+
- Enforces `AI_PROFILE_NAME` as `profile_name`, even if `TEAM_ATTRIBUTES_JSON` includes a different value
156+
- Converts common installation failures into user-friendly log messages, including missing OCI compartment id, tablespace quota errors, and embedding-dimension mismatch errors
157+
- Verifies that the expected agent tools were recreated successfully
158+
159+
`RECREATE_EXISTING = Y` behavior:
160+
161+
- Cleans up any existing Select AI team, agent, and task objects for the requested team name
162+
- Drops the existing team metadata and vectorized object state
163+
- Recreates the team using the resolved attributes
164+
165+
### Monitoring Background Installation
166+
167+
Each submission writes one row to `DATABASE_INSPECT_AGENT_JOB_LOG$`.
168+
169+
Use a query like this to monitor progress:
170+
171+
```sql
172+
SELECT *
173+
FROM <INSTALL_SCHEMA_NAME>.DATABASE_INSPECT_AGENT_JOB_LOG$
174+
ORDER BY run_id DESC;
175+
```
176+
177+
Typical statuses include `PRECHECK`, `QUEUED`, `RUNNING`, `SUCCEEDED`, `FAILED`, `TEAM_EXISTS`, and `FAILED_TO_QUEUE`.
78178

79179
---
80180

81181
## Architecture Overview
82182

83-
```text
84-
Run database_inspect_tool.sql to install DATABASE_INSPECT package and tools
85-
|
86-
v
87-
Run database_inspect_agent.sql to configure and create the inspect agent team
88-
|
89-
v
90-
Execute DATABASE_INSPECT.create_inspect_agent_team(<inspect_agent_team>, <attributes_in_json_object>)
91-
to create an inspect agent
92-
|
93-
v
183+
Run `database_inspect_tool.sql` to install the `DATABASE_INSPECT` package and prerequisites
184+
↓
185+
Run `database_inspect_agent.sql` to validate inputs and queue background installation
186+
↓
187+
`DATABASE_INSPECT_AGENT_WORKER`
188+
├── Ensures `DATABASE_INSPECT.setup` completed
189+
├── Validates profile and attributes
190+
├── Optionally drops and recreates existing team state
191+
└── Creates tools, task, team, and vectorized object metadata
192+
↓
94193
User query
95-
|
96-
v
194+
↓
97195
<inspect_agent_team>
98-
|
99-
v
100-
Agent reasoning
101-
|
102-
+-- LIST_OBJECTS
103-
+-- LIST_INCOMING_DEPENDENCIES
104-
+-- LIST_OUTGOING_DEPENDENCIES
105-
+-- RETRIEVE_OBJECT_METADATA
106-
+-- RETRIEVE_OBJECT_METADATA_CHUNKS
107-
+-- EXPAND_OBJECT_METADATA_CHUNK
108-
+-- SUMMARIZE_OBJECT
109-
`-- GENERATE_PLDOC
110-
|
111-
v
112-
Final verified answer
113-
```
196+
↓
197+
Agent Reasoning
198+
├── LIST_OBJECTS
199+
├── LIST_INCOMING_DEPENDENCIES
200+
├── LIST_OUTGOING_DEPENDENCIES
201+
├── RETRIEVE_OBJECT_METADATA
202+
├── RETRIEVE_OBJECT_METADATA_CHUNKS
203+
├── EXPAND_OBJECT_METADATA_CHUNK
204+
├── SUMMARIZE_OBJECT
205+
└── GENERATE_PLDOC
206+
↓
207+
Final Verified Answer
114208

115209
---
116210

@@ -121,12 +215,14 @@ Final verified answer
121215
├── database_inspect_tool.sql
122216
│ ├── Installer script for DATABASE_INSPECT package and tool framework
123217
│ ├── Grants required privileges to the target schema
124-
│ └── Compiles package specification and body
218+
│ ├── Compiles package specification and body
219+
│ └── Leaves internal table setup to target-schema execution
125220
│
126221
├── database_inspect_agent.sql
127222
│ ├── Installer and configuration script for DATABASE_INSPECT AI team
128-
│ ├── Accepts target schema, AI profile, and optional team attributes
129-
│ └── Recreates the inspect team using DATABASE_INSPECT package APIs
223+
│ ├── Accepts target schema, AI profile, team name, recreate flag, and optional team attributes
224+
│ ├── Logs asynchronous installation progress to DATABASE_INSPECT_AGENT_JOB_LOG$
225+
│ └── Creates or recreates the inspect team using background job execution
130226
│
131227
├── README.md
132228
└── README_nl2sql.md
@@ -199,23 +295,21 @@ DATABASE_INSPECT.update_inspect_agent_team(
199295

200296
| attribute name | description | Mandatory | attribute value format |
201297
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------- |
202-
| profile_name | AI profile name for the agent team. If provided, the exisiting profile_name value will be overwritten. If a different AI provider is specified, the `object_list` will be re-vectorized due to embedding dimension mismatches. | N | |
298+
| profile_name | AI profile name for the agent team. If provided, the exisiting profile_name value will be overwritten. Any profile change triggers re-vectorization of the `object_list`, because embedding dimensions or similarity semantics can change even within the same provider. | N | |
203299
| object_list | List of database objects the agent team is allowed to inspect.<br />Support "owner", "type" and optional "name" for the object. if "name" is not provided, we will set all objects in the schema.<br />If provided, the original object_list will be removed and the new object_list will be vectorized. | N | e.g.<br />'[{"owner":"DEMO", "type":"schema"}]'<br />'[{"owner":"DEMO", "type":"package body", "name":"CHECKOUT_PKG"}]' |
204300
| match_limit | Specifies the maximum number of results to return in a hybrid/vector search query from RETRIEVE_OBJECT_METADATA agent tool. | N | default value is 10 |
205301

206-
207302
---
208303

209304
## Agent Setup
210305

211-
An inspection agent is created when you call `DATABASE_INSPECT.create_inspect_agent_team`.
306+
An inspection agent can be created directly by calling `DATABASE_INSPECT.create_inspect_agent_team`, but the recommended installation path is to use `database_inspect_agent.sql` so that setup, validation, logging, and background execution are handled for you.
212307

213308
### Supported Tools
214309

215310
* **list_objects**: List all available objects for the agent
216311
* **list_incoming_dependencies**: List objects that depend on or reference the given object
217312
* **list_outgoing_dependencies**: List objects that the given object itself depends on or references
218-
* **generate_graph**: Generate relationship visualizations as Mermaid graph syntax or HTML/CSS tree markup (dependency, hierarchy, binary-tree style, network)
219313
* **retrieve_object_metadata**: Retrieve the full metadata for the given object
220314
* **retrieve_object_metadata_chunks**: Retrieve a list of metadata chunks by performing hybrid search (vector search + Oracle Text search) to answer user’s query
221315
* **expand_object_metadata_chunk**: Given a selected result from the retrieve_object_metadata_chunks tool, returns an expanded metadata segment around the specified chunk to provide additional context
@@ -238,14 +332,15 @@ This schema includes more than 10 tables, such as customers, products, orders, a
238332
4. Explain what the CHECKOUT_PKG.reprice_order procedure is used for, including its purpose, parameters and business rules.
239333
5. Can you write and run a test script for the calc_tax_amount function to verify the results and check for any bugs?
240334
6. When I call the calc_tax_amount function, for state_code = 'CA' (rate 0.0825), calc_tax_amount(10.01, 'CA') returns 0.82, but it should return 0.83. Please debug the function and show me the exact code that needs to be fixed.
241-
7. Please show me a dependency graph for my table relationships.
242-
8. Show the object call hierarchy as a binary-tree style diagram.
243-
9. Render the outgoing dependency hierarchy as HTML + CSS tree markup for my web app.
335+
7. Summarize the CHECKOUT_PKG package body in one paragraph.
336+
8. Generate PLDoc comments for the calc_tax_amount function.
337+
9. Which packages and procedures will be impacted if I modify the ORDERS table?
338+
10.Get me a list of tables available for inspection.
244339

245340
---
246341

247342
## License
248343

249-
Universal Permissive License (UPL) 1.0
344+
Universal Permissive License (UPL) 1.0
250345
https://oss.oracle.com/licenses/upl/
251346
Copyright (c) 2026 Oracle and/or its affiliates.

0 commit comments

Comments
 (0)