lgch (Hjleepapa)

LGCH Todo系统：LangGraph+Twilio+MCP+LangChain语音AI

LGCH Todo系统利用LangGraph、模型上下文协议（MCP）和LangChain的强大功能，创建了一个名为Luna的智能语音AI助手。该系统展示了先进的代理架构，具有工具调用功能、状态管理以及与外部服务的无缝集成。

Luna可以通过自然语音交互或web API调用来管理待办任务、提醒和日历事件。所有数据都存储在PostgreSQL数据库中，并自动与谷歌日历同步，提供全面的生产力管理解决方案。

🌟 主要特点

• 语音AI助手：通过语音或电话与Luna进行自然对话
• 待办事项列表管理：创建、更新、完成和删除具有优先级的待办事项
• 提醒系统：创建和管理具有重要性级别和日期的提醒
• 日历事件管理：使用开始/结束时间安排和管理日历事件
• 谷歌日历集成：自动将所有数据与Google日历同步
• Twilio手机集成：拨打和接听电话进行语音交互
• WebSocket实时通信：实时音频流和处理
• RESTful API端点：通过web API进行编程访问
• ngrok隧道管理：用于生产部署的安全webhook处理
• MCP工具集成：用于标准化工具管理的模型上下文协议
• 数据库持久性：使用SQLAlchemy ORM的PostgreSQL存储

🛠️ 技术栈

核心技术

• LangGraph：代理编排和状态管理
• 模型上下文协议（MCP）：标准化的工具管理和服务器通信
• LangChain：LLM框架和工具集成
• 烧瓶：用于REST API和Web界面的Web框架
• SQLAlchemy：ORM用于数据库操作
• PostgreSQL：用于数据存储的本地数据库
• OpenAI API：GPT-4、Whisper（语音转文本）、TTS（文本转语音）
• 特维里奥：电话集成和媒体流
• 吸烟：用于webhook处理的安全隧道
• WebSocket：实时通信协议
• 谷歌日历API：日历同步

音频处理

• Twilio媒体流：来自电话的实时音频流
• OpenAI耳语：语音转文本转录
• OpenAI TTS：文本到语音音频生成
• 数值Python：音频处理和μ律到PCM的转换

📋 先决条件

• Python 3.13
• OpenAI API密钥
• 带有电话号码的Twilio帐户
• ngrok帐户和authtoken
• 本地PostgreSQL数据库
• Google日历API凭证
• 用于语音交互的电话（或用于开发的麦克风/扬声器）

🚀 入门指南

1.设置虚拟环境并安装依赖项

导航到 lgch_todo 目录并设置环境：

cd lgch_todo

（推荐）使用 紫外线 对于依赖关系管理：

uv sync

或者，使用pip：

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e .

2.设置环境变量

创建一个 .env 项目根目录中的文件，包含以下变量：

# OpenAI Configuration
OPENAI_API_KEY=your_openai_api_key

# Database Configuration
DB_URI=postgresql://username:password@localhost:5432/database_name

# Twilio Configuration
TWILIO_ACCOUNT_SID=your_twilio_account_sid
TWILIO_AUTH_TOKEN=your_twilio_auth_token
TWILIO_PHONE_NUMBER=+1234567890

# Google Calendar Configuration
GOOGLE_CREDENTIALS_B64=base64_encoded_google_credentials_json
GOOGLE_TOKEN_B64=base64_encoded_token_pickle  # Optional, auto-generated

# Webhook Configuration
WEBHOOK_BASE_URL=https://your-ngrok-url.ngrok.io
WEBSOCKET_BASE_URL=wss://your-ngrok-url.ngrok.io

3.建立数据库

通过运行SQL脚本创建所需的表：

psql -d your_database -f generate_tables.sql

4.设置Google日历API

1. 首选 谷歌云控制台
2. 创建新项目或选择现有项目
3. 启用Google日历API
4. 创建凭据（OAuth 2.0客户端ID）
5. 下载凭据JSON文件
6. Base64编码JSON文件并将其添加到您的 .env 作为 GOOGLE_CREDENTIALS_B64

5.设置Twilio

