README.md

---
title: MarketSync
emoji: 🎉
colorFrom: blue
colorTo: green
sdk: streamlit
app_file: streamlit_app.py
pinned: false
---

# 🎉 MarketSync (마켓싱크)
... (기존 README 내용은 그대로 둠) ...


# 🎉 MarketSync (마켓싱크)

### Agentic RAG 기반 소상공인 맞춤형 지역 축제 추천 & 마케팅 AI 컨설턴트

신한카드 빅데이터와 전국 축제 정보를 통합 분석하여, **AI 에이전트**가 가게별로 참여할 만한 지역 축제를 추천하고 최적의 마케팅 전략 보고서를 자동 생성합니다. 🤖

---

## 🧭 프로젝트 개요

MarketSync는 **Streamlit 웹 인터페이스, FastAPI 데이터 서버, LangChain 에이전트**를 결합하여 소상공인을 위한 AI 컨설팅 서비스를 제공합니다. 사용자는 자신의 가게를 선택하여 상세 프로필과 분석 그래프를 확인한 뒤, "10월에 열리는 축제 추천해줘", "추천된 축제들의 마케팅 전략 알려줘" 와 같은 자연어 질문을 통해 맞춤형 컨설팅을 받을 수 있습니다.

**핵심 아키텍처는 Agentic RAG**입니다. AI 에이전트(`Orchestrator`)는 사용자의 질문과 가게의 상세 프로필(JSON)을 바탕으로 상황에 맞는 **도구(Tool)**를 자율적으로 선택하고, 사용자의 질문에 따라 필요하다면 여러 도구를 순차적으로 호출하여 최종 컨설팅 보고서를 생성합니다.

---

## 🛠️ 핵심 도구 및 작동 방식

AI 에이전트가 사용하는 주요 도구와 내부 처리 과정은 다음과 같습니다.

| 기능 분류        | 도구 함수명 (`tools/`)                                   | 주요 처리 과정 (`modules/`)                                                                                                                                                             |
| :--------------- | :------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **축제 추천** | `recommend_festivals` (festival\_recommender.py)         | **하이브리드 5단계 파이프라인 (`filtering.py`)**: <br> 1. LLM 쿼리 재작성 <br> 2. FAISS 벡터 검색 (유사 축제 후보 선정) <br> 3. LLM 동적 속성 평가 (가게 맞춤성) <br> 4. 하이브리드 점수 계산 <br> 5. 최종 Top3 결과 포맷팅 (2026 예측 포함) |
| **마케팅 (RAG)** | `search_contextual_marketing_strategy` (marketing\_strategy.py) | **컨텍스트 기반 RAG (`knowledge_base.py`)**: <br> 1. 가게 프로필 + 질문 → LLM 검색 쿼리 생성 <br> 2. FAISS 벡터 검색 (관련 전략 문서 추출) <br> 3. LLM 답변 생성 (추출된 내용을 바탕으로 자연스러운 전략 제안)       |
| **마케팅 (생성)** | `create_festival_specific_marketing_strategy` (marketing\_strategy.py) | **LLM 기반 전략 생성**: <br> 1. 축제 프로필 조회 (`profile_analyzer.py`) <br> 2. 가게 프로필 + 축제 프로필 + RAG 검색 → LLM 프롬프트 구성 <br> 3. LLM이 특정 축제 맞춤 전략 생성                           |
| **마케팅 (생성)** | `create_marketing_strategies_for_multiple_festivals` (marketing\_strategy.py) | **LLM 기반 전략 생성 (다수)**: <br> 1. 여러 축제 이름 입력받음 <br> 2. 각 축제별로 `create_festival_specific_marketing_strategy` 반복 호출 <br> 3. 모든 전략을 하나의 보고서로 취합                     |
| **가게 분석** | `analyze_merchant_profile` (profile\_analyzer.py)      | **LLM 기반 분석**: <br> 가게 프로필(JSON) 입력 → LLM이 SWOT 분석 및 핵심 고객 특성 요약 보고서 생성                                                                                             |
| **축제 분석** | `analyze_festival_profile` (profile\_analyzer.py)      | **LLM 기반 분석**: <br> 축제 프로필(JSON) 입력 → LLM이 축제의 핵심 특징 및 주요 방문객 특성 요약 보고서 생성                                                                                      |
| **축제 조회** | `get_festival_profile_by_name` (profile\_analyzer.py)  | **단순 데이터 조회**: 축제 이름 입력 → `festival_df.csv`에서 해당 축제 정보(JSON) 반환 (캐싱 활용)                                                                                           |

