AI导哈

自然语言查询CSV工具

一款允许非技术用户上传CSV文件并通过聊天界面使用自然语言查询数据的Web应用程序。

  • by Samar-Bons
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 samar-bons/snowflake-mcp-lambda

使用说明

数据聊天MVP

一个web应用程序，使非技术用户能够上传CSV文件，并通过聊天界面使用自然语言进行查询。

📊 项目状态

当前阶段：CSV上传MVP实施

✅ 已完成（85%后端基础）

  • P0-基础：Git仓库、预提交挂钩、CI管道、Docker设置✅
  • P1-后端核心：FastAPI应用程序、配置管理、数据库基础、健康端点✅
  • P2-身份验证和会话：完成Google OAuth与用户管理的集成✅
    • 具有首选项的用户SQLAlchemy模型
    • 基于JWT的会话管理
    • 身份验证端点（登录、回调、注销、配置文件、首选项）
    • 103项测试，覆盖率89.73%
  • P3-数据集成：LLM管道和数据处理基础设施✅
    • Gemini API服务，BYOK模型和即时工程
    • 模式服务已准备好从CSV上传SQLite数据
    • NL的聊天端点→支持自动运行的SQL转换
    • SQL验证和注入预防
    • 55次测试，新组件覆盖率超过95%
  • P4-前端认证：完成身份验证流程✅
    • 与Google OAuth集成的React应用程序
    • 受保护的路由和用户上下文
    • 仪表板布局已为数据组件做好准备

🎯 下一个优先级：CSV上传MVP（提示11）

  • 后端：CSV上传端点、文件处理、SQLite转换
  • 前端：文件上传组件、模式预览、聊天界面集成
  • 整合：完成上传→ 怎么翻译→ 结果流

🔮 未来功能（MVP后）

  • 多种文件格式：Excel、JSON、Parquet支持
  • 数据库连接：PostgreSQL、MySQL、Snowflake集成
  • 高级功能：查询历史、收藏夹、数据可视化
  • 企业：SSO、RBAC、协作功能

🚀 Docker快速入门（推荐）

为了获得最快的开发体验：

# 1. Clone and setup environment
git clone <your-repo-url>
cd snowflake-mcp-lambda
make setup  # Copies .env.example to .env

# 2. IMPORTANT: Edit .env with required values
# Required: GEMINI_API_KEY (for LLM functionality)
# Optional: GOOGLE_CLIENT_* (for auth), database passwords

# 3. Start everything with one command
make dev-setup
# This builds containers, starts services, and runs migrations

# 4. Access the application
# - Frontend: http://localhost:3000 (React app)
# - Backend API: http://localhost:8000 (FastAPI)
# - API Docs: http://localhost:8000/docs (Interactive API docs)

常见开发命令：

make help           # Show all available commands
make up             # Start services
make down           # Stop services
make logs           # View all logs
make test           # Run backend tests
make health         # Check service health
make wait-healthy   # Wait for all services to be ready
make clean          # Clean up containers/volumes

💡 主要特点

🎯 MVP用户体验

  1. 上传CSV文件 -带有进度指示的拖放界面
  2. 架构预览 -自动检测列和数据类型并确认
  3. 聊天界面 -用自然语言询问有关数据的问题
  4. SQL生成 -Gemini LLM将问题转换为SQLite查询
  5. 结果显示 -具有排序、过滤和导出选项的交互式表格

🔒 安全与隐私

  • 无数据持久性 -会话结束后删除的文件
  • 只读查询 -只允许SELECT语句
  • 用户提供的API密钥 -Gemini API密钥从未存储在服务器端
  • 文件验证 -大小限制、格式验证、安全处理

⚡ 演出

  • 快速上传 -支持高达100MB的文件
  • 有效处理 -CSV→ 带模式推理的SQLite转换
  • 快速查询 -用于快速查询执行的内存SQLite
  • 基于会话 -核心功能不依赖于数据库

⚙️ 配置

必需的API密钥

Gemini API（LLM功能所需）

  1. 首选 谷歌人工智能工作室
  2. 创建新的API密钥
  3. 添加到您的 .env 文件： GEMINI_API_KEY=your-api-key