1. 创建一个 Twilio帐户
2. 购买具有语音功能的电话号码
3. 在Twilio电话号码设置中配置webhook URL
4. 将您的Twilio凭据添加到 .env 文件

6.设立ngrok

1. 安装ngrok： brew install ngrok （macOS）或从下载 ngrok.com
2. 从获取您的authtoken ngrok仪表板
3. 配置ngrok： ngrok config add-authtoken your_ngrok_token

7.运行应用程序

生产设置（推荐）

# Start all servers and ngrok tunnels
python start_servers.py

这将开始：

• 端口5000上的Flask服务器
• 端口5001上的WebSocket服务器
• 用于webhooks的ngrok隧道
• 所有必要的后台流程

开发设置

# Start individual components
python app.py                    # Flask server
python lgch_todo/http_websocket_server.py  # WebSocket server
python setup_ngrok_tunnels.py   # ngrok tunnels

接入点

• http://localhost:5000/lgch_todo/ -LGCH Todo网页界面
• http://localhost:5000/lgch-tech-spec -技术规格页
• ws://localhost:5001/ws -用于语音通话的WebSocket端点

🎤 使用Luna

电话语音接口（生产）

1. 使用以下命令运行应用程序 python start_servers.py
2. 拨打您的Twilio电话号码
3. 自然地说出你的要求（例如，“创建一个高优先级的待办事项，以便在明天之前完成项目报告”）
4. Luna将处理您的请求，与数据库和谷歌日历交互，并口头回复
5. 继续对话或挂断电话结束通话

web界面

1. 使用以下命令运行Flask应用程序 python app.py
2. 访问 http://localhost:5000/lgch_todo/ 对于web界面
3. 使用REST API终结点 /lgch_todo/run_agent 以编程方式与Luna交互

API使用

向发送POST请求 /lgch_todo/run_agent 使用JSON有效载荷：

{
  "prompt": "Create a high priority todo to finish the project report by tomorrow"
}

答复：

{
  "result": "I've created a high priority todo for you: 'Finish the project report by tomorrow'. The task has been added to your todo list and synced with your Google Calendar."
}

示例命令

待办事项管理：

• “创建一个待办事项，优先购买杂货”
• “显示我所有待处理的待办事项”
• “将杂货购物待办事项标记为已完成”
• “删除旧项目todo”

提醒管理：

• “创建一个提醒，明天下午2点给妈妈打电话”
• “为下周的医生预约设置提醒”
• “删除会议提醒”

日历事件：

• “安排下周五下午2点至3点的会议”
• “我这周的日程表上有什么？”
• “为明天的团队站立活动创建日历活动”

概述：

• “你能帮我什么？”
• “显示我的生产力摘要”
• “帮我安排今天的任务”

🧩 项目结构

Project Root/
├── app.py                       # Main Flask application
├── start_servers.py             # Production server startup script
├── setup_ngrok_tunnels.py       # ngrok tunnel management
├── ngrok.yml                    # ngrok configuration file
├── requirements.txt             # Python dependencies
├── recordings/                  # Call recording storage (git-ignored)
└── lgch_todo/                   # LGCH Todo module
    ├── __init__.py              # Package initialization, exports blueprint
    ├── routes.py                # Flask routes and Twilio webhooks
    ├── http_websocket_server.py # Hybrid HTTP/WebSocket server
    ├── twilio_handler.py        # Twilio Media Streams handler
    ├── assistant_graph_todo.py  # LangGraph agent definition
    ├── state.py                 # Agent state management
    ├── voice_utils.py           # Audio recording and playback
    ├── generate_tables.sql      # Database schema
    ├── templates/               # Flask templates
    │   └── lgch_todo_index.html # Web interface template
    └── mcps/                    # Model Context Protocol servers
        ├── mcp_config.json      # MCP server configuration
        └── local_servers/
            ├── db_todo.py       # Database operations via MCP
            └── google_calendar.py # Calendar operations via MCP

Flask集成

该项目被集成到一个更大的Flask应用程序中，其结构如下：

main_project/
├── app.py                       # Main Flask application
├── lgch_todo/                   # LGCH Todo module (this project)
├── syfw_todo/                   # Other todo modules
├── vapi_todo/                   # Other todo modules
├── blnd_todo/                   # Other todo modules
└── templates/
    └── lgch_tech_spec.html      # Technical specification page

🔧 自定义代理

修改系统提示

要更改Luna的个性或能力，请编辑 system_prompt 在 assistant_graph_todo.py:

system_prompt = """You are Luna, the personal productivity assistant...

Flask集成定制

Flask集成在 /lgch_todo/run_agent。您可以通过以下方式自定义web界面：

1. 修改模板：编辑 templates/lgch_todo_index.html 更改web界面
2. 添加新端点：在中添加新路线 routes.py 用于附加功能
3. 自定义API响应：修改 run_agent 功能在 routes.py 更改响应的格式

添加新工具

1. 在中创建新的MCP服务器或向现有服务器添加工具 mcps/local_servers/
2. 在中注册服务器 mcps/mcp_config.json
3. 代理将自动使用这些工具

更改语音设置

在中修改TTS设置 voice_utils.py:

async def play_audio(message: str):
    # ...
    async with openai_async.audio.speech.with_streaming_response.create(
        model="gpt-4o-mini-tts",
        voice="fable",  # Change the voice here
        input=cleaned_message,
        instructions="Speak in a cheerful, helpful tone with a brisk pace.",  # Modify instructions
        response_format="pcm",
        speed=1.2,  # Adjust speed
    ) as response:
        # ...

📊 数据库模式

应用程序使用以下表格：

• 所有_lgch：带有标题、描述、优先级、截止日期和完成状态的待办事项
• reminders_lgch：带有文本、重要性级别和提醒日期的提醒
• 日历_活动\_ lgch：带有标题、描述、开始/结束时间的日历事件
• 通话记录\_ lgch：通话记录元数据和文件路径

所有表都包含用于同步的Google日历事件ID，并前缀为 lgch_ 用于命名空间隔离。

🔄 谷歌日历集成

• 自动同步：所有待办事项、提醒和事件都会自动与谷歌日历同步
• 事件创建：待办事项成为带有“TODO:”前缀的日历事件
• 状态更新：已完成的待办事项将其日历事件更新为“已完成：”
• 提醒事件：提醒成为带有“提醒：”前缀的日历事件
• 清理：已删除的邮件会删除其关联的日历事件
• 双向同步：谷歌日历中的更改可以反映回系统

🧪 测试结果和验证

LGCH Todo系统已经过全面测试，重点是核心MCP工具：create_Todo、complete_Todo、create_reminder和delete_reminder功能。所有测试都证明了语音界面、数据库操作和谷歌日历同步的成功集成。

测试组件

1. 创建待办事项工具：语音输入→ 语音到文本→ LangGraph代理→ create_todo MCP工具→ 数据库存储→ 谷歌日历同步→ 文本转语音响应
2. 完整的待办事项工具：语音输入→ 语音到文本→ LangGraph代理→ complete_todo MCP工具→ 数据库更新→ 谷歌日历更新→ 文本转语音响应
3. 创建提醒工具：语音输入→ 语音到文本→ LangGraph代理→ create_reminder MCP工具→ 数据库存储→ 谷歌日历同步→ 文本转语音响应
4. 删除提醒工具：语音输入→ 语音到文本→ LangGraph代理→ delete_reminder MCP工具→ 数据库删除→ 谷歌日历删除→ 文本转语音响应

配套基础设施

• ✅ LangGraph代理处理
• ✅ 文本转语音（OpenAI TTS）
• ✅ WebSocket通信
• ✅ ngrok隧道管理
• ✅ MCP服务器集成
• ✅ Twilio手机集成

📚 学习资源

• LangGraph简介
• 部署LangGraph代理
• 带LangGraph代理的MCP
• LangGraph文档
• OpenAI API文档
• 模型上下文协议（MCP）
• Twilio Voice API文档
• ngrok文件
• SQLAlchemy文档
• Google日历API文档
• WebSocket文档

🤝 贡献

欢迎投稿！请随时提交拉取请求。

📝 许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。