---

## 📂 프로젝트 구조 및 코드 설명

```plaintext
MarketSync/
├── streamlit_app.py        # Streamlit 웹 인터페이스 (UI)
├── orchestrator.py         # AI 에이전트: LangChain AgentExecutor, 도구 라우팅, 최종 답변 생성 로직
├── config.py               # 설정 중앙화: 경로, API 키, 모델명, 로깅 설정 등
│
├── api/                    # 데이터 제공 및 전처리 서버
│   ├── server.py           # FastAPI 서버: /profile, /merchants 엔드포인트 제공
│   └── data_loader.py      # 데이터 로딩 및 전처리 (final_df.csv, festival_df.csv)
│
├── tools/                  # LangChain @tool 도구 정의 레이어
│   ├── festival_recommender.py # [Tool] recommend_festivals 도구 정의 (filtering.py 호출)
│   ├── marketing_strategy.py   # [Tool] 마케팅 전략 관련 도구 3개 정의 (knowledge_base.py, profile_analyzer.py 등 호출)
│   ├── profile_analyzer.py     # [Tool] 가게/축제 분석 및 축제 프로필 조회 도구 3개 정의 (LLM 호출, 데이터 조회)
│   └── tool_loader.py          # 모든 도구(@tool)를 리스트로 묶어 Orchestrator에 제공
│
├── modules/                # 핵심 로직 구현 모듈
│   ├── filtering.py        # [축제 추천] FestivalRecommender 클래스 (5단계 파이프라인 구현)
│   ├── knowledge_base.py   # [RAG] FAISS 벡터 스토어 로딩 (축제, 마케팅), 임베딩 모델 관리
│   ├── llm_provider.py     # LLM 인스턴스 관리 (전역 공유 및 Temperature 조절)
│   ├── profile_utils.py    # 가게 프로필 JSON 가공 유틸리티 (채팅용/분석용)
│   └── visualization.py    # Streamlit 시각화: Matplotlib 그래프 생성 함수
│
├── utils/                  # 공통 유틸리티
│   └── parser_utils.py     # LLM 응답에서 JSON 추출 파서
│
├── data/                   # 원본 데이터
│   ├── final_df.csv        # 신한카드 가맹점 데이터
│   └── festival_df.csv     # 전국 축제 정보 데이터
│
└── vectorstore/            # FAISS 벡터 데이터베이스 저장 폴더
    ├── faiss_festival      # 축제 정보 벡터 DB 
    └── faiss_marketing     # 마케팅 전략 벡터 DB
```

------------------------------------------------------------------------

## 🔄 아키텍처 및 데이터 흐름

이 시스템은 **에이전트 중심의 도구 호출 (Tool-Calling)** 아키텍처를 기반으로 작동합니다. 사용자의 자연어 질문은 `Orchestrator`라는 AI 에이전트에 의해 해석되며, 에이전트는 제공된 `[가게 프로필]` 컨텍스트와 **시스템 프롬프트**의 지침에 따라 가장 적절한 도구를 선택하고 실행합니다. 필요하다면 여러 도구를 순차적으로 호출하여 얻은 정보를 종합한 뒤, 최종 컨설팅 답변을 생성합니다.

------------------------------------------------------------------------

## 📍 데이터 흐름 상세

1.  **초기 설정 (UI → API → UI)**
    * `streamlit_app.py` 실행 시 `load_data()` 함수가 FastAPI 서버(`api/server.py`)의 `/merchants` 엔드포인트를 호출하여 전체 가맹점 목록(ID, 이름)을 받아옵니다.
    * 사용자가 Streamlit 드롭다운 메뉴에서 자신의 가게를 선택합니다.
    * 선택된 가게 ID로 FastAPI 서버의 `/profile` 엔드포인트를 호출하여 해당 가게의 상세 프로필(JSON)과 상권/업종 평균 데이터를 받아옵니다.
    * 받아온 프로필 데이터는 `modules/visualization.py`를 통해 그래프와 표로 시각화되어 사용자에게 보여지고, `st.session_state.profile_data`에 저장됩니다.

