Hugging Face's logo

Spaces:
MCP-1st-Birthday
/
Seoul_Hunters
Sleeping

App Files Community
1
AnnaKong commited on
Commit
328cf8e
Β·
verified Β·
1 Parent(s): c5e859a

Update README.md

Browse files
Files changed (1) hide show
  1. README.md +109 -2
README.md CHANGED
@@ -1,12 +1,119 @@
1
  ---
2
  title: Seoul Hunters
3
- emoji: πŸ“ˆ
4
  colorFrom: gray
5
  colorTo: gray
6
  sdk: gradio
7
  sdk_version: 6.0.1
8
  app_file: app.py
9
  pinned: false
 
 
 
 
 
10
  ---
 
11
 
12
- Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
  ---
2
  title: Seoul Hunters
3
+ emoji: πŸš€
4
  colorFrom: gray
5
  colorTo: gray
6
  sdk: gradio
7
  sdk_version: 6.0.1
8
  app_file: app.py
9
  pinned: false
10
+ tags:
11
+ - mcp-in-action-track-consumer
12
+ license: mit
13
+ thumbnail: >-
14
+ https://cdn-uploads.huggingface.co/production/uploads/6751c83a68c1eb2ea7cdf16b/LdBNxZ1k0ZuLWieheX7_i.png
15
  ---
16
+ ## πŸ‘₯ Team Members : [**AnnaKong**](https://huggingface.co/AnnaKong), [**rintle**](https://huggingface.co/rintle)
17
 
18
+ # πŸ—ΊοΈ Seoul Hunters
19
+ > AI-powered personalized travel planner for exploring Seoul πŸšΆβ€β™€οΈβ˜•πŸœ
20
+
21
+ ---
22
+ ![Python](https://img.shields.io/badge/Python-3.10%2B-blue)
23
+ ![LangGraph](https://img.shields.io/badge/AI-LangGraph-orange)
24
+ ![Gradio](https://img.shields.io/badge/UI-Gradio-purple)
25
+ ![OpenAI](https://img.shields.io/badge/LLM-GPT--4o-green)
26
+
27
+ ## ✨ Overview
28
+
29
+ **Seoul Hunters** is an AI-driven travel planning system that generates customized itineraries for travelers visiting Seoul.
30
+
31
+ Based on natural-language user input, multiple intelligent agents collaborate to:
32
+
33
+ - Understand travel preferences
34
+ - Collect place candidates via external APIs
35
+ - Recommend optimal spots
36
+ - Build a route final itinerary
37
+
38
+
39
+ ---
40
+
41
+ ## πŸ€– Multi-Agent Workflow
42
+
43
+ | Agent | Responsibility |
44
+ |-------|---------------|
45
+ | `agent0_router.py` | Routes user input and determines next system action |
46
+ | `agent1_planner.py` | Extracts trip requirements (area, dates, interests) |
47
+ | `agent2_allocator.py` | Allocates itinerary slots based on category balance |
48
+ | `agent3_collector_kakao.py` | Collects POIs via Kakao Local Search API |
49
+ | `agent3_collector_naver.py` | Collects POIs via Naver Local Search API |
50
+ | `agent4_suggester.py` | Scores and recommends user-fit candidate places |
51
+ | `agent5_path_finder.py` | Generates the **optimal route with step-by-step itinerary** |
52
+
53
+ πŸ“Œ `state.py` maintains the shared memory between agents.
54
+ πŸ“Œ `app.py` provides the Gradio-based user interface and entry point.
55
+
56
+ ## πŸ—οΈ Architecture
57
+
58
+ The workflow is orchestrated through **LangGraph**, enabling a **cyclic, stateful reasoning loop** across agents.
59
+
60
+ ```mermaid
61
+ graph TD
62
+ User((User Input)) --> Router
63
+ Router{Agent0: Router}
64
+
65
+ Router -- "Start New Plan" --> Planner[Agent1: Planner]
66
+ Router -- "Refinement" --> Suggester
67
+ Router -- "Selection" --> Validator
68
+
69
+ Planner --> Allocator[Agent2: Allocator]
70
+ Allocator --> KakaoCollector[Agent3: Kakao API]
71
+ Allocator --> NaverCollector[Agent3: Naver API]
72
+
73
+ KakaoCollector --> Suggester[Agent4: Suggester]
74
+ NaverCollector --> Suggester
75
+
76
+ Suggester --> UserReview{Human Feedback}
77
+ UserReview --> Validator[Agent4: Validator]
78
+ Validator --> PathFinder[Agent5: Path Finder]
79
+
80
+ PathFinder --> FinalPlan((Final Optimized Itinerary))
81
+ ```
82
+
83
+ ---
84
+ ## ✨ Key Features
85
+
86
+ | Feature | Description |
87
+ |--------|------------|
88
+ | πŸ—£οΈ Natural Language Input | Just talk β€” no forms required. |
89
+ | 🌍 Multi-language Support | Korean, English, Japanese, and Chinese auto-detected. |
90
+ | 🧠 Multi-Agent Coordination | Reasoning agents collaborate using LangGraph. |
91
+ | 🀝 Human-in-the-Loop | Users review candidates before route generation. |
92
+ | πŸ“ Real-Time Place Search | Powered by Kakao Local API & Naver API. |
93
+ | πŸ—ΊοΈ Interactive Map | Final route visualization with Folium. |
94
+
95
+ ---
96
+
97
+ ## 🧩 Tech Stack
98
+
99
+ | Category | Technology |
100
+ |----------|------------|
101
+ | UI / Frontend | **Gradio** |
102
+ | Backend | **Python (3.10+)** |
103
+ | LLM & Reasoning | **LangChain, OpenAI API** |
104
+ | External APIs | **Kakao Local API, Naver Local API** |
105
+ | Hosting | **Hugging Face Spaces** |
106
+ ---
107
+ ## πŸ”— Social Media Post (Required)
108
+ I submitted this project for the MCP Hackathon!
109
+ - Link: [LinkedIn](https://www.linkedin.com/pulse/mcp-1%25EC%25A3%25BC%25EB%2585%2584-%25EC%25B6%2595%25ED%2595%2598%25ED%2595%25A9%25EB%258B%2588%25EB%258B%25A4-%25EC%258A%25B9%25ED%2599%2598-%25EA%25B0%2595-astqc/)
110
+
111
+ ## πŸŽ₯ Demo Video (Required)
112
+ Check out how it works:
113
+ - Link: [![YouTube Preview](https://img.youtube.com/vi/8weFJuXJw8s/maxresdefault.jpg)](https://www.youtube.com/watch?v=8weFJuXJw8s)
114
+
115
+ ---
116
+
117
+ > Built for the **MCP 1st Birthday Hackathon πŸŽ‰**
118
+
119
+ ---