Skip to content

Database inspect v2 #75

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jpmc-github merged 2 commits into from
Mar 31, 2026
Merged

Database inspect v2 #75

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ad50295
Database Inspect agent v2
sandeepkhot Mar 31, 2026
ab3e90a
Database Inspect agent v2
sandeepkhot Mar 31, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
185 changes: 140 additions & 45 deletions autonomous-ai-agents/database_inspect/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Select AI Inspect - Database Inspection Tool Built Using Select AI Agent (26ai)
# Select AI Inspect - Database Inspection Tool Built Using Select AI Agent

## Overview

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

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:

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

## Prerequisites

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

---

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

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

You can also execute the contents of `database_inspect_tool.sql` and `database_inspect_agent.sql` in SQL Worksheet.
`database_inspect_agent.sql` uses interactive prompts, so run it as a script instead of copy/pasting individual statements into a worksheet.

### Step 1: Install `DATABASE_INSPECT` Package and Tool Framework

Run `database_inspect_tool.sql` first.

The script prompts for:

- `SCHEMA_NAME`: target schema where `DATABASE_INSPECT` is compiled

What the tools installer does:

- Grants required execute privileges to the target schema
- Switches `CURRENT_SCHEMA` to the target schema
- Compiles the `DATABASE_INSPECT` package specification and body inline
- Is safe to rerun

Notes:

- 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`.
- 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.

### Step 2: Create or Recreate the Inspect Agent Team

Run `database_inspect_agent.sql` after the package is installed.

The script prompts for:

- `INSTALL_SCHEMA_NAME`: schema where the team is created
- `AI_PROFILE_NAME`: profile used for reasoning and embeddings
- `AGENT_TEAM_NAME`: team name to create
- `RECREATE_EXISTING`: `Y` to drop and recreate an existing team, otherwise `N`
- `SCOPE_MODE`: guided scope mode; supported values are `SCHEMA`, `TABLE`, `PACKAGE`, and `JSON`
- `SCOPE_OWNERS`: use this for `SCHEMA` mode; enter one or more schema owners separated by commas, or leave blank to use `INSTALL_SCHEMA_NAME`
- `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`
- `OBJECT_NAMES`: use this for `TABLE` or `PACKAGE` mode; enter one or more object names separated by commas
- `MATCH_LIMIT`: optional
- `TEAM_ATTRIBUTES_JSON`: use this for `JSON` mode

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.

Guided input examples:

- Single schema scope:
`SCOPE_MODE = SCHEMA`
`SCOPE_OWNERS = <INSTALL_SCHEMA_NAME>`
- Multiple schema owners:
`SCOPE_MODE = SCHEMA`
`SCOPE_OWNERS = SH,HR`
- Multiple tables in one schema:
`SCOPE_MODE = TABLE`
`OBJECT_OWNER = SH`
`OBJECT_NAMES = SALES,CUSTOMERS,PRODUCTS`
- Multiple packages in one schema:
`SCOPE_MODE = PACKAGE`
`OBJECT_OWNER = HR`
`OBJECT_NAMES = EMP_PKG,PAYROLL_PKG`

Advanced `TEAM_ATTRIBUTES_JSON` example for JSON mode:

```json
{"object_list":[
{"owner":"SH","type":"TABLE","name":"SALES"},
{"owner":"SH","type":"TABLE","name":"CUSTOMERS"},
{"owner":"SH","type":"TABLE","name":"PRODUCTS"}
]}
```

What the agent installer does:

- Grants required privileges for agent creation and background jobs, including `CREATE JOB`, `CREATE SEQUENCE`, `CREATE PROCEDURE`, and `CREATE VIEW`
- Creates `DATABASE_INSPECT_AGENT_JOB_LOG$` in the target schema
- Creates submitter and worker procedures in the target schema
- Validates that `AI_PROFILE_NAME` has a non-null `embedding_model`
- Requires `AI_PROFILE_NAME` to include `oci_compartment_id` when the profile uses an OCI Generative AI model/provider
- Enforces `AI_PROFILE_NAME` as `profile_name`, even if `TEAM_ATTRIBUTES_JSON` includes a different value
- Converts common installation failures into user-friendly log messages, including missing OCI compartment id, tablespace quota errors, and embedding-dimension mismatch errors
- Verifies that the expected agent tools were recreated successfully

`RECREATE_EXISTING = Y` behavior:

- Cleans up any existing Select AI team, agent, and task objects for the requested team name
- Drops the existing team metadata and vectorized object state
- Recreates the team using the resolved attributes

### Monitoring Background Installation

Each submission writes one row to `DATABASE_INSPECT_AGENT_JOB_LOG$`.

Use a query like this to monitor progress:

```sql
SELECT *
FROM <INSTALL_SCHEMA_NAME>.DATABASE_INSPECT_AGENT_JOB_LOG$
ORDER BY run_id DESC;
```

Typical statuses include `PRECHECK`, `QUEUED`, `RUNNING`, `SUCCEEDED`, `FAILED`, `TEAM_EXISTS`, and `FAILED_TO_QUEUE`.

---

## Architecture Overview

```text
Run database_inspect_tool.sql to install DATABASE_INSPECT package and tools
|
v
Run database_inspect_agent.sql to configure and create the inspect agent team
|
v
Execute DATABASE_INSPECT.create_inspect_agent_team(<inspect_agent_team>, <attributes_in_json_object>)
to create an inspect agent
|
v
Run `database_inspect_tool.sql` to install the `DATABASE_INSPECT` package and prerequisites
↓
Run `database_inspect_agent.sql` to validate inputs and queue background installation
↓
`DATABASE_INSPECT_AGENT_WORKER`
├── Ensures `DATABASE_INSPECT.setup` completed
├── Validates profile and attributes
├── Optionally drops and recreates existing team state
└── Creates tools, task, team, and vectorized object metadata
↓
User query
|
v
↓
<inspect_agent_team>
|
v
Agent reasoning
|
+-- LIST_OBJECTS
+-- LIST_INCOMING_DEPENDENCIES
+-- LIST_OUTGOING_DEPENDENCIES
+-- RETRIEVE_OBJECT_METADATA
+-- RETRIEVE_OBJECT_METADATA_CHUNKS
+-- EXPAND_OBJECT_METADATA_CHUNK
+-- SUMMARIZE_OBJECT
`-- GENERATE_PLDOC
|
v
Final verified answer
```
↓
Agent Reasoning
├── LIST_OBJECTS
├── LIST_INCOMING_DEPENDENCIES
├── LIST_OUTGOING_DEPENDENCIES
├── RETRIEVE_OBJECT_METADATA
├── RETRIEVE_OBJECT_METADATA_CHUNKS
├── EXPAND_OBJECT_METADATA_CHUNK
├── SUMMARIZE_OBJECT
└── GENERATE_PLDOC
↓
Final Verified Answer

