|
| 1 | +<!-- |
| 2 | +Copyright (C) 2025 Intel Corporation |
| 3 | +SPDX-License-Identifier: Apache-2.0 |
| 4 | +--> |
| 5 | + |
| 6 | +# LLM DB Query (ODBC SuperBuilder) |
| 7 | + |
| 8 | +Lightweight toolkit for LLM-driven natural-language data exploration across multiple local SQLite databases using the MCP toolchain. |
| 9 | +Natural-language SQL queries across many local .sqlite files, with optional AI analysis of results. |
| 10 | + |
| 11 | +## Key features |
| 12 | +- Query multiple local `.sqlite` files from a single natural-language prompt |
| 13 | +- Convert NL → SQL via a local OpenAI*-compatible or llama.cpp endpoint |
| 14 | +- Execute SQL across attached databases using ODBC (pyodbc) |
| 15 | +- Chain SQL results into an MCP data analysis server for AI-powered reports |
| 16 | +- Export database schema and data to text files for verification and auditing |
| 17 | + |
| 18 | +## Architecture |
| 19 | + |
| 20 | + |
| 21 | +## Example (Increased Playback Speed) |
| 22 | +<img src="./docs/LLMDB.gif" alt="Example" width="800" /> |
| 23 | + |
| 24 | +## Validated hardware |
| 25 | +- CPU: Intel Core Ultra Series 1 and above |
| 26 | +- GPU: Intel® Arc™ B60 graphics (serve 2 MCP and Intel Superbuilder in 1 machine) |
| 27 | +- RAM: 64GB |
| 28 | +- DISK: 256GB |
| 29 | + |
| 30 | +## Software requirements |
| 31 | +- Python 3.10+ (see requirements.txt) |
| 32 | +- ODBC driver appropriate for your platform |
| 33 | +- Windows 11 supported; test on the platform matching your environment |
| 34 | + |
| 35 | +## Quick start (Windows PowerShell) |
| 36 | +1. Install Python dependencies: |
| 37 | +```cmd |
| 38 | +pip install -r requirements.txt |
| 39 | +``` |
| 40 | + |
| 41 | +2. (Optional) Create sample databases and generated exports: |
| 42 | +```cmd |
| 43 | +python create_databases.py |
| 44 | +``` |
| 45 | + |
| 46 | +3. Run preflight checks: |
| 47 | +```cmd |
| 48 | +python startup_check.py |
| 49 | +``` |
| 50 | + |
| 51 | +4. Start MCP servers (two terminals) |
| 52 | +- Database query server: |
| 53 | +```powershell |
| 54 | +cd ./mcp_odbcserver |
| 55 | +run.ps1 |
| 56 | +``` |
| 57 | + |
| 58 | +- Data analysis server: |
| 59 | +```powershell |
| 60 | +cd ./mcp_data_analysis_server |
| 61 | +run.ps1 |
| 62 | +``` |
| 63 | + |
| 64 | +5. From your MCP client (for example, Intel® AI Superbuilder): |
| 65 | +- Configure the MCP servers/agents for ODBC querying and data analysis |
| 66 | +- Send natural-language queries to the ODBC server; receive JSON results and analysis from the data-analysis server |
| 67 | +- Use System Prompt at Intel AI Assistant Builder as below: |
| 68 | +``` |
| 69 | +# Data Assistant Tools: query_database, analyze_data (both are MCP tools) ## Workflow For every user question: **STEP 1: Execute Task 1** Call `query_database("user's question")` - Returns JSON: `{"data": [...], "reasoning": {...}}` Show: - 🧠 Model Reasoning: [reasoning.model_reasoning] - 🔍 SQL: [reasoning.generated_sql] - 📊 Data: [display as table] - 🎯 Sources: [reasoning.databases_queried] **STEP 2: Execute Task 2** Call `analyze_data(data=result["data"], analysis_question="user's question")` **If analyze_data fails:** - Display the error message - Stop the workflow (do not retry) - Ask user if they want to proceed with just the query results ## Rules ✅ Pass result["data"] as JSON to analyze_data ✅ Stop immediately if analyze_data throws an error ✅ Do not attempt to retry analyze_data on failure ✅ Complete all steps only if both succeed |
| 70 | +``` |
| 71 | + |
| 72 | +## Project layout |
| 73 | +``` |
| 74 | +usecases/ai/llm_dbquery/ |
| 75 | +├── create_databases.py # create sample DBs and exports |
| 76 | +├── query_databases.py # ODBC helpers & multi-db logic |
| 77 | +├── nl_query.py # NL -> SQL interface (schema discovery) |
| 78 | +├── startup_check.py # preflight checks (drivers, LLM, deps) |
| 79 | +├── requirements.txt |
| 80 | +├── /databases # place your .sqlite files here |
| 81 | +├── /database_exports # generated text exports |
| 82 | +├── /mcp_odbcserver # ODBC server (MCP) |
| 83 | +└── /mcp_data_analysis_server # data analysis server (MCP) |
| 84 | +``` |
| 85 | + |
| 86 | +## FAQ |
| 87 | +Q: Where do I put my SQLite files? |
| 88 | +A: Add .sqlite files to the `databases/` folder. The toolkit auto-discovers all `.sqlite` files (no hardcoded names) but make sure to select your primary database when you run `startup_check.py` |
| 89 | + |
0 commit comments