# MeetSpot
### AI Agent for Multi-Person Meeting Point Recommendations
*Not just a search tool. An autonomous agent that decides the fairest meeting point for everyone.*
[](https://meetspot-irq2.onrender.com)
[](https://www.bilibili.com/video/BV1aUK7zNEvo/)
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://fastapi.tiangolo.com/)
[](https://github.com/calderbuild/MeetSpot/actions)
[English](README.md) | [简体中文](README_ZH.md)
---
## 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
```bash
# 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`
```json
{
"locations": ["Peking University", "Tsinghua University", "Renmin University"],
"keywords": "cafe restaurant",
"user_requirements": "parking, quiet environment"
}
```
**Response:**
```json
{
"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
 Agent Chain-of-Thought |
 Interactive Map View |
 Multi-Factor AI Scoring |
 Venue Recommendation Cards |
More Screenshots
 Homepage |
 Meeting Point Finder |
 Results Summary |
 AI Customer Service |
---
## 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
```bash
# 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
|
**Email:** Johnrobertdestiny@gmail.com
**GitHub:** [Issues](https://github.com/calderbuild/MeetSpot/issues)
**Blog:** [jasonrobert.me](https://jasonrobert.me/)
|
**Personal WeChat**
|
**WeChat Group**
|
---
## License
MIT License - see [LICENSE](LICENSE) for details.
---
**If MeetSpot helps you, please give it a star!**
[](https://star-history.com/#calderbuild/MeetSpot&Date)