黑客马拉松II–第三阶段
人工智能驱动的Todo聊天机器人（代理+MCP工具）
这个项目是 符合第三阶段标准、基于代理的Todo聊天机器人 专为 黑客马拉松II.\ 使用 快速API, OpenAI代理SDK，以及 官方MCP工具 通过以下方式管理任务 自然语言，与 持久对话记忆 由...支持 Neon PostgreSQL.
后端是 Docker化 并部署在 拥抱面部空间，而前端是用 Next.js（应用路由器） 并部署在 维塞尔.
______________________________________________________________________
🚀 特点（第三阶段范围）
- 🤖 基于代理的聊天机器人 （无正则表达式/基于规则的逻辑）
- 🧠 OpenAI代理SDK 用于推理+工具编排
- 🧰 仅限MCP官方工具 适用于所有任务操作\
（代理无法直接访问数据库）
- 💬 自然语言命令:
- add - list - complete - delete - stats
- 🗂️ 持久对话记忆
- 🔁 对话id已保留 跨消息
- 🗄️ Neon PostgreSQL 用于：
- 任务 - 交谈 - 消息
- 🔐 安全环境变量
- 🐳 Docker化后端 用于生产
- 🎨 高级UI仪表板+浮动AI聊天机器人
- 🧩 自定义ChatKit风格的用户界面 （与App Router兼容）
______________________________________________________________________
🧱 架构概述
前端（Next.js应用路由器） │ │ 浮动AI聊天机器人小部件 │ └── 调用/api/{user_id}/聊天 │ 后端（拥抱面上的FastAPI） │ ├── OpenAI代理（代理SDK） │ ├── MCP工具：add_task │ ├── MCP工具：list_tasks │ ├── MCP工具：complete_task │ ├── MCP工具：delete_task │ └── MCP工具：统计数据 │ └── Neon PostgreSQL ├── tasks ├── 对话 └── 消息
______________________________________________________________________
🖥️ 前端
- 框架：Next.js（应用路由器）
- 用户界面:
- 登录欢迎屏幕 - 高级Todo仪表板 - 漂浮 人工智能按钮 → 打开聊天机器人
- 认证:
- 通过演示身份验证 localStorage (todo_user_id)
- 部署：Vercel
前端环境变量
NEXT_PUBLIC_API_BASE=https://.hf.space
⚙️ Backend
Framework: FastAPI
Agent: OpenAI Agents SDK
Tools: MCP (Model Context Protocol)
Database: Neon PostgreSQL
Deployment: Hugging Face Spaces
Container: Docker
Backend Environment Variables
OPENAI_API_KEY=sk-****
DATABASE_URL=postgresql+asyncpg://...
🧪 Example Chat Commands
add buy milk
list
complete 1
delete 2
stats
🧠 Conversation Memory (Phase-3 Requirement)
Each chat creates or reuses a conversation_id
The same conversation continues across messages
Stored in Neon PostgreSQL
Enables context-aware responses
🧑⚖️ For Judges (Phase-3 Checklist)
This project fully satisfies Hackathon II – Phase 3 requirements:
✅ Agent-based system (no regex, no hardcoded rules)
✅ OpenAI Agents SDK used
✅ All task actions via MCP tools only
✅ Persistent conversation memory implemented
✅ conversation_id maintained across turns
✅ Database-backed (Neon PostgreSQL)
✅ Deployed backend (Hugging Face)
✅ Deployed frontend (Vercel)
✅ Clean UI + integrated chatbot
✅ Dockerized backend for production
⚠️ Note on ChatKit
Official ChatKit UI could not be used due to Next.js App Router incompatibility.
A custom ChatKit-style UI was implemented instead, while keeping agent + MCP logic fully compliant.
📦 Repository Structure
hackathon-ii-phase3-chatbot/
│
├── backend/
│ ├── app/
│ │ ├── agents/
│ │ ├── mcp_tools/
│ │ ├── models/
│ │ ├── routers/
│ │ └── main.py
│ ├── Dockerfile
│ └── requirements.txt
│
├── frontend/
│ ├── app/
│ │ ├── page.tsx
│ │ ├── signin/
│ │ └── dashboard/
│ ├── components/
│ │ └── ChatbotWidget.tsx
│ └── lib/
│
└── README.md
🚀 Live Deployments
Frontend (Vercel)
👉 https://phase3-ismatfatima-ai-todo.vercel.app
Backend (Hugging Face Spaces)
👉 https://ismat110-hackathon-ii-phase3-chatbot.hf.space
🏁 Final Notes
This project demonstrates a production-ready, agent-driven AI system with:
Clear separation of concerns
Tool-only task execution
Persistent memory
Real deployment
It is fully aligned with Hackathon II – Phase 3 objectives.```