oracle-devrel · anshoracle · Oct 20, 2025 · Oct 20, 2025
diff --git a/ai/gen-ai-agents/sql_graph_generator_dashboard/LICENSE.txt b/ai/gen-ai-agents/sql_graph_generator_dashboard/LICENSE.txt
@@ -0,0 +1,35 @@
+Copyright (c) 2025 Oracle and/or its affiliates.
+
+The Universal Permissive License (UPL), Version 1.0
+
+Subject to the condition set forth below, permission is hereby granted to any
+person obtaining a copy of this software, associated documentation and/or data
+(collectively the "Software"), free of charge and under any and all copyright
+rights in the Software, and any and all patent rights owned or freely
+licensable by each licensor hereunder covering either (i) the unmodified
+Software as contributed to or provided by such licensor, or (ii) the Larger
+Works (as defined below), to deal in both
+
+(a) the Software, and
+(b) any piece of software and/or hardware listed in the lrgrwrks.txt file if
+one is included with the Software (each a "Larger Work" to which the Software
+is contributed by such licensors),
+
+without restriction, including without limitation the rights to copy, create
+derivative works of, display, perform, and distribute the Software and make,
+use, sell, offer for sale, import, export, have made, and have sold the
+Software and the Larger Work(s), and to sublicense the foregoing rights on
+either these or other terms.
+
+This license is subject to the following condition:
+The above copyright notice and either this complete permission notice or at
+a minimum a reference to the UPL must be included in all copies or
+substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/ai/gen-ai-agents/sql_graph_generator_dashboard/README.md b/ai/gen-ai-agents/sql_graph_generator_dashboard/README.md
@@ -0,0 +1,231 @@
+# SQL Graph Generator Dashboard
+
+SQL Graph Generator Dashboard is an AI-powered assistant that enables natural language database queries and intelligent chart generation.
+It extracts data from your database using conversational queries, automatically generates appropriate visualizations, and provides multi-turn conversational context for data exploration.
+It runs as an interactive Next.js web app backed by a FastAPI server, LangChain orchestration, and Oracle Cloud Infrastructure GenAI models.
+
+Reviewed: October 13, 2025
+
+# When to use this asset?
+
+Use this asset when you want to:
+
+- Query databases using natural language instead of SQL
+- Automatically generate charts and visualizations from query results
+- Build conversational data exploration interfaces
+- Integrate OCI GenAI models with database operations
+- Demonstrate intelligent routing between data queries, visualizations, and insights
+
+Ideal for:
+
+- AI engineers building conversational data analytics tools
+- Data teams needing natural language database interfaces
+- OCI customers integrating GenAI into business intelligence workflows
+- Anyone showcasing LangChain + OCI GenAI + dynamic visualization generation
+
+# How to use this asset?
+
+This assistant can be launched via:
+
+- Next.js Web UI
+
+It supports:
+
+- Natural language to SQL conversion
+- Automatic chart generation from query results
+- Multi-turn conversations with context preservation
+- Multiple chart types: bar, line, pie, scatter, heatmap
+- Real-time data visualization using matplotlib/seaborn
+- Intelligent routing between data queries, visualizations, and insights
+
+## Setup Instructions
+
+### OCI Generative AI Model Configuration
+
+1. Go to: OCI Console → Generative AI
+2. Select your model (this demo uses OpenAI GPT OSS 120B):
+   `ocid1.generativeaimodel.oc1.eu-frankfurt-1.amaaaaaask7dceyav...`
+3. Set up an OCI Agent Runtime endpoint for SQL queries
+4. Copy the following values:
+   - MODEL_ID
+   - AGENT_ENDPOINT_ID
+   - COMPARTMENT_ID
+   - SERVICE_ENDPOINT (e.g., `https://inference.generativeai.eu-frankfurt-1.oci.oraclecloud.com`)
+5. Configure them in `backend/utils/config.py`
+
+Documentation:
+[OCI Generative AI Documentation](https://docs.oracle.com/en-us/iaas/Content/generative-ai/home.htm)
+
+No API key is required — authentication is handled via OCI identity.
+
+Ensure your OCI CLI credentials are configured.
+Edit or create the following config file at `~/.oci/config`:
+
+```
+[DEFAULT]
+user=ocid1.user.oc1..exampleuniqueID
+fingerprint=c6:4f:66:e7:xx:xx:xx:xx
+tenancy=ocid1.tenancy.oc1..exampleuniqueID
+region=eu-frankfurt-1
+key_file=~/.oci/oci_api_key.pem
+```
+
+### Install Dependencies
+
+Backend:
+
+```bash
+cd backend
+pip install -r requirements.txt
+```
+
+Frontend:
+
+```bash
+cd ..
+npm install
+```
+
+### Configure Database
+
+1. Set up your database connection in OCI Agent Runtime
+2. The demo uses a sample e-commerce database with tables:
+   - orders
+   - customers
+   - products
+   - order_items
+
+### Start the Application
+
+Backend (FastAPI):
+
+```bash
+cd backend
+python -m uvicorn api.main:app --reload --host 0.0.0.0 --port 8000
+```
+
+Frontend (Next.js):
+
+```bash
+npm run dev
+```
+
+Access the application at: http://localhost:3000
+
+## Key Features
+
+| Feature                  | Description                                                      |
+| ------------------------ | ---------------------------------------------------------------- |
+| Natural Language Queries | Ask questions like "show me the top 5 orders"                    |
+| Intelligent Routing      | GenAI-powered routing between data queries, charts, and insights |
+| Auto Chart Generation    | Automatically creates appropriate visualizations from data       |
+| Multi-Turn Conversations | Maintains context across multiple queries                        |
+| Real-Time Visualization  | Generates matplotlib/seaborn charts as base64 images             |
+| Multiple Chart Types     | Supports bar, line, pie, scatter, and heatmap charts             |
+| OCI GenAI Integration    | Uses OCI Agent Runtime and Chat API                              |
+| LangChain Runnables      | Clean integration pattern wrapping OCI SDK calls                 |
+| Conversation Management  | Tracks query history and data state                              |
+| Error Handling           | Clear error messages and fallback behavior                       |
+
+## Architecture
+
+### Backend Components
+
+1. **Router Agent** (OCI Chat API)
+
+   - Intelligent query routing using GenAI
+   - Routes: DATA_QUERY, CHART_EDIT, INSIGHT_QA
+   - Returns structured JSON decisions
+
+2. **SQL Agent** (OCI Agent Runtime)
+
+   - Natural language to SQL conversion
+   - Database query execution
+   - Structured data extraction
+
+3. **Chart Generator** (OCI Chat API + Python Execution)
+
+   - GenAI generates matplotlib/seaborn code
+   - Safe code execution in sandboxed environment
+   - Returns base64-encoded chart images
+
+4. **Orchestrator**
+   - Coordinates agents based on routing decisions
+   - Manages conversation state
+   - Handles multi-turn context
+
+### Frontend Components
+
+1. **Chat Interface**
+
+   - Real-time message display
+   - Support for text, tables, and images
+   - Speech recognition integration
+
+2. **Service Layer**
+
+   - API communication with backend
+   - Response transformation
+   - Error handling
+
+3. **Context Management**
+   - User session handling
+   - Message history
+   - State management
+
+## Example Queries
+
+```
+"Show me the top 5 orders"
+→ Returns table with order data
+
+"Make a bar chart of those orders by total amount"
+→ Generates bar chart visualization
+
+"Show me orders grouped by region"
+→ Returns data aggregated by region
+
+"Create a pie chart of the order distribution"
+→ Generates pie chart from current data
+
+"What insights can you provide about these sales?"
+→ Provides AI-generated analysis
+```
+
+## Configuration Files
+
+Key configuration in `backend/utils/config.py`:
+
+- MODEL_ID: Your OCI GenAI model OCID
+- AGENT_ENDPOINT_ID: Your OCI Agent Runtime endpoint
+- COMPARTMENT_ID: Your OCI compartment
+- SERVICE_ENDPOINT: GenAI service endpoint URL
+- DATABASE_SCHEMA: Database table definitions
+
+## Notes
+
+- Prompts can be customized in `backend/orchestration/oci_direct_runnables.py`
+- Chart generation code is dynamically created by GenAI
+- Designed specifically for Oracle Cloud Infrastructure + Generative AI
+- Sample database schema included for e-commerce use case
+- Frontend uses Material-UI for consistent design
+
+# Useful Links
+
+- [OCI Generative AI](https://docs.oracle.com/en-us/iaas/Content/generative-ai/home.htm)
+  Official documentation for Oracle Generative AI
+
+- [OCI Agent Runtime](https://docs.oracle.com/en-us/iaas/Content/generative-ai/agent-runtime.htm)
+  Documentation for OCI Agent Runtime
+
+- [LangChain Documentation](https://python.langchain.com/docs/get_started/introduction)
+  LangChain framework documentation
+
+- [Next.js Documentation](https://nextjs.org/docs)
+  Next.js framework documentation
+
+# License
+
+Copyright (c) 2025 Oracle and/or its affiliates.
+
+Licensed under the Universal Permissive License (UPL), Version 1.0.
diff --git a/ai/gen-ai-agents/sql_graph_generator_dashboard/files/DATABASE_SETUP.md b/ai/gen-ai-agents/sql_graph_generator_dashboard/files/DATABASE_SETUP.md
@@ -0,0 +1,130 @@
+# Database Setup
+
+## Overview
+
+This application uses OCI Agent Runtime to query your database. The sample schema is for an e-commerce database.
+
+## Database Schema
+
+### CUSTOMERS Table
+```sql
+CREATE TABLE CUSTOMERS (
+    CUSTOMER_ID NUMBER PRIMARY KEY,
+    CUSTOMER_NAME VARCHAR2(100),
+    EMAIL VARCHAR2(100),
+    SIGNUP_DATE DATE,
+    SEGMENT VARCHAR2(50),
+    COUNTRY VARCHAR2(50),
+    LIFETIME_VALUE NUMBER(10,2),
+    CREATION_DATE DATE,
+    CREATED_BY VARCHAR2(50),
+    LAST_UPDATED_DATE DATE,
+    LAST_UPDATED_BY VARCHAR2(50)
+);
+```
+
+### PRODUCTS Table
+```sql
+CREATE TABLE PRODUCTS (
+    PRODUCT_ID NUMBER PRIMARY KEY,
+    PRODUCT_NAME VARCHAR2(200),
+    CATEGORY VARCHAR2(100),
+    PRICE NUMBER(10,2),
+    COST NUMBER(10,2),
+    STOCK_QUANTITY NUMBER,
+    LAUNCH_DATE DATE,
+    CREATION_DATE DATE,
+    CREATED_BY VARCHAR2(50),
+    LAST_UPDATED_DATE DATE,
+    LAST_UPDATED_BY VARCHAR2(50)
+);
+```
+
+### ORDERS Table
+```sql
+CREATE TABLE ORDERS (
+    ORDER_ID NUMBER PRIMARY KEY,
+    CUSTOMER_ID NUMBER,
+    ORDER_DATE DATE,
+    TOTAL_AMOUNT NUMBER(10,2),
+    STATUS VARCHAR2(50),
+    REGION VARCHAR2(100),
+    SALES_REP VARCHAR2(100),
+    CREATION_DATE DATE,
+    CREATED_BY VARCHAR2(50),
+    LAST_UPDATED_DATE DATE,
+    LAST_UPDATED_BY VARCHAR2(50),
+    FOREIGN KEY (CUSTOMER_ID) REFERENCES CUSTOMERS(CUSTOMER_ID)
+);
+```
+
+### ORDER_ITEMS Table
+```sql
+CREATE TABLE ORDER_ITEMS (
+    ORDER_ITEM_ID NUMBER PRIMARY KEY,
+    ORDER_ID NUMBER,
+    PRODUCT_ID NUMBER,
+    QUANTITY NUMBER,
+    UNIT_PRICE NUMBER(10,2),
+    DISCOUNT_PERCENT NUMBER(5,2),
+    CREATION_DATE DATE,
+    CREATED_BY VARCHAR2(50),
+    LAST_UPDATED_DATE DATE,
+    LAST_UPDATED_BY VARCHAR2(50),
+    FOREIGN KEY (ORDER_ID) REFERENCES ORDERS(ORDER_ID),
+    FOREIGN KEY (PRODUCT_ID) REFERENCES PRODUCTS(PRODUCT_ID)
+);
+```
+
+## Sample Data
+
+### Sample Customers
+```sql
+INSERT INTO CUSTOMERS VALUES (1, 'Acme Corp', 'contact@acme.com', DATE '2023-01-15', 'Enterprise', 'USA', 150000, SYSDATE, 'SYSTEM', SYSDATE, 'SYSTEM');
+INSERT INTO CUSTOMERS VALUES (2, 'TechStart Inc', 'info@techstart.com', DATE '2023-03-20', 'SMB', 'UK', 45000, SYSDATE, 'SYSTEM', SYSDATE, 'SYSTEM');
+INSERT INTO CUSTOMERS VALUES (3, 'Global Solutions', 'sales@global.com', DATE '2023-02-10', 'Enterprise', 'Germany', 200000, SYSDATE, 'SYSTEM', SYSDATE, 'SYSTEM');
+```
+
+### Sample Products
+```sql
+INSERT INTO PRODUCTS VALUES (1, 'Enterprise Security Suite', 'Software', 3499.99, 1200, 100, DATE '2023-01-01', SYSDATE, 'SYSTEM', SYSDATE, 'SYSTEM');
+INSERT INTO PRODUCTS VALUES (2, 'AI Analytics Platform', 'Software', 2999.99, 1000, 150, DATE '2023-02-01', SYSDATE, 'SYSTEM', SYSDATE, 'SYSTEM');
+INSERT INTO PRODUCTS VALUES (3, 'Cloud Storage Pro', 'Cloud', 999.99, 300, 500, DATE '2023-03-01', SYSDATE, 'SYSTEM', SYSDATE, 'SYSTEM');
+INSERT INTO PRODUCTS VALUES (4, 'Premium Consulting', 'Services', 5000, 2000, 50, DATE '2023-01-15', SYSDATE, 'SYSTEM', SYSDATE, 'SYSTEM');
+INSERT INTO PRODUCTS VALUES (5, 'Training Program', 'Services', 2500, 800, 100, DATE '2023-02-20', SYSDATE, 'SYSTEM', SYSDATE, 'SYSTEM');
+```
+
+### Sample Orders
+```sql
+INSERT INTO ORDERS VALUES (1, 1, DATE '2024-01-15', 8999.98, 'Completed', 'North America', 'John Smith', SYSDATE, 'SYSTEM', SYSDATE, 'SYSTEM');
+INSERT INTO ORDERS VALUES (2, 2, DATE '2024-01-20', 2999.99, 'Completed', 'Europe', 'Sarah Johnson', SYSDATE, 'SYSTEM', SYSDATE, 'SYSTEM');
+INSERT INTO ORDERS VALUES (3, 3, DATE '2024-02-01', 12499.97, 'Completed', 'Europe', 'Mike Davis', SYSDATE, 'SYSTEM', SYSDATE, 'SYSTEM');
+INSERT INTO ORDERS VALUES (4, 1, DATE '2024-02-15', 7500, 'Processing', 'North America', 'John Smith', SYSDATE, 'SYSTEM', SYSDATE, 'SYSTEM');
+INSERT INTO ORDERS VALUES (5, 2, DATE '2024-03-01', 999.99, 'Completed', 'Europe', 'Sarah Johnson', SYSDATE, 'SYSTEM', SYSDATE, 'SYSTEM');
+```
+
+### Sample Order Items
+```sql
+INSERT INTO ORDER_ITEMS VALUES (1, 1, 1, 2, 3499.99, 0, SYSDATE, 'SYSTEM', SYSDATE, 'SYSTEM');
+INSERT INTO ORDER_ITEMS VALUES (2, 1, 3, 2, 999.99, 10, SYSDATE, 'SYSTEM', SYSDATE, 'SYSTEM');
+INSERT INTO ORDER_ITEMS VALUES (3, 2, 2, 1, 2999.99, 0, SYSDATE, 'SYSTEM', SYSDATE, 'SYSTEM');
+INSERT INTO ORDER_ITEMS VALUES (4, 3, 1, 1, 3499.99, 0, SYSDATE, 'SYSTEM', SYSDATE, 'SYSTEM');
+INSERT INTO ORDER_ITEMS VALUES (5, 3, 2, 2, 2999.99, 10, SYSDATE, 'SYSTEM', SYSDATE, 'SYSTEM');
+INSERT INTO ORDER_ITEMS VALUES (6, 3, 5, 1, 2500, 0, SYSDATE, 'SYSTEM', SYSDATE, 'SYSTEM');
+INSERT INTO ORDER_ITEMS VALUES (7, 4, 4, 1, 5000, 0, SYSDATE, 'SYSTEM', SYSDATE, 'SYSTEM');
+INSERT INTO ORDER_ITEMS VALUES (8, 4, 5, 1, 2500, 0, SYSDATE, 'SYSTEM', SYSDATE, 'SYSTEM');
+INSERT INTO ORDER_ITEMS VALUES (9, 5, 3, 1, 999.99, 0, SYSDATE, 'SYSTEM', SYSDATE, 'SYSTEM');
+```
+
+## OCI Agent Runtime Configuration
+
+1. Create database connection in OCI Agent Runtime
+2. Configure database tool/function with:
+   - Connection string
+   - User credentials
+   - Query permissions
+3. Test connection with simple query
+4. Update AGENT_ENDPOINT_ID in config.py
+
+
+