---

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

---

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

Agent Chain-of-Thought	Interactive Map View
Homepage	Meeting Point Finder

More Screenshots

Full Results Page (NYC example)

AI Assistant Chat

---

Tech Stack

Layer	Technologies
Backend	FastAPI, Pydantic, aiohttp, SQLAlchemy 2.0, asyncio
Frontend	HTML5, CSS3, Vanilla JavaScript, Boxicons
Maps	Amap (Gaode) for China + Google Maps Platform for international (auto-routed by language)
AI	OpenRouter (default openai/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

Email: Johnrobertdestiny@gmail.com GitHub: Issues Blog: calderbuild.github.io

Personal WeChat

WeChat Group

---

Acknowledgements

Special thanks to AIGC Link for the promotions on XiaoHongShu.

---

License

MIT License - see LICENSE for details.

---