Google OAuth（MVP可选）

  1. 首选 谷歌云控制台
  2. 创建OAuth 2.0客户端ID凭据
  3. 添加重定向URI: http://localhost:8000/api/v1/auth/callback
  4. 增添 .env: GOOGLE_CLIENT_ID 和 GOOGLE_CLIENT_SECRET

环境变量

复制 .env.example 向 .env 并填写您的值：

# Required for core functionality
GEMINI_API_KEY=your-gemini-api-key

# Optional for authentication (can use without login)
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

# Auto-generated secure secrets
JWT_SECRET_KEY=your-secure-secret-key
POSTGRES_PASSWORD=your-db-password

🏗️ 建筑

技术栈

  • 后端：FastAPI（Python）+用于依赖管理的Poetry
  • 前端：React+Vite+TypeScript+顺风CSS
  • 数据处理：pandas+SQLite用于CSV文件处理
  • LLM集成：用于自然语言查询的Google Gemini API
  • 认证：带有JWT Cookie的Google OAuth（可选）
  • 发展：Docker Compose用于本地开发

文件处理管道

CSV Upload → Schema Detection → SQLite Conversion → Query Interface
     ↓              ↓                   ↓               ↓
File validation  Column types    In-memory DB    Natural language
Size limits      Data preview    Fast queries    SQL generation
Error handling   User confirm    Session scope   Results display

🧪 测试与开发

提交前质量检查

我们的预提交挂钩运行与CI相同的检查，以获得即时反馈：

  • 拉夫 -快速Python linting和格式化
  • MyPy 的 -严格模式下的类型检查
  • Pytest -完整的测试套件，覆盖率要求达到85%以上
  • 安全 -基本漏洞扫描
# Setup development environment
./scripts/setup-dev.sh

# All commits now run full CI checks locally
# (30-60 seconds per commit, but zero CI failures)

测试覆盖率

  • 后端：91%以上的覆盖率，包括全面的单元和集成测试
  • 前端：vitest组件测试+柏树E2E测试
  • 文件处理：各种CSV格式和编码的边缘案例
  • LLM集成：模拟双子座的反应，以进行可靠的测试

📋 开发状态

实施进度

看 docs/planning/PROJECT_STATUS.md 了解详细状态和下一步行动

开发人员和人工智能助理的关键文件：

  • docs/planning/PROJECT_STATUS.md -当前状态和准备执行提示
  • docs/planning/spec_v2.md -完整的功能需求和架构
  • DEVELOPMENT.md -开发人员设置和故障排除指南
  • CLAUDE.md -AI代码助理的项目背景

当前优先级：CSV上传MVP

下一个重要里程碑是实现CSV文件上传功能，允许用户：

  1. 上传CSV文件，无需数据库凭据
  2. 预览并验证检测到的架构
  3. 通过聊天使用自然语言查询上传的数据
  4. 导出结果并管理会话数据

这创建了一个完整的、演示就绪的应用程序，完全可以使用用户提供的文件。

🤖 人工智能辅助开发说明

该项目旨在实现无缝的人工智能辅助开发：

为什么要使用全面的预提交钩子？

AI助手不能直接访问CI日志。当CI失败时，人类必须手动将错误消息复制回AI，从而创建一个令人沮丧的调试循环。我们的解决方案：

  • 即时反馈 -AI会立即出错，而不是在CI失败后
  • 环境 -本地通过的内容在CI中通过
  • 更快的迭代 -修复同一对话中的问题
  • 无上下文切换 -人工智能可以在没有人为干预的情况下解决问题

AI助手友好功能

  • 清晰的文件 -综合规划文件 docs/planning/
  • 准备执行提示 -PROJECT_STATUS.md中的具体实施任务
  • 模块化架构 -清晰地分离关注点，以实现重点变更
  • 综合测试 -确信更改不会破坏现有功能

这种方法将人工智能助手从有用但有时令人沮丧的发展伙伴转变为真正可靠的发展伙伴。

通过自然语言对话将CSV数据转化为见解。无需数据库设置-只需上传并开始提问！

相关 MCP