🗺️ MRRA

Mobility Retrieve-and-Reflect Agent

GraphRAG + Multi-Agent Reflection for Intelligent Mobility Analysis

🚀 Quick Start • 📖 Documentation • 🌟 Features • 🛠️ Installation

🎯 Overview

MRRA is a cutting-edge Python package that revolutionizes mobility trajectory analysis through the fusion of GraphRAG (Graph-based Retrieval-Augmented Generation) and multi-agent reflection. Simply provide trajectory data with user_id, timestamp, latitude, longitude columns, and unlock intelligent predictions for next locations, future positions, and complete daily routes.

✨ Key Features

🛠️ Installation

Quick Install

pip install mrra

Development Install

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

Optional Dependencies

# For MCP tools integration
pip install mrra[mcp]

# For development
pip install mrra[dev]

🚀 Quick Start

Basic Usage

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

# 📊 Prepare your trajectory data
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, 31.2404, 31.2504],
    'longitude': [121.4737, 121.4837, 121.4937],
})

# 🔄 Create trajectory batch and retriever
tb = TrajectoryBatch(df)
retriever = GraphRAGGenerate(tb=tb)

# 🤖 Build MRRA agent
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"  # Use environment variables in production
    },
    retriever=retriever,
    reflection={
        "max_round": 3,
        "subAgents": [
            {"name": "temporal", "prompt": "Temporal reasoning specialist", "mcp": {"weather": {}}},
            {"name": "spatial", "prompt": "Spatial analysis expert", "mcp": {"maps": {}}},
            {"name": "pattern", "prompt": "Behavior pattern analyst", "mcp": {}},
        ],
        "aggregator": "confidence_weighted_voting"
    }
)

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

Advanced MCP Integration

# 🗺️ Configure with real-world services
reflection_config = {
    "subAgents": [
        {
            "name": "spatial", 
            "prompt": "Expert in spatial analysis with real-time map data", 
            "mcp": {
                "gmap": {
                    "url": "https://mcp.amap.com/sse?key=YOUR_AMAP_KEY", 
                    "transport": "sse"
                }
            }
        }
    ]
}

🎯 Supported Tasks

📊 Data Format

Required Columns

• user_id: Unique identifier for each user
• timestamp: ISO format timestamp (e.g., "2023-01-01 09:00:00")
• latitude: Latitude coordinate (float)
• longitude: Longitude coordinate (float)

🌍 MCP Tools Integration

MRRA supports multiple MCP integration strategies with graceful fallback:

1. Primary: langchain-mcp-adapters (recommended)
2. Fallback: langchain-mcp toolkit
3. Native: Raw MCP SSE discovery

Supported Services

• 🗺️ Maps: Google Maps, Amap, OpenStreetMap
• 🌤️ Weather: Real-time weather data
• 📍 Geocoding: Address to coordinate conversion

📖 Documentation

• 🏠 Homepage: mrra.tech
• 📚 Documentation: mrra.tech/en/docs
• 🇨🇳 中文文档: mrra.tech/zh/docs

🧪 Examples & Demos

# 🌟 GeoLife dataset demo
python scripts/verify_geolife.py

# 🔍 Retriever testing
python scripts/check_retriever.py

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Setup

# Create environment
conda create -n mrra-dev python=3.10
conda activate mrra-dev

# Install in development mode
pip install -e .[dev]

# Run tests
pytest

# Code formatting
ruff format .
ruff check .

🔒 Security & Best Practices

• 🔐 Never commit API keys - Use environment variables or secret managers
• 📁 Large datasets are git-ignored by default
• 🛡️ Secure MCP connections with proper authentication

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built on the shoulders of giants:

• LangChain for LLM orchestration
• NetworkX for graph processing
• Pandas for data manipulation

📊 Project Stats