2.  **컨설팅 요청 (UI → Orchestrator)**
    * 사용자가 Streamlit 채팅 입력창에 질문을 입력합니다.
    * `streamlit_app.py`는 `orchestrator.invoke_agent()` 함수를 호출합니다.
    * 이때 **사용자 질문(Query)**, **채팅용으로 가공된 가게 프로필(JSON 문자열)**, **이전 대화 기록(History)**, **마지막 추천 축제 목록(선택적)**이 `Orchestrator`로 전달됩니다.

3.  **의도 분석 및 도구 라우팅 (Orchestrator → LLM → Tool)**
    * `orchestrator.py`의 `AgentExecutor`는 시스템 프롬프트와 전달된 컨텍스트(가게 프로필, 질문 등)를 조합하여 **첫 번째 LLM(도구 선택용)**을 호출합니다.
    * LLM은 질문의 의도를 분석하고, 시스템 프롬프트의 가이드라인에 따라 `tools/tool_loader.py`에 정의된 **도구 목록 중 가장 적합한 도구를 선택**하고 필요한 입력값(Arguments)을 결정합니다.

4.  **도구 실행 (Tool → Modules/API/VectorDB/LLM)**
    * 선택된 도구 함수(`tools/*.py`)가 실행됩니다.
    * 도구는 필요에 따라 `modules/*.py`의 핵심 로직(예: `FestivalRecommender`), 외부 API(날씨 등), VectorDB(`modules/knowledge_base.py` 경유), 또는 별도의 LLM(`modules/llm_provider.py` 경유)을 호출하여 작업을 수행합니다.

5.  **결과 취합 및 반복 (Tool → Orchestrator → LLM → Tool ...)**
    * 도구 실행 결과(Observation)는 다시 `AgentExecutor`로 반환됩니다.
    * 에이전트는 이 결과를 바탕으로 **다음 행동을 결정**합니다. (예: 추가 정보가 필요하면 다른 도구를 호출하거나, 모든 정보가 모였다고 판단되면 최종 답변 생성을 준비)
    * 이 "LLM 판단 → 도구 호출 → 결과 확인" 과정은 사용자의 요청이 완전히 해결될 때까지 **여러 번 반복**될 수 있습니다 (Agentic 특성).

6.  **최종 답변 생성 및 출력 (Orchestrator → LLM → UI)**
    * `AgentExecutor`가 최종적으로 도출한 결과(`response['output']`) 또는 필요 시 `orchestrator.py`가 직접 **두 번째 LLM(답변 생성용)**을 호출하여, 모든 중간 결과와 컨텍스트를 종합한 **최종 컨설팅 보고서(자연어)**를 생성합니다.
    * 생성된 보고서는 `streamlit_app.py`로 반환되어 사용자 화면에 출력됩니다.

---

## ⚙️ 주요 특징 요약

| 기능                   | 설명                                                                                         |
| :--------------------- | :------------------------------------------------------------------------------------------- |
| **Agentic RAG** | LLM 에이전트가 가게 프로필 컨텍스트를 바탕으로 스스로 도구를 선택하고, 동적으로 RAG 검색 쿼리를 생성하여 실행 |
| **Tool Calling Agent** | LangChain의 `create_tool_calling_agent`를 사용하여 여러 도구를 자율적으로 호출 및 연계       |
| **하이브리드 추천** | FAISS 벡터 검색(유사도) + LLM 동적 평가(맞춤성) 점수를 결합하여 축제 추천 정확도 향상        |
| **컨텍스트 기반 분석** | 모든 도구 호출 및 최종 답변 생성 시, 현재 분석 중인 가게의 프로필(JSON)을 핵심 컨텍스트로 활용 |
| **모듈화된 구조** | 기능별(UI, API, Orchestrator, Modules, Tools)로 코드를 분리하여 유지보수성 및 확장성 증대     |
| **데이터 캐싱** | Streamlit의 `@st.cache_data` / `@st.cache_resource`를 활용하여 데이터 및 모델 로딩 속도 최적화 |

---

## 💡 기술 스택

* **Frontend:** Streamlit
* **Backend (Data API):** FastAPI
* **LLM:** Google Gemini 2.5 Flash (`gemini-2.5-flash`)
* **AI Framework:** LangChain (Agents, Tool Calling, Prompts)
* **VectorStore:** FAISS (Facebook AI Similarity Search)
* **Embedding model:** HuggingFace `dragonkue/BGE-m3-ko` (한국어 특화 모델)
* **Data Handling:** Pandas, NumPy
* **Visualization:** Matplotlib

