README.md

metadata

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

---

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

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 (가게 목록) 엔드포인트를 제공합니다.

# 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"