---

Expand All @@ -121,12 +215,14 @@ Final verified answer
├── database_inspect_tool.sql
│ ├── Installer script for DATABASE_INSPECT package and tool framework
│ ├── Grants required privileges to the target schema
│ └── Compiles package specification and body
│ ├── Compiles package specification and body
│ └── Leaves internal table setup to target-schema execution
│
├── database_inspect_agent.sql
│ ├── Installer and configuration script for DATABASE_INSPECT AI team
│ ├── Accepts target schema, AI profile, and optional team attributes
│ └── Recreates the inspect team using DATABASE_INSPECT package APIs
│ ├── Accepts target schema, AI profile, team name, recreate flag, and optional team attributes
│ ├── Logs asynchronous installation progress to DATABASE_INSPECT_AGENT_JOB_LOG$
│ └── Creates or recreates the inspect team using background job execution
│
├── README.md
└── README_nl2sql.md
Expand Down Expand Up @@ -199,23 +295,21 @@ DATABASE_INSPECT.update_inspect_agent_team(

| attribute name | description | Mandatory | attribute value format |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------- |
| 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 | |
| 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 | |
| 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"}]' |
| 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 |


---

## Agent Setup

An inspection agent is created when you call `DATABASE_INSPECT.create_inspect_agent_team`.
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.

### Supported Tools

* **list_objects**: List all available objects for the agent
* **list_incoming_dependencies**: List objects that depend on or reference the given object
* **list_outgoing_dependencies**: List objects that the given object itself depends on or references
* **generate_graph**: Generate relationship visualizations as Mermaid graph syntax or HTML/CSS tree markup (dependency, hierarchy, binary-tree style, network)
* **retrieve_object_metadata**: Retrieve the full metadata for the given object
* **retrieve_object_metadata_chunks**: Retrieve a list of metadata chunks by performing hybrid search (vector search + Oracle Text search) to answer user’s query
* **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
Expand All @@ -238,14 +332,15 @@ This schema includes more than 10 tables, such as customers, products, orders, a
4. Explain what the CHECKOUT_PKG.reprice_order procedure is used for, including its purpose, parameters and business rules.
5. Can you write and run a test script for the calc_tax_amount function to verify the results and check for any bugs?
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.
7. Please show me a dependency graph for my table relationships.
8. Show the object call hierarchy as a binary-tree style diagram.
9. Render the outgoing dependency hierarchy as HTML + CSS tree markup for my web app.
7. Summarize the CHECKOUT_PKG package body in one paragraph.
8. Generate PLDoc comments for the calc_tax_amount function.
9. Which packages and procedures will be impacted if I modify the ORDERS table?
10.Get me a list of tables available for inspection.

---

## License

Universal Permissive License (UPL) 1.0
Universal Permissive License (UPL) 1.0
https://oss.oracle.com/licenses/upl/
Copyright (c) 2026 Oracle and/or its affiliates.
Loading