<div align="center">

MeetSpot

<img src="docs/logo.jpg" alt="MeetSpot Logo" width="200"/>

AI Agent for Multi-Person Meeting Point Recommendations

Not just a search tool. An autonomous agent that decides the fairest meeting point for everyone.

English | 简体中文

</div>

---

Why MeetSpot?

Most location tools return results near you. MeetSpot calculates the geographic center of all participants and returns AI-ranked venues that minimize everyone's travel time.

| Traditional Tools | MeetSpot | |-------------------|----------| | Search near your location | Calculate fair center for all | | Keyword-based ranking | AI-powered multi-factor scoring | | Static results | Adaptive dual-mode routing | | No reasoning | Explainable AI with chain-of-thought |

<div align="center"> <img src="docs/show1.jpg" alt="MeetSpot Interface" width="85%"/> </div>

---

Agent Architecture

MeetSpot is an AI Agent - it makes autonomous decisions based on request complexity, not just executes searches.

                              User Request
                                   │
                    ┌──────────────┴──────────────┐
                    │      Complexity Router      │
                    │    (Autonomous Decision)    │
                    └──────────────┬──────────────┘
                                   │
              ┌────────────────────┼────────────────────┐
              │                    │                    │
              ▼                    │                    ▼
    ┌─────────────────┐            │          ┌─────────────────┐
    │    Rule Mode    │            │          │   Agent Mode    │
    │   (2-4 sec)     │            │          │   (8-15 sec)    │
    │  Deterministic  │            │          │  LLM-Enhanced   │
    └────────┬────────┘            │          └────────┬────────┘
             │                     │                   │
             └─────────────────────┼───────────────────┘
                                   │
                    ┌──────────────┴──────────────┐
                    │    5-Step Processing        │
                    │        Pipeline             │
                    └──────────────┬──────────────┘
                                   │
        ┌──────────┬──────────┬────┴────┬──────────┬──────────┐
        │          │          │         │          │          │
        ▼          ▼          ▼         ▼          ▼          ▼
    Geocode    Center     POI      Ranking     HTML      Result
              Calc      Search               Gen

Intelligent Mode Selection

The Agent autonomously decides which processing mode to use:

| Factor | Score | Example | |--------|-------|---------| | Location count | +10/location | 4 locations = 40 pts | | Complex keywords | +15 | "quiet business cafe with private rooms" | | Special requirements | +10 | "parking, wheelchair accessible, WiFi" |

• Score < 40: Rule Mode (fast, deterministic, pattern-matched)
• Score >= 40: Agent Mode (LLM reasoning, semantic understanding)

Agent Mode Scoring

Final Score = Rule Score × 0.4 + LLM Score × 0.6

The LLM analyzes semantic fit between venues and requirements, then blends with rule-based scoring. Results include Explainable AI visualization showing the agent's reasoning process.

5-Step Pipeline

| Step | Function | Details | |------|----------|---------| | Geocode | Address → Coordinates | 90+ smart mappings (universities, landmarks) | | Center Calc | Fair point calculation | Spherical geometry for accuracy | | POI Search | Venue discovery | Concurrent async search, auto-fallback | | Ranking | Multi-factor scoring | Base(30) + Popularity(20) + Distance(25) + Scenario(15) + Requirements(10) | | HTML Gen | Interactive map | Amap JS API integration |

---

Quick Start

# Clone and install
git clone https://github.com/calderbuild/MeetSpot.git && cd MeetSpot
pip install -r requirements.txt

# Configure (get key from https://lbs.amap.com/)
cp config/config.toml.example config/config.toml
# Edit config.toml and add your AMAP_API_KEY

# Run
python web_server.py

Open http://127.0.0.1:8000

---

API Reference

Main Endpoint

POST /api/find_meetspot

{
  "locations": ["Peking University", "Tsinghua University", "Renmin University"],
  "keywords": "cafe restaurant",
  "user_requirements": "parking, quiet environment"
}

Response:

{
  "success": true,
  "html_url": "/workspace/js_src/recommendation_xxx.html",
  "center": {"lat": 39.99, "lng": 116.32},
  "venues_count": 8
}

Other Endpoints

| Endpoint | Method | Description | |----------|--------|-------------| | /api/find_meetspot_agent | POST | Force Agent Mode (LLM reasoning) | | /api/ai_chat | POST | AI customer service chat | | /health | GET | System health check | | /docs | GET | Interactive API documentation |

---

Screenshots

<table> <tr> <td width="50%"><img src="docs/agent-thinking.jpg" alt="Agent Reasoning"/><p align="center"><b>Agent Chain-of-Thought</b></p></td> <td width="50%"><img src="docs/result-map.jpg" alt="Interactive Map"/><p align="center"><b>Interactive Map View</b></p></td> </tr> <tr> <td width="50%"><img src="docs/多维度智能评分show4.jpg" alt="AI Scoring"/><p align="center"><b>Multi-Factor AI Scoring</b></p></td> <td width="50%"><img src="docs/show5推荐地点.jpg" alt="Venue Cards"/><p align="center"><b>Venue Recommendation Cards</b></p></td> </tr> </table> <details> <summary><b>More Screenshots</b></summary> <table> <tr> <td width="50%"><img src="docs/homepage.jpg" alt="Homepage"/><p align="center"><b>Homepage</b></p></td> <td width="50%"><img src="docs/finder-input.jpg" alt="Input Interface"/><p align="center"><b>Meeting Point Finder</b></p></td> </tr> <tr> <td width="50%"><img src="docs/result-summary.jpg" alt="Results"/><p align="center"><b>Results Summary</b></p></td> <td width="50%"><img src="docs/AI客服.jpg" alt="AI Chat"/><p align="center"><b>AI Customer Service</b></p></td> </tr> </table> </details>

---

Tech Stack

| Layer | Technologies | |-------|--------------| | Backend | FastAPI, Pydantic, aiohttp, SQLAlchemy 2.0, asyncio | | Frontend | HTML5, CSS3, Vanilla JavaScript, Boxicons | | Maps | Amap (Gaode) - Geocoding, POI Search, JS API | | AI | DeepSeek / GPT-4o-mini for semantic analysis | | Deploy | Render, Railway, Docker, Vercel |

---

Project Structure

MeetSpot/
├── api/
│   └── index.py                 # FastAPI application entry
├── app/
│   ├── tool/
│   │   └── meetspot_recommender.py  # Core recommendation engine
│   ├── config.py                # Configuration management
│   └── design_tokens.py         # WCAG-compliant color system
├── templates/                   # Jinja2 templates
├── public/                      # Static assets
└── workspace/js_src/            # Generated result pages

---

Development

# Development server with hot reload
uvicorn api.index:app --reload

# Run tests
pytest tests/ -v

# Code quality
black . && ruff check . && mypy app/

---

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

Contact

<table> <tr> <td>

Email: Johnrobertdestiny@gmail.com

GitHub: Issues

Blog: jasonrobert.me

</td> <td align="center"> <img src="public/docs/vx_chat.png" alt="WeChat" width="150"/>

Personal WeChat

</td> <td align="center"> <img src="public/docs/vx_group.png" alt="WeChat Group" width="150"/>

WeChat Group

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

---

License

MIT License - see LICENSE for details.

---

<div align="center">

If MeetSpot helps you, please give it a star!

</div>