---

## 🚀 실행 방법

### 1️⃣ 사전 준비

* Python 3.11 이상 설치
* `uv` (Python 패키지 설치 도구) 설치 (`pip install uv`)
* Google API Key 발급 (Gemini 모델 사용)

### 2️⃣ FastAPI 서버 실행

FastAPI 서버는 가맹점 데이터(`final_df.csv`)를 로드하고, `/profile` (가게 상세 정보), `/merchants` (가게 목록) 엔드포인트를 제공합니다.

```bash
# 1. 프로젝트 루트 폴더로 이동
cd C:(다운받은 폴더 위치)

# 2. 가상환경 생성 및 활성화 (최초 1회)
uv venv

# 3. 가상환경 활성화 (Windows)
.\.venv\Scripts\activate.bat
# (macOS/Linux: source .venv/bin/activate)

# 4. 필요한 라이브러리 설치
uv pip install -r requirements.txt

# 5. FastAPI 서버 실행 (api 폴더의 server.py를 모듈로 실행)
python -m api.server

### 3️⃣ Streamlit 앱 실행

Streamlit 앱은 사용자 인터페이스를 제공하고, FastAPI 서버에서 데이터를 가져오며, `Orchestrator`를 통해 AI 컨설팅을 수행합니다.

```bash
# 1. (FastAPI 서버와 다른 터미널에서) 프로젝트 루트 폴더로 이동
cd C:\(다운받은 폴더 위치)

# 2. 가상환경 활성화 (Windows)
.\.venv\Scripts\activate.bat
# (macOS/Linux: source .venv/bin/activate)

# 3. Streamlit secrets 파일 생성 (최초 1회)
#    - .streamlit 폴더를 생성합니다.
mkdir .streamlit
#      아래 명령어의 "(발급받은 gemini API key)" 부분을 실제 키로 대체하세요.
echo GOOGLE_API_KEY="(발급받은 gemini API key)" > .streamlit\secrets.toml

# 4. Streamlit 앱 실행
uv run streamlit run streamlit_app.py
```
이제 웹 브라우저에서 Streamlit 앱 주소(보통 http://localhost:8501)로 접속하여 MarketSync를 사용할 수 있습니다.

------------------------------------------------------------------------

## 📈 예시 시나리오

| 사용자 입력                         | 주요 실행 도구                                            | 예상 결과                               |
| :---------------------------------- | :------------------------------------------------------ | :-------------------------------------- |
| "우리 가게 분석해줘"                | `analyze_merchant_profile`                              | 가게 SWOT 분석 및 핵심 고객 리포트      |
| "주말 방문객 늘릴 만한 축제 추천해줘" | `recommend_festivals`                                   | Top 3 맞춤 축제 추천 리스트             |
| "`서울디저트페어` 마케팅 전략 알려줘" | `create_festival_specific_marketing_strategy`           | 해당 축제 맞춤형 마케팅 전략 제안       |
| "추천된 축제들 마케팅 방법 알려줘"    | `create_marketing_strategies_for_multiple_festivals`    | 여러 축제에 대한 통합 마케팅 전략 제안  |
| "요즘 뜨는 홍보 방법 알려줘"        | `search_contextual_marketing_strategy` (RAG)            | 가게 특성 기반 최신 마케팅 트렌드/팁 |

---

## 🧠 핵심 아이디어

> "LLM이 스스로 도구를 선택하고 실행하는 **Agentic RAG**"

* **LangChain의 Tool-Calling Agent 구조**: LLM이 사용자의 복잡한 요청을 이해하고, 필요한 기능(도구)을 자율적으로 호출하며 작업을 수행합니다.
* **컨텍스트 기반 의사결정**: 가게 프로필(JSON) 데이터를 핵심 컨텍스트로 활용하여, 모든 분석과 추천이 현재 분석 중인 가게에 맞춰 이루어집니다.
* **하이브리드 추천 엔진**: FAISS 벡터 검색(유사도 기반)과 LLM 재평가(가게 맞춤성 기반)를 결합하여 추천의 정확성과 관련성을 극대화합니다.
"# MarketSync"