Skip to content

Commit c018120

Browse files
sandeepkhotsandeepkhot
committed
Database inspect agent V1
1 parent 45d1e5e commit c018120

3 files changed

Lines changed: 4416 additions & 0 deletions

File tree

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

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
# Select AI Inspect - Database Inspection Tool Built Using Select AI Agent
2+
3+
## Overview
4+
5+
Select AI Inspect is an AI-powered inspection tool built using the **Select AI Agent** framework. It enables users to explore, understand, and interact with database objects and their metadata using natural language.
6+
7+
### Use Cases
8+
9+
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:
10+
11+
* How are these tables related?
12+
* Why am I receiving this error from a function call?
13+
* What is this function used for?
14+
* What objects will be impacted if I modify this package?
15+
16+
Common use cases for Select AI Inspect include:
17+
18+
* **Code inspection and debugging** , particularly for unfamiliar or legacy code.
19+
* **Dependency analysis** , such as identifying which tables, functions, or packages would be affected by a change.
20+
* **Test case generation** for functions or procedures.
21+
* **Automatic documentation generation** based on source code and object metadata.
22+
23+
### Implementation
24+
25+
Select AI Inspect is delivered as the `DATABASE_INSPECT` PL/SQL package. It provides a set of APIs that allow users to create and configure AI agents to handle inspection and analysis tasks.
26+
27+
Users can create multiple agents, each scoped to a specific set of database objects. This enables flexible configuration for different environments, projects, or teams.
28+
29+
### Supported Object Types
30+
31+
Select AI Inspect supports the following database object types:
32+
33+
* Tables
34+
* Views
35+
* Types
36+
* Triggers
37+
* Functions
38+
* Procedures
39+
* Packages
40+
* Package Bodies
41+
* Schema
42+
43+
Users may define the inspection scope either at the individual object level or at the schema level. When a schema is specified, all supported object types within that schema are included.
44+
45+
---
46+
47+
## Architecture Overview
48+
49+
Run `database_inspect_tool.sql` to install `DATABASE_INSPECT` package and tools
50+
↓
51+
Run `database_inspect_agent.sql` to configure and create the inspect agent team
52+
↓
53+
execute `DATABASE_INSPECT.create_inspect_agent_team(<inspect_agent_team>, <attributes_in_json_object>)` to create an Inspect agent;
54+
↓
55+
User query
56+
↓
57+
<inspect_agent_team>
58+
↓
59+
Agent Reasoning
60+
├── LIST_OBJECTS
61+
├── LIST_INCOMING_DEPENDENCIES
62+
├── LIST_OUTGOING_DEPENDENCIES
63+
├── RETRIEVE_OBJECT_METADATA
64+
├── RETRIEVE_OBJECT_METADATA_CHUNKS
65+
├── EXPAND_OBJECT_METADATA_CHUNK
66+
├── SUMMARIZE_OBJECT
67+
└── GENERATE_PLDOC
68+
↓
69+
Final Verified Answer
70+
71+
---
72+
73+
## Repository Contents
74+
75+
```text
76+
.
77+
├── database_inspect_tool.sql
78+
│ ├── Installer script for DATABASE_INSPECT package and tool framework
79+
│ ├── Grants required privileges to the target schema
80+
│ └── Compiles package specification and body
81+
│
82+
├── database_inspect_agent.sql
83+
│ ├── Installer and configuration script for DATABASE_INSPECT AI team
84+
│ ├── Accepts target schema, AI profile, and optional team attributes
85+
│ └── Recreates the inspect team using DATABASE_INSPECT package APIs
86+
│
87+
├── README.md
88+
└── README_nl2sql.md
89+
```
90+
91+
---
92+
93+
## Supported APIs
94+
95+
##### create_inspect_agent_team
96+
97+
Creates an inspect agent team using the provided `attributes` such as `profile_name` and `object_list`.
98+
99+
```
100+
DATABASE_INSPECT.create_inspect_agent_team(
101+
agent_team_name IN VARCHAR2,
102+
attributes IN CLOB);
103+
```
104+
105+
**Syntax**
106+
107+
| argument | Description | Mandatory | value format |
108+
| :-------------: | ----------------------------- | --------- | ------------------------------------------------------------------------------------------------------------ |
109+
| agent_team_name | Name of the agent team | Y | |
110+
| attributes | Team configuration attributes | Y | JSON object CLOB, e.g.`{"profile_name":"openai_profile","object_list":[{"owner":"DEMO","type":"schema"}]}` |
111+
112+
**Attributes**
113+
114+
| attribute name | description | Mandatory | attribute value format |
115+
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------- |
116+
| profile_name | AI profile name for the agent team. | Y | |
117+
| 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. | Y | e.g.<br />'[{"owner":"DEMO", "type":"schema"}]'<br />'[{"owner":"DEMO", "type":"package body", "name":"CHECKOUT_PKG"}]' |
118+
| 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 |
119+
120+
##### drop_inspect_agent_team
121+
122+
Drop the specified inspect agent team.
123+
124+
```
125+
DATABASE_INSPECT.drop_inspect_agent_team(
126+
agent_team_name IN VARCHAR2,
127+
force IN BOOLEAN DEFAULT FALSE);
128+
```
129+
130+
**Syntax**
131+
132+
| argument | Description | Mandatory | value format |
133+
| :-------------: | ------------------------------------ | --------- | ------------ |
134+
| agent_team_name | Name of the agent team | Y | |
135+
| force | If `TRUE`, skip errors during drop | N | TRUE, FALSE |
136+
137+
##### update_inspect_agent_team
138+
139+
Update an inspect agent team’s attributes.
140+
141+
```
142+
DATABASE_INSPECT.update_inspect_agent_team(
143+
agent_team_name IN VARCHAR2,
144+
attributes IN CLOB);
145+
```
146+
147+
**Syntax**
148+
149+
| argument | Description | Mandatory | value format |
150+
| :-------------: | ----------------------------- | --------- | ------------------------------------------------------------------------------------------------------------ |
151+
| agent_team_name | Name of the agent team | Y | |
152+
| attributes | Team configuration attributes | Y | JSON object CLOB, e.g.`{"profile_name":"openai_profile","object_list":[{"owner":"DEMO","type":"schema"}]}` |
153+
154+
**Attributes**
155+
156+
| attribute name | description | Mandatory | attribute value format |
157+
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------- |
158+
| 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 | |
159+
| 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"}]' |
160+
| 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 |
161+
162+
163+
---
164+
165+
## Agent Setup
166+
167+
An inspection agent is created when you call `DATABASE_INSPECT.create_inspect_agent_team`.
168+
169+
### Supported Tools
170+
171+
* **list_objects**: List all available objects for the agent
172+
* **list_incoming_dependencies**: List objects that depend on or reference the given object
173+
* **list_outgoing_dependencies**: List objects that the given object itself depends on or references
174+
* **retrieve_object_metadata**: Retrieve the full metadata for the given object
175+
* **retrieve_object_metadata_chunks**: Retrieve a list of metadata chunks by performing hybrid search (vector search + Oracle Text search) to answer user’s query
176+
* **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
177+
* **generate_pldoc**: Generates a PLDoc/JavaDoc-style comment block (/** ... */) for a given object
178+
* **summarize_object**: Summarize the definition, purpose or behavior of the given object
179+
180+
---
181+
182+
## Example Prompts
183+
184+
We use a small but realistic product purchase order schema and some example prompts to show how you can use Selec AI Inspect agent to interact with your database.
185+
186+
This schema includes more than 10 tables, such as customers, products, orders, and tax rates, 3 standalone functions, including a tax-calculation function, and one package that contains the main checkout logic.
187+
188+
**Prompts**:
189+
190+
1. Show me all database objects available for us to inspect.
191+
2. Show me the column definitions for the PRODUCTS table, and list all database objects that reference or depend on it.
192+
3. If I rename the active_flag column in the PRODUCTS table to is_active, where do I need to update the code?
193+
4. Explain what the CHECKOUT_PKG.reprice_order procedure is used for, including its purpose, parameters and business rules.
194+
5. Can you write and run a test script for the calc_tax_amount function to verify the results and check for any bugs?
195+
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.

0 commit comments

Comments
 (0)