Skip to content

Commit 2501b38

Browse files
239573049239573049
committed
fix: 修正 README 文件中的拼写和格式错误，更新内容以提高可读性
1 parent dc7e05a commit 2501b38

File tree

2 files changed

+197
-181
lines changed

2 files changed

+197
-181
lines changed

‎README.md‎

Lines changed: 86 additions & 143 deletions
Original file line numberDiff line numberDiff line change
@@ -1,51 +1,54 @@
11
# SQLBox
22

3-
AI powered SQL agent with vector indexed schema retrieval
3+
AI powered SQL agent with vector-indexed schema retrieval
4+
5+
[简体中文](README.zh-CN.md)
46

57
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE) [![.NET](https://img.shields.io/badge/.NET-8.0-512BD4.svg)](https://dotnet.microsoft.com/) [![React](https://img.shields.io/badge/React-19-61dafb.svg)](https://react.dev/) [![Vite](https://img.shields.io/badge/Vite-7-646cff.svg)](https://vite.dev/) [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178c6.svg)](https://www.typescriptlang.org/) [![OpenAI](https://img.shields.io/badge/OpenAI-gpt--4o--mini-000.svg)](https://platform.openai.com/)
68

79
- Production-ready SQL agent that turns natural language into safe, parameterized SQL
8-
- Vector indexed schema retrieval for relevance aware query generation
9-
- Streaming SSE responses with delta and content blocks
10-
- First class ECharts option generation with data injection placeholders
11-
- Works with Sqlite, PostgreSQL, MySQL, SQL Server
10+
- Vector-indexed schema retrieval to ground SQL generation with database context
11+
- SSE streaming responses with delta text and typed content blocks
12+
- First-class ECharts option generation with data placeholders injection
13+
- Works with SQLite, PostgreSQL, MySQL, SQL Server
1214

13-
Repo structure at a glance
15+
Repository structure (key files)
1416

1517
- [Program.cs](src/SQLAgent.Hosting/Program.cs)
1618
- [EndpointRouteBuilderExtensions.cs](src/SQLAgent.Hosting/Extensions/EndpointRouteBuilderExtensions.cs)
1719
- [ChatService.cs](src/SQLAgent.Hosting/Services/ChatService.cs)
18-
- [SqlBoxClient.cs](src/SQLAgent/Facade/SqlBoxClient.cs)
19-
- [EmbeddingSchemaIndexer.cs](src/SQLAgent/Infrastructure/Defaults/EmbeddingSchemaIndexer.cs)
20-
- [VectorSchemaRetriever.cs](src/SQLAgent/Infrastructure/Defaults/VectorSchemaRetriever.cs)
20+
- [SSEMessage.cs](src/SQLAgent.Hosting/Dto/SSEMessage.cs)
21+
- [SQLAgentClient.cs](src/SQLAgent/Facade/SQLAgentClient.cs)
22+
- [SQLAgentBuilder.cs](src/SQLAgent/Facade/SQLAgentBuilder.cs)
23+
- [SQLAgentOptions.cs](src/SQLAgent/Facade/SQLAgentOptions.cs)
2124
- [web/vite.config.ts](web/vite.config.ts)
2225

2326
Key entry points
2427

25-
- [EndpointRouteBuilderExtensions.MapAllApis()](src/SQLAgent.Hosting/Extensions/EndpointRouteBuilderExtensions.cs:194)
28+
- [EndpointRouteBuilderExtensions.MapAllApis()](src/SQLAgent.Hosting/Extensions/EndpointRouteBuilderExtensions.cs:193)
2629
- [ChatService.CompletionAsync()](src/SQLAgent.Hosting/Services/ChatService.cs:39)
2730

2831
## Architecture
2932

30-
The system consists of a .NET 8 minimal API backend and a React + Vite frontend. The backend exposes REST endpoints for connections, providers, settings and vector indexing, plus an SSE chat endpoint. The SQL generation pipeline uses OpenAI function calling to invoke SqlBox tools which search schema, fetch table metadata, produce parameterized SQL and optionally generate ECharts options.
33+
The system consists of a .NET 8 minimal API backend and a React + Vite frontend. The backend exposes REST endpoints for connections, providers, settings and vector indexing, plus an SSE chat endpoint. The SQL generation pipeline uses OpenAI function calling to invoke a generate_sql tool; the agent produces parameterized SQL and can generate ECharts options with data placeholders that are later injected with real data.
3134

3235
```mermaid
3336
flowchart LR
34-
UI[Web UI React] -->|SSE chat completion| API[Hosting API]
37+
UI[Web UI (React)] -->|SSE /api/chat/completion| API[.NET Hosting API]
3538
API -->|function calling| LLM[LLM Client]
36-
LLM -->|tool generate_sql| SqlBox[SqlBoxClient]
37-
SqlBox -->|search tables schema| DB[Target Database]
38-
SqlBox -->|embed and retrieve| Vec[Sqlite Vec Store]
39-
API -->|delta block done error| UI
39+
LLM -->|tool generate_sql| Agent[SQLAgentClient]
40+
Agent -->|search tables/schema| DB[Target Database]
41+
Agent -->|embed & retrieve| Vec[SQLite Vec Store]
42+
API -->|delta / block / done / error| UI
4043
```
4144

4245
Backend building blocks
4346

44-
- Hosting and wiring in [Program.cs](src/SQLAgent.Hosting/Program.cs)
47+
- Minimal host and wiring in [Program.cs](src/SQLAgent.Hosting/Program.cs)
4548
- Endpoint mapping in [EndpointRouteBuilderExtensions.cs](src/SQLAgent.Hosting/Extensions/EndpointRouteBuilderExtensions.cs)
46-
- SSE types in [SSEMessage.cs](src/SQLAgent.Hosting/Dto/SSEMessage.cs)
47-
- SQL agent facade in [SqlBoxClient.cs](src/SQLAgent/Facade/SqlBoxClient.cs)
48-
- Vector indexing and retrieval in [EmbeddingSchemaIndexer.cs](src/SQLAgent/Infrastructure/Defaults/EmbeddingSchemaIndexer.cs) and [VectorSchemaRetriever.cs](src/SQLAgent/Infrastructure/Defaults/VectorSchemaRetriever.cs)
49+
- SSE contract/types in [SSEMessage.cs](src/SQLAgent.Hosting/Dto/SSEMessage.cs)
50+
- SQL agent facade in [SQLAgentClient.cs](src/SQLAgent/Facade/SQLAgentClient.cs)
51+
- Vector store (SQLite-vec) and embedder wiring in Infrastructure
4952

5053
### SSE data flow
5154

@@ -54,22 +57,22 @@ sequenceDiagram
5457
participant UI
5558
participant API
5659
participant LLM
57-
participant SqlBox
58-
UI->>API: POST api chat completion
59-
API->>LLM: messages with tool generate_sql
60-
LLM-->>API: tool_call generate_sql
61-
API->>SqlBox: Execute question
62-
SqlBox->>DB: query
63-
SqlBox-->>API: sql and chart option
64-
API-->>UI: delta streaming
65-
API-->>UI: block sql data chart
60+
participant Agent
61+
UI->>API: POST /api/chat/completion (SSE)
62+
API->>LLM: messages + tool(generate_sql)
63+
LLM-->>API: tool_call(generate_sql) [stream]
64+
API->>Agent: Execute natural language question
65+
Agent->>DB: Query (parameterized)
66+
Agent-->>API: sql and optional echarts option
67+
API-->>UI: delta streaming (text)
68+
API-->>UI: block(sql/chart)
6669
API-->>UI: done
6770
```
6871

69-
SSE message types
72+
SSE message types (see [SSEMessage.cs](src/SQLAgent.Hosting/Dto/SSEMessage.cs))
7073

7174
- delta: incremental text chunks
72-
- block: content blocks sql data chart
75+
- block: typed content block (sql, data, chart, error)
7376
- done: completion with elapsedMs
7477
- error: error details
7578

@@ -85,6 +88,14 @@ Example SQL block
8588
{ "type": "block", "block": { "type": "sql", "sql": "SELECT ...", "tables": ["orders"], "dialect": "sqlite" } }
8689
```
8790

91+
Example Chart block (ECharts option JSON string)
92+
93+
```json
94+
{ "type": "block", "block": { "type": "chart", "chartType": "echarts", "echartsOption": "{ ... }" } }
95+
```
96+
97+
Note: Current server streams SQL and optional ECharts option. Data blocks can be added later if needed.
98+
8899
## Quickstart
89100

90101
Prerequisites
@@ -95,61 +106,66 @@ Prerequisites
95106

96107
Backend
97108

98-
- Configure ports. Default project uses 18080 via [launchSettings.json](src/SQLAgent.Hosting/Properties/launchSettings.json). If you prefer 5218, change applicationUrl and Urls and update the frontend proxy accordingly.
99-
- Run
109+
- Default port is 18080 as configured in [launchSettings.json](src/SQLAgent.Hosting/Properties/launchSettings.json)
110+
- Run the hosting project:
100111

101112
```bash
102113
dotnet run --project src/SQLAgent.Hosting/SQLAgent.Hosting.csproj
103114
```
104115

105116
Frontend
106117

107-
- Ensure the dev proxy in [web/vite.config.ts](web/vite.config.ts) points to backend url
108-
- Optionally set VITE_API_BASE_URL to override default /api
109-
- Install and run
118+
- Dev server defaults to 5173
119+
- The dev proxy for API is defined in [web/vite.config.ts](web/vite.config.ts). If you change backend port, update the proxy target or set VITE_API_BASE_URL.
120+
- Install and run:
110121

111122
```bash
112123
cd web
113124
pnpm install
114125
pnpm dev
115126
```
116127

117-
Visit http://localhost:5173 and open Providers and Connections to configure.
128+
Open http://localhost:5173 and configure Providers and Connections first.
118129

119130
## Configuration
120131

121132
System settings
122133

123-
- The backend reads and persists settings at runtime via [MapSettingsApis()](src/SQLAgent.Hosting/Extensions/EndpointRouteBuilderExtensions.cs:106)
124-
- Recommended values
134+
- The backend exposes GET/PUT /api/settings (merged with an optional settings.json at content root). Mapping is in [EndpointRouteBuilderExtensions.MapSettingsApis()](src/SQLAgent.Hosting/Extensions/EndpointRouteBuilderExtensions.cs:106)
135+
- Recommended settings.json:
125136

126137
```json
127138
{
128139
"EmbeddingProviderId": "openai",
129140
"EmbeddingModel": "text-embedding-3-small",
130141
"VectorDbPath": "Data Source=vectors.db",
131142
"VectorCollection": "table_vectors",
132-
"DistanceMetric": "Cosine",
133-
"AutoCreateCollection": true
143+
"AutoCreateCollection": true,
144+
"VectorCacheExpireMinutes": 60,
145+
"DefaultChatProviderId": "openai",
146+
"DefaultChatModel": "gpt-4o-mini"
134147
}
135148
```
136149

137150
AI providers
138151

139-
- POST /api/providers with an OpenAI key. Example payload
152+
- POST /api/providers with your OpenAI (or compatible) key. Input schema expects availableModels as an array.
140153

141154
```json
142155
{
143156
"name": "OpenAI",
144157
"type": "OpenAI",
145158
"endpoint": "",
146159
"apiKey": "sk-...your key...",
147-
"availableModels": "gpt-4o-mini,text-embedding-3-small",
160+
"availableModels": ["gpt-4o-mini", "text-embedding-3-small"],
148161
"defaultModel": "gpt-4o-mini",
149-
"isEnabled": true
162+
"isEnabled": true,
163+
"extraConfig": {}
150164
}
151165
```
152166

167+
- List models for a provider: GET /api/providers/{id}/models
168+
153169
Database connections
154170

155171
- POST /api/connections to register a database
@@ -163,141 +179,68 @@ Database connections
163179
}
164180
```
165181

182+
- Test a connection: POST /api/connections/{id}/test
183+
166184
Vector index
167185

168-
- Initialize or update per connection
186+
- Initialize or update the vector index for a connection (SQLite vec store)
169187

170188
```bash
171189
curl -X POST http://localhost:18080/api/connections/{id}/index/init
172190
curl -X POST http://localhost:18080/api/connections/{id}/index/update
173191
```
174192

175-
Chat completion
193+
## Chat completion (SSE)
176194

177-
- The frontend uses SSE, see [web/src/services/sse.ts](web/src/services/sse.ts)
178-
- Minimal request
195+
- Frontend SSE client is implemented in [sse.ts](web/src/services/sse.ts)
196+
- Endpoint: POST /api/chat/completion
197+
- Minimal request (matches [CompletionInput](src/SQLAgent.Hosting/Dto/CompletionInput.cs)):
179198

180199
```json
181200
{
182201
"connectionId": "conn-id",
183202
"messages": [{ "role": "user", "content": "top 10 products by sales" }],
184203
"execute": true,
185-
"maxRows": 100,
186204
"suggestChart": true,
187205
"providerId": "openai",
188206
"model": "gpt-4o-mini"
189207
}
190208
```
191209

210+
- The server streams:
211+
- delta messages with reasoning or status text
212+
- SQL blocks for generated statements (parameterized)
213+
- optional chart blocks with ECharts option JSON
214+
- done message with elapsedMs
215+
192216
## Security and quality
193217

194218
- Parameterized SQL only. The agent produces SQL with parameters and never inlines user input.
195-
- Read vs write control. You can enforce read only with validation and options in [SqlBoxOptions](src/SQLAgent/Facade/SqlBoxOptions.cs).
196-
- SQL validation reports warnings and errors server side.
219+
- Read vs write control. You can configure write permission via agent options. See [SQLAgentOptions](src/SQLAgent/Facade/SQLAgentOptions.cs).
220+
- Server-side validation planned to report SQL risks.
197221

198222
## Supported databases and models
199223

200-
- Databases: Sqlite, PostgreSQL, MySQL, SQL Server
201-
- Models: OpenAI chat gpt-4o-mini, embedding text-embedding-3-small
224+
- Databases: SQLite, PostgreSQL, MySQL, SQL Server
225+
- Models: OpenAI chat gpt-4o-mini; embeddings text-embedding-3-small (via configurable provider)
202226

203227
## Troubleshooting
204228

205-
- If SSE stops abruptly, check reverse proxy buffering and ensure header X-Accel-Buffering is respected
206-
- If vector search returns empty, run index init and verify EmbeddingProviderId and EmbeddingModel
207-
- Use /scalar in dev to inspect OpenAPI when enabled in development
229+
- SSE stops abruptly: Check reverse proxy buffering and ensure header X-Accel-Buffering is respected
230+
- Empty vector search or options generation missing: initialize index and verify EmbeddingProviderId/EmbeddingModel
231+
- API reference: In Development, OpenAPI/Scalar is available at /scalar (see [Program.cs](src/SQLAgent.Hosting/Program.cs))
208232

209233
## Roadmap
210234

211235
- Additional vector backends
212-
- Advanced schema statistics and join graph
213-
- Pluggable validators and repair strategies
214-
215-
## License
216-
217-
MIT
218-
219-
---
220-
221-
# SQLBox 中文版
222-
223-
以向量索引驱动的 AI SQL 代理
224-
225-
- 自然语言生成安全的参数化 SQL
226-
- 向量化表与列描述进行相关性检索
227-
- SSE 流式返回 delta 与内容块 sql 数据 图表
228-
- 支持自动生成 ECharts 配置并注入数据占位符
229-
- 兼容 Sqlite PostgreSQL MySQL SQL Server
230-
231-
关键入口
232-
233-
- [Program.cs](src/SQLAgent.Hosting/Program.cs)
234-
- [EndpointRouteBuilderExtensions.MapAllApis()](src/SQLAgent.Hosting/Extensions/EndpointRouteBuilderExtensions.cs:194)
235-
- [ChatService.CompletionAsync()](src/SQLAgent.Hosting/Services/ChatService.cs:39)
236-
237-
## 架构总览
238-
239-
```mermaid
240-
flowchart LR
241-
UI[Web UI React] -->|SSE chat completion| API[Hosting API]
242-
API -->|function calling| LLM[LLM Client]
243-
LLM -->|tool generate_sql| SqlBox[SqlBoxClient]
244-
SqlBox -->|search tables schema| DB[Target Database]
245-
SqlBox -->|embed and retrieve| Vec[Sqlite Vec Store]
246-
API -->|delta block done error| UI
247-
```
248-
249-
## 快速开始
236+
- Richer schema statistics and join graph
237+
- Pluggable validators and auto-repair strategies
238+
- Data blocks streaming for query results
250239

251-
- 安装 .NET 8 SDK 和 Node 20+ 与 PNPM
252-
- 后端默认端口 18080 如需 5218 可修改 [launchSettings.json](src/SQLAgent.Hosting/Properties/launchSettings.json) 并同步前端代理 [web/vite.config.ts](web/vite.config.ts)
253-
- 启动后端
240+
## Contributing
254241

255-
```bash
256-
dotnet run --project src/SQLAgent.Hosting/SQLAgent.Hosting.csproj
257-
```
258-
259-
- 启动前端
260-
261-
```bash
262-
cd web
263-
pnpm install
264-
pnpm dev
265-
```
266-
267-
浏览器访问 http://localhost:5173 完成 提供商 与 连接 配置
268-
269-
## 配置指南
270-
271-
- 系统设置通过 [MapSettingsApis()](src/SQLAgent.Hosting/Extensions/EndpointRouteBuilderExtensions.cs:106) 暴露 GET PUT
272-
- 推荐 EmbeddingModel 使用 text-embedding-3-small 并设置 EmbeddingProviderId 为 openai
273-
- 提供商 POST /api/providers 示例见上文英文部分
274-
- 连接 POST /api/connections 支持 sqlite postgres mysql sqlserver
275-
276-
向量索引
242+
- Issues and PRs are welcome. Please add tests where applicable and follow existing coding style.
277243

278-
- 初始化与增量更新接口
279-
280-
```bash
281-
curl -X POST http://localhost:18080/api/connections/{id}/index/init
282-
curl -X POST http://localhost:18080/api/connections/{id}/index/update
283-
```
284-
285-
对话与 SSE
286-
287-
- 前端 SSE 实现在 [web/src/services/sse.ts](web/src/services/sse.ts)
288-
- 消息类型 delta block done error
289-
290-
## 安全与质量
291-
292-
- 始终使用参数化查询 防止注入
293-
- 可按需限制写操作 参见 [SqlBoxOptions](src/SQLAgent/Facade/SqlBoxOptions.cs)
294-
- 服务端校验会对风险 SQL 给出警告或错误
295-
296-
## 支持矩阵
297-
298-
- 数据库 Sqlite PostgreSQL MySQL SQL Server
299-
- 模型 OpenAI gpt-4o-mini 与 text-embedding-3-small
300-
301-
## 许可
244+
## License
302245

303246
MIT

0 commit comments

Comments
 (0)