|
23 | 23 | - **PDF Parsing:** PyPDF2 >=3.0.0 |
24 | 24 |
|
25 | 25 | --- |
26 | | - |
27 | | -## 3. Functionality Specification |
28 | | - |
29 | | -### Core Features |
30 | | - |
31 | | -#### 3.1 Database Connection Management |
32 | | - |
33 | | -- Add PostgreSQL database connections with connection details |
34 | | -- Test database connectivity |
35 | | -- Store connection configurations securely |
36 | | -- Support multiple database connections |
37 | | - |
38 | | -#### 3.2 Schema Introspection |
39 | | - |
40 | | -- Automatically fetch table names and column information |
41 | | -- Store schema in PostgreSQL with pgvector for semantic search |
42 | | -- Support uploading schema documentation (PDF) |
43 | | - |
44 | | -#### 3.3 Natural Language to SQL |
45 | | - |
46 | | -- Accept natural language queries |
47 | | -- Use LLM to convert natural language to SQL |
48 | | -- Support SELECT, INSERT, UPDATE, DELETE operations |
49 | | -- Include validation and error handling |
50 | | - |
51 | | -#### 3.4 Semantic Schema Search |
52 | | - |
53 | | -- Embed schema documentation using sentence-transformers |
54 | | -- Store embeddings in pgvector |
55 | | -- Search schema semantically to find relevant tables/columns |
56 | | - |
57 | | -#### 3.5 Query Execution |
58 | | - |
59 | | -- Execute generated SQL against target database |
60 | | -- Return formatted results |
61 | | -- Handle errors gracefully with user-friendly messages |
62 | | - |
63 | | -#### 3.6 Query History |
64 | | - |
65 | | -- Store all queries with timestamps |
66 | | -- View past queries and their results |
67 | | -- Re-run previous queries |
68 | | - |
69 | | -### User Interactions |
70 | | - |
71 | | -1. **Add Database:** User enters connection details → System tests connection → Saves if successful |
72 | | -2. **Ask Question:** User types natural language → System generates SQL → User reviews → Executes → Views results |
73 | | -3. **Search Schema:** User enters search term → System returns semantically similar schema elements |
74 | | -4. **Upload Docs:** User uploads PDF → System extracts text → Embeds and stores in vector DB |
75 | | - |
76 | | -### Data Handling |
77 | | - |
78 | | -- Query history stored in SQLite (local) |
79 | | -- Database connections stored encrypted |
80 | | -- Schema embeddings stored in PostgreSQL via pgvector |
81 | | - |
82 | | -### Edge Cases |
83 | | - |
84 | | -- Invalid SQL generated → Show error with suggestion to retry |
85 | | -- Database connection failed → Show connection error with troubleshooting tips |
86 | | -- Empty results → Show "No results found" message |
87 | | -- Large result sets → Paginate results |
88 | | -- Network timeout → Show timeout error with retry option |
89 | | - |
90 | | ---- |
91 | | - |
92 | | -## 4. API Endpoints |
93 | | - |
94 | | -| Method | Endpoint | Description | |
95 | | -| ------ | ----------------------------- | ------------------------------ | |
96 | | -| GET | /api/connections/ | List all database connections | |
97 | | -| POST | /api/connections/ | Add new database connection | |
98 | | -| GET | /api/connections/{id}/ | Get connection details | |
99 | | -| PUT | /api/connections/{id}/ | Update connection | |
100 | | -| DELETE | /api/connections/{id}/ | Delete connection | |
101 | | -| POST | /api/connections/{id}/test/ | Test connection | |
102 | | -| GET | /api/connections/{id}/schema/ | Get database schema | |
103 | | -| POST | /api/query/ | Execute natural language query | |
104 | | -| GET | /api/history/ | Get query history | |
105 | | -| POST | /api/docs/ | Upload schema document | |
106 | | -| GET | /api/docs/ | List schema documents | |
107 | | -| POST | /api/docs/search/ | Semantic search in documents | |
108 | | - |
109 | | ---- |
110 | | - |
111 | | -## 5. Acceptance Criteria |
112 | | - |
113 | | -1. ✓ User can add PostgreSQL database connections |
114 | | -2. ✓ User can test database connectivity |
115 | | -3. ✓ User can enter natural language queries |
116 | | -4. ✓ System generates valid SQL from natural language |
117 | | -5. ✓ User can execute queries and view results |
118 | | -6. ✓ User can upload PDF schema documentation |
119 | | -7. ✓ System performs semantic search over schema docs |
120 | | -8. ✓ Query history is maintained |
121 | | -9. ✓ Web interface is responsive and functional |
122 | | -10. ✓ Error handling provides helpful feedback |
0 commit comments