Phone Recommendation Agent

电话推荐代理

人工智能副驾驶在几秒钟内缩小了手机选择范围。后端运行由规划者编排的模型上下文协议（MCP）工具链，而新的glassmorphism React接口提供了会话内存、推理透明度和实时突尼斯定价的优质体验。

______________________________________________________________________

✨ 亮点

• 基于记忆的代理推理：编排器将LLM规划与启发式相结合，并持久化对话上下文，因此后续问题会自动重用之前讨论的设备。
• 实时市场数据：并发scraper（requests+cloudscraper+BeautifulSoup）并行查询Tunisianet、Zoom和Spacenet，并对定价元数据进行标准化，以便快速比较。
• 丰富的见解：工具利用规格、Reddit情绪、替代建议和需求验证来提出可操作的谈话要点。
• 玻璃UIVite+React 18+Tailwind前端将所有内容都封装在磨砂玻璃仪表板中，配有聊天历史记录、推理切换和有趣的机器人徽章。
• 基于标准的集成JSON-RPC 2.0和MCP兼容的工具模式使得在外部产品中嵌入代理变得容易。

______________________________________________________________________

🧱 架构概述

┌─────────────────────────────────┐
│           React Frontend        │
│  - ChatPane + Reasoning Panel   │
│  - Tailwind / Framer Motion     │
│  - React Query session client   │
└───────────────▲────────────────┘
								│ REST / JSON-RPC
┌───────────────┴────────────────┐
│         FastAPI MCP Server     │
│  ToolOrchestrator (LLM+rules)  │
│  Session memory, logging       │
│  JSON-RPC dispatcher           │
└───────────────▲────────────────┘
								│ Tool calls (thread pool)
┌───────────────┴────────────────┐
│           Tool Suite           │
│  phone_specs / specs_analyzer  │
│  price_extractor (concurrent)  │
│  web_scraper (Reddit PRAW)     │
│  sentiment / alternatives      │
│  spec_validator                │
└───────────────┴────────────────┘
								│
				 CSV / Postgres + APIs

______________________________________________________________________

🛠 后端堆栈

• FastAPI+JSON-RPC：公开REST帮助程序和 /rpc 具有JSON-RPC 2.0响应、CORS和线程池工具执行的端点。
• 工具编排器：将启发式意图检测与可选功能相结合 mistralai 规划、维护会话上下文并协调MCP工具调用。
• 规格数据层：默认为a pandas DataFrame来源于 Backend/database/mobile.csv，带有可选的PostgreSQL+ SQLAlchemy 后端和三元组相似性。
• 蜘蛛定价：用途 requests, cloudscraper，以及 BeautifulSoup 在...之内 ThreadPoolExecutor 弹性收集TND定价信号。
• 检查摄入情况：依赖 praw 对Reddit进行身份验证，并过滤提交/评论，以获得无谣言的情绪输入。
• 相似性启发式：适用 rapidfuzz 评分和自定义数值解析助手，以保持模糊匹配的可解释性和确定性。

______________________________________________________________________

🚀 入门指南

后端

1. 创建并激活虚拟环境

   python -m venv venv
   source venv/bin/activate  # Windows: venv\Scripts\activate

1. 安装依赖项

   pip install -r requirements.txt

1. 配置环境 （后端/.env）

   MISTRAL_API_KEY=your_mistral_key               enables LLM synthesis
   MCP_SERVER_URL=http://127.0.0.1:8000
   FRONTEND_ORIGIN=http://localhost:5173
   # Optional PostgreSQL backing store
   POSTGRES_HOST=...
   POSTGRES_DB=...
   POSTGRES_USER=...
   POSTGRES_PASSWORD=...

1. 运行服务器

   uvicorn Backend.mcp_server:app --host 0.0.0.0 --port 8000 --reload

前端

1. ```bash

cd frontend npm install npm run dev

1. 访问 `http://localhost:5173` 用于实时玻璃UI。

______________________________________________________________________

### 🧠 会话代理

- **端点**: `POST /agent/chat`
- **请求**:

{ "query": "What is the price of iPhone 14 Pro?", "session_id": "optional-stable-id", "include_reasoning": true }

- **响应**：自然语言答案加上工具推理快照（如有要求）。
- 对话会自动重用最新的电话上下文来回答后续问题。

要直接使用MCP/JSON-RPC，请将结构化调用发送到 `POST /rpc` 使用方法：

|方法|目的|
|--------------------|--------------------------------------------------|
| `mcp.list_tools` |枚举可用的工具架构。                |
| `mcp.call_tool` |使用关键字参数调用单个工具。     |
| `agent.recommend` |运行RAG+推荐管道。           |
| `agent.chat` |与REST助手的行为相同。               |
| `system.ping` |轻量级健康检查。                        |

`Backend/mcp_client.py` 包含现成的Python包装器。

______________________________________________________________________

### 🛠️ 工具目录

- **电话规格** – `pandas` + `rapidfuzz` 通过可选的PostgreSQL三元组搜索进行模糊匹配 `SQLAlchemy`.
- **web_scraper** –Reddit聚合由 `praw`，具有谣言过滤和身份验证诊断功能。
- **规格分析器** –启发式地对性能/电池/摄像头/显示器特征进行分类。
- **情感分析** –在Reddit评论批次上进行关键字驱动的利弊提取。
- **价格提取器** – `requests`/`cloudscraper`/`BeautifulSoup` 突尼斯零售商与时间指标的并发性。
- **替代品** –纯Python规范距离启发式算法，用于预算敏感的替代方案。
- **spec_validator** –使用正则表达式解析助手进行基于规则的需求检查。

所有工具结果均遵循共享 `ToolOutput` 一致性测井合同。

______________________________________________________________________

### 🧰 前端功能

- **聊天窗格** 带有动画消息气泡、乐观更新和推理切换。
- **会话持续** 通过localStorage，重新加载可以保持上下文的完整性。
- **顺风设计代币** (`src/theme/tokens.ts`)用于快速主题化。
- **机器人徽章** 它在没有GPU开销的情况下锚定了品牌标识。

应用程序结构反映了原子设计原则，并已准备好通过Storybook（尚未配置）进行组件文档记录。

______________________________________________________________________

### 📂 项目结构

Backend/ mcp_server.py # FastAPI app, JSON-RPC dispatcher, CORS setup orchestrator.py # LLM + heuristic planner with session memory tools/ # All MCP tool implementations frontend/ src/ App.tsx # Glass dashboard + chat integration components/ # Layout, chat, and common UI pieces hooks/useAgentChat.ts # React Query powered chat state utils/ # env, id, and session helpers public/assets/robot-sticker.svg

### 🔖 许可证

此存储库根据MIT许可证获得许可。看 `LICENSE` 了解详情。