🏝️ CityPick

Urban Cultural Tourism AI Agent Platform — AI helps you discover the best of the city.

中文

---

📊 Highlights

Metric	Value
AI Agents	7 (Search + Extract + Fuse + Recommend + Itinerary + Present + Monitor)
Agent Skills	9
LLM Engine	DeepSeek (Query Understanding + Recommendation + Itinerary Tips)
Query Response	<1s (rule engine) / <3s (LLM enhanced)
Mock Data	25+ entries (conflict/expired/boundary scenarios)
Automated Tests	13/13 passing

---

🎯 Overview

CityPick is a multi-Agent collaborative urban cultural tourism AI platform.

Users ask questions in natural language — "What's happening in Lingang this weekend?", "Where to go with kids?", "Plan a one-day trip" — and CityPick automatically orchestrates 7 AI Agents through a pipeline: Search → Extract → Fuse → Recommend → Itinerary → Present → Update.

Lingang New Area is the pilot verification scenario. The architecture is designed for seamless replication to any city nationwide.

---

🏗️ Architecture

After downloading, you will see the following structure (public/ is the runnable directory):

citypick/
├── public/                        ← ★ Runnable directory (all business code here)
│   ├── main.py                    # HTTP server entry, run with `python main.py`
│   ├── backend_engine.dat         # ★ Encrypted backend blob (16.9 KB)
│   ├── backend_loader.py          # ★ Decrypt loader
│   ├── templates/index.html       # Frontend UI (Chinese locale)
│   ├── agents/                    # 7 Agent interfaces
│   ├── skills/                    # 9 Skill implementations
│   ├── mock/                      # Mock data (18 Lingang items)
│   ├── config/                    # Configuration
│   ├── docs/                      # Documentation
│   ├── config.yaml                # Global config
│   ├── requirements.txt           # Python dependencies
│   └── .env.example               # Env template
├── test_imports.py                # 8 automated tests
├── README.md / README_EN.md       # Project docs
└── .gitignore                     # Excludes .env, caches

How It Works

Browser (open source frontend)           Python Server (closed source backend)
     │                                         │
     │  POST /api/query                        │
     │  {"query":"weekend trip"}  ───────────→ │
     │                                         │  public/main.py
     │                                         │    └─ backend_loader.py
     │                                         │         ├─ decrypt backend_engine.dat
     │                                         │         ├─ load 28 Python modules
     │                                         │         └─ run_query(q, prefs, budget)
     │                                         │              └─ 7 Agent pipeline
     │                        ←────────────────│                  → JSON result
     │  JSON result                            │
     │                                         │
     └─ Render cards + itinerary               │

• Frontend: Pure HTML/JS (open source), calls POST API via fetch()
• Backend: Core logic encrypted in public/backend_engine.dat (17 KB, XOR + zlib), decrypted at runtime
• Expiry: Status bar shows expiry date and remaining days in real-time

---

🚀 Quick Start

Option 1: One-Click Launch (Recommended)

Double-click 启动项目.bat in the root directory. It will:

1. Check Python installation
2. Install dependencies automatically
3. Auto-open browser at http://127.0.0.1:7860

First launch installs dependencies (~10-30s).

Option 2: Manual Launch

Requirements

• Python 3.10+

Run (enter public/ directory first)

cd public                           # ★ enter the runnable directory
pip install -r requirements.txt     # install dependencies
python main.py                      # start server

Open http://127.0.0.1:7860.

---

🔄 Agent Pipeline

User input (natural language)
    ↓
SearchAgent   →  Multi-dimension scoring (keywords/tags/name)
    ↓
ExtractAgent  →  Normalize to unified 10-field schema
    ↓
FuseAgent     →  Deduplicate + official source priority + confidence
    ↓
RecommendAgent → Tag matching + budget filter → graded recommendations
    ↓
ItineraryAgent → Time-constrained 4-stop itinerary + lunch insertion
    ↓
PresentAgent  →  Assemble cards + itinerary for frontend
    ↓
UpdateAgent   →  Data freshness check

---

📋 Agents

Agent	Role	Responsibility
🔍 SearchAgent	Searcher	Keyword/tag/name multi-dimension matching
📋 ExtractAgent	Extractor	Unstructured → structured 10-field normalization
🔗 FuseAgent	Fuser	Deduplication + official priority + confidence
🎯 RecommendAgent	Recommender	Tag match + budget → strong/yes/maybe grading
🗺️ ItineraryAgent	Planner	Time-constrained itinerary + lunch + cost
🎨 PresentAgent	Presenter	Cards + timeline formatting
🔄 UpdateAgent	Monitor	Freshness check (>7d marked expired)

---

🛡️ Security

• User queries are NOT stored (in-memory only)
• API keys in local vault (~/.citypick/vault.json, chmod 600)
• Backend source is encrypted distribution, not directly readable
• Input truncated to 500 chars + HTML-escaped against XSS
• 1-month expiry protection; engine refuses to work after expiration

---

📄 License

CityPick Non-Commercial License

1. Non-commercial use: Allowed for personal study, research, evaluation
2. No commercial use: Commercial use requires explicit authorization
3. No SaaS deployment: Cloud service deployment prohibited without authorization
4. Derivative works: Must retain original copyright notice
5. Commercial license: Contact gauss.opc@outlook.com

© 2026 CityPick. All rights reserved.

---

"Discover the overlooked beauty in every city."

—— CityPick, an AI travel assistant for every city.