Hackathon Ii Phase3 Chatbot

黑客马拉松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.```