<div align="center"> <img src="assets/icon.svg" alt="MRRA 图标" width="120" height="120">

🗺️ MRRA

移动检索与反射代理

基于图检索增强生成（GraphRAG）和多代理反射的智能移动分析

🚀 快速开始 • 📖 文档 • 🌟 功能 • 🛠️ 安装

</div>

---

🎯 概述

MRRA 是一个前沿的 Python 包，通过融合 GraphRAG（基于图的检索增强生成）和 多代理反射，彻底改变了移动轨迹分析。只需提供包含 user_id、timestamp、latitude 和 longitude 列的轨迹数据，即可解锁对未来位置、未来定位以及完整日常路线的智能预测。

<div align="center"> <img src="assets/mrra-framwork.png" alt="MRRA 架构" width="800"> </div>

✨ 关键特性

<table> <tr> <td>

🧠 智能架构

• GraphRAG 集成：高级基于图的检索系统
• 多代理反射：具有置信度加权的复杂代理编排
• 时空推理：对移动模式的深刻理解

</td> <td>

🔧 开发者友好

• 即插即用：最小配置即可使用
• 兼容 LangChain：无缝集成到 LangChain 生态系统
• MCP 工具：内置支持天气、地图和地理空间服务

</td> </tr> <tr> <td>

📊 数据处理

• 灵活输入：支持标准轨迹格式
• 图构建：自动生成移动图
• 模式识别：智能活动和行为检测

</td> <td>

🎯 预测任务

• 下一个位置：预测立即的下一个位置
• 未来位置：预测特定时间的位置
• 全天轨迹：生成完整的日常路线模式

</td> </tr> </table>

🛠️ 安装

快速安装

pip install mrra

开发安装

git clone https://github.com/AoWangg/mrra.git
cd mrra
pip install -e .

可选依赖项

# 用于 MCP 工具集成
pip install mrra[mcp]

# 用于开发
pip install mrra[dev]

🚀 快速开始

基本用法

import pandas as pd
from mrra.data.trajectory import TrajectoryBatch
from mrra.retriever.graph_rag import GraphRAGGenerate
from mrra.agents.builder import build_mrra_agent

# 📊 准备您的轨迹数据
df = pd.DataFrame({
    'user_id': ['user_1', 'user_1', 'user_1'],
    'timestamp': ['2023-01-01 09:00:00', '2023-01-01 12:00:00', '2023-01-01 18:00:00'],
    'latitude': [31.2304, 121.4737, 31.2404],
    'longitude': [121.4737, 31.2504, 121.4937],
})

# 🔄 创建轨迹批次和检索器
tb = TrajectoryBatch(df)
retriever = GraphRAGGenerate(tb=tb)

# 🤖 构建 MRRA 代理
agent = build_mrra_agent(
    llm={
        "provider": "openai-compatible",
        "model": "qwen-plus",
        "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "api_key": "YOUR_API_KEY"  # 生产中使用环境变量
    },
    retriever=retriever,
    reflection={
        "max_round": 3,
        "subAgents": [
            {"name": "temporal", "prompt": "时间推理专家", "mcp": {"weather": {}}},
            {"name": "spatial", "prompt": "空间分析专家", "mcp": {"maps": {}}},
            {"name": "pattern", "prompt": "行为模式分析师", "mcp": {}},
        ],
        "aggregator": "confidence_weighted_voting"
    }
)

# 🎯 进行预测
result = agent.invoke({
    "task": "next_position", 
    "user_id": "user_1", 
    "t": "2023-01-02 09:30:00"
})
print(result)

高级 MCP 集成

# 🗺️ 配置真实世界服务
reflection_config = {
    "subAgents": [
        {
            "name": "spatial", 
            "prompt": "具有实时地图数据的空间分析专家", 
            "mcp": {
                "gmap": {
                    "url": "https://mcp.amap.com/sse?key=YOUR_AMAP_KEY", 
                    "transport": "sse"
                }
            }
        }
    ]
}

🎯 支持的任务

任务	描述	输入	输出
next_position	在给定时间之后预测下一个位置	user_id, t	下一个坐标预测
future_position	预测特定未来的地点	user_id, t	未来坐标预测
full_day_traj	生成完整的日常轨迹	user_id, date	全天路线序列

📊 数据格式

必要列

• user_id：每个用户的唯一标识符
• timestamp：ISO 格式的时间戳（例如，“2023-01-01 09:00:00”）
• latitude：纬度坐标（浮点数）
• longitude：经度坐标（浮点数）

🌍 MCP 工具集成

MRRA 支持多种 MCP 集成策略，并具有优雅的回退机制：

1. 主要：langchain-mcp-adapters（推荐）
2. 回退：langchain-mcp 工具包
3. 原生：原始 MCP SSE 发现

支持的服务

• 🗺️ 地图：Google 地图、高德地图、OpenStreetMap
• 🌤️ 天气：实时天气数据
• 📍 地理编码：地址到坐标的转换

📖 文档

• 🏠 主页：mrra.tech
• 📚 文档：mrra.tech/en/docs
• 🇨🇳 中文文档：mrra.tech/zh/docs

🧪 示例 & 演示

# 🌟 GeoLife 数据集演示
python scripts/verify_geolife.py

# 🔍 检索器测试
python scripts/check_retriever.py

🤝 贡献

我们欢迎贡献！请参阅我们的 贡献指南 获取详细信息。

开发设置

# 创建环境
conda create -n mrra-dev python=3.10
conda activate mrra-dev

# 开发模式安装
pip install -e .[dev]

# 运行测试
pytest

# 代码格式化
ruff format .
ruff check .

🔒 安全 & 最佳实践

• 🔐 从不提交 API 密钥 - 使用环境变量或密钥管理器
• 📁 大型数据集 默认被 git 忽略
• 🛡️ 安全 MCP 连接 使用适当的认证

📄 许可证

本项目采用 MIT 许可证 - 详情见 LICENSE 文件。

🙏 致谢

站在巨人的肩膀上：

• LangChain 用于大语言模型编排
• NetworkX 用于图处理
• Pandas 用于数据操作

📊 项目统计

<div align="center">

</div>

---

<div align="center"> _{🚀 <strong>准备好彻底改变移动分析了吗？</strong> <a href="#-快速开始">现在就开始吧！</a>} </div>