Initial project commit with LFS

.devcontainer/devcontainer.json

@@ -0,0 +1,33 @@
+{
+  "name": "Python 3",
+  // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
+  "image": "mcr.microsoft.com/devcontainers/python:1-3.11-bullseye",
+  "customizations": {
+    "codespaces": {
+      "openFiles": [
+        "README.md",
+        "streamlit_app.py"
+      ]
+    },
+    "vscode": {
+      "settings": {},
+      "extensions": [
+        "ms-python.python",
+        "ms-python.vscode-pylance"
+      ]
+    }
+  },
+  "updateContentCommand": "[ -f packages.txt ] && sudo apt update && sudo apt upgrade -y && sudo xargs apt install -y <packages.txt; [ -f requirements.txt ] && pip3 install --user -r requirements.txt; pip3 install --user streamlit; echo '✅ Packages installed and Requirements met'",
+  "postAttachCommand": {
+    "server": "streamlit run streamlit_app.py --server.enableCORS false --server.enableXsrfProtection false"
+  },
+  "portsAttributes": {
+    "8501": {
+      "label": "Application",
+      "onAutoForward": "openPreview"
+    }
+  },
+  "forwardPorts": [
+    8501
+  ]
+}

.gitattributes

@@ -0,0 +1,5 @@
+data/*.csv filter=lfs diff=lfs merge=lfs -text
+data/final_df.csv filter=lfs diff=lfs merge=lfs -text
+vectorstore/faiss_festival/* filter=lfs diff=lfs merge=lfs -text
+vectorstore/faiss_marketing/* filter=lfs diff=lfs merge=lfs -text
+assets/*.png filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,232 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be added to the global gitignore or merged into this project gitignore.  For a PyCharm
+#  project, it is recommended to include the following files:
+#  .idea/
+#  *.iml
+#  *.ipr
+#  *.iws
+
+# VS Code
+.vscode/
+
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Windows
+Thumbs.db
+Thumbs.db:encryptable
+ehthumbs.db
+ehthumbs_vista.db
+*.tmp
+*.temp
+Desktop.ini
+$RECYCLE.BIN/
+*.cab
+*.msi
+*.msix
+*.msm
+*.msp
+*.lnk
+
+# Linux
+*~
+
+# temporary files which can be created if a process still has a handle open of a deleted file
+.fuse_hidden*
+
+# KDE directory preferences
+.directory
+
+# Linux trash folder which might appear on any partition or disk
+.Trash-*
+
+# .nfs files are created when an open file is removed but is still being accessed
+.nfs*
+
+# Streamlit
+.streamlit/
+
+# Project specific
+*.log
+*.tmp
+temp/
+tmp/
+
+# Data files (if they contain sensitive information)
+# data/
+# *.csv
+# *.json
+# *.pkl
+# *.npy
+
+# Model files (if they are large)
+# *.model
+# *.pkl
+# *.h5
+# *.pt
+# *.pth
+
+# Jupyter notebook checkpoints
+.ipynb_checkpoints/
+
+# Virtual environment
+.venv/
+venv/
+env/

.python-version

@@ -0,0 +1 @@
+3.11

LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

README.md

@@ -0,0 +1,429 @@
+# 🎉 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를 통해 질문하면, **에이전트(Orchestrator)** 가 작동하고, 필요 시 FastAPI 서버나 **여러 도구(Tool)** 와 상호작용합니다.
+
+```mermaid
+graph TD
+    %% ========================
+    %% AI 컨설팅 엔진 (최상단)
+    %% ========================
+    subgraph SG_Engine ["🧠 AI 컨설팅 엔진"]
+        direction TB
+        C["🤖 Orchestrator (핵심 에이전트)\n(orchestrator.py)\nAgentExecutor (LangChain)"]
+        D{"🚦 Tool Routing\nLLM 의도 분석 & 도구 선택"}
+
+        subgraph SG_Tools ["🔧 등록된 도구 목록 (tools/)"]
+            T1["recommend_festivals\n(축제 추천)"]
+            T2["search_contextual_marketing_strategy\n(RAG 마케팅 전략)"]
+            T3["create_festival_specific_marketing_strategy\n(단일 축제 전략)"]
+            T3_multi["create_marketing_strategies_for_multiple_festivals\n(다수 축제 전략)"]
+            T4["analyze_merchant_profile\n(가게 분석)"]
+            T5["analyze_festival_profile\n(축제 분석)"]
+            T6["get_festival_profile_by_name\n(축제 프로필 조회)"]
+        end
+
+        LLM_Final["🪄 LLM (Final Report Generation)\n최종 보고서 생성"]
+    end
+
+    %% ========================
+    %% 사용자 인터페이스 & 데이터 서버 (하단)
+    %% ========================
+    subgraph SG_UserServer ["💻 사용자 인터페이스 & 데이터 서버"]
+        direction LR
+        A["🖥️ Streamlit UI\n(streamlit_app.py)\n사용자 상호작용"] <--> B["🚀 FastAPI Server\n(api/server.py)\n📊 가게 프로필 / 목록 조회"]
+    end
+
+    %% ========================
+    %% 연결 관계 (수정)
+    %% ========================
+    A -- "자연어 질문 입력" --> C
+    C -- "의도 분석 요청" --> D
+    D -- "적합 도구 선택/실행" --> SG_Tools
+    SG_Tools -- "도구 실행 결과" --> C
+    C -- "최종 보고서 생성 요청" --> LLM_Final
+    LLM_Final -- "최종 결과 전달" --> A
+
+    %% ========================
+    %% 스타일 지정 (GitHub 호환)
+    %% ========================
+    style A fill:#4CAF50,color:#fff,stroke:#388E3C,stroke-width:2px
+    style B fill:#FF9800,color:#fff,stroke:#EF6C00,stroke-width:2px
+    style C fill:#E91E63,color:#fff,stroke:#C2185B,stroke-width:2px
+    style D fill:#9C27B0,color:#fff,stroke:#7B1FA2,stroke-width:2px,shape:diamond
+    style SG_Tools fill:#E1F5FE, stroke:#0277BD,color:#000
+    style T1,T2,T3,T3_multi,T4,T5,T6 fill:#03A9F4,color:#fff,stroke:#0288D1,stroke-width:2px,shape:hexagon
+    style LLM_Final fill:#BA68C8,color:#fff,stroke:#8E24AA,stroke-width:2px
+```
+
+---
+
+### (2) 축제 추천 도구 상세 — `recommend_festivals`
+
+LLM 기반 **하이브리드 5단계 파이프라인**을 통해,
+가게 맞춤형 축제를 추천합니다.
+```mermaid
+graph TD
+    %% ========================
+    %% Orchestrator 요청
+    %% ========================
+    subgraph SG_Orchestrator_Req ["🧠 Orchestrator 요청"]
+        Agent["🤖 AgentExecutor"] -- "축제 추천 요청" --> Tool_Rec["🧩 Tool: recommend_festivals"]
+    end
+
+    %% ========================
+    %% 지식 베이스 (수정)
+    %% ========================
+    subgraph SG_KnowledgeBase ["📚 지식 베이스 (modules/knowledge_base.py)"]
+        direction LR
+        EM["🧬 Embedding Model\n(HuggingFace)"]
+        VSF["📂 FAISS (축제 DB)"]
+        EM -- "임베딩 생성 (Offline)" --> VSF
+    end
+
+    %% ========================
+    %% Filtering Pipeline
+    %% ========================
+    subgraph SG_Filtering_Pipeline ["🔍 Filtering Pipeline (modules/filtering.py)"]
+        Tool_Rec --> Step1["1️⃣ LLM 쿼리 재작성"]
+        Step1 --> Step2["2️⃣ FAISS 벡터 검색\n(유사 축제 후보 탐색)"]
+        
+        %% RAG 흐름 명확화 (수정)
+        Step2 -- "쿼리 임베딩" --> EM
+        Step2 -- "유사도 검색" --> VSF
+
+        Step2 --> Step3["3️⃣ LLM 동적 속성 평가\n(가게 맞춤성 판단)"]
+        Step3 --> LLM1["🤖 LLM (Dynamic Evaluation)"]
+        Step3 --> Step4["4️⃣ 하이브리드 점수 계산\n(유사도 + 맞춤성)"]
+        Step4 --> Step5["5️⃣ 최종 결과 포맷팅\n(Top3 + 2026 예측 포함)"]
+    end
+
+    %% ========================
+    %% 결과 반환
+    %% ========================
+    subgraph SG_Result_Return ["📦 결과 반환"]
+        Step5 -- "Top3 축제 추천 결과" --> Agent
+    end
+
+    %% ========================
+    %% 스타일
+    %% ========================
+    style Agent fill:#E91E63,color:#fff
+    style Tool_Rec fill:#03A9F4,color:#fff
+    style Step1,Step2,Step3,Step4,Step5 fill:#81D4FA,color:#000
+    style VSF fill:#FFC107,color:#000
+    style EM fill:#4DD0E1,color:#000 
+    style LLM1 fill:#BA68C8,color:#fff
+    style SG_KnowledgeBase fill:#F5F5F5,stroke:#9E9E9E
+```
+
+---
+
+### (3) 마케팅 전략 (RAG) 도구 상세 — `search_contextual_marketing_strategy`
+
+**RAG** 기반으로 **가게 프로필 + 질문 컨텍스트**를 이용해
+가장 관련성 높은 마케팅 전략 문서를 검색하고, LLM이 자연스럽게 요약/제안합니다.
+
+```mermaid
+graph TD
+    %% ========================
+    %% Orchestrator 요청
+    %% ========================
+    subgraph SG_Orchestrator_Req_RAG ["🧠 Orchestrator 요청"]
+        Agent["🤖 AgentExecutor"] -- "마케팅 전략 (RAG) 요청" --> Tool_RAG["🧩 Tool: search_contextual_marketing_strategy"]
+    end
+
+    %% ========================
+    %% 지식 베이스 (수정)
+    %% ========================
+    subgraph SG_KnowledgeBase_RAG ["📚 지식 베이스 (modules/knowledge_base.py)"]
+        direction LR
+        EM["🧬 Embedding Model\n(HuggingFace)"]
+        VSM["📂 FAISS (마케팅 DB)"]
+        EM -- "임베딩 생성 (Offline)" --> VSM
+    end
+
+    %% ========================
+    %% RAG Logic
+    %% ========================
+    subgraph SG_RAG_Logic ["⚙️ RAG Logic (tools/marketing_strategy.py)"]
+        Tool_RAG --> Step1["1️⃣ LLM 검색 쿼리 생성\n(가게 프로필 + 질문 기반)"]
+        Step1 --> Step2["2️⃣ FAISS 벡터 검색\n(마케팅 DB 탐색)"]
+        
+        %% RAG 흐름 명확화 (수정)
+        Step2 -- "쿼리 임베딩" --> EM
+        Step2 -- "유사도 검색" --> VSM
+        
+        Step2 --> Step3["3️⃣ LLM 답변 생성\n(검색된 컨텍스트 기반)"]
+        Step3 --> LLM2["🤖 LLM (Answer Synthesis)"]
+    end
+
+    %% ========================
+    %% 결과 반환
+    %% ========================
+    subgraph SG_Result_Return_RAG ["📦 결과 반환"]
+        Step3 -- "생성된 마케팅 전략 텍스트" --> Agent
+    end
+
+    %% ========================
+    %% 스타일
+    %% ========================
+    style Agent fill:#E91E63,color:#fff
+    style Tool_RAG fill:#03A9F4,color:#fff
+    style Step1,Step2,Step3 fill:#81D4FA,color:#000
+    style VSM fill:#FFC107,color:#000
+    style EM fill:#4DD0E1,color:#000 
+    style LLM2 fill:#BA68C8,color:#fff
+    style SG_KnowledgeBase_RAG fill:#F5F5F5,stroke:#9E9E9E
+```
+
+---
+
+### (4) LLM 기반 분석 도구 상세 — `analyze_merchant_profile` / `analyze_festival_profile`
+
+가게 또는 축제의 프로필(JSON)을 입력받아
+LLM이 **SWOT 분석 / 주요 특징 요약**을 수행합니다.
+
+```mermaid
+graph TD
+    %% ========================
+    %% Orchestrator 요청
+    %% ========================
+    subgraph SG_Orchestrator_Req_Analyze ["🧠 Orchestrator 요청"]
+        Agent["🤖 AgentExecutor"] -- "가게/축제 분석 요청" --> Tool_Analyze["🧩 Tool: analyze_merchant_profile / analyze_festival_profile"]
+    end
+
+    %% ========================
+    %% LLM 분석
+    %% ========================
+    subgraph SG_LLM_Analysis ["📊 LLM 분석 (tools/profile_analyzer.py)"]
+        Tool_Analyze -- "프로필(JSON) 전달" --> LLM_Analyze["🤖 LLM (SWOT / 요약 분석)"]
+    end
+
+    %% ========================
+    %% 결과 반환
+    %% ========================
+    subgraph SG_Result_Return_Analyze ["📦 결과 반환"]
+        LLM_Analyze -- "분석 보고서 텍스트" --> Agent
+    end
+
+    %% ========================
+    %% 스타일
+    %% ========================
+    style Agent fill:#E91E63,color:#fff
+    style Tool_Analyze fill:#03A9F4,color:#fff
+    style LLM_Analyze fill:#BA68C8,color:#fff
+```
+
+------------------------------------------------------------------------
+
+## 📍 데이터 흐름 상세
+
+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" 

config.py

@@ -0,0 +1,48 @@
+# config.py
+
+import logging
+from pathlib import Path
+
+# --- Paths ---
+PROJECT_ROOT = Path(__file__).resolve().parent
+PATH_DATA_DIR = PROJECT_ROOT / 'data'
+PATH_VECTORSTORE_DIR = PROJECT_ROOT / 'vectorstore'
+ASSETS =  PROJECT_ROOT / "assets"
+
+# Data Files
+PATH_FINAL_DF = PATH_DATA_DIR / 'final_df.csv'
+PATH_FESTIVAL_DF = PATH_DATA_DIR / 'festival_df.csv'
+
+# Vectorstore Paths
+PATH_FAISS_MARKETING = PATH_VECTORSTORE_DIR / 'faiss_marketing'
+PATH_FAISS_FESTIVAL = PATH_VECTORSTORE_DIR / 'faiss_festival'
+
+
+# --- API ---
+API_SERVER_URL = "http://127.0.0.1:8000"
+API_PROFILE_ENDPOINT = f"{API_SERVER_URL}/profile"
+API_MERCHANTS_ENDPOINT = f"{API_SERVER_URL}/merchants"
+
+
+# --- Models ---
+LLM_MODEL_NAME = "gemini-2.5-pro" 
+EMBEDDING_MODEL = "dragonkue/BGE-m3-ko"
+
+
+# --- RAG Weights ---
+FESTIVAL_EMBEDDING_WEIGHT = 0.4
+FESTIVAL_DYNAMIC_WEIGHT = 0.6
+
+
+# --- Logging ---
+LOGGING_LEVEL = logging.INFO
+LOGGING_FORMAT = "%(asctime)s - [%(levelname)s] - %(name)s (%(funcName)s): %(message)s"
+
+def get_logger(name: str):
+    """
+    표준화된 포맷으로 로거를 반환합니다.
+    """
+    logging.basicConfig(level=LOGGING_LEVEL, format=LOGGING_FORMAT)
+    logger = logging.getLogger(name)
+    logger.setLevel(LOGGING_LEVEL)
+    return logger

data/big_data_set1_f.csv

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:70c7eb4e4ab4351dfa309f26589738e7b1f804cabd8499bc37308be4cc45d510
+size 377760

data/big_data_set2_f.csv

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:caf8ba53f32c65d1666703b60c503d4e3f57eddfa322679ecf3a64498a9bb7b7
+size 10299462

data/big_data_set3_f.csv

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8ef850fcc6a15db9366603f077bd59214454401a4d57b93276e46452516bedfd
+size 9622819

data/festival_df.csv

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e6805b51be222cf84d60b01aeb7c4ec7f99d4cde1662a82fd9c9d145d3bad2eb
+size 259519

data/final_df.csv

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6ccc3ea7f1a9f714b6d9bd538faabfcf30d4995055e86ea027f386c5c4855999
+size 34118076

modules/filtering.py

@@ -0,0 +1,397 @@
+# modules/filtering.py
+
+import json
+import traceback
+from typing import List, Dict, Any, Optional, Tuple
+import pandas as pd
+
+from langchain_core.messages import HumanMessage 
+from langchain_community.vectorstores import FAISS
+from langchain_core.documents import Document
+
+import config
+from modules.knowledge_base import load_festival_vectorstore
+from modules.llm_provider import get_llm
+from utils.parser_utils import extract_json_from_llm_response 
+
+logger = config.get_logger(__name__)
+
+# 4번 제안: 파이프라인 로직을 클래스로 캡슐화
+class FestivalRecommender:
+    """
+    하이브리드 축제 추천 파이프라인을 캡슐화한 클래스.
+    """
+    def __init__(self, store_profile: str, user_query: str, specific_intent: Optional[str] = None):
+        self.store_profile = store_profile
+        self.user_query = user_query
+        self.specific_intent = specific_intent
+        
+        # LLM 인스턴스를 미리 생성
+        self.llm_temp_01 = get_llm(0.1)
+        self.llm_temp_03 = get_llm(0.3)
+        
+        # VectorStore 로드
+        self.vectorstore = load_festival_vectorstore()
+        
+        # 가중치 (config에서 로드)
+        self.embedding_weight = config.FESTIVAL_EMBEDDING_WEIGHT
+        self.dynamic_weight = config.FESTIVAL_DYNAMIC_WEIGHT
+
+    def _rewrite_query(self) -> str:
+        """
+        (1단계) 가게 프로필과 사용자 질문을 바탕으로 Vector Store 검색용 쿼리를 LLM이 재작성합니다.
+        """
+        logger.info("--- [Filter 1/5] 쿼리 재작성 시작 ---")
+        
+        intent_prompt = f"사용자의 구체적인 요청: {self.specific_intent}" if self.specific_intent else ""
+
+        # --- (사용자 요청) 프롬프트 원본 유지 ---
+        prompt = f"""
+        당신은 소상공인 마케팅을 위한 AI 컨설턴트입니다.
+        당신의 임무는 [가게 프로필]과 [사용자 질문]의 의도를 완벽하게 이해하고, 
+        이 가게에 가장 적합한 축제를 찾기 위한 '최적의 검색 키워드'를 생성하는 것입니다.
+        검색 엔진은 '축제 소개 내용'을 기반으로 유사도를 측정하여 축제를 찾아냅니다.
+    
+        [가게 프로필]
+        {self.store_profile}
+
+        [사용자 질문]
+        {self.user_query}
+        {intent_prompt}
+
+        [검색 키워드 생성 가이드]
+        1. 가게의 '업종', '상권', '주요 고객층(성별/연령)'을 핵심 키워드로 사용하세요.
+        2. 가게의 '강점'이나 '약점'을 보완할 수 있는 방향을 고려하세요. 
+        (예: '신규 고객 확보'가 필요하면 '유동 인구', '관광객', '대규모' 등)
+        (예: '객단가'가 낮으면 '구매력 높은', '3040대 직장인' 등)
+        3. 사용자 질문의 의도를 반영하세요. (예: '여름' 축제, '특정 지역' 축제)
+        4. 5~8개의 핵심 키워드를 조합하여 자연스러운 문장이나 구문으로 만드세요.
+
+        [검색 키워드 생성 단계 및 가이드]
+        1. **분석:** 가게 프로필(업종, 상권, 주요 고객)을 바탕으로 현재 가게가 마케팅적으로 가장 필요로 하는 것(예: 신규 고객 유입, 객단가 상승, 특정 연령대 확보)이 무엇인지 내부적으로 분석합니다.
+        2. **목표 설정:** 분석 결과와 사용자 질문의 의도를 결합하여, 축제에 기대하는 최종적인 목표를 명확히 합니다. (예: "20대 여성의 유입을 증가시킬 축제", "가족 단위 관광객이 많은 축제")
+        3. **키워드 추출:** 설정된 목표에 부합하는 **핵심 키워드 7개를 명사 형태로 추출**합니다.
+        - '업종', '주요 고객층(성별/연령)', '필요한 고객 유입 형태(예: 관광객, 가족단위, 직장인)', '시즌/테마'를 포함하여 구체적으로 만듭니다.
+
+
+        [출력 형식]
+        (오직 재작성된 쿼리만 출력)
+        """
+        
+        try:
+            response = self.llm_temp_01.invoke([HumanMessage(content=prompt)])
+            rewritten_query = response.content.strip().replace('"', '').replace("'", "")
+            
+            if not rewritten_query:
+                logger.warning("--- [Filter 1/5 ERROR] 쿼리 재작성 실패, 원본 쿼리 사용 ---")
+                return self.user_query
+                
+            return rewritten_query
+            
+        except Exception as e:
+            logger.critical(f"--- [Filter 1/5 CRITICAL ERROR] {e} ---", exc_info=True)
+            return self.user_query # 실패 시 원본 쿼리 반환
+
+    def _search_candidates(self, query: str, k: int) -> List[Tuple[Document, float]]:
+        """
+        (2단계) 재작성된 쿼리를 사용하여 Vector Store에서 K개의 후보를 검색합니다.
+        """
+        logger.info(f"--- [Filter 2/5] 후보 검색 (임베딩 점수) 시작 (Query: {query}) ---")
+        try:
+            if self.vectorstore is None:
+                raise RuntimeError("축제 벡터스토어가 로드되지 않았습니다.")
+                
+            candidates_with_scores = self.vectorstore.similarity_search_with_relevance_scores(query, k=k)
+            return candidates_with_scores
+
+        except Exception as e:
+            logger.critical(f"--- [Filter 2/5 CRITICAL ERROR] {e} ---", exc_info=True)
+            return []
+
+    def _evaluate_candidates_dynamically(self, candidates: List[Document]) -> Dict[str, Dict[str, Any]]:
+        """
+        (3단계) LLM을 사용하여 후보들의 '동적 속성'을 평가합니다.
+        """
+        logger.info(f"--- [Filter 3/5] 동적 속성 평가 (LLM) 시작 (후보 {len(candidates)}개) ---")
+        
+        candidates_data = []
+        for doc in candidates:
+            meta = doc.metadata
+            candidates_data.append({
+                "축제명": meta.get('축제명'),
+                "주요성별": meta.get('주요성별'),
+                "주요연령대": meta.get('주요연령대'),
+                "주요고객층": meta.get('주요고객층'),
+                "주요방문자": meta.get('주요방문자'),
+                "축제인기": meta.get('축제인기'),
+                "축제인기도": meta.get('축제인기도'),
+                "인기도_점수": meta.get('인기도_점수')
+            })
+        
+        candidates_json_str = json.dumps(candidates_data, ensure_ascii=False, indent=2)
+
+        # --- (사용자 요청) 프롬프트 원본 유지 ---
+        prompt = f"""
+        당신은 냉철한 축제 데이터 분석가입니다. [가게 프로필]과 [사용자 요청]을 바탕으로,
+        각 [축제 후보]가 이 가게의 '타겟 고객' 및 '마케팅 목표'와 얼마나 잘 맞는지
+        **오직 제공된 '동적 속성' (주요성별, 주요연령대, 주요고객층, 주요방문자, 인기도)만을
+        기준으로** 평가하고 '동적_점수' (0~100점)를 매기세요.
+
+        [가게 프로필]
+        {self.store_profile}
+
+        [사용자 요청]
+        {self.user_query}
+
+        [평가 대상 축제 후보 목록 (JSON)]
+        {candidates_json_str}
+
+        [동적 점수 평가 가이드]
+        1.  **타겟 일치 (성별/연령)**: 가게의 '핵심고객'(예: 30대 여성)과 축제의 '주요성별', '주요연령대'가 일치할수록 높은 점수를 주세요.
+        2.  **고객층 일치**: 가게의 '업종'(예: 카페)과 축제의 '주요고객층'(예: 2030 여성, 연인)이 시너지가 날수록 높은 점수를 주세요.
+        3.  **방문자 특성**: 가게가 '신규 고객 확보'가 필요하고 축제의 '주요방문자'가 '외지인'이라면 높은 점수를 주세요. 반대로 '단골 확보'가 목표인데 '현지인' 방문자가 많다면 높은 점수를 주세요.
+        4.  **인기도**: '축제인기', '축제인기도', '인기도_점수'가 높을수록 방문객 수가 보장되므로 높은 점수를 주세요.
+        5.  **복합 평가**: 이 모든 요소를 종합하여 0점에서 100점 사이의 '동적_점수'를 부여하세요.
+        6.  **이유 작성**: 왜 그런 점수를 주었는지 '평가_이유'에 간략히 요약하세요.
+
+        [출력 형식 (JSON 리스트)]
+        [
+          {{
+            "축제명": "[축제 이름]",
+            "동적_점수": 85,
+            "평가_이유": "가게의 핵심 고객인 30대 여성과 축제의 주요연령대/주요성별이 일치하며, '외지인' 방문자 특성이 신규 고객 확보 목표에 부합함."
+          }},
+          ...
+        ]
+        """
+        
+        try:
+            response = self.llm_temp_01.invoke([HumanMessage(content=prompt)])
+            response_text = response.content.strip()
+            
+            # 5번 제안: 공통 파서 사용
+            scores_list = extract_json_from_llm_response(response_text)
+            
+            scores_dict = {
+                item['축제명']: {
+                    "dynamic_score": item.get('동적_점수', 0),
+                    "dynamic_reason": item.get('평가_이유', 'N/A')
+                } 
+                for item in scores_list if isinstance(item, dict) and '축제명' in item
+            }
+            return scores_dict
+            
+        except (ValueError, json.JSONDecodeError) as e:
+            logger.error(f"--- [Filter 3/5 CRITICAL ERROR] 동적 점수 JSON 파싱 실패: {e} ---")
+            logger.debug(f"LLM 원본 응답 (앞 500자): {response_text[:500]} ...")
+            return {} # 오류 발생 시 빈 딕셔너리 반환 (Fallback)
+        except Exception as e:
+            logger.critical(f"--- [Filter 3/5 CRITICAL ERROR] (Outer Catch) {e} ---", exc_info=True)
+            return {}
+
+    def _calculate_hybrid_scores(
+        self,
+        embedding_candidates: List[Tuple[Document, float]], 
+        dynamic_scores: Dict[str, Dict[str, Any]]
+    ) -> List[Dict[str, Any]]:
+        """
+        (4단계) Score 1(임베딩)과 Score 2(동적)를 가중 합산하여 최종 '하이브리드 점수'를 계산합니다.
+        """
+        logger.info("--- [Filter 4/5] 하이브리드 점수 계산 시작 ---")
+        hybrid_results = []
+
+        for doc, embedding_score in embedding_candidates:
+            festival_name = doc.metadata.get('축제명')
+            if not festival_name:
+                continue
+                
+            normalized_embedding_score = embedding_score * 100
+            dynamic_eval = dynamic_scores.get(festival_name, {"dynamic_score": 0, "dynamic_reason": "N/A"})
+            dynamic_score = dynamic_eval["dynamic_score"]
+            
+            hybrid_score = (normalized_embedding_score * self.embedding_weight) + \
+                           (dynamic_score * self.dynamic_weight)
+                           
+            hybrid_results.append({
+                "document": doc,
+                "metadata": doc.metadata,
+                "score_embedding": normalized_embedding_score,
+                "score_dynamic": dynamic_score,
+                "score_dynamic_reason": dynamic_eval["dynamic_reason"],
+                "score_hybrid": hybrid_score
+            })
+            
+        hybrid_results.sort(key=lambda x: x.get("score_hybrid", 0), reverse=True)
+        return hybrid_results
+
+
+    # 2026년 날짜 예측 헬퍼 함수
+    def _predict_next_year_date(self, date_str_2025: Optional[str]) -> str:
+        """2025년 날짜 문자열(YYYY.MM.DD~...)을 받아 2026년 예상 시기를 텍스트로 반환합니다."""
+        if not date_str_2025 or not isinstance(date_str_2025, str):
+            return "2026년 정보 없음" # 날짜 정보 없으면 명시적 반환
+
+        try:
+            # "~" 앞부분만 사용하여 시작 날짜 파싱 (YYYY.MM.DD 형식 가정)
+            start_date_str = date_str_2025.split('~')[0].strip()
+            date_2025 = pd.to_datetime(start_date_str, format='%Y.%m.%d', errors='coerce')
+
+            if pd.isna(date_2025): # YYYY.MM.DD 파싱 실패 시 다른 형식 시도 (예: YYYY-MM-DD)
+                date_2025 = pd.to_datetime(start_date_str, errors='coerce')
+
+            if pd.isna(date_2025): # 최종 파싱 실패 시
+                 logger.warning(f"날짜 예측 실패: '{start_date_str}' (원본: '{date_str_2025}') 형식을 인식할 수 없습니다.")
+                 return f"2026년 정보 없음 (2025년: {date_str_2025})"
+
+            month = date_2025.month
+            day = date_2025.day
+
+            if day <= 10:
+                timing = f"{month}월 초"
+            elif day <= 20:
+                timing = f"{month}월 중순"
+            else:
+                timing = f"{month}월 말"
+
+            return f"2026년 {timing}경 예상 (2025년: {date_str_2025})"
+        except Exception as e:
+            logger.error(f"날짜 예측 중 오류 ({date_str_2025}): {e}")
+            return f"2026년 정보 없음 (오류: {e})"
+
+    def _format_recommendation_results(
+        self,
+        ranked_list: List[Dict[str, Any]],
+        top_k: int
+    ) -> List[Dict[str, Any]]:
+        
+        """ (5단계) 최종 답변 포맷팅 (LLM) """
+        logger.info(f"--- [Filter 5/5] 최종 답변 포맷팅 (LLM) 시작 (Top {top_k}) ---")
+        top_candidates = ranked_list[:top_k]
+        candidates_data = []
+        for candidate in top_candidates:
+            meta = candidate["metadata"]
+            date_2025 = meta.get('2025_기간')
+            predicted_2026_timing = self._predict_next_year_date(date_2025)
+            candidates_data.append({
+                "축제명": meta.get('축제명'),
+                "소개": meta.get('소개'),
+                "predicted_2026_timing": predicted_2026_timing,
+                "주요고객층": meta.get('주요고객층'),
+                "주요방문자": meta.get('주요방문자'),
+                "축제인기": meta.get('축제인기'),
+                "홈페이지": meta.get('홈페이지'),
+                "추천_점수": round(candidate["score_hybrid"], 1),
+                "추천_근거_키워드": f"키워드/소개 일치도 ({round(candidate['score_embedding'], 0)}점)",
+                "추천_근거_동적": f"가게 맞춤성({round(candidate['score_dynamic'], 0)}점): {candidate['score_dynamic_reason']}"
+            })
+        candidates_json_str = json.dumps(candidates_data, ensure_ascii=False, indent=2)
+
+        prompt = f"""
+        당신은 소상공인 컨설턴트입니다. [가게 프로필]과 AI가 분석한 [최종 추천 축제 목록]을 바탕으로,
+        사장님께 제안할 최종 추천 답변을 생성하세요.
+
+        [가게 프로필]
+        {self.store_profile}
+
+        [최종 추천 축제 목록 (JSON) - 소개, 2026년 예상 시기 포함]
+        {candidates_json_str}
+
+        [최종 답변 생성 가이드라인]
+        1.  **[최종 추천 축제 목록]의 모든 정보**를 사용하여 최종 답변을 JSON 형식으로 생성합니다.
+        2.  '추천_이유'는 '추천_근거_키워드'와 '추천_근거_동적'을 조합하여 **자연스러운 서술형 문장**으로 작성하세요.
+        3.  **(수정) '축제_기본정보'**: 입력 JSON의 **'소개', '주요고객층', '주요방문자', '축제인기'** 정보를 조합하여 축제를 설명하는 자연스러운 문장으로 작성하세요. '소개' 내용을 바탕으로 축제의 핵심 내용을 요약하고, 고객층/방문자/인기도 정보를 덧붙입니다. (예: "**'{{소개 요약}}'**을(를) 주제로 하는 축제이며, 주로 **{{주요고객층}}**이 방문하고 **{{주요방문자}}** 특성을 보입니다. (인기도: **{{축제인기}}**)")
+        4.  **(중요) '2026년 예상 시기'**: 입력 JSON에 있는 **`predicted_2026_timing` 값을 그대로** 가져와서 출력 JSON의 `'2026년 예상 시기'` 필드 값으로 사용하세요. **절대 직접 계산하거나 수정하지 마세요.**
+        5.  **(중요) 단점 제외**: '단점'이나 '부적합한 이유'는 절대 출력하지 마세요.
+        6.  **(중요) 취소선 금지**: 절대로 `~~text~~`와 같은 취소선 마크다운을 사용하지 마세요.
+        7.  **출력 형식 (JSON)**: 반드시 아래의 JSON 리스트 형식으로만 응답하세요. 다른 설명 없이 JSON만 출력해야 합니다.
+
+        [응답 형식 (JSON 리스트)]
+        [
+          {{
+            "축제명": "[축제 이름]",
+            "추천_점수": 95.2,
+            "축제_기본정보": "[축제 소개 요약, 주요 고객층, 주요 방문자, 인기도를 조합한 서술형 문장]",
+            "추천_이유": "[가게 프로필과 추천 근거를 바탕으로 이 축제를 추천하는 이유를 서술형으로 작성.]",
+            "홈페이지": "[축제 홈페이지 URL]",
+            "2026년 예상 시기": "[입력 JSON의 predicted_2026_timing 값을 그대로 사용]"
+          }},
+          ...
+        ]
+        """
+        response_text = ""
+        try:
+            response = self.llm_temp_03.invoke([HumanMessage(content=prompt)])
+            response_text = response.content.strip()
+            final_list = extract_json_from_llm_response(response_text)
+            return final_list
+        except (ValueError, json.JSONDecodeError) as e:
+            logger.error(f"--- [Filter 5/5 CRITICAL ERROR] 최종 답변 JSON 파싱 실패: {e} ---")
+            logger.debug(f"LLM 원본 응답 (앞 500자): {response_text[:500]} ...")
+            return [{"error": f"최종 답변 생성 중 JSON 파싱 오류 발생: {e}", "details": response_text}]
+        except Exception as e:
+            logger.critical(f"--- [Filter 5/5 CRITICAL ERROR] (Outer Catch) {e} ---", exc_info=True)
+            return [{"error": f"최종 답변 생성 중 알 수 없는 오류 발생: {e}"}]
+
+
+    def run(self, search_k: int = 10, top_k: int = 3) -> List[Dict[str, Any]]:
+        """
+        파이프라인 1~5단계를 순차적으로 실행합니다.
+        """
+        try:
+            # 1단계: 쿼리 재작성
+            rewritten_query = self._rewrite_query()
+            logger.info(f"--- [Filter 1/5] 쿼리 재작성 완료: {rewritten_query} ---")
+
+            # 2단계: 후보 검색
+            embedding_candidates = self._search_candidates(query=rewritten_query, k=search_k)
+            if not embedding_candidates:
+                logger.warning("--- [Filter 2/5] 후보 검색 결과 없음 ---")
+                return [{"error": "추천할 만한 축제를 찾지 못했습니다."}]
+            
+            logger.info(f"--- [Filter 2/5] 후보 검색 완료 (후보 {len(embedding_candidates)}개) ---")
+
+            # 3단계: 동적 속성 평가
+            candidate_docs = [doc for doc, score in embedding_candidates]
+            dynamic_scores_dict = self._evaluate_candidates_dynamically(candidates=candidate_docs)
+            
+            if not dynamic_scores_dict:
+                logger.warning("--- [Filter 3/5 WARNING] 동적 속성 평가 실패. 임베딩 점수만으로 추천을 진행합니다. ---")
+                # dynamic_scores_dict = {} (빈 딕셔너리로 계속 진행)
+
+            logger.info(f"--- [Filter 3/5] 동적 속성 평가 완료 ({len(dynamic_scores_dict)}개) ---")
+            
+            # 4단계: 하이브리드 점수 계산
+            hybrid_results = self._calculate_hybrid_scores(
+                embedding_candidates=embedding_candidates,
+                dynamic_scores=dynamic_scores_dict
+            )
+            logger.info(f"--- [Filter 4/5] 하이브리드 점수 계산 및 정렬 완료 ---")
+
+            # 5단계: 최종 답변 포맷팅
+            final_recommendations = self._format_recommendation_results(
+                ranked_list=hybrid_results,
+                top_k=top_k
+            )
+            logger.info(f"--- [Filter 5/5] 최종 답변 포맷팅 완료 ---")
+            
+            # 5단계(LLM 포맷팅) 실패 시 Fallback
+            if final_recommendations and isinstance(final_recommendations, list) and "error" in final_recommendations[0]:
+                 logger.warning(f"--- [Tool WARNING] 최종 답변 포맷팅 실패. 4단계 원본 데이터로 Fallback. ({final_recommendations[0]['error']}) ---")
+                 
+                 fallback_results = []
+                 for item in hybrid_results[:top_k]:
+                     meta = item.get("metadata", {})
+                     fallback_results.append({
+                         "축제명": meta.get("축제명", "N/A"),
+                         "추천_점수": round(item.get("score_hybrid", 0), 1),
+                         "추천_이유": f"임베딩({round(item.get('score_embedding',0),0)}점), 맞춤성({round(item.get('score_dynamic',0),0)}점): {item.get('score_dynamic_reason', 'N/A')}",
+                         "축제_기본정보": meta.get("소개", "N/A")[:100] + "...",
+                         "홈페이지": meta.get("홈페이지", "N/A")
+                     })
+                 return fallback_results
+                 
+            return final_recommendations
+
+        except Exception as e:
+            logger.critical(f"--- [Tool CRITICAL] 축제 추천 파이프라인 전체 오류: {e} ---", exc_info=True)
+            return [{"error": f"축제를 추천하는 과정에서 예기치 못한 오류가 발생했습니다: {e}"}]

modules/knowledge_base.py

@@ -0,0 +1,103 @@
+# modules/knowledge_base.py
+
+import os
+import streamlit as st
+from pathlib import Path
+from langchain_community.vectorstores import FAISS
+from langchain_community.embeddings import HuggingFaceEmbeddings 
+import traceback 
+
+import config 
+
+logger = config.get_logger(__name__)
+
+@st.cache_resource
+def _load_embedding_model():
+    """
+    임베딩 모델을 별도 함수로 분리하여 캐싱 (FAISS 로드 시 재사용)
+    """
+    try:
+        logger.info("--- [Cache] HuggingFace 임베딩 모델 최초 로딩 시작 ---")
+
+        model_name = config.EMBEDDING_MODEL
+        model_kwargs = {'device': 'cpu'}
+        encode_kwargs = {'normalize_embeddings': True}
+
+        embeddings = HuggingFaceEmbeddings(
+            model_name=model_name,
+            model_kwargs=model_kwargs,
+            encode_kwargs=encode_kwargs
+        )
+        logger.info(f"--- [Cache] HuggingFace 임베딩 모델 ({model_name}) 로딩 성공 ---")
+        return embeddings
+    except Exception as e:
+        logger.critical(f"--- [CRITICAL ERROR] 임베딩 모델 로딩 실패: {e} ---", exc_info=True)
+        st.error(f"임베딩 모델('{config.EMBEDDING_MODEL}') 로딩 중 심각한 오류가 발생했습니다: {e}")
+        return None
+
+@st.cache_resource
+def load_marketing_vectorstore():
+    """
+    '마케팅 전략' FAISS Vector Store를 로드하여 Retriever를 생성합니다.
+    """
+    try:
+        logger.info("--- [Cache] '마케팅' FAISS Vector Store 최초 로딩 시작 ---")
+        embeddings = _load_embedding_model()
+        
+        if embeddings is None:
+            raise RuntimeError("임베딩 모델 로딩에 실패하여 Retriever를 생성할 수 없습니다.")
+
+        vector_db_path = config.PATH_FAISS_MARKETING
+        
+        if not vector_db_path.exists():
+            logger.critical(f"--- [CRITICAL ERROR] '마케팅' Vector DB 경로를 찾을 수 없습니다: {vector_db_path}")
+            st.error(f"'마케팅' Vector DB 파일을 찾을 수 없습니다. (경로: {vector_db_path})")
+            return None
+        
+        db = FAISS.load_local(
+            folder_path=str(vector_db_path), 
+            embeddings=embeddings, 
+            allow_dangerous_deserialization=True 
+        )
+        
+        retriever = db.as_retriever(search_kwargs={"k": 2})
+        
+        logger.info("--- [Cache] '마케팅' FAISS Vector Store 로딩 성공 ---")
+        return retriever
+        
+    except Exception as e:
+        logger.critical(f"--- [CRITICAL ERROR] '마케팅' FAISS 로딩 실패: {e} ---", exc_info=True)
+        st.error(f"'마케팅' Vector Store 로딩 중 오류 발생: {e}")
+        return None
+
+@st.cache_resource
+def load_festival_vectorstore():
+    """
+    '축제 정보' FAISS Vector Store를 로드합니다.
+    """
+    try:
+        logger.info("--- [Cache] '축제' FAISS Vector Store 최초 로딩 시작 ---")
+        embeddings = _load_embedding_model() 
+
+        if embeddings is None:
+            raise RuntimeError("임베딩 모델 로딩에 실패하여 '축제' Vector Store를 로드할 수 없습니다.")
+
+        vector_db_path = config.PATH_FAISS_FESTIVAL
+
+        if not vector_db_path.exists():
+            logger.critical(f"--- [CRITICAL ERROR] '축제' Vector DB 경로를 찾을 수 없습니다: {vector_db_path}")
+            st.error(f"'축제' Vector DB 파일을 찾을 수 없습니다. (경로: {vector_db_path})")
+            return None
+
+        db = FAISS.load_local(
+            folder_path=str(vector_db_path),
+            embeddings=embeddings,
+            allow_dangerous_deserialization=True
+        )
+        logger.info("--- [Cache] '축제' FAISS Vector Store 로딩 성공 ---")
+        return db
+
+    except Exception as e:
+        logger.critical(f"--- [CRITICAL ERROR] '축제' FAISS 로딩 실패: {e} ---", exc_info=True)
+        st.error(f"'축제' Vector Store 로딩 중 오류 발생: {e}")
+        return None

modules/llm_provider.py

@@ -0,0 +1,51 @@
+# modules/llm_provider.py
+
+from langchain_google_genai import ChatGoogleGenerativeAI
+from typing import Optional
+
+import config
+
+logger = config.get_logger(__name__)
+
+_llm_instance: Optional[ChatGoogleGenerativeAI] = None
+
+def set_llm(llm: ChatGoogleGenerativeAI):
+    """
+    Orchestrator가 생성한 기본 LLM 인스턴스를
+    글로벌 변수에 저장합니다.
+    """
+    global _llm_instance
+    if _llm_instance is None:
+        logger.info(f"--- [LLM Provider] Global LLM instance set. (Model: {llm.model}, Temp: {llm.temperature}) ---")
+        _llm_instance = llm
+    else:
+        logger.info("--- [LLM Provider] Global LLM instance already set. ---")
+
+
+def get_llm(temperature: float = 0.1) -> ChatGoogleGenerativeAI:
+    """
+    저장된 글로벌 LLM 인스턴스를 검색합니다.
+    만약 도구가 요청한 temperature가 기본값과 다르면,
+    기본 인스턴스의 설정을 복사하여 temperature만 변경한
+    새로운 인스턴스를 반환합니다. (API 키 등은 재사용)
+    """
+    global _llm_instance
+    if _llm_instance is None:
+        logger.error("--- [LLM Provider] LLM not initialized. ---")
+        raise RuntimeError(
+            "LLM not initialized. The Orchestrator must call set_llm() before any tools are used."
+        )
+    
+    if _llm_instance.temperature == temperature:
+        logger.debug(f"--- [LLM Provider] Reusing global LLM instance (temp={temperature}) ---")
+        return _llm_instance
+    
+    logger.info(f"--- [LLM Provider] Creating new LLM instance with temp={temperature} (default was {_llm_instance.temperature}) ---")
+    
+    try:
+        # Pydantic v2+ (langchain-core 0.1.23+)
+        return _llm_instance.model_copy(update={"temperature": temperature})
+    except AttributeError:
+        # Pydantic v1 (fallback)
+        logger.warning("--- [LLM Provider] Using .copy() fallback (Pydantic v1) ---")
+        return _llm_instance.copy(update={"temperature": temperature})

modules/profile_utils.py

@@ -0,0 +1,46 @@
+# modules/profile_utils.py
+
+from typing import Dict, Any
+import config
+
+logger = config.get_logger(__name__)
+
+def get_chat_profile_dict(store_profile_dict: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    FastAPI (server.py)에서 받은 'store_profile' 딕셔너리를 기반으로,
+    visualization.py와 orchestrator.py에서 공통으로 사용할
+    '채팅용 프로필 딕셔너리' (사장님이 요청하신 항목)를 생성합니다.
+    
+    이 함수가 '채팅용 프로필'의 단일 정의(Source of Truth) 역할을 합니다.
+    """
+    try:
+        # 1. 기본 정보
+        chat_profile_data = {
+            "가맹점명": store_profile_dict.get('가맹점명', 'N/A'),
+            "가맹점ID": store_profile_dict.get('가맹점ID', 'N/A'),
+            "상권": store_profile_dict.get('상권', 'N/A'),
+            "업종": store_profile_dict.get('업종', 'N/A'),
+            "주소": store_profile_dict.get('가맹점주소', 'N/A'), 
+            "운영 기간 수준": store_profile_dict.get('운영개월수_수준', 'N/A'),
+            "매출 수준": store_profile_dict.get('매출구간_수준', 'N/A'),
+            "매출 건수 수준": store_profile_dict.get('월매출건수_수준', 'N/A'),
+            "방문 고객수 수준": store_profile_dict.get('월유니크고객수_수준', 'N/A'),
+            "객단가 수준": store_profile_dict.get('월객단가_수준', 'N/A'),
+            "신규/재방문율": f"신규 {(store_profile_dict.get('신규고객비율') or 0):.1f}% / 재방문 {(store_profile_dict.get('재이용고객비율') or 0):.1f}%",
+            "동일 상권 대비 매출 순위": f"상위 {(store_profile_dict.get('동일상권내매출순위비율') or 0):.1f}%",
+            "동일 업종 대비 매출 순위": f"상위 {(store_profile_dict.get('동일업종내매출순위비율') or 0):.1f}%"
+        }
+        
+        # 2. '자동추출특징' 추가
+        chat_profile_data["자동추출특징"] = store_profile_dict.get('자동추출특징', {})
+        
+        return chat_profile_data
+        
+    except Exception as e:
+        logger.critical(f"--- [Profile Utils CRITICAL] 채팅 프로필 딕셔너리 생성 실패: {e} ---", exc_info=True)
+        return {
+            "업종": store_profile_dict.get('업종', '알 수 없음'),
+            "자동추출특징": store_profile_dict.get('자동추출특징', {}),
+            "주소": store_profile_dict.get('가맹점주소', '알 수 없음'),
+            "error": "프로필 요약 중 오류 발생"
+        }

modules/visualization.py

@@ -0,0 +1,230 @@
+# modules/visualization.py
+
+import pandas as pd
+import matplotlib.pyplot as plt
+from matplotlib import font_manager
+import numpy as np
+import streamlit as st
+
+import config
+from modules.profile_utils import get_chat_profile_dict
+
+logger = config.get_logger(__name__)
+
+def set_korean_font():
+    """
+    시스템에 설치된 한글 폰트를 찾아 Matplotlib에 설정합니다.
+    """
+    font_list = ['Malgun Gothic', 'AppleGothic', 'NanumGothic']
+    
+    found_font = False
+    for font_name in font_list:
+        if any(font.name == font_name for font in font_manager.fontManager.ttflist):
+            plt.rc('font', family=font_name)
+            logger.info(f"✅ 한글 폰트 '{font_name}'을(를) 찾아 그래프에 적용합니다.")
+            found_font = True
+            break
+            
+    if not found_font:
+        logger.warning("⚠️ 경고: Malgun Gothic, AppleGothic, NanumGothic 폰트를 찾을 수 없습니다.")
+    
+    plt.rcParams['axes.unicode_minus'] = False
+
+
+def display_merchant_profile(profile_data: dict):
+    set_korean_font()
+
+    """
+    분석된 가맹점 프로필 전체를 Streamlit 화면에 시각화합니다.
+    """
+    if not profile_data or "store_profile" not in profile_data:
+        st.error("분석할 가맹점 데이터가 없습니다.")
+        return
+
+    store_data = profile_data["store_profile"]
+    store_name = store_data.get('가맹점명', '선택 매장')
+
+    st.info(f"**'{store_name}'**의 상세 분석 결과입니다.")
+
+    tab1, tab2, tab3, tab4 = st.tabs([
+        "📋 기본 정보", 
+        "🧑‍🤝‍🧑 주요 고객층 (성별/연령대)", 
+        "🚶 주요 고객 유형 (상권)", 
+        "🔁 고객 충성도 (신규/재방문)"
+    ])
+
+    with tab1:
+        render_basic_info_table(store_data)
+
+    with tab2:
+        st.subheader("🧑‍🤝‍🧑 주요 고객층 분포 (성별/연령대)")
+        fig2 = plot_customer_distribution(store_data)
+        st.pyplot(fig2)
+
+    with tab3:
+        st.subheader("🚶 주요 고객 유형 (상권)")
+        fig3 = plot_customer_type_pie(store_data)
+        st.pyplot(fig3)
+
+    with tab4:
+        st.subheader("🔁 신규 vs 재방문 고객 비율") 
+        fig4 = plot_loyalty_donut(store_data)
+        st.pyplot(fig4)
+
+
+def get_main_customer_segment(store_data):
+    """주요 고객층(성별/연령대) 텍스트를 반환합니다."""
+    segments = {
+        '남성 20대 이하': store_data.get('남성20대이하비율', 0),
+        '남성 30대': store_data.get('남성30대비율', 0),
+        '남성 40대': store_data.get('남성40대비율', 0),
+        '남성 50대 이상': store_data.get('남성50대비율', 0) + store_data.get('남성60대이상비율', 0),
+        '여성 20대 이하': store_data.get('여성20대이하비율', 0),
+        '여성 30대': store_data.get('여성30대비율', 0),
+        '여성 40대': store_data.get('여성40대비율', 0),
+        '여성 50대 이상': store_data.get('여성50대비율', 0) + store_data.get('여성60대이상비율', 0)
+    }
+    
+    if not any(segments.values()):
+        return None
+    
+    max_segment = max(segments, key=segments.get)
+    max_value = segments[max_segment]
+    
+    if max_value == 0:
+        return None
+        
+    return f"'{max_segment}({max_value:.1f}%)'"
+
+
+def render_basic_info_table(store_data):
+    """(Tab 1) 기본 정보 요약 표와 텍스트를 렌더링합니다."""
+    
+    summary_data = get_chat_profile_dict(store_data)
+    
+    st.subheader("📋 가맹점 기본 정보")
+    summary_df = pd.DataFrame(summary_data.items(), columns=["항목", "내용"])
+    summary_df = summary_df[summary_df['항목'] != '자동추출특징']
+    summary_df = summary_df.astype(str) 
+    st.table(summary_df.set_index('항목'))
+
+    st.subheader("📌 분석 요약")
+    st.write(f"✅ **{summary_data.get('가맹점명', 'N/A')}**은(는) '{summary_data.get('상권', 'N/A')}' 상권의 '{summary_data.get('업종', 'N/A')}' 업종 가맹점입니다.")
+    st.write(f"📈 매출 수준은 **{summary_data.get('매출 수준', 'N/A')}**이며, 동일 상권 내 매출 순위는 **{summary_data.get('동일 상권 대비 매출 순위', 'N/A')}**입니다.")
+    st.write(f"💰 방문 고객수는 **{summary_data.get('방문 고객수 수준', 'N/A')}** 수준이며, 객단가는 **{summary_data.get('객단가 수준', 'N/A')}** 수준입니다.")
+    
+    main_customer = get_main_customer_segment(store_data)
+    if main_customer:
+        st.write(f"👥 주요 고객층은 **{main_customer}**이(가) 가장 많습니다.")
+
+
+def plot_customer_distribution(store_data):
+    """(Tab 2) 고객 특성 분포 (성별/연령대)를 보여주는 막대 그래프를 생성합니다."""
+    labels = ['20대 이하', '30대', '40대', '50대 이상']
+    male_percents = [
+        store_data.get('남성20대이하비율', 0), store_data.get('남성30대비율', 0),
+        store_data.get('남성40대비율', 0),
+        store_data.get('남성50대비율', 0) + store_data.get('남성60대이상비율', 0)
+    ]
+    female_percents = [
+        store_data.get('여성20대이하비율', 0), store_data.get('여성30대비율', 0),
+        store_data.get('여성40대비율', 0),
+        store_data.get('여성50대비율', 0) + store_data.get('여성60대이상비율', 0)
+    ]
+
+    x = np.arange(len(labels))
+    width = 0.35
+    fig, ax = plt.subplots(figsize=(10, 6))
+    rects1 = ax.bar(x - width/2, male_percents, width, label='남성', color='cornflowerblue')
+    rects2 = ax.bar(x + width/2, female_percents, width, label='여성', color='salmon')
+
+    ax.set_ylabel('고객 비율 (%)')
+    ax.set_title('주요 고객층 분포 (성별/연령대)', fontsize=16)
+    ax.set_xticks(x)
+    ax.set_xticklabels(labels, fontsize=12)
+    ax.legend()
+    ax.grid(axis='y', linestyle='--', alpha=0.7)
+
+    ax.bar_label(rects1, padding=3, fmt='%.1f')
+    ax.bar_label(rects2, padding=3, fmt='%.1f')
+    
+    fig.tight_layout()
+    return fig
+
+
+def plot_customer_type_pie(store_data):
+    """(Tab 3) 주요 고객 유형 (거주자, 직장인, 유동인구)을 파이 차트로 생성합니다."""
+    
+    customer_data = {
+        '유동인구': store_data.get("유동인구이용비율", 0),
+        '거주자': store_data.get("거주자이용비율", 0),
+        '직장인': store_data.get("직장인이용비율", 0)
+    }
+    
+    filtered_data = {label: (size or 0) for label, size in customer_data.items()}
+    filtered_data = {label: size for label, size in filtered_data.items() if size > 0}
+    
+    sizes = list(filtered_data.values())
+    labels = list(filtered_data.keys())
+
+    if not sizes or sum(sizes) == 0:
+        fig, ax = plt.subplots(figsize=(6, 6))
+        ax.text(0.5, 0.5, "데이터 없음", horizontalalignment='center', verticalalignment='center', transform=ax.transAxes)
+        ax.set_title("주요 고객 유형", fontsize=13)
+        return fig
+
+    pie_labels = [f"{label} ({size:.1f}%)" for label, size in zip(labels, sizes)]
+
+    fig, ax = plt.subplots(figsize=(6, 6))
+    
+    wedges, texts, autotexts = ax.pie(
+        sizes,
+        labels=pie_labels,
+        autopct='%1.1f%%',
+        startangle=90,
+        pctdistance=0.8
+    )
+    
+    plt.setp(autotexts, size=9, weight="bold", color="white")
+    ax.set_title("주요 고객 유형", fontsize=13)
+    ax.axis('equal')
+    
+    return fig
+
+
+def plot_loyalty_donut(store_data):
+    """(Tab 4) 신규 vs 재방문 고객 비율을 도넛 차트로 생성합니다."""
+    
+    visit_ratio = {
+        '신규 고객': store_data.get('신규고객비율') or 0,
+        '재이용 고객': store_data.get('재이용고객비율') or 0
+    }
+    
+    sizes = list(visit_ratio.values())
+    labels = list(visit_ratio.keys())
+    
+    if not sizes or sum(sizes) == 0:
+        fig, ax = plt.subplots(figsize=(5, 5))
+        ax.text(0.5, 0.5, "데이터 없음", horizontalalignment='center', verticalalignment='center', transform=ax.transAxes)
+        ax.set_title("신규 vs 재방문 고객 비율")
+        return fig
+
+    fig, ax = plt.subplots(figsize=(5, 5))
+    
+    wedges, texts, autotexts = ax.pie(
+        sizes,
+        labels=labels,
+        autopct='%1.1f%%',
+        startangle=90,
+        pctdistance=0.85,
+        colors=['lightcoral', 'skyblue']
+    )
+    
+    centre_circle = plt.Circle((0, 0), 0.70, fc='white')
+    ax.add_artist(centre_circle)
+    
+    plt.setp(autotexts, size=10, weight="bold")
+    ax.set_title("신규 vs 재방문 고객 비율", fontsize=14)
+    ax.axis('equal')
+    
+    return fig

orchestrator.py

@@ -0,0 +1,247 @@
+# orchestrator.py
+
+import json
+import traceback
+from typing import List, Optional, Dict, Any 
+from pydantic import ValidationError
+
+from langchain.agents import AgentExecutor, create_tool_calling_agent
+from langchain_core.prompts import ChatPromptTemplate
+from langchain_google_genai import ChatGoogleGenerativeAI
+from langchain.tools.render import render_text_description
+
+import config
+from modules.llm_provider import set_llm
+from modules.profile_utils import get_chat_profile_dict
+
+# tools/tool_loader.py 에서 모든 도구를 가져옴
+from tools.tool_loader import ALL_TOOLS
+
+logger = config.get_logger(__name__)
+
+# --- 헬퍼 함수를 공통 유틸리티 호출로 변경 ---
+def _get_chat_profile_json_string(store_profile_dict: Dict[str, Any]) -> str:
+    """
+    공통 유틸리티(profile_utils.py)를 호출하여 '채팅용 프로필 딕셔너리'를 생성하고,
+    이를 JSON 문자열로 변환하여 반환합니다.
+    """
+    try:
+        summary_dict = get_chat_profile_dict(store_profile_dict)
+        return json.dumps(summary_dict, ensure_ascii=False)
+        
+    except Exception as e:
+        logger.critical(f"--- [Orchestrator CRITICAL] 채팅용 JSON 생성 실패: {e} ---", exc_info=True)
+        fallback_data = {
+            "업종": store_profile_dict.get('업종', '알 수 없음'),
+            "자동추출특징": store_profile_dict.get('자동추출특징', {}),
+            "주소": store_profile_dict.get('가맹점주소', '알 수 없음'),
+            "error": "프로필 요약 중 오류 발생"
+        }
+        return json.dumps(fallback_data, ensure_ascii=False)
+
+
+class AgentOrchestrator:
+    def __init__(self, google_api_key):
+        """Gemini Flash 기반 Agent Orchestrator 초기화"""
+        self.llm = ChatGoogleGenerativeAI(
+            model=config.LLM_MODEL_NAME,
+            google_api_key=google_api_key,
+            temperature=0.1  
+        )
+        set_llm(self.llm)
+
+        # tool_loader 에서 도구 목록을 가져옴
+        self.tools = ALL_TOOLS
+
+        self.rendered_tools = render_text_description(self.tools)
+
+        self.system_prompt_template = """
+        {base_system_prompt}
+
+        ---
+        📦 [현재 가게 프로필 (JSON)]
+        {store_profile_context}
+
+        📜 [이전 추천 축제 리스트]
+        {last_recommended_festivals}
+
+        ---
+        💡 반드시 위 정보를 기반으로 판단하되,
+        도구 라우팅 규칙(1~4순위)에 따라 *적절한 단 하나의 도구를 호출*해야 합니다.
+        """
+
+        self.prompt = ChatPromptTemplate.from_messages([
+            ("system", self.system_prompt_template),
+            ("placeholder", "{chat_history}"),
+            ("human", "{input}"),
+            ("placeholder", "{agent_scratchpad}"),
+        ])
+
+        self.agent = create_tool_calling_agent(self.llm, self.tools, self.prompt)
+
+        self.agent_executor = AgentExecutor(
+            agent=self.agent,
+            tools=self.tools,
+            verbose=True,
+            handle_parsing_errors=True,
+            return_intermediate_steps=True,
+        )
+        logger.info(f"--- [Streamlit] AgentOrchestrator 초기화 완료 (Model: {config.LLM_MODEL_NAME}) ---")
+
+
+    def setup_system_prompt(self):
+        """Gemini Flash 전용 강화 프롬프트"""
+        
+        logger.info("--- [Orchestrator] 시스템 프롬프트 설정 완료 ---")
+
+        # --- (사용자 요청) 프롬프트 원본 유지 ---
+        return f"""
+        당신은 **신한카드 데이터 기반 지역축제 전문 AI 컨설턴트**입니다.
+        당신의 임무는 사장님의 가게 정보를 기반으로
+        **가게 분석 → 축제 추천 → 축제 분석 → 마케팅 전략 제안**을 수행하는 것입니다.
+
+        ---
+        🔧 [사용 가능한 도구 목록]
+        (도구 목록은 에이전트에 내장되어 있으며, 아래 [도구 라우팅 규칙]에 따라 호출됩니다.)
+
+        ---
+        🎯 **[핵심 임무 요약]**
+        1️⃣ 사용자의 요청을 완수하기 위해 **필요한 모든 도구를 자율적으로 호출**해야 합니다. 때로는 **여러 도구를 순차적으로 호출**해야 할 수도 있습니다. (예: 축제 추천 → 마케팅 전략 생성)
+        2️⃣ **도구 호출 없이** "죄송합니다" 또는 "잘 모르겠습니다" 같은 답변을 생성하는 것은 절대 금지입니다.
+        3️⃣ 모든 요청은 반드시 적합한 도구 호출로 이어져야 합니다.
+        4️⃣ 모든 도구 실행 결과를 바탕으로, 사장님에게 제공할 [최종 답변]을
+           **자연스러운 한국어(마크다운 형식)**로 생성합니다.
+
+        ---
+        🧭 **[도구 라우팅 규칙 (우선순위 적용)]**
+
+        **[1순위] 축제 추천 요청**
+        - 키워드: "축제 추천", "참여할 만한 축제", "어떤 축제", "행사 찾아줘", "어디가 좋아"
+        - → `recommend_festivals`
+
+        **[2순위] 특정 축제 분석/전략 요청**
+       - **2-1. 마케팅 전략 요청 (축제 1개)**: 축제 이름이 1개 포함되어 있고 '마케팅', '전략' 등의 키워드가 있는 경우
+            - → `create_festival_specific_marketing_strategy`
+        - **2-2. 마케팅 전략 요청 (축제 2개 이상)**: 축제 이름이 2개 이상 포함되어 있고 '마케팅', '전략' 등의 키워드가 있는 경우
+            - → `create_marketing_strategies_for_multiple_festivals`
+        - **2-3. 축제 상세 분석 요청**: "~축제 어때?", "분석해줘"
+            - → `analyze_festival_profile`
+
+        **[3순위] 가게 분석 요청**
+        - 키워드: “우리 가게”, “SWOT”, “고객 특성”, “분석해줘”
+        - → `analyze_merchant_profile`
+
+        **[4순위] 일반 마케팅/홍보 요청**
+        - 키워드: “마케팅”, “홍보”, “매출”, “전략”
+        - → `search_contextual_marketing_strategy`
+
+        **[기타]**
+        - 명확히 분류되지 않으면 4순위 도구 사용
+        - → `search_contextual_marketing_strategy`
+
+        ---
+        ✅ **[행동 체크리스트]**
+        - 1️⃣ 사용자의 요청이 **완전히 해결될 때까지** 필요한 모든 도구를 호출할 것  
+        - 2️⃣ [1순위] 작업 시, 마케팅 전략 요청이 있었는지 **반드시 재확인**하고 2단계 도구 호출을 결정할 것
+        - 3️⃣ 도구 호출 없이 종료하지 말 것
+        - 4️⃣ 최종 답변은 자연스러운 한국어(마크다운)로 생성할 것
+
+        ---
+        ✍️ **[최종 답변 가이드라인] (매우 중요)**
+        1.  **친절한 전문가 말투**: 항상 사장님을 대하듯, 전문적이면서도 친절하고 이해하기 쉬운 말투를 사용합니다.
+        2.  **(요청 2) 추천 점수 표시**: `recommend_festivals` 도구의 결과를 포맷팅할 때, 각 축제 이름 옆이나 바로 아래에 **(추천 점수: XX.X점)**과 같이 '추천_점수'를 **반드시** 명시하세요.
+        3.  **(요청 4) 취소선 금지**: 절대로 `~~text~~`와 같은 취소선 마크다운을 사용하지 마세요.
+        4.  **(요청 3) 다음 질문 제안**: 사용자가 다음에 무엇을 할 수 있을지 알 수 있도록, 답변의 **가장 마지막**에 아래와 같은 [다음 질문 예시]를 2~3개 제안하세요.
+
+        [다음 질문 예시]
+        * "방금 추천해준 축제들의 마케팅 전략을 알려줘"
+        * "[축제이름]에 대한 마케팅 전략을 짜줘"
+        * "내 가게의 강점을 활용한 다른 홍보 방법은?"
+        """
+    
+    def invoke_agent(
+        self,
+        user_query: str,                  
+        store_profile_dict: dict,          
+        chat_history: list,
+        last_recommended_festivals: Optional[List[str]] = None,
+    ):
+
+        """사용자 입력을 받아 Agent를 실행하고 결과를 반환"""
+        logger.info(f"--- [Orchestrator] Agent 실행 시작 (Query: {user_query[:30]}...) ---")
+        
+        base_system_prompt = self.setup_system_prompt()
+        store_profile_chat_json_str = _get_chat_profile_json_string(store_profile_dict)
+        last_recommended_festivals_str = (
+            "없음" if not last_recommended_festivals else str(last_recommended_festivals)
+        )
+        
+        try:
+            response = self.agent_executor.invoke({
+                "input": user_query, 
+                "chat_history": chat_history,
+                "store_profile_context": store_profile_chat_json_str, 
+                "store_profile": store_profile_chat_json_str,       
+                "last_recommended_festivals": last_recommended_festivals_str,
+                "base_system_prompt": base_system_prompt, 
+            })
+
+            output_text = response.get("output", "").strip()
+
+            is_garbage_response = (
+                len(output_text) < 10 and ("}" in output_text or "`" in output_text)
+            )
+
+            if not output_text or is_garbage_response:
+                
+                if is_garbage_response:
+                    logger.warning(f"--- [Orchestrator WARNING] 비정상 응답 감지 ('{output_text}') → 재시도 수행 ---")
+                else:
+                    logger.warning("--- [Orchestrator WARNING] 응답 비어있음 → 재시도 수행 ---")
+
+                retry_input = f"""
+                [재시도 요청]
+                이전 응답이 비어있거나 비정상적인 값('{output_text}')이었습니다.
+                사용자 질문: "{user_query}" 
+
+                당신은 반드시 하나의 도구를 호출해야 합니다.
+                도구 라우팅 규칙(1~4순위)에 따라 적절한 도구를 선택하고 호출하십시오.
+                """
+                
+                response = self.agent_executor.invoke({
+                    "input": retry_input,
+                    "chat_history": chat_history,
+                    "store_profile_context": store_profile_chat_json_str, 
+                    "store_profile": store_profile_chat_json_str,       
+                    "last_recommended_festivals": last_recommended_festivals_str,
+                    "base_system_prompt": base_system_prompt,
+                })
+                
+                final_response = response.get("output", "").strip()
+            
+            else:
+                final_response = output_text
+
+            if not final_response:
+                final_response = "죄송합니다. 요청을 처리하는 중 오류가 발생했습니다. 질문을 조금 더 명확히 말씀해주시겠어요?"
+
+            logger.info("--- [Orchestrator] Agent 실행 완료 ---\n")
+            
+            return {
+                "final_response": final_response,
+                "intermediate_steps": response.get("intermediate_steps", [])
+            }
+
+        except ValidationError as e:
+            logger.error(f"--- [Orchestrator Pydantic ERROR] {e} ---\n", exc_info=True)
+            return {
+                "final_response": f"죄송합니다. 도구 입력값(Pydantic) 오류가 발생했습니다: {e}",
+                "intermediate_steps": []
+            }
+
+        except Exception as e:
+            logger.critical(f"--- [Orchestrator CRITICAL ERROR] {e} ---\n", exc_info=True)
+            return {
+                "final_response": f"죄송합니다. 알 수 없는 오류가 발생했습니다: {e}",
+                "intermediate_steps": []
+            }

pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "shcard_2025_bigcontest_chatbot"
+version = "0.1.0"
+description = "신한카드 가맹점 추천 챗봇"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "streamlit>=1.38.0",
+    "google-generativeai>=0.8.0",
+    "pandas>=2.2.0",
+    "mcp>=1.13.1",
+    "fastmcp>=2.11.0",
+    "langchain>=0.1.0",
+    "langchain-google-genai>=1.0.0",
+    "langchain-mcp-adapters>=0.1.0",
+    "langchain-core>=0.1.0",
+    "langgraph>=0.1.0",
+    "pillow>=10.0.0",
+    "asyncio>=4.0.0",
+    "matplotlib>=3.7.2",
+]

requirements.txt

@@ -0,0 +1,25 @@
+streamlit>=1.38.0
+google-generativeai>=0.8.0
+pandas>=2.2.0
+numpy>=1.24.0
+
+mcp>=1.13.1
+fastmcp>=2.11.0
+
+langchain>=0.2.0
+langchain-core>=0.2.0
+langchain-google-genai>=1.0.0
+langchain-mcp-adapters>=0.1.0
+langgraph>=0.1.0
+langchain-community>=0.2.0
+
+faiss-cpu>=1.8.0 
+pypdf>=4.2.0      
+sentence-transformers 
+torch
+
+Pillow>=10.0.0
+
+fastapi>=0.111.0
+uvicorn>=0.26.0
+matplotlib>=3.7.2

streamlit_app.py

@@ -0,0 +1,500 @@
+# streamlit_app.py (FastAPI 통합 버전)
+
+import streamlit as st
+import os
+import pandas as pd
+import numpy as np  # api/server.py에서 필요
+import math       # api/server.py에서 필요
+import json
+import traceback
+# import requests # 더 이상 API 호출에 필요하지 않음
+from PIL import Image
+from pathlib import Path
+
+from langchain_core.messages import HumanMessage, AIMessage
+
+import config 
+from orchestrator import AgentOrchestrator
+from modules.visualization import display_merchant_profile
+from modules.knowledge_base import load_marketing_vectorstore, load_festival_vectorstore
+
+logger = config.get_logger(__name__)
+
+# --- 페이지 설정 ---
+st.set_page_config(
+    page_title="MarketSync(마켓싱크)",
+    page_icon="🎉",
+    layout="wide",
+    initial_sidebar_state="expanded"
+)
+
+# --- (1) api/data_loader.py에서 가져온 함수 ---
+# config.py를 직접 임포트하므로 sys.path 조작 필요 없음
+def load_and_preprocess_data():
+    """
+    미리 가공된 final_df.csv 파일을 안전하게 찾아 로드하고,
+    데이터를 처리하는 과정에서 발생할 수 있는 모든 오류를 방어합니다.
+    (api/data_loader.py의 원본 함수)
+    """
+    try:
+        file_path = config.PATH_FINAL_DF
+
+        if not file_path.exists():
+            logger.critical(f"--- [CRITICAL DATA ERROR] 데이터 파일을 찾을 수 없습니다. 예상 경로: {file_path}")
+            logger.critical(f"--- 현재 작업 경로: {Path.cwd()} ---")
+            return None
+            
+        df = pd.read_csv(file_path)
+
+    except Exception as e:
+        logger.critical(f"--- [CRITICAL DATA ERROR] 데이터 파일 로딩 중 예측하지 못한 오류 발생: {e} ---", exc_info=True)
+        return None
+        
+    logger.info("--- [Preprocess] Streamlit Arrow 변환 오류 방지용 데이터 클리닝 시작 ---")
+    for col in df.select_dtypes(include='object').columns:
+        temp_series = (
+            df[col]
+            .astype(str)
+            .str.replace('%', '', regex=False)
+            .str.replace(',', '', regex=False)
+            .str.strip()
+        )
+        numeric_series = pd.to_numeric(temp_series, errors='coerce') 
+        df[col] = numeric_series.fillna(temp_series)
+        
+    logger.info("--- [Preprocess] 데이터 클리닝 완료 ---")
+
+    cols_to_process = ['월매출금액_구간', '월매출건수_구간', '월유니크고객수_구간', '월객단가_구간']
+    
+    for col in cols_to_process:
+        if col in df.columns:
+            try:
+                series_str = df[col].astype(str).fillna('')
+                series_split = series_str.str.split('_').str[0]
+                series_numeric = pd.to_numeric(series_split, errors='coerce')
+                df[col] = series_numeric.fillna(0).astype(int)
+            except Exception as e:
+                logger.warning(f"--- [DATA WARNING] '{col}' 컬럼 처리 중 오류 발생: {e}. 해당 컬럼을 건너뜁니다. ---", exc_info=True)
+                continue
+                
+    logger.info(f"--- [Preprocess] 데이터 로드 및 전처리 최종 완료. (Shape: {df.shape}) ---")
+    return df
+
+# --- (2) api/server.py에서 가져온 헬퍼 함수 ---
+def replace_nan_with_none(data):
+    """
+    딕셔셔너리나 리스트 내의 모든 NaN 값을 None으로 재귀적으로 변환합니다.
+    (api/server.py의 원본 함수)
+    """
+    if isinstance(data, dict):
+        return {k: replace_nan_with_none(v) for k, v in data.items()}
+    elif isinstance(data, list):
+        return [replace_nan_with_none(i) for i in data]
+    elif isinstance(data, float) and math.isnan(data):
+        return None
+    return data
+
+# --- (3) api/server.py의 POST /profile 로직을 변환한 함수 ---
+def get_merchant_profile_logic(merchant_id: str, df_merchant: pd.DataFrame):
+    """
+    가맹점 ID와 마스터 데이터프레임을 받아 프로파일링된 데이터를 반환합니다.
+    (api/server.py의 POST /profile 엔드포인트 로직)
+    """
+    logger.info(f"✅ [Local Logic] 가맹점 ID '{merchant_id}' 프로파일링 요청 수신")
+    try:
+        store_df_multiple = df_merchant[df_merchant['가맹점ID'] == merchant_id]
+
+        if store_df_multiple.empty:
+            logger.warning(f"⚠️ [Local Logic] 404 - '{merchant_id}' 가맹점 ID를 찾을 수 없습니다.")
+            raise ValueError(f"'{merchant_id}' 가맹점 ID를 찾을 수 없습니다.")
+        
+        if len(store_df_multiple) > 1:
+            logger.info(f"   [INFO] '{merchant_id}'에 대해 {len(store_df_multiple)}개의 데이터 발견. 최신 데이터로 필터링합니다.")
+            temp_df = store_df_multiple.copy()
+            temp_df['기준년월_dt'] = pd.to_datetime(temp_df['기준년월'])
+            latest_store_df = temp_df.sort_values(by='기준년월_dt', ascending=False).iloc[[0]]
+        else:
+            latest_store_df = store_df_multiple
+
+        store_data = latest_store_df.iloc[0].to_dict()
+
+        # (고객 비율 및 자동추출특징 계산 로직은 원본과 동일)
+        # 4-1. 고객 성별 비율 계산 및 저장
+        store_data['남성고객비율'] = (
+            store_data.get('남성20대이하비율', 0) + store_data.get('남성30대비율', 0) + 
+            store_data.get('남성40대비율', 0) + store_data.get('남성50대비율', 0) + 
+            store_data.get('남성60대이상비율', 0)
+        )
+        store_data['여성고객비율'] = (
+            store_data.get('여성20대이하비율', 0) + store_data.get('여성30대비율', 0) + 
+            store_data.get('여성40대비율', 0) + store_data.get('여성50대비율', 0) + 
+            store_data.get('여성60대이상비율', 0)
+        )
+        
+        # 4-2. 연령대별 비율 계산 (20대이하, 30대, 40대, 50대이상)
+        store_data['연령대20대이하고객비율'] = store_data.get('남성20대이하비율', 0) + store_data.get('여성20대이하비율', 0)
+        store_data['연령대30대고객비율'] = store_data.get('남성30대비율', 0) + store_data.get('여성30대비율', 0)
+        store_data['연령대40대고객비율'] = store_data.get('남성40대비율', 0) + store_data.get('여성40대비율', 0)
+        store_data['연령대50대고객비율'] = (
+            store_data.get('남성50대비율', 0) + store_data.get('여성50대비율', 0) + 
+            store_data.get('남성60대이상비율', 0) + store_data.get('여성60대이상비율', 0)
+        )
+
+        male_ratio = store_data.get('남성고객비율', 0)
+        female_ratio = store_data.get('여성고객비율', 0)
+        핵심고객_성별 = '남성 중심' if male_ratio > female_ratio else '여성 중심' 
+
+        age_ratios = {
+            '20대이하': store_data.get('연령대20대이하고객비율', 0),
+            '30대': store_data.get('연령대30대고객비율', 0),
+            '40대': store_data.get('연령대40대고객비율', 0),
+            '50대이상': store_data.get('연령대50대고객비율', 0),
+        }
+        핵심연령대_결과 = max(age_ratios, key=age_ratios.get)
+        
+        store_data['자동추출특징'] = {
+            "핵심고객": 핵심고객_성별,
+            "핵심연령대": 핵심연령대_결과,
+            "매출순위": f"상권 내 상위 {store_data.get('동일상권내매출순위비율', 0):.1f}%, 업종 내 상위 {store_data.get('동일업종내매출순위비율', 0):.1f}%"
+        }
+
+        area = store_data.get('상권')
+        category = store_data.get('업종')
+        
+        average_df = df_merchant[(df_merchant['상권'] == area) & (df_merchant['업종'] == category)]
+
+        if average_df.empty:
+            average_data = {}
+        else:
+            numeric_cols = average_df.select_dtypes(include=np.number).columns
+            average_data = average_df[numeric_cols].mean().to_dict()
+
+        average_data['가맹점명'] = f"{area} {category} 업종 평균"
+        
+        final_result = {
+            "store_profile": store_data,
+            "average_profile": average_data
+        }
+        
+        clean_result = replace_nan_with_none(final_result)
+        
+        logger.info(f"✅ [Local Logic] '{store_data.get('가맹점명')}({merchant_id})' 프로파일링 성공 (기준년월: {store_data.get('기준년월')})")
+        return clean_result
+
+    except ValueError as e: # HTTPException을 ValueError로 변경
+        logger.error(f"❌ [Local Logic ERROR] 처리 중 오류: {e}", exc_info=True)
+        raise e
+    except Exception as e:
+        logger.critical(f"❌ [Local Logic CRITICAL] 예측하지 못한 오류: {e}\n{traceback.format_exc()}", exc_info=True)
+        raise Exception(f"서버 내부 오류 발생: {e}")
+
+# --- (끝) API 로직 통합 ---
+
+
+# --- 이미지 로드 함수 ---
+@st.cache_data
+def load_image(image_name: str) -> Image.Image | None:
+    """assets 폴더에서 이미지를 로드하고 캐시합니다."""
+    try:
+        image_path = config.ASSETS / image_name
+        if not image_path.is_file():
+            logger.error(f"이미지 파일을 찾을 수 없습니다: {image_path}")
+            # ... (오류 로깅) ...
+            return None
+        return Image.open(image_path)
+    except Exception as e:
+        logger.error(f"이미지 로딩 중 오류 발생 ({image_name}): {e}", exc_info=True)
+        return None
+
+# --- (4) 데이터 로드 함수 수정 ---
+
+@st.cache_data
+def load_master_dataframe():
+    """
+    (수정) FastAPI 서버의 역할을 대신하여,
+    앱 시작 시 'final_df.csv' 마스터 데이터 전체를 로드하고 전처리합니다.
+    """
+    logger.info("마스터 데이터프레임 로드 시도...")
+    df = load_and_preprocess_data() # (1)에서 복사한 함수 호출
+    if df is None:
+        logger.critical("--- [Streamlit Error] 마스터 데이터 로딩 실패! ---")
+        return None
+    logger.info("--- [Streamlit] 마스터 데이터프레임 로드 및 캐시 완료 ---")
+    return df
+
+@st.cache_data
+def load_merchant_list_for_ui(_df_master: pd.DataFrame):
+    """
+    (수정) 마스터 데이터프레임에서 UI 검색용 (ID, 이름) 목록만 추출합니다.
+    (api/server.py의 GET /merchants 엔드포인트 로직)
+    """
+    try:
+        if _df_master is None:
+            return None
+        logger.info(f"✅ [Local Logic] '/merchants' 가맹점 목록 요청 수신")
+        merchant_list = _df_master[['가맹점ID', '가맹점명']].drop_duplicates().to_dict('records')
+        logger.info(f"✅ [Local Logic] 가맹점 목록 {len(merchant_list)}개 반환 완료")
+        return pd.DataFrame(merchant_list)
+    except Exception as e:
+        st.error(f"가게 목록을 불러오는 데 실패했습니다: {e}")
+        logger.critical(f"가게 목록 로딩 실패: {e}", exc_info=True)
+        return None
+
+# --- 데이터 로드 실행 (수정) ---
+# 마스터 데이터프레임을 먼저 로드합니다.
+MASTER_DF = load_master_dataframe() 
+if MASTER_DF is None:
+    st.error("🚨 데이터 로딩 실패! data/final_df.csv 파일을 확인해주세요.")
+    st.stop()
+
+# UI용 가맹점 목록을 마스터에서 추출합니다.
+merchant_df = load_merchant_list_for_ui(MASTER_DF)
+if merchant_df is None:
+    st.error("🚨 가맹점 목록 추출 실패!")
+    st.stop()
+
+# --- 세션 초기화 함수 ---
+def initialize_session():
+    """ 세션 초기화 및 AI 모듈 로드 """
+    if "orchestrator" not in st.session_state:
+        google_api_key = os.environ.get("GOOGLE_API_KEY")
+        if not google_api_key:
+            st.error("🔑 GOOGLE_API_KEY 환경변수가 설정되지 않았습니다!")
+            st.stop()
+        with st.spinner("🧠 AI 모델과 빅데이터를 로딩하고 있어요... 잠시만 기다려주세요!"):
+            try:
+                # LLM 캐시 설정
+                try:
+                    from langchain.cache import InMemoryCache
+                    from langchain.globals import set_llm_cache
+                    set_llm_cache(InMemoryCache())
+                    logger.info("--- [Streamlit] 전역 LLM 캐시(InMemoryCache) 활성화 ---")
+                except ImportError:
+                     logger.warning("--- [Streamlit] langchain.cache 임포트 실패. LLM 캐시 비활성화 ---")
+
+
+                load_marketing_vectorstore()
+                db = load_festival_vectorstore()
+                if db is None:
+                    st.error("💾 축제 벡터 DB 로딩 실패! 'build_vector_store.py' 실행 여부를 확인하세요.")
+                    st.stop()
+                logger.info("--- [Streamlit] 모든 AI 모듈 로딩 완료 ---")
+            except Exception as e:
+                st.error(f"🤯 AI 모듈 초기화 중 오류 발생: {e}")
+                logger.critical(f"AI 모듈 초기화 실패: {e}", exc_info=True)
+                st.stop()
+        st.session_state.orchestrator = AgentOrchestrator(google_api_key)
+
+    # 세션 상태 변수 초기화
+    if "step" not in st.session_state:
+        st.session_state.step = "get_merchant_name"
+        st.session_state.messages = []
+        st.session_state.merchant_id = None
+        st.session_state.merchant_name = None
+        st.session_state.profile_data = None
+        st.session_state.consultation_result = None
+        if "last_recommended_festivals" not in st.session_state:
+            st.session_state.last_recommended_festivals = []
+
+# --- 처음으로 돌아가기 함수 ---
+def restart_consultation():
+    """ 세션 상태 초기화 """
+    keys_to_reset = ["step", "merchant_name", "merchant_id", "profile_data", "messages", "consultation_result", "last_recommended_festivals"]
+    for key in keys_to_reset:
+        if key in st.session_state:
+            del st.session_state[key]
+
+# --- 사이드바 렌더링 함수 ---
+def render_sidebar():
+    """ 사이드바 렌더링 (Synapse 로고 강조 및 간격 조정) """
+    with st.sidebar:
+        # 로고 이미지 로드
+        synapse_logo = load_image("Synapse.png")
+        shinhancard_logo = load_image("ShinhanCard_Logo.png")
+
+        col1, col2, col3 = st.columns([1, 5, 1]) # 가운데 컬럼 너비 조정
+        with col2:
+            if synapse_logo:
+                st.image(synapse_logo, use_container_width=True)
+
+        st.write("")
+        st.markdown(" ")
+        col_sh1, col_sh2, col_sh3 = st.columns([1, 5, 1]) 
+        with col_sh2:
+            if shinhancard_logo:
+                st.image(shinhancard_logo, use_container_width=True) # 컬럼 너비에 맞춤
+
+        st.markdown("<p style='text-align: center; color: grey; margin-top: 20px;'>2025 Big Contest</p>", unsafe_allow_html=True) # 위쪽 마진 살짝 늘림
+        st.markdown("<p style='text-align: center; color: grey;'>AI DATA 활용분야</p>", unsafe_allow_html=True)
+        st.markdown("---")
+
+        if st.button('처음으로 돌아가기', key='restart_button_styled', use_container_width=True): # 버튼 아이콘 추가
+            restart_consultation()
+            st.rerun()
+
+# --- 가게 검색 UI 함수 (수정) ---
+def render_get_merchant_name_step():
+    """ UI 1단계: 가맹점 검색 및 선택 (API 호출 로직 수정) """
+    st.subheader("🔍 컨설팅 받을 가게를 검색해주세요")
+    st.caption("가게 이름 또는 가맹점 ID의 일부를 입력하여 검색할 수 있습니다.")
+
+    search_query = st.text_input(
+        "가게 이름 또는 가맹점 ID 검색",
+        placeholder="예: 메가커피, 스타벅스, 003AC99735 등",
+        label_visibility="collapsed"
+    )
+
+    if search_query:
+        mask = (
+            merchant_df['가맹점명'].str.contains(search_query, case=False, na=False, regex=False) |
+            merchant_df['가맹점ID'].str.contains(search_query, case=False, na=False, regex=False)
+        )
+        search_results = merchant_df[mask].copy()
+
+        if not search_results.empty:
+            search_results['display'] = search_results['가맹점명'] + " (" + search_results['가맹점ID'] + ")"
+            options = ["⬇ 아래 목록에서 가게를 선택해주세요..."] + search_results['display'].tolist()
+            selected_display_name = st.selectbox(
+                "가게 선택:",
+                options,
+                label_visibility="collapsed"
+            )
+
+            if selected_display_name != "⬇️ 아래 목록에서 가게를 선택해주세요...":
+                try:
+                    selected_row = search_results[search_results['display'] == selected_display_name].iloc[0]
+                    selected_merchant_id = selected_row['가맹점ID']
+                    selected_merchant_name = selected_row['가맹점명']
+                    button_label = f"🚀 '{selected_merchant_name}' 분석 시작하기"
+                    is_selection_valid = True
+                except (IndexError, KeyError):
+                    button_label = "분석 시작하기"
+                    is_selection_valid = False
+
+                if st.button(button_label, disabled=not is_selection_valid, type="primary", use_container_width=True):
+                    with st.spinner(f"📈 '{selected_merchant_name}' 가게 정보를 분석 중입니다... 잠시만 기다려주세요!"):
+                        profile_data = None
+                        try:
+                            # --- (수정) API POST 요청 대신 (3)에서 만든 로컬 함수 호출 ---
+                            profile_data = get_merchant_profile_logic(selected_merchant_id, MASTER_DF)
+                            # --------------------------------------------------------
+                            
+                            if "store_profile" not in profile_data or "average_profile" not in profile_data:
+                                st.error("프로필 생성 형식이 올바르지 않습니다.")
+                                profile_data = None
+                        except ValueError as e: # 404 오류
+                            st.error(f"가게 프로필 로딩 실패: {e}")
+                        except Exception as e:
+                            st.error(f"가게 프로필 로딩 중 예상치 못한 오류 발생: {e}")
+                            logger.critical(f"가게 프로필 로컬 로직 실패: {e}", exc_info=True)
+
+                        if profile_data:
+                            st.session_state.merchant_name = selected_merchant_name
+                            st.session_state.merchant_id = selected_merchant_id
+                            st.session_state.profile_data = profile_data
+                            st.session_state.step = "show_profile_and_chat"
+                            st.success(f"✅ '{selected_merchant_name}' 분석 완료!")
+                            st.rerun()
+        else:
+            st.info("💡 검색 결과가 없습니다. 다른 검색어를 시도해보세요.")
+
+# --- 프로필 및 채팅 UI 함수 ---
+def render_show_profile_and_chat_step():
+    """UI 2단계: 프로필 확인 및 AI 채팅"""
+    st.subheader(f"✨ '{st.session_state.merchant_name}' 가게 분석 완료")
+    with st.expander("📊 상세 데이터 분석 리포트 보기", expanded=True):
+        try:
+            display_merchant_profile(st.session_state.profile_data)
+        except Exception as e:
+            st.error(f"프로필 시각화 중 오류 발생: {e}")
+            logger.error(f"--- [Visualize ERROR]: {e}\n{traceback.format_exc()}", exc_info=True)
+
+    st.divider()
+    st.subheader("💬 AI 컨설턴트와 상담을 시작하세요.")
+    st.info("가게 분석 정보를 바탕으로 궁금한 점을 질문해보세요. (예: '20대 여성 고객을 늘리고 싶어요')")
+
+    for message in st.session_state.messages:
+        with st.chat_message(message["role"]):
+            st.markdown(message["content"])
+
+    if prompt := st.chat_input("요청사항을 입력하세요..."):
+        st.session_state.messages.append({"role": "user", "content": prompt})
+        with st.chat_message("user"):
+            st.markdown(prompt)
+
+        with st.chat_message("assistant"):
+            with st.spinner("AI 컨설턴트가 답변을 생성 중입니다...(최대 1~2분)"):
+                orchestrator = st.session_state.orchestrator
+                
+                if "store_profile" not in st.session_state.profile_data:
+                    st.error("세션에 'store_profile' 데이터가 없습니다. 다시 시작해주세요.")
+                    st.stop()
+                    
+                agent_history = []
+                history_to_convert = st.session_state.messages[:-1][-10:]
+                
+                for msg in history_to_convert:
+                    if msg["role"] == "user":
+                        agent_history.append(HumanMessage(content=msg["content"]))
+                    elif msg["role"] == "assistant":
+                        agent_history.append(AIMessage(content=msg["content"]))
+                
+                result = orchestrator.invoke_agent(
+                    user_query=prompt,
+                    store_profile_dict=st.session_state.profile_data["store_profile"],
+                    chat_history=agent_history,
+                    last_recommended_festivals=st.session_state.last_recommended_festivals,
+                )
+
+                response_text = ""
+                st.session_state.last_recommended_festivals = []
+
+                if "error" in result:
+                    response_text = f"오류 발생: {result['error']}"
+
+                elif "final_response" in result:
+                    response_text = result.get("final_response", "응답을 생성하지 못했습니다.")
+                    intermediate_steps = result.get("intermediate_steps", [])
+                    
+                    try:
+                        for step in intermediate_steps:
+                            action = step[0]
+                            tool_output = step[1]
+                            
+                            if hasattr(action, 'tool') and action.tool == "recommend_festivals":
+                                if tool_output and isinstance(tool_output, list) and isinstance(tool_output[0], dict):
+                                    recommended_list = [
+                                        f.get("축제명") for f in tool_output if f.get("축제명")
+                                    ]
+                                    
+                                    st.session_state.last_recommended_festivals = recommended_list
+                                    logger.info(f"--- [Streamlit] 추천 축제 저장됨 (Intermediate Steps): {recommended_list} ---")
+                                    break 
+                                    
+                    except Exception as e:
+                        logger.critical(f"--- [Streamlit CRITICAL] Intermediate steps 처리 중 예외 발생: {e} ---", exc_info=True)
+
+                else:
+                    response_text = "알 수 없는 오류가 발생했습니다."
+
+                st.markdown(response_text)
+                st.session_state.messages.append({"role": "assistant", "content": response_text})
+
+# --- 메인 실행 함수 ---
+def main():
+    st.title("🎉 MarketSync (마켓싱크)")
+    st.subheader("소상공인 맞춤형 축제 추천 & 마케팅 AI 컨설턴트")
+    st.caption("신한카드 빅데이터와 AI 에이전트를 활용하여, 사장님 가게에 꼭 맞는 지역 축제와 마케팅 전략을 찾아드립니다.")
+    st.divider()
+
+    initialize_session()
+    render_sidebar()
+
+    if st.session_state.step == "get_merchant_name":
+        render_get_merchant_name_step()
+    elif st.session_state.step == "show_profile_and_chat":
+        render_show_profile_and_chat_step()
+
+# --- 앱 실행 ---
+if __name__ == "__main__":
+    main()

tools/festival_recommender.py

@@ -0,0 +1,30 @@
+# tools/festival_recommender.py
+
+from langchain_core.tools import tool
+from typing import List, Dict, Any
+
+import config
+from modules.filtering import FestivalRecommender
+
+logger = config.get_logger(__name__)
+
+@tool
+def recommend_festivals(user_query: str, store_profile: str) -> List[Dict[str, Any]]:
+    """
+    (도구) 사용자의 질문과 가게 프로필을 바탕으로 맞춤형 축제를 추천하는
+    [하이브리드 5단계 파이프라인]을 실행합니다.
+    1. 쿼리 재작성 (프로필 기반)
+    2. 후보 검색 (임베딩 점수 - Score 1)
+    3. 동적 속성 평가 (LLM 기반 - Score 2)
+    4. 하이브리드 점수 계산 (Score 1 + Score 2)
+    5. 최종 답변 포맷팅 (LLM 기반)
+    
+    이 도구는 '축제 추천해줘'와 같은 요청 시 단독으로 사용되어야 합니다.
+    """
+    logger.info(f"--- [Tool] (신규) 하이브리드 축제 추천 파이프라인 시작 (Query: {user_query[:30]}...) ---")
+    
+    # 4번 제안: 파이프라인 클래스를 인스턴스화하고 실행
+    pipeline = FestivalRecommender(store_profile, user_query)
+    
+    # .run() 메서드가 모든 예외처리를 포함
+    return pipeline.run()

tools/marketing_strategy.py

@@ -0,0 +1,230 @@
+# tools/marketing_strategy.py
+
+import traceback
+import json
+from typing import List
+
+from langchain_core.tools import tool
+
+import config
+from modules.llm_provider import get_llm
+from modules.knowledge_base import load_marketing_vectorstore
+
+from tools.profile_analyzer import get_festival_profile_by_name
+
+logger = config.get_logger(__name__)
+
+
+@tool
+def search_contextual_marketing_strategy(user_query: str, store_profile: str) -> str:
+    """
+    (RAG Tool) 사용자의 질문과 가게 프로필(JSON 문자열)을 바탕으로 '마케팅 전략' Vector DB에서
+    관련성이 높은 컨텍스트(전략)를 검색하고, LLM을 통해 최종 답변을 생성하여 반환합니다.
+    """
+    logger.info("--- [Tool] RAG 마케팅 전략 검색 호출됨 ---")
+    
+    try:
+        retriever = load_marketing_vectorstore()
+        if retriever is None:
+            raise RuntimeError("마케팅 Retriever가 로드되지 않았습니다.")
+
+        # 1. 컨텍스트를 고려한 검색 쿼리 생성
+        try:
+            profile_dict = json.loads(store_profile)
+            profile_for_query = (
+                f"가게 위치: {profile_dict.get('주소', '알 수 없음')}\n"
+                f"가게 업종: {profile_dict.get('업종', '알 수 없음')}\n"
+                f"핵심 고객: {profile_dict.get('자동추출특징', {}).get('핵심고객', '알 수 없음')}"
+            )
+        except Exception:
+            profile_for_query = store_profile 
+
+        contextual_query = f"[가게 정보:\n{profile_for_query}\n]에 대한 [질문: {user_query}]"
+        logger.info(f"--- [Tool] RAG 검색 쿼리: {contextual_query} ---")
+        
+        # 2. Vector DB 검색
+        docs = retriever.invoke(contextual_query)
+
+        if not docs:
+            logger.warning("--- [Tool] RAG 검색 결과 없음 ---")
+            return "죄송합니다. 사장님의 가게 프로필과 질문에 맞는 마케팅 전략을 찾지 못했습니다. 가게의 특징을 조금 더 알려주시거나, 다른 질문을 시도해보시겠어요?"
+
+        # 3. LLM에 전달할 컨텍스트 포맷팅
+        context = "\n\n---\n\n".join([doc.page_content for doc in docs])
+        logger.info("--- [Tool] RAG 컨텍스트 생성 완료 ---")
+
+        # 4. LLM을 통한 답변 재구성
+        llm = get_llm(temperature=0.3) 
+
+        # --- (사용자 요청) 프롬프트 원본 유지 ---
+        prompt = f"""
+        당신은 소상공인 전문 마케팅 컨설턴트입니다.
+        아래 [가게 프로필]과 [참고 마케팅 전략]을 바탕으로, 사용자의 [질문]에 대한 맞춤형 마케팅 전략 3가지를 제안해주세요.
+
+        [가게 프로필]
+        {store_profile}
+
+        [질문]
+        {user_query}
+
+        [참고 마케팅 전략]
+        {context}
+
+        [작성 가이드라인]
+        1.  [참고 마케팅 전략]을 그대로 복사하지 말고, [가게 프로필]의 특징(예: 업종, 핵심 고객, 상권)과 [질문]의 의도를 조합하여 **가게에 특화된 새로운 아이디어**로 재구성해주세요.
+        2.  각 전략은 구체적인 실행 방안을 포함해야 합니다.
+        3.  친절하고 전문적인 말투를 사용하세요.
+        4.  아래 [출력 형식]을 정확히 지켜주세요.
+        5.  **취소선 금지**: 절대로 `~~text~~`와 같은 취소선 마크다운을 사용하지 마세요.
+
+        [출력 형식]
+        사장님 가게의 특성을 고려한 3가지 마케팅 아이디어를 제안해 드립니다.
+
+        **1. [전략 제목 1]**
+        * **전략 내용:** (가게의 어떤 특징을 활용하여 어떻게 실행하는지 구체적으로 서술)
+        * **기대 효과:** (이 전략을 통해 얻을 수 있는 구체적인 효과)
+
+        **2. [전략 제목 2]**
+        * **전략 내용:** (가게의 어떤 특징을 활용하여 어떻게 실행하는지 구체적으로 서술)
+        * **기대 효과:** (이 전략을 통해 얻을 수 있는 구체적인 효과)
+
+        **3. [전략 제목 3]**
+        * **전략 내용:** (가게의 어떤 특징을 활용하여 어떻게 실행하는지 구체적으로 서술)
+        * **기대 효과:** (이 전략을 통해 얻을 수 있는 구체적인 효과)
+        """
+
+
+        try:
+            response = llm.invoke(prompt)
+            logger.info("--- [Tool] RAG + LLM 답변 생성 완료 ---")
+            return response.content
+        except Exception as llm_e:
+            logger.critical(f"--- [Tool CRITICAL] RAG LLM 호출 중 오류: {llm_e} ---", exc_info=True)
+            return f"오류: 검색된 전략을 처리하는 중 오류가 발생했습니다. (LLM 오류: {llm_e})"
+
+    except Exception as e:
+        logger.critical(f"--- [Tool CRITICAL] RAG 마케팅 전략 검색 중 오류: {e} ---", exc_info=True)
+        return f"죄송합니다. 마케팅 전략을 생성하는 중 오류가 발생했습니다: {e}"
+
+
+@tool
+def create_festival_specific_marketing_strategy(festival_name: str, store_profile: str) -> str:
+    """
+    (RAG x2 Tool) 특정 축제 이름(예: '관악강감찬축제')과 가게 프로필(JSON 문자열)을 입력받아,
+    '축제 DB'와 '마케팅 DB'를 *동시에* RAG로 참조하여,
+    해당 축제 기간 동안 실행할 수 있는 맞춤형 마케팅 전략 *1개*를 생성합니다.
+    """
+    logger.info(f"--- [Tool] '*단일* 축제 맞춤형 전략 생성 (RAGx2)' 도구 호출 (대상: {festival_name}) ---")
+    
+    try:
+        # 1. (RAG 1) 축제 정보 가져오기 (기존 도구 재사용)
+        festival_profile_str = get_festival_profile_by_name.invoke({"festival_name": festival_name})
+        
+        if "오류" in festival_profile_str or "찾을 수 없음" in festival_profile_str:
+            logger.warning(f"--- [Tool WARNING] 축제 프로필을 찾지 못함: {festival_name} ---")
+            festival_profile_str = f"{{\"축제명\": \"{festival_name}\", \"정보\": \"상세 정보를 찾을 수 없습니다.\"}}"
+        else:
+            logger.info(f"--- [Tool] (RAG 1) 축제 프로필 로드 성공: {festival_name} ---")
+
+        # 2. (RAG 2) 관련 마케팅 전략 검색
+        marketing_retriever = load_marketing_vectorstore()
+        if marketing_retriever is None:
+            raise RuntimeError("마케팅 Retriever가 로드되지 않았습니다.")
+        
+        combined_query = f"""
+        축제 정보: {festival_profile_str}
+        가게 프로필: {store_profile}
+        질문: 위 가게가 위 축제 기간 동안 할 수 있는 최고의 마케팅 전략은?
+        """
+        marketing_docs = marketing_retriever.invoke(combined_query)
+        
+        if not marketing_docs:
+            marketing_context = "참고할 만한 마케팅 전략을 찾지 못했습니다."
+            logger.warning("--- [Tool] (RAG 2) 마케팅 전략 검색 결과 없음 ---")
+        else:
+            marketing_context = "\n\n---\n\n".join([doc.page_content for doc in marketing_docs])
+            logger.info(f"--- [Tool] (RAG 2) 마케팅 전략 컨텍스트 {len(marketing_docs)}개 확보 ---")
+
+        # 3. LLM을 통한 최종 전략 생성
+        llm = get_llm(temperature=0.5)
+        
+        # --- (사용자 요청) 프롬프트 원본 유지 ---
+        prompt = f"""
+        당신은 축제 연계 마케팅 전문 컨설턴트입니다.
+        아래 [가게 프로필], [축제 프로필], [참고 마케팅 전략]을 모두 고려하여,
+        [가게 프로필]의 사장님이 [축제 프로필] 기간 동안 실행할 수 있는
+        **창의적이고 구체적인 맞춤형 마케팅 전략 1가지**를 제안해주세요.
+
+        [가게 프로필]
+        {store_profile}
+
+        [축제 프로필]
+        {festival_profile_str}
+
+        [참고 마케팅 전략]
+        {marketing_context}
+
+        [작성 가이드라인]
+        1.  **매우 중요:** [가게 프로필]의 특징(업종, 위치, 핵심 고객)과 [축제 프로필]의 특징(주제, 주요 방문객)을 
+            **반드시 연관지어** 구체적인 전략을 만드세요.
+        2.  [참고 마케팅 전략]은 아이디어 발상에만 활용하고, 복사하지 마세요.
+        3.  전략은 1가지만 깊이 있게 제안합니다.
+        4.  친절하고 전문적인 말투를 사용하세요.
+        5.  아래 [출력 형식]을 정확히 지켜주세요.
+        6.  **취소선 금지**: 절대로 `~~text~~`와 같은 취소선 마크다운을 사용하지 마세요.
+
+        [출력 형식]
+        ### 🎈 {json.loads(festival_profile_str).get('축제명', festival_name)} 맞춤형 마케팅 전략
+
+        **1. (전략 아이디어 제목)**
+        * **전략 개요:** (가게의 어떤 특징과 축제의 어떤 특징을 연관지었는지 설명)
+        * **구체적 실행 방안:** (사장님이 '무엇을', '어떻게' 해야 하는지 단계별로 설명. 예: 메뉴 개발, 홍보 문구, SNS 이벤트 등)
+        * **타겟 고객:** (이 전략이 축제 방문객 중 누구에게 매력적일지)
+        * **기대 효과:** (예상되는 결과, 예: 신규 고객 유입, 객단가 상승 등)
+        """
+
+        try:
+            response = llm.invoke(prompt)
+            logger.info("--- [Tool] (RAGx2) 최종 전략 생성 완료 ---")
+            return response.content
+        except Exception as llm_e:
+            logger.critical(f"--- [Tool CRITICAL] '축제 맞춤형 전략 생성 (RAGx2)' LLM 호출 중 오류: {llm_e} ---", exc_info=True)
+            return f"오류: 검색된 전략을 처리하는 중 오류가 발생했습니다. (LLM 오류: {llm_e})"
+
+    except Exception as e:
+        logger.critical(f"--- [Tool CRITICAL] '축제 맞춤형 전략 생성 (RAG)' 중 오류: {e} ---", exc_info=True)
+        return f"죄송합니다. '{festival_name}' 축제 전략을 생성하는 중 오류가 발생했습니다: {e}"
+    
+
+@tool
+def create_marketing_strategies_for_multiple_festivals(festival_names: List[str], store_profile: str) -> str:
+    """
+    여러 개의 축제 이름 리스트와 가게 프로필(JSON 문자열)을 입력받아,
+    각 축제에 특화된 맞춤형 마케팅 전략을 *모두* 생성하고 하나의 문자열로 취합하여 반환합니다.
+    (예: ["청송사과축제", "부천국제만화축제"])
+    """
+    logger.info(f"--- [Tool] '*다수* 축제 맞춤형 전략 생성' 도구 호출 (대상: {festival_names}) ---")
+    
+    final_report = []
+    
+    if not festival_names:
+        logger.warning("--- [Tool] 축제 이름 목록이 비어있음 ---")
+        return "오류: 축제 이름 목록이 비어있습니다. 전략을 생성할 수 없습니다."
+
+    # 개별 전략 생성 도구를 재사용
+    for festival_name in festival_names:
+        try:
+            strategy = create_festival_specific_marketing_strategy.invoke({
+                "festival_name": festival_name,
+                "store_profile": store_profile
+            })
+            
+            final_report.append(strategy)
+            
+        except Exception as e:
+            error_message = f"--- [오류] '{festival_name}'의 전략 생성 중 문제가 발생했습니다: {e} ---"
+            logger.critical(f"--- [Tool CRITICAL] '{festival_name}' 전략 생성 중 오류: {e} ---", exc_info=True)
+            final_report.append(error_message)
+
+    logger.info("--- [Tool] '다수 축제 맞춤형 전략 생성' 완료 ---")
+    return "\n\n---\n\n".join(final_report)

tools/profile_analyzer.py

@@ -0,0 +1,205 @@
+# tools/profile_analyzer.py
+
+import json
+import traceback
+import pandas as pd
+import math
+import streamlit as st
+from langchain_core.tools import tool
+from langchain_core.messages import HumanMessage
+
+import config
+from modules.llm_provider import get_llm
+# filtering 모듈에서 날짜 예측 함수 가져오기
+from modules.filtering import FestivalRecommender
+
+logger = config.get_logger(__name__)
+
+# nan 값 처리기
+def replace_nan_with_none(data):
+    if isinstance(data, dict):
+        return {k: replace_nan_with_none(v) for k, v in data.items()}
+    elif isinstance(data, list):
+        return [replace_nan_with_none(i) for i in data]
+    elif isinstance(data, float) and math.isnan(data):
+        return None
+    return data
+
+# 축제 데이터 로더
+@st.cache_data
+def _load_festival_data():
+    try:
+        file_path = config.PATH_FESTIVAL_DF
+        if not file_path.exists():
+            logger.error(f"--- [Tool Definition ERROR] '{config.PATH_FESTIVAL_DF}' 파일을 찾을 수 없습니다.")
+            return None
+        df = pd.read_csv(file_path)
+        if '축제명' not in df.columns:
+            logger.error("--- [Tool Definition ERROR] '축제명' 컬럼이 df에 없습니다.")
+            return None
+        df_dict = df.set_index('축제명').to_dict(orient='index')
+        logger.info(f"--- [Cache] 축제 원본 CSV 로드 및 딕셔너리 변환 완료 (총 {len(df_dict)}개) ---")
+        return df_dict
+    except Exception as e:
+        logger.critical(f"--- [Tool Definition CRITICAL ERROR] 축제 데이터 로드 실패: {e} ---", exc_info=True)
+        return None
+
+# ----------------------------
+# Tool 1: 특정 축제 정보 조회
+@tool
+def get_festival_profile_by_name(festival_name: str) -> str:
+    """
+    축제 이름을 입력받아, 해당 축제의 상세 프로필(소개, 지역, 키워드, 기간, 고객층 등)을 
+    JSON 문자열로 반환합니다. 데이터베이스에서 정확한 이름을 찾아야 합니다.
+    (예: "보령머드축제 상세 정보 알려줘")
+    """
+    logger.info(f"--- [Tool] '특정 축제 정보 조회' 도구 호출 (대상: {festival_name}) ---")
+    try:
+        festival_db = _load_festival_data()
+        if festival_db is None:
+            return json.dumps({"error": "축제 데이터베이스를 로드하지 못했습니다."})
+        profile_dict = festival_db.get(festival_name)
+        if profile_dict:
+            profile_dict = replace_nan_with_none(profile_dict)
+            profile_dict['축제명'] = festival_name
+            return json.dumps(profile_dict, ensure_ascii=False)
+        else:
+            return json.dumps({"error": f"'{festival_name}' 축제를 찾을 수 없습니다. 철자를 확인해주세요."})
+    except Exception as e:
+        logger.critical(f"--- [Tool CRITICAL] '특정 축제 정보 조회' 중 오류: {e} ---", exc_info=True)
+        return json.dumps({"error": f"'{festival_name}' 축제 검색 중 오류 발생: {e}"})
+
+# ----------------------------
+# Tool 2: 가맹점 프로필 분석 (LLM)
+@tool
+def analyze_merchant_profile(store_profile: str) -> str:
+    """
+    가맹점(가게)의 프로필 데이터(JSON 문자열)를 입력받아, LLM을 사용하여 
+    [강점, 약점, 기회 요인]을 분석하는 컨설팅 리포트를 생성합니다.
+    이 도구는 가게의 현재 상태를 진단하고 마케팅 전략을 제안하는 데 사용됩니다.
+    """
+    logger.info("--- [Tool] '가맹점 프로필 분석' 도구 호출 ---")
+    try:
+        llm = get_llm(temperature=0.3)
+        prompt = f"""
+        당신은 최고의 상권 분석 전문가입니다.
+        아래 [가게 프로필] 데이터를 바탕으로, 이 가게의 [강점], [약점], [기회 요인]을
+        사장님이 이해하기 쉽게 컨설팅 리포트 형식으로 요약해주세요.
+
+        [가게 프로필]
+        {store_profile}
+
+        [분석 가이드라인]
+        1.  **강점 (Strengths)**: '동일 상권/업종 대비' 높은 수치(매출, 방문객, 객단가 등)나 '재방문율' 등을 찾아 **경쟁 우위**가 되는 핵심 요소 강조하세요.
+        2.  **약점 (Weaknesses)**: '동일 상권/업종 대비' 낮은 수치나 '신규 고객 비율' 등을 찾아 **개선이 시급한 영역**을 언급하세요.
+        3.  **기회 (Opportunities)**: 가게의 현재 강점과 '주요 고객층'이나 '상권' 특성을 바탕으로, **가게가 활용할 수 있는 마케팅(예: 특정 연령대 타겟, 신규 고객 유치)이 효과적일지 제안하고 이를 달성하기 위한 방향성을 제시하세요.
+        4.  **형식**: 마크다운을 사용하여 명확하고 가독성 좋게 작성하세요.
+        5.  **전문성/친절함**: 전문적인 분석 용어를 사용하되, 사장님이 쉽게 이해할 수 있도록 친절하고 명확하게 설명하세요.
+        6.  **(요청 4) 취소선 금지**: 절대로 `~~text~~`와 같은 취소선 마크다운을 사용하지 마세요.
+
+        [답변 형식]
+        ### 🏪 사장님 가게 프로필 분석 리포트
+
+        **1. 강점 (Strengths)**
+        * [분석된 강점 1] (분석 근거 명시)
+        * [분석된 강점 2] (분석 근거 명시)
+        * [필요시 추가 강점]
+
+        **2. 약점 (Weaknesses)**
+        * [분석된 약점 1] (개선 필요성 명시)
+        * [분석된 약점 2] (개선 필요성 명시)
+        * [필요시 추가 약점]
+
+        **3. 기회 (Opportunities)**
+        * [분석된 기회 요인 1] (활용 방안 제시)
+        * [분석된 기회 요인 2] (활용 방안 제시)
+        * [필요시 추가 기회 요인]
+        """
+        response = llm.invoke([HumanMessage(content=prompt)])
+        analysis_report = response.content.strip()
+        return analysis_report
+    except Exception as e:
+        logger.critical(f"--- [Tool CRITICAL] '가맹점 프로필 분석' 중 오류: {e} ---", exc_info=True)
+        return f"가게 프로필을 분석하는 중 오류가 발생했습니다: {e}"
+
+# ----------------------------
+# Tool 3: 축제 프로필 분석 (LLM)
+@tool
+def analyze_festival_profile(festival_name: str) -> str:
+    """
+    축제 이름을 입력받아, 해당 축제의 상세 프로필을 조회하고,
+    LLM을 사용하여 [핵심 특징]과 [주요 방문객 특성]을 요약 리포트로 반환합니다.
+    (예: "보령머드축제는 어떤 축제야?")
+    """
+    logger.info(f"--- [Tool] '축제 프로필 분석' 도구 호출 (대상: {festival_name}) ---")
+    try:
+        # 1. Tool 1 호출
+        profile_json = get_festival_profile_by_name.invoke(festival_name)
+        
+        profile_dict = json.loads(profile_json)
+
+        if "error" in profile_dict:
+            return profile_json
+
+        # 2. LLM 요약을 위한 정보 추출
+        summary = {
+            "축제명": profile_dict.get('축제명'),
+            "소개": profile_dict.get('소개'),
+            "지역": profile_dict.get('지역'),
+            "키워드": profile_dict.get('키워드'),
+            "2025_기간": profile_dict.get('2025_기간'),
+            "주요_고객층": profile_dict.get('주요고객층', 'N/A'),
+            "주요_방문자": profile_dict.get('주요방문자', 'N/A'),
+            "축제_인기도": profile_dict.get('축제인기', 'N/A'),
+            "인기도_점수": profile_dict.get('인기도_점수', 'N/A'),
+            "홈페이지": profile_dict.get('홈페이지')
+        }
+
+        # 2026년 날짜 예측 추가
+        temp_recommender = FestivalRecommender("", "") 
+        predicted_2026_timing = temp_recommender._predict_next_year_date(summary["2025_기간"])
+
+        summary_str = json.dumps(summary, ensure_ascii=False, indent=2)
+
+        llm = get_llm(temperature=0.1)
+
+        # --- 프롬프트 수정 ---
+        prompt = f"""
+        당신은 축제 전문 분석가입니다. 아래 [축제 프로필 요약]을 바탕으로,
+        이 축제의 **핵심 특징**과 **주요 방문객(타겟 고객) 특성**을
+        이해하기 쉽게 요약해주세요.
+
+        [축제 프로필 요약]
+        {summary_str}
+
+        [분석 가이드라인]
+        1.  **핵심 특징**: 입력된 **'소개'** 내용을 바탕으로 축제의 주제와 주요 내용을 **2~3문장으로 상세히 요약**하고, '키워드'와 '축제_인기도', '인기도_점수'를 언급하여 부연 설명합니다. (예: "'{summary.get("소개", "소개 정보 없음")[:50]}...'을(를) 주제로 하는 축제입니다. 주요 키워드는 '{summary.get("키워드", "N/A")}'이며, 인기도는 '{summary.get("축제_인기도", "N/A")}' 수준입니다.")
+        2.  **주요 방문객**: '주요_고객층'과 '주요_방문자' 컬럼을 직접 인용하여 설명합니다.
+            (예: {summary.get("주요_고객층", "N/A")}이 주로 방문하며, {summary.get("주요_방문자", "N/A")} 비율이 높습니다.)
+        3.  **형식**: 아래와 같은 마크다운 형식으로 답변을 작성하세요.
+        4.  **취소선 금지**: 절대로 `~~text~~`와 같은 취소선 마크다운을 사용하지 마세요.
+
+        [답변 형식]
+        ### 🎈 축제 프로필 분석 리포트: {summary.get("축제명")}
+
+        **1. 축제 핵심 특징**
+        * [축제 소개 내용을 바탕으로 2~3문장 요약. 키워드와 인기도 포함]
+
+        **2. 주요 방문객 특성**
+        * **주요 고객층:** {summary.get("주요_고객층")}
+        * **주요 방문자:** {summary.get("주요_방문자")}
+
+        **3. 2026년 개최 기간 (예상)**
+        * {predicted_2026_timing}
+
+        **4. 홈페이지**
+        * {summary.get("홈페이지", "정보 없음")}
+        """
+
+        response = llm.invoke([HumanMessage(content=prompt)])
+        analysis_report = response.content.strip()
+        return analysis_report
+
+    except Exception as e:
+        logger.critical(f"--- [Tool CRITICAL] '축제 프로필 분���' 중 오류: {e} ---", exc_info=True)
+        return f"'{festival_name}' 축제 프로필을 분석하는 중 오류가 발생했습니다: {e}"

tools/tool_loader.py

@@ -0,0 +1,24 @@
+# tools/tool_loader.py
+
+from .festival_recommender import recommend_festivals
+from .marketing_strategy import (
+    search_contextual_marketing_strategy,
+    create_festival_specific_marketing_strategy,
+    create_marketing_strategies_for_multiple_festivals
+)
+from .profile_analyzer import (
+    get_festival_profile_by_name,
+    analyze_merchant_profile,
+    analyze_festival_profile,
+)
+
+# 오케스트레이터가 사용할 최종 도구 리스트
+ALL_TOOLS = [
+    recommend_festivals,                      # (통합) 가게 맞춤형 축제 추천 (쿼리 재작성 ~ 최종 랭킹) 
+    get_festival_profile_by_name,             # (DB조회) 축제 이름으로 상세 프로필(JSON) 검색
+    search_contextual_marketing_strategy,     # (RAG) 일반적인 마케팅/홍보 전략을 Vector DB에서 검색
+    create_festival_specific_marketing_strategy,        # (LLM) *단일* 축제에 대한 맞춤형 마케팅 전략 생성 
+    create_marketing_strategies_for_multiple_festivals, # (LLM) *여러* 축제에 대한 맞춤형 마케팅 전략 동시 생성 
+    analyze_merchant_profile,                 # (LLM) 가게 프로필(JSON)을 받아 SWOT/고객 특성 분석 
+    analyze_festival_profile,                 # (LLM) 축제 프로필(JSON)을 받아 핵심 특징/방문객 분석 
+]

utils/parser_utils.py

@@ -0,0 +1,52 @@
+# utils/parser_utils.py
+
+import re
+import json
+from typing import List, Dict, Any, Union
+
+def extract_json_from_llm_response(response_text: str) -> Union[List[Dict[str, Any]], Dict[str, Any]]:
+    """
+    LLM 응답 텍스트에서 ```json ... ``` 또는 [...] 또는 {...} 블록을
+    안전하게 추출하고 파싱합니다.
+    실패 시 ValueError를 발생시킵니다.
+    """
+    json_str = None
+    
+    # 1. ```json [...] ``` 마크다운 블록 검색 (가장 우선)
+    # re.DOTALL (s) 플래그: 줄바꿈 문자를 포함하여 매칭
+    # re.MULTILINE (m) 플래그: ^, $가 각 줄의 시작/끝에 매칭
+    json_match = re.search(
+        r'```json\s*([\s\S]*?)\s*```', 
+        response_text, 
+        re.DOTALL | re.IGNORECASE
+    )
+    
+    if json_match:
+        json_str = json_match.group(1).strip()
+    else:
+        # 2. 마크다운이 없다면, 첫 번째 { 또는 [ 를 찾음
+        first_bracket_match = re.search(r'[{|\[]', response_text)
+        if first_bracket_match:
+            start_index = first_bracket_match.start()
+            
+            # 응답이 리스트([])로 시작하는 경우
+            if response_text[start_index] == '[':
+                list_match = re.search(r'(\[[\s\S]*\])', response_text[start_index:], re.DOTALL)
+                if list_match:
+                    json_str = list_match.group(0)
+            
+            # 응답이 딕셔너리({})로 시작하는 경우
+            elif response_text[start_index] == '{':
+                 dict_match = re.search(r'(\{[\s\S]*\})', response_text[start_index:], re.DOTALL)
+                 if dict_match:
+                    json_str = dict_match.group(0)
+
+    if json_str is None:
+        raise ValueError(f"응답에서 JSON 블록을 찾지 못했습니다. (응답 시작: {response_text[:150]}...)")
+    
+    try:
+        # (디버깅) 추출된 문자열 로깅
+        # print(f"--- [Parser DEBUG] Extracted JSON String: {json_str[:200]}... ---")
+        return json.loads(json_str)
+    except json.JSONDecodeError as e:
+        raise ValueError(f"JSON 파싱에 실패했습니다: {e}. (추출된 문자열: {json_str[:150]}...)")

vectorstore/faiss_festival/index.faiss

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:78a06f6935bd51302619b61b155efa818a2ce0aaa5b3b8c2f7b498151b8a2619
+size 364589

vectorstore/faiss_festival/index.pkl

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2bc78f137c400ceb373cc99cae9b9a016bd74ecce05cf9b40460b1847af6b19d
+size 503563

vectorstore/faiss_marketing/index.faiss

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:997ab4e4061ea89a33e067f80e45b1ee05865a7f8839ee9914c0e43fee705df3
+size 4288557

vectorstore/faiss_marketing/index.pkl

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6349770bbc7f676dee108982fe181e1af15ee1485eb539ad9eb8226f799e9fbd
+size 1494859

기타/create_faiss_festival.py

@@ -0,0 +1,106 @@
+import pandas as pd
+import os
+import traceback
+from pathlib import Path
+import time
+
+from langchain_community.embeddings import HuggingFaceEmbeddings
+from langchain_community.vectorstores import FAISS
+from langchain.docstore.document import Document
+
+# --- 1. 축제 데이터 로더 ---
+def _load_and_process_festivals_for_indexing():
+    """
+    1. 날짜 처리, dropna, 컬럼명 변경 로직을 모두 제거합니다.
+    2. 원본 CSV를 그대로 읽고 NaN을 빈 문자열("")로 변환합니다.
+       (Filtering 단계에서 모든 원본 컬럼을 metadata로 사용하기 위함)
+    """
+    print("--- [Indexer] 'festival_df.csv' 로딩 및 전처리 시작... ---")
+    try:
+        project_root = Path(__file__).resolve().parent
+        file_path = project_root / 'data' / 'festival_df.csv'
+        if not file_path.exists():
+            raise FileNotFoundError(f"데이터 파일을 찾을 수 없습니다: {file_path}")
+        
+        df = pd.read_csv(file_path)
+        if df.empty:
+            raise ValueError("'festival_df.csv' 파일에 데이터가 없습니다.")
+
+        # 모든 NaN 값을 빈 문자열로 대체 (데이터 유실 방지)
+        df = df.fillna("")
+        
+        print(f"--- [Indexer] 'festival_df.csv' 로딩 성공. {len(df)}개 축제 발견 ---")
+        return df.to_dict('records')
+        
+    except Exception as e:
+        print(f"--- [Indexer CRITICAL] 'festival_df.csv' 로딩 실패: {e}\n{traceback.format_exc()} ---")
+        return None
+
+# --- 2. 임베딩 모델 준비 (유지) ---
+def get_embeddings_model():
+    print("--- [Indexer] HuggingFace 임베딩 모델 로딩 시작... ---")
+    model_name = "dragonkue/BGE-m3-ko"
+    model_kwargs = {'device': 'cpu'} 
+    encode_kwargs = {'normalize_embeddings': True} 
+    
+    embeddings = HuggingFaceEmbeddings(
+        model_name=model_name,
+        model_kwargs=model_kwargs,
+        encode_kwargs=encode_kwargs
+    )
+    print("--- [Indexer] HuggingFace 임베딩 모델 로딩 완료 ---")
+    return embeddings
+
+# --- 3. 벡터 스토어 구축 및 저장  ---
+def build_and_save_vector_store():
+    start_time = time.time()
+    
+    # 1. 축제 데이터 로드 (유지)
+    festivals = _load_and_process_festivals_for_indexing()
+    if not festivals:
+        print("--- [Indexer ERROR] 축제 데이터가 없어 인덱싱을 중단합니다.")
+        return
+
+    # 2. 임베딩 모델 로드 (유지)
+    embeddings = get_embeddings_model()
+
+    # 3. LangChain Document 객체 생성
+    documents = []
+    print("--- [Indexer] 축제 정보 -> 문서(Document) 변환 시작 ---")
+    for festival in festivals:
+        
+        # 1번 점수(임베딩)에 '축제명'을 다시 추가합니다. (지적해주신 사항 반영)
+        content = (
+            f"축제명: {festival.get('축제명', '')}\n"  # <-- 이 부분 추가
+            f"축제 키워드: {festival.get('키워드', '')}\n"
+            f"축제 소개: {festival.get('소개', '')}"
+        )
+        
+        # 2번 점수(동적)에 사용될 메타데이터 (가장 중요)
+        # (축제명, 주요고객층, 인기도_점수 등 모든 원본 컬럼이 포함됨)
+        metadata = festival
+        
+        documents.append(Document(page_content=content, metadata=metadata))
+    
+    print(f"--- [Indexer] 문서 변환 완료. 총 {len(documents)}개 문서 생성 ---")
+
+    # 4. FAISS 벡터 스토어 생성 (유지)
+    print("--- [Indexer] FAISS 벡터 스토어 생성 시작 (시간이 걸릴 수 있습니다)... ---")
+    vector_store = FAISS.from_documents(documents, embeddings)
+    print("--- [Indexer] FAISS 벡터 스토어 생성 완료 ---")
+
+    # 5. 로컬에 저장 (유지)
+    project_root = Path(__file__).resolve().parent
+    save_path = project_root / 'faiss_festival'
+    
+    os.makedirs(save_path.parent, exist_ok=True)
+    vector_store.save_local(str(save_path))
+    
+    end_time = time.time()
+    print("=" * 50)
+    print(f"🎉 성공! FAISS 벡터 스토어를 생성하여 '{save_path}'에 저장했습니다.")
+    print(f"총 소요 시간: {end_time - start_time:.2f}초")
+    print("=" * 50)
+
+if __name__ == "__main__":
+    build_and_save_vector_store()

기타/create_faiss_marketing.py

@@ -0,0 +1,99 @@
+# create_marketing_retriever.py
+# -*- coding: utf-8 -*-
+
+import os
+import time
+from langchain_community.document_loaders import DirectoryLoader, PyPDFLoader
+from langchain.text_splitter import RecursiveCharacterTextSplitter
+from langchain_community.vectorstores import FAISS
+# [변경] Google 대신 HuggingFace 임베딩을 가져옵니다.
+from langchain_community.embeddings import HuggingFaceEmbeddings
+# [삭제] from dotenv import load_dotenv (더 이상 필요 없음)
+
+def create_and_save_retriever():
+    """
+    (수정됨) 로컬 Hugging Face 임베딩 모델('dragonkue/BGE-m3-ko')을 사용하여
+    마케팅 PDF 문서로부터 Retriever를 생성하고 파일로 저장합니다.
+    """
+    try:
+        # 0. [변경] API 키 로딩 로직 삭제
+        print("✅ 로컬 임베딩 모델을 사용합니다. (API 키 필요 없음)")
+
+        # 1. 데이터 로드
+        loader = DirectoryLoader(
+            './marketing',
+            glob="**/*.pdf",
+            loader_cls=PyPDFLoader,
+            show_progress=True,
+            use_multithreading=True
+        )
+        documents = loader.load()
+        print(f"✅ 총 {len(documents)}개의 PDF 문서를 불러왔습니다.")
+
+        if not documents:
+            raise ValueError("🚨 'marketing' 폴더에 PDF 파일이 없습니다. 문서를 추가해주세요.")
+
+        # 2. 텍스트 분할
+        text_splitter = RecursiveCharacterTextSplitter(
+            chunk_size=1000,
+            chunk_overlap=100
+        )
+        docs = text_splitter.split_documents(documents)
+        print(f"✅ 문서를 총 {len(docs)}개의 청크(chunk)로 분할했습니다.")
+
+        if not docs:
+            raise ValueError("🚨 문서를 청크로 분할하는 데 실패했습니다.")
+
+        # 3. [변경] 임베딩 모델 설정
+        print(f"✅ 임베딩 모델 'dragonkue/BGE-m3-ko' 로드를 시작합니다...")
+        
+        model_name = "dragonkue/BGE-m3-ko"
+        # 💡 [참고] 로컬 PC/서버에 GPU가 있다면 {'device': 'cuda'}로 변경하세요.
+        model_kwargs = {'device': 'cpu'} 
+        # 💡 [중요] BGE 모델은 검색 성능을 위해 정규화(normalize)를 강력히 권장합니다.
+        encode_kwargs = {'normalize_embeddings': True}
+
+        embeddings = HuggingFaceEmbeddings(
+            model_name=model_name,
+            model_kwargs=model_kwargs,
+            encode_kwargs=encode_kwargs
+        )
+        print(f"✅ 임베딩 모델을 성공적으로 로드했습니다.")
+
+        # 4. Vector Store 생성 (FAISS)
+        vectorstore = None
+        
+        # [변경] 로컬 모델은 배치 처리가 매우 빠르므로, API 제한(time.sleep)이 필요 없습니다.
+        # [참고] BGE-m3-ko 모델은 배치 처리를 지원하므로, FAISS.from_documents가 내부적으로 효율적으로 처리합니다.
+        print(f"🔄 총 {len(docs)}개의 청크에 대한 임베딩을 시작합니다. (시간이 걸릴 수 있음)")
+        
+        vectorstore = FAISS.from_documents(docs, embeddings)
+
+        # 5. [변경] 로컬 저장 (경로는 동일)
+        save_dir = './retriever/marketing_retriever' # [경로 수정] knowledge_base.py와 맞춤
+        os.makedirs(save_dir, exist_ok=True)
+
+        vectorstore.save_local(save_dir)
+
+        print(f"🎉 Retriever가 성공적으로 생성되어 '{save_dir}' 폴더에 저장되었습니다!")
+
+    except Exception as e:
+        print(f"🚨🚨 치명적인 오류 발생 🚨🚨: {e}")
+        import traceback
+        traceback.print_exc()
+
+if __name__ == '__main__':
+    # 1. 필요한 라이브러리가 설치되었는지 확인
+    try:
+        import langchain_community
+        import sentence_transformers
+        import faiss
+        import torch
+    except ImportError as e:
+        print(f"🚨 [오류] {e.name} 라이브러리가 설치되지 않았습니다.")
+        print("👉 다음 명령어를 실행하여 필요한 라이브러리를 설치해주세요:")
+        print("pip install langchain-community sentence-transformers faiss-cpu torch")
+        print("(GPU 사용 시: pip install langchain-community sentence-transformers faiss-gpu torch)")
+        exit(1)
+        
+    create_and_save_retriever()

기타/create_final_df.py

@@ -0,0 +1,530 @@
+<<<<<<< HEAD
+# final_df.py 
+
+import pandas as pd
+import numpy as np
+import os
+import sys
+
+# 스크립트 파일이 위치한 디렉토리를 기준으로 경로 설정
+script_path = os.path.abspath(sys.argv[0]) 
+script_dir = os.path.dirname(script_path)
+
+# 데이터 폴더 경로
+data_dir = os.path.join(script_dir, 'data')
+
+# 'data' 폴더가 실제로 존재하는지 확인 (안전장치)
+if not os.path.exists(data_dir):
+    print(f"Error: Data directory not found at {data_dir}. Please check your folder structure.")
+    sys.exit(1)
+
+# 파일 경로 함수
+def get_file_path(filename):
+    """data 폴더 내의 파일 경로를 반환합니다."""
+    return os.path.join(data_dir, filename)
+
+# --------------------------------------------------------------------------
+#### 1) 데이터 1 - **가맹점 개요정보**
+# --------------------------------------------------------------------------
+
+file_path1 = get_file_path('big_data_set1_f.csv')
+
+try:
+    df1 = pd.read_csv(file_path1, encoding="cp949")
+except FileNotFoundError:
+    print(f"Error: File not found at {file_path1}. Please ensure big_data_set1_f.csv is in the 'data' folder.")
+    sys.exit(1)
+
+col_map1 = {
+    "ENCODED_MCT": "가맹점ID",
+    "MCT_BSE_AR": "가맹점주소",
+    "MCT_NM": "가맹점명",
+    "MCT_BRD_NUM": "브랜드구분코드",
+    "MCT_SIGUNGU_NM": "지역명",
+    "HPSN_MCT_ZCD_NM": "업종",
+    "HPSN_MCT_BZN_CD_NM": "상권",
+    "ARE_D": "개설일",
+    "MCT_ME_D": "폐업여부"
+}
+
+df1 = df1.rename(columns=col_map1)
+
+# - 전처리
+df1['브랜드구분코드'] = df1['브랜드구분코드'].fillna('미확인')
+df1['상권'] = df1['상권'].fillna('미확인')
+
+df1['개설일'] = df1['개설일'].astype(str)
+# errors='coerce' 추가: ipynb 코드에는 없지만, 안전한 datetime 변환을 위해 유지 (원본 py 코드 유지)
+df1['개설일'] = pd.to_datetime(df1['개설일'], format='%Y%m%d', errors='coerce') 
+
+# ipynb 파일에서는 errors='coerce'가 없었지만, int 변환 시 오류 방지를 위해 원본 py 코드의 안전 로직을 따름.
+df1['폐업여부'] = df1['폐업여부'].apply(lambda x: pd.to_datetime(int(x), format='%Y%m%d', errors='coerce') if pd.notna(x) and str(x).isdigit() else pd.NaT)
+df1['운영상태'] = df1['폐업여부'].apply(lambda x: '운영중' if pd.isna(x) else '폐업')
+
+# --------------------------------------------------------------------------
+#### 2) 데이터 2 - **가맹점 월별 이용정보**
+# --------------------------------------------------------------------------
+
+file_path2 = get_file_path('big_data_set2_f.csv')
+
+try:
+    df2 = pd.read_csv(file_path2, encoding="cp949")
+except FileNotFoundError:
+    print(f"Error: File not found at {file_path2}. Please ensure big_data_set2_f.csv is in the 'data' folder.")
+    sys.exit(1)
+
+col_map2 = {
+    "ENCODED_MCT": "가맹점ID",
+    "TA_YM": "기준년월",
+    "MCT_OPE_MS_CN": "운영개월수_구간",
+    "RC_M1_SAA": "월매출금액_구간",
+    "RC_M1_TO_UE_CT": "월매출건수_구간",
+    "RC_M1_UE_CUS_CN": "월유니크고객수_구간",
+    "RC_M1_AV_NP_AT": "월객단가_구간",
+    "APV_CE_RAT": "취소율_구간",
+    "DLV_SAA_RAT": "배달매출비율",
+    "M1_SME_RY_SAA_RAT": "동일업종매출대비비율",
+    "M1_SME_RY_CNT_RAT": "동일업종건수대비비율",
+    "M12_SME_RY_SAA_PCE_RT": "동일업종내매출순위비율",
+    "M12_SME_BZN_SAA_PCE_RT": "동일상권내매출순위비율",
+    "M12_SME_RY_ME_MCT_RAT": "동일업종해지가맹점비중",
+    "M12_SME_BZN_ME_MCT_RAT": "동일상권해지가맹점비중"
+}
+
+df2 = df2.rename(columns=col_map2)
+
+# - 전처리
+df2['기준년월'] = pd.to_datetime(df2['기준년월'].astype(str), format='%Y%m')
+
+df2.replace(-999999.9, np.nan, inplace=True)
+
+# --------------------------------------------------------------------------
+#### 3) 데이터 3 - **가맹점 월별 이용 고객정보**
+# --------------------------------------------------------------------------
+
+file_path3 = get_file_path('big_data_set3_f.csv')
+
+try:
+    df3 = pd.read_csv(file_path3, encoding="cp949")
+except FileNotFoundError:
+    print(f"Error: File not found at {file_path3}. Please ensure big_data_set3_f.csv is in the 'data' folder.")
+    sys.exit(1)
+
+col_map3 = {
+    "ENCODED_MCT": "가맹점ID",
+    "TA_YM": "기준년월",
+    "M12_MAL_1020_RAT": "남성20대이하비율",
+    "M12_MAL_30_RAT": "남성30대비율",
+    "M12_MAL_40_RAT": "남성40대비율",
+    "M12_MAL_50_RAT": "남성50대비율",
+    "M12_MAL_60_RAT": "남성60대이상비율",
+    "M12_FME_1020_RAT": "여성20대이하비율",
+    "M12_FME_30_RAT": "여성30대비율",
+    "M12_FME_40_RAT": "여성40대비율",
+    "M12_FME_50_RAT": "여성50대비율",
+    "M12_FME_60_RAT": "여성60대이상비율",
+    "MCT_UE_CLN_REU_RAT": "재이용고객비율",
+    "MCT_UE_CLN_NEW_RAT": "신규고객비율",
+    "RC_M1_SHC_RSD_UE_CLN_RAT": "거주자이용비율",
+    "RC_M1_SHC_WP_UE_CLN_RAT": "직장인이용비율",
+    "RC_M1_SHC_FLP_UE_CLN_RAT": "유동인구이용비율"
+}
+
+df3 = df3.rename(columns=col_map3)
+
+# - 전처리
+df3['기준년월'] = pd.to_datetime(df3['기준년월'].astype(str), format='%Y%m')
+
+df3.replace(-999999.9, np.nan, inplace=True)
+
+# --------------------------------------------------------------------------
+#### 데이터 통합
+# --------------------------------------------------------------------------
+
+df23 = pd.merge(df2, df3, on=["가맹점ID", "기준년월"], how="inner")
+
+final_df = pd.merge(df23, df1, on="가맹점ID", how="left")
+
+# --------------------------------------------------------------------------
+#### 이상값 처리
+# --------------------------------------------------------------------------
+
+non_seongdong_areas = [
+    '압구정로데오', '풍산지구', '미아사거리', '방배역',
+    '자양', '동대문역사문화공원역', '건대입구',
+    '서면역', '오남'
+]
+
+# Step 1️⃣ 주소가 '성동구'에 포함된 데이터만 남기기
+mask_seongdong_addr = final_df['가맹점주소'].str.contains('성동구', na=False)
+seongdong_df = final_df[mask_seongdong_addr].copy()
+
+# Step 2️⃣ 상권명이 성동구 외인데 주소는 성동구인 경우 → 라벨 교정
+mask_mislabel = seongdong_df['상권'].isin(non_seongdong_areas)
+seongdong_df.loc[mask_mislabel, '상권'] = '미확인(성동구)'
+
+# Step 3️⃣ (ipynb 코드 로직 적용) 상권명이 '미확인'인데 주소가 성동구가 아닌 경우 제거
+# 주피터 노트북의 로직을 그대로 반영합니다. (실제 필터링 효과는 없지만, 코드 일치성 확보)
+final_clean_df = seongdong_df[
+    ~(
+        (seongdong_df['상권'].str.contains('미확인')) &
+        (~seongdong_df['가맹점주소'].str.contains('성동구', na=False))
+    )
+].copy()
+
+# 업종 - 한 업종이 100퍼인 경우 제외(이상치 취급)
+final_clean_df = final_clean_df[final_clean_df['업종'] != '유제품'].copy()
+
+# 월매출금액_구간 컬럼의 고유값
+unique_sales_bins = final_clean_df['월매출금액_구간'].dropna().unique()
+
+# 매출구간수준 매핑 딕셔너리 정의
+# --------------------------------------------------------------------------
+# ❇️ [수정] 구간 -> 수준 변환 (컬럼별 다른 명칭 적용)
+# --------------------------------------------------------------------------
+
+# --------------------------------------------------------------------------
+# ❇️ [수정] 구간 -> 수준 변환 (모든 컬럼 적용)
+# --------------------------------------------------------------------------
+
+# 1. '월매출금액_구간' (규모/순위 기준)
+sales_volume_map = {
+    '1_10%이하': '최상위',  
+    '2_10-25%': '상위',    
+    '3_25-50%': '중상위',  
+    '4_50-75%': '중하위',  
+    '5_75-90%': '하위',    
+    '6_90%초과(하위 10% 이하)': '최하위' 
+}
+
+# 2. '월객단가_구간' (가격대 기준)
+price_level_map = {
+    '1_10%이하': '최고가',  
+    '2_10-25%': '고가',    
+    '3_25-50%': '중가',    
+    '4_50-75%': '중저가',  
+    '5_75-90%': '저가',    
+    '6_90%초과(하위 10% 이하)': '최저가' 
+}
+
+# 3. '운영개월수_구간' (경험/연차 기준)
+operation_period_map = {
+    '1_10%이하': '최장기',  # 가장 오래 운영
+    '2_10-25%': '장기',
+    '3_25-50%': '중기',
+    '4_50-75%': '단기',
+    '5_75-90%': '신규',
+    '6_90%초과(하위 10% 이하)': '최신규' # 가장 최근 개업
+}
+
+# 4. '월매출건수_구간' (거래량/빈도 기준)
+transaction_count_map = {
+    '1_10%이하': '거래 최다', # 거래가 가장 많음
+    '2_10-25%': '거래 많음',
+    '3_25-50%': '거래 보통',
+    '4_50-75%': '거래 적음',
+    '5_75-90%': '거래 희소',
+    '6_90%초과(하위 10% 이하)': '거래 최저' 
+}
+
+# 5. '월유니크고객수_구간' (고객 규모 기준)
+customer_count_map = {
+    '1_10%이하': '고객 최다', # 고객 수가 가장 많음
+    '2_10-25%': '고객 많음',
+    '3_25-50%': '고객 보통',
+    '4_50-75%': '고객 적음',
+    '5_75-90%': '고객 희소',
+    '6_90%초과(하위 10% 이하)': '고객 최저'
+}
+
+
+# --- 새 컬럼 생성 ---
+
+final_clean_df['매출구간_수준'] = final_clean_df['월매출금액_구간'].map(sales_volume_map)
+final_clean_df['월객단가_수준'] = final_clean_df['월객단가_구간'].map(price_level_map)
+final_clean_df['운영개월수_수준'] = final_clean_df['운영개월수_구간'].map(operation_period_map)
+final_clean_df['월매출건수_수준'] = final_clean_df['월매출건수_구간'].map(transaction_count_map)
+final_clean_df['월유니크고객수_수준'] = final_clean_df['월유니크고객수_구간'].map(customer_count_map)
+
+# --- 미확인 값 처리 ---
+final_clean_df['매출구간_수준'] = final_clean_df['매출구간_수준'].fillna('미확인')
+final_clean_df['월객단가_수준'] = final_clean_df['월객단가_수준'].fillna('미확인')
+final_clean_df['운영개월수_수준'] = final_clean_df['운영개월수_수준'].fillna('미확인')
+final_clean_df['월매출건수_수준'] = final_clean_df['월매출건수_수준'].fillna('미확인')
+final_clean_df['월유니크고객수_수준'] = final_clean_df['월유니크고객수_수준'].fillna('미확인')
+# --------------------------------------------------------------------------
+# final_df 저장
+# --------------------------------------------------------------------------
+
+# 'data' 폴더 내에 저장
+save_path = get_file_path("final_df.csv")
+
+# CSV 파일 저장 (인덱스 제외)
+final_clean_df.to_csv(save_path, index=False, encoding="utf-8-sig")
+
+=======
+# final_df.py 
+
+import pandas as pd
+import numpy as np
+import os
+import sys
+
+# 스크립트 파일이 위치한 디렉토리를 기준으로 경로 설정
+script_path = os.path.abspath(sys.argv[0]) 
+script_dir = os.path.dirname(script_path)
+
+# 데이터 폴더 경로
+data_dir = os.path.join(script_dir, 'data')
+
+# 'data' 폴더가 실제로 존재하는지 확인 (안전장치)
+if not os.path.exists(data_dir):
+    print(f"Error: Data directory not found at {data_dir}. Please check your folder structure.")
+    sys.exit(1)
+
+# 파일 경로 함수
+def get_file_path(filename):
+    """data 폴더 내의 파일 경로를 반환합니다."""
+    return os.path.join(data_dir, filename)
+
+# --------------------------------------------------------------------------
+#### 1) 데이터 1 - **가맹점 개요정보**
+# --------------------------------------------------------------------------
+
+file_path1 = get_file_path('big_data_set1_f.csv')
+
+try:
+    df1 = pd.read_csv(file_path1, encoding="cp949")
+except FileNotFoundError:
+    print(f"Error: File not found at {file_path1}. Please ensure big_data_set1_f.csv is in the 'data' folder.")
+    sys.exit(1)
+
+col_map1 = {
+    "ENCODED_MCT": "가맹점ID",
+    "MCT_BSE_AR": "가맹점주소",
+    "MCT_NM": "가맹점명",
+    "MCT_BRD_NUM": "브랜드구분코드",
+    "MCT_SIGUNGU_NM": "지역명",
+    "HPSN_MCT_ZCD_NM": "업종",
+    "HPSN_MCT_BZN_CD_NM": "상권",
+    "ARE_D": "개설일",
+    "MCT_ME_D": "폐업여부"
+}
+
+df1 = df1.rename(columns=col_map1)
+
+# - 전처리
+df1['브랜드구분코드'] = df1['브랜드구분코드'].fillna('미확인')
+df1['상권'] = df1['상권'].fillna('미확인')
+
+df1['개설일'] = df1['개설일'].astype(str)
+# errors='coerce' 추가: ipynb 코드에는 없지만, 안전한 datetime 변환을 위해 유지 (원본 py 코드 유지)
+df1['개설일'] = pd.to_datetime(df1['개설일'], format='%Y%m%d', errors='coerce') 
+
+# ipynb 파일에서는 errors='coerce'가 없었지만, int 변환 시 오류 방지를 위해 원본 py 코드의 안전 로직을 따름.
+df1['폐업여부'] = df1['폐업여부'].apply(lambda x: pd.to_datetime(int(x), format='%Y%m%d', errors='coerce') if pd.notna(x) and str(x).isdigit() else pd.NaT)
+df1['운영상태'] = df1['폐업여부'].apply(lambda x: '운영중' if pd.isna(x) else '폐업')
+
+# --------------------------------------------------------------------------
+#### 2) 데이터 2 - **가맹점 월별 이용정보**
+# --------------------------------------------------------------------------
+
+file_path2 = get_file_path('big_data_set2_f.csv')
+
+try:
+    df2 = pd.read_csv(file_path2, encoding="cp949")
+except FileNotFoundError:
+    print(f"Error: File not found at {file_path2}. Please ensure big_data_set2_f.csv is in the 'data' folder.")
+    sys.exit(1)
+
+col_map2 = {
+    "ENCODED_MCT": "가맹점ID",
+    "TA_YM": "기준년월",
+    "MCT_OPE_MS_CN": "운영개월수_구간",
+    "RC_M1_SAA": "월매출금액_구간",
+    "RC_M1_TO_UE_CT": "월매출건수_구간",
+    "RC_M1_UE_CUS_CN": "월유니크고객수_구간",
+    "RC_M1_AV_NP_AT": "월객단가_구간",
+    "APV_CE_RAT": "취소율_구간",
+    "DLV_SAA_RAT": "배달매출비율",
+    "M1_SME_RY_SAA_RAT": "동일업종매출대비비율",
+    "M1_SME_RY_CNT_RAT": "동일업종건수대비비율",
+    "M12_SME_RY_SAA_PCE_RT": "동일업종내매출순위비율",
+    "M12_SME_BZN_SAA_PCE_RT": "동일상권내매출순위비율",
+    "M12_SME_RY_ME_MCT_RAT": "동일업종해지가맹점비중",
+    "M12_SME_BZN_ME_MCT_RAT": "동일상권해지가맹점비중"
+}
+
+df2 = df2.rename(columns=col_map2)
+
+# - 전처리
+df2['기준년월'] = pd.to_datetime(df2['기준년월'].astype(str), format='%Y%m')
+
+df2.replace(-999999.9, np.nan, inplace=True)
+
+# --------------------------------------------------------------------------
+#### 3) 데이터 3 - **가맹점 월별 이용 고객정보**
+# --------------------------------------------------------------------------
+
+file_path3 = get_file_path('big_data_set3_f.csv')
+
+try:
+    df3 = pd.read_csv(file_path3, encoding="cp949")
+except FileNotFoundError:
+    print(f"Error: File not found at {file_path3}. Please ensure big_data_set3_f.csv is in the 'data' folder.")
+    sys.exit(1)
+
+col_map3 = {
+    "ENCODED_MCT": "가맹점ID",
+    "TA_YM": "기준년월",
+    "M12_MAL_1020_RAT": "남성20대이���비율",
+    "M12_MAL_30_RAT": "남성30대비율",
+    "M12_MAL_40_RAT": "남성40대비율",
+    "M12_MAL_50_RAT": "남성50대비율",
+    "M12_MAL_60_RAT": "남성60대이상비율",
+    "M12_FME_1020_RAT": "여성20대이하비율",
+    "M12_FME_30_RAT": "여성30대비율",
+    "M12_FME_40_RAT": "여성40대비율",
+    "M12_FME_50_RAT": "여성50대비율",
+    "M12_FME_60_RAT": "여성60대이상비율",
+    "MCT_UE_CLN_REU_RAT": "재이용고객비율",
+    "MCT_UE_CLN_NEW_RAT": "신규고객비율",
+    "RC_M1_SHC_RSD_UE_CLN_RAT": "거주자이용비율",
+    "RC_M1_SHC_WP_UE_CLN_RAT": "직장인이용비율",
+    "RC_M1_SHC_FLP_UE_CLN_RAT": "유동인구이용비율"
+}
+
+df3 = df3.rename(columns=col_map3)
+
+# - 전처리
+df3['기준년월'] = pd.to_datetime(df3['기준년월'].astype(str), format='%Y%m')
+
+df3.replace(-999999.9, np.nan, inplace=True)
+
+# --------------------------------------------------------------------------
+#### 데이터 통합
+# --------------------------------------------------------------------------
+
+df23 = pd.merge(df2, df3, on=["가맹점ID", "기준년월"], how="inner")
+
+final_df = pd.merge(df23, df1, on="가맹점ID", how="left")
+
+# --------------------------------------------------------------------------
+#### 이상값 처리
+# --------------------------------------------------------------------------
+
+non_seongdong_areas = [
+    '압구정로데오', '풍산지구', '미아사거리', '방배역',
+    '자양', '동대문역사문화공원역', '건대입구',
+    '서면역', '오남'
+]
+
+# Step 1️⃣ 주소가 '성동구'에 포함된 데이터만 남기기
+mask_seongdong_addr = final_df['가맹점주소'].str.contains('성동구', na=False)
+seongdong_df = final_df[mask_seongdong_addr].copy()
+
+# Step 2️⃣ 상권명이 성동구 외인데 주소는 성동구인 경우 → 라벨 교정
+mask_mislabel = seongdong_df['상권'].isin(non_seongdong_areas)
+seongdong_df.loc[mask_mislabel, '상권'] = '미확인(성동구)'
+
+# Step 3️⃣ (ipynb 코드 로직 적용) 상권명이 '미확인'인데 주소가 성동구가 아닌 경우 제거
+# 주피터 노트북의 로직을 그대로 반영합니다. (실제 필터링 효과는 없지만, 코드 일치성 확보)
+final_clean_df = seongdong_df[
+    ~(
+        (seongdong_df['상권'].str.contains('미확인')) &
+        (~seongdong_df['가맹점주소'].str.contains('성동구', na=False))
+    )
+].copy()
+
+# 업종 - 한 업종이 100퍼인 경우 제외(이상치 취급)
+final_clean_df = final_clean_df[final_clean_df['업종'] != '유제품'].copy()
+
+# 월매출금액_구간 컬럼의 고유값
+unique_sales_bins = final_clean_df['월매출금액_구간'].dropna().unique()
+
+# 매출구간수준 매핑 딕셔너리 정의
+# --------------------------------------------------------------------------
+# ❇️ [수정] 구간 -> 수준 변환 (컬럼별 다른 명칭 적용)
+# --------------------------------------------------------------------------
+
+# --------------------------------------------------------------------------
+# ❇️ [수정] 구간 -> 수준 변환 (모든 컬럼 적용)
+# --------------------------------------------------------------------------
+
+# 1. '월매출금액_구간' (규모/순위 기준)
+sales_volume_map = {
+    '1_10%이하': '최상위',  
+    '2_10-25%': '상위',    
+    '3_25-50%': '중상위',  
+    '4_50-75%': '중하위',  
+    '5_75-90%': '하위',    
+    '6_90%초과(하위 10% 이하)': '최하위' 
+}
+
+# 2. '월객단가_구간' (가격대 기준)
+price_level_map = {
+    '1_10%이하': '최고가',  
+    '2_10-25%': '고가',    
+    '3_25-50%': '중가',    
+    '4_50-75%': '중저가',  
+    '5_75-90%': '저가',    
+    '6_90%초과(하위 10% 이하)': '최저가' 
+}
+
+# 3. '운영개월수_구간' (경험/연차 기준)
+operation_period_map = {
+    '1_10%이하': '최장기',  # 가장 오래 운영
+    '2_10-25%': '장기',
+    '3_25-50%': '중기',
+    '4_50-75%': '단기',
+    '5_75-90%': '신규',
+    '6_90%초과(하위 10% 이하)': '최신규' # 가장 최근 개업
+}
+
+# 4. '월매출건수_구간' (거래량/빈도 기준)
+transaction_count_map = {
+    '1_10%이하': '거래 최다', # 거래가 가장 많음
+    '2_10-25%': '거래 많음',
+    '3_25-50%': '거래 보통',
+    '4_50-75%': '거래 적음',
+    '5_75-90%': '거래 희소',
+    '6_90%초과(하위 10% 이하)': '거래 최저' 
+}
+
+# 5. '월유니크고객수_구간' (고객 규모 기준)
+customer_count_map = {
+    '1_10%이하': '고객 최다', # 고객 수가 가장 많음
+    '2_10-25%': '고객 많음',
+    '3_25-50%': '고객 보통',
+    '4_50-75%': '고객 적음',
+    '5_75-90%': '고객 희소',
+    '6_90%초과(하위 10% 이하)': '고객 최저'
+}
+
+
+# --- 새 컬럼 생성 ---
+
+final_clean_df['매출구간_수준'] = final_clean_df['월매출금액_구간'].map(sales_volume_map)
+final_clean_df['월객단가_수준'] = final_clean_df['월객단가_구간'].map(price_level_map)
+final_clean_df['운영개월수_수준'] = final_clean_df['운영개월수_구간'].map(operation_period_map)
+final_clean_df['월매출건수_수준'] = final_clean_df['월매출건수_구간'].map(transaction_count_map)
+final_clean_df['월유니크고객수_수준'] = final_clean_df['월유니크고객수_구간'].map(customer_count_map)
+
+# --- 미확인 값 처리 ---
+final_clean_df['매출구간_수준'] = final_clean_df['매출구간_수준'].fillna('미확인')
+final_clean_df['월객단가_수준'] = final_clean_df['월객단가_수준'].fillna('미확인')
+final_clean_df['운영개월수_수준'] = final_clean_df['운영개월수_수준'].fillna('미확인')
+final_clean_df['월매출건수_수준'] = final_clean_df['월매출건수_수준'].fillna('미확인')
+final_clean_df['월유니크고객수_수준'] = final_clean_df['월유니크고객수_수준'].fillna('미확인')
+# --------------------------------------------------------------------------
+# final_df 저장
+# --------------------------------------------------------------------------
+
+# 'data' 폴더 내에 저장
+save_path = get_file_path("final_df.csv")
+
+# CSV 파일 저장 (인덱스 제외)
+final_clean_df.to_csv(save_path, index=False, encoding="utf-8-sig")
+
+>>>>>>> 4025576cc0b52c8393af0ca720a1f6fabeb5e43a
+print(f"CSV 파일 저장 완료: {save_path}")

기타/feastival_df_add_keywords.py

@@ -0,0 +1,118 @@
+import os
+import pandas as pd
+from langchain_google_genai import ChatGoogleGenerativeAI
+from langchain_core.messages import HumanMessage
+import time
+
+# --- 설정 ---
+# ⚠️ 원본 파일 경로와 저장될 파일 이름을 확인하세요.
+INPUT_CSV_PATH = 'festival_df.csv'
+OUTPUT_CSV_PATH = 'festival_df_updated.csv'
+# ----------------
+
+def generate_keywords_from_description(llm, description: str) -> str:
+    """
+    축제 소개글을 바탕으로 Gemini AI를 사용하여 키워드를 생성합니다.
+    """
+    if not isinstance(description, str) or not description.strip():
+        return ""
+
+    # AI에게 역할을 부여하고, 원하는 결과물의 형식과 내용을 구체적으로 지시하는 프롬프트
+    prompt = f"""
+    당신은 지역 축제 전문 마케팅 분석가입니다.
+    아래 제공된 축제 소개글을 읽고, 부스 참가를 고려하는 가게 사장님에게 도움이 될 만한 핵심 키워드를 추출해주세요.
+
+    [추출 가이드라인]
+    1. 다음 5가지 카테고리로 키워드를 분류해주세요:
+       - **타겟 고객**: (예: 20대, 가족 단위, 친구, 연인, 외국인 관광객)
+       - **계절**: (예: 봄, 여름, 가을, 겨울)
+       - **축제 분위기**: (예: 활기찬, 전통적인, 힙한, 자연 친화적)
+       - **주요 콘텐츠**: (예: 먹거리, 푸드트럭, 체험 활동, 공연, 전통문화, 불꽃놀이, 특산물)
+       - **핵심 테마**: (예: 역사, 문화, 음악, 예술, 계절)
+    2. 모든 키워드를 쉼표(,)로 구분된 하나의 문자열로 만들어 반환해주세요.
+       (예시: 가족 단위, 연인, 활기찬, 전통적인, 먹거리, 체험, 역사, 문화)
+    3. 소개글에서 근거를 찾을 수 없는 내용은 추측하여 만들지 마세요.
+
+    [축제 소개글]
+    {description}
+
+    [추출된 키워드 (쉼표로 구분)]
+    """
+    
+    try:
+        message = HumanMessage(content=prompt)
+        response = llm.invoke([message])
+        return response.content.strip()
+    except Exception as e:
+        print(f"  [오류] API 호출 중 문제 발생: {e}")
+        return ""
+
+def main():
+    """
+    메인 실행 함수
+    """
+    print("--- 🤖 '소개' 기반 AI 키워드 자동 생성 작업을 시작합니다. ---")
+
+    # 1. Google API 키 및 LLM 초기화
+    try:
+        # 'GOOGLE_API_KEY' 라는 이름의 환경 변수를 찾습니다.
+        google_api_key = os.getenv("GOOGLE_API_KEY")
+        if not google_api_key:
+            raise ValueError("GOOGLE_API_KEY 환경 변수가 설정되지 않았습니다. API 키를 설정해주세요.")
+        
+        # 정확한 판단을 위해 temperature를 낮게 설정
+        llm = ChatGoogleGenerativeAI(
+            model="gemini-2.5-flash", 
+            # 환경 변수에서 불러온 키를 사용합니다.
+            google_api_key=google_api_key, 
+            temperature=0.1
+        )
+        print("✅ Gemini 모델 초기화 완료.")
+    except Exception as e:
+        print(f"❌ [치명적 오류] Gemini 모델 초기화 실패: {e}")
+        return
+
+    # 2. CSV 파일 로드
+    try:
+        df = pd.read_csv(INPUT_CSV_PATH)
+        print(f"✅ '{INPUT_CSV_PATH}' 파일 로딩 완료. (총 {len(df)}개 축제)")
+    except FileNotFoundError:
+        print(f"❌ [치명적 오류] 파일을 찾을 수 없습니다: '{INPUT_CSV_PATH}'")
+        print("    프로젝트 폴더 내에 'festival_df.csv' 파일이 있는지 확인해주세요.")
+        return
+
+    # 3. 각 축제별로 키워드 생성 및 추가
+    new_keywords_list = []
+    total_rows = len(df)
+
+    for index, row in df.iterrows():
+        print(f"\n--- ({index + 1}/{total_rows}) '{row['축제명']}' 작업 중 ---")
+        
+        description = row['소개']
+        
+        print("  - AI를 호출하여 키워드를 생성합니다...")
+        new_keywords = generate_keywords_from_description(llm, description)
+        
+        original_keywords = str(row.get('키워드', ''))
+        
+        all_keywords = original_keywords.split(',') + new_keywords.split(',')
+        unique_keywords = sorted(list(set([k.strip() for k in all_keywords if k.strip()])))
+        
+        final_keywords_str = ', '.join(unique_keywords)
+        new_keywords_list.append(final_keywords_str)
+        
+        print(f"  - [기존 키워드]: {original_keywords if original_keywords else '없음'}")
+        print(f"  - [AI 생성 키워드]: {new_keywords}")
+        print(f"  - [최종 키워드]: {final_keywords_str}")
+
+        time.sleep(0.5) 
+
+    # 4. DataFrame에 새로운 키워드 열 추가 및 저장
+    df['키워드'] = new_keywords_list
+    
+    df.to_csv(OUTPUT_CSV_PATH, index=False, encoding='utf-8-sig')
+    print(f"\n--- 🎉 작업 완료! ---")
+    print(f"✅ 새로운 키워드가 추가된 파일이 '{OUTPUT_CSV_PATH}' 경로에 저장되었습니다.")
+
+if __name__ == "__main__":
+    main()

기타/festival_df_first.py

@@ -0,0 +1,58 @@
+import pandas as pd
+import glob
+import os
+
+# --- 설정 부분 ---
+# 1. 데이터 파일들이 저장된 폴더 경로를 지정합니다.
+# Windows 경로의 경우, 역슬래시(\)를 두 번 쓰거나(C:\\...) 슬래시(/)로 변경해야 합니다.
+folder_path = 'C:/projects/shcard_2025_bigcontest/data/festival'
+
+# 2. 통합된 파일을 저장할 경로를 지정합니다. (결과를 같은 폴더에 저장)
+output_path = 'C:/projects/shcard_2025_bigcontest/data'
+
+# --- 데이터 통합 함수 정의 ---
+def combine_festival_data(path, pattern, output_filename):
+    """
+    지정된 경로에서 특정 패턴의 CSV 파일들을 찾아 하나로 통합하고 저장하는 함수.
+    
+    :param path: CSV 파일들이 있는 폴더 경로
+    :param pattern: 찾을 파일 이름의 패턴 (예: '*_문화관광축제 주요 지표.csv')
+    :param output_filename: 저장할 최종 CSV 파일 이름
+    """
+    # 지정된 경로와 패턴을 결합하여 파일 목록을 가져옵니다.
+    file_list = glob.glob(os.path.join(path, pattern))
+    
+    if not file_list:
+        print(f"⚠️ 경고: '{pattern}' 패턴에 해당하는 파일을 찾을 수 없습니다.")
+        print(f"경로를 확인해주세요: {path}\n")
+        return
+
+    # 각 파일을 DataFrame으로 읽어 리스트에 추가합니다.
+    df_list = [pd.read_csv(file) for file in file_list]
+    
+    # 모든 DataFrame을 하나로 합칩니다.
+    combined_df = pd.concat(df_list, ignore_index=True)
+    
+    # 통합된 데이터를 CSV 파일로 저장합니다.
+    # encoding='utf-8-sig'는 Excel에서 한글이 깨지지 않도록 해줍니다.
+    output_filepath = os.path.join(output_path, output_filename)
+    combined_df.to_csv(output_filepath, index=False, encoding='utf-8-sig')
+    
+    print(f"✅ 성공: {len(file_list)}개의 파일을 통합하여 '{output_filename}'으로 저장했습니다.")
+    print(f"    - 총 {len(combined_df)}개의 행이 생성되었습니다.")
+    print(f"    - 저장 경로: {output_filepath}\n")
+    
+
+# --- 메인 코드 실행 ---
+print("===== 축제 데이터 통합을 시작합니다. =====\n")
+
+# 1. 문화관광축제 주요 지표 통합
+combine_festival_data(folder_path, '*_문화관광축제 주요 지표.csv', '통합_문화관광축제_주요_지표.csv')
+
+# 2. 성_연령별 내국인 방문자 통합
+combine_festival_data(folder_path, '*_성_연령별 내국인 방문자.csv', '통합_성_연령별_내국인_방문자.csv')
+
+# 3. 연도별 방문자 추이 통합
+combine_festival_data(folder_path, '*_연도별 방문자 추이.csv', '통합_연도별_방문자_추이.csv')
+
+print("===== 모든 데이터 통합 작업이 완료되었습니다. =====")

기타/festival_df_processing.py

@@ -0,0 +1,235 @@
+# -*- coding: utf-8 -*-
+"""festival_processing.ipynb
+
+Automatically generated by Colab.
+
+Original file is located at
+    https://colab.research.google.com/drive/1NnUdWSIUNLRY4O9PmcX5GFgeaTekcO7c
+"""
+
+# 1. 구글 드라이브 마운트
+from google.colab import drive
+drive.mount('/content/drive')
+
+
+# 2. CSV 파일 경로 지정
+file_path = '/content/drive/MyDrive/Colab Notebooks/BigContest_2025/festival_df.csv'
+
+# 3. 데이터 불러오기
+import pandas as pd
+festival_df = pd.read_csv(file_path, encoding='utf-8')
+
+# 4. 데이터 확인
+print("===== 데이터 정보 =====")
+print(festival_df.info())
+print("\n===== 데이터 샘플 =====")
+print(festival_df.head())
+print("\n===== 기본 통계 =====")
+print(festival_df.describe())
+
+"""- 주요 성별
+
+- 주요 나이
+"""
+
+# 주요 성별
+# 남/여 컬럼 리스트
+male_cols = [c for c in festival_df.columns if '남성비율' in c]
+female_cols = [c for c in festival_df.columns if '여성비율' in c]
+
+# 남성/여성 비율 합 계산 - 남성+여성이 100%인지 체크
+festival_df['남성합'] = festival_df[male_cols].sum(axis=1)
+festival_df['여성합'] = festival_df[female_cols].sum(axis=1)
+festival_df['남녀합계'] = festival_df['남성합'] + festival_df['여성합']
+
+# 합계가 100 근처인지 확인
+print(festival_df[['축제명', '남성합', '여성합', '남녀합계']].head())
+
+import numpy as np
+
+# 1️⃣ 주요 성별 컬럼 추가
+festival_df['주요성별'] = np.where(
+    festival_df['남성합'] > festival_df['여성합'], '남성', '여성'
+)
+
+# 2️⃣ 주요 연령대 컬럼 추가
+age_groups = ['09세', '1019세', '2029세', '3039세', '4049세', '5059세', '6069세', '70세이상']
+
+# 각 연령대별 남+여 합 계산
+for age in age_groups:
+    festival_df[f'연령대_{age}_합'] = (
+        festival_df[f'남성비율_{age}'] + festival_df[f'여성비율_{age}']
+    )
+
+# 각 행별로 가장 큰 연령대 찾기 (NaN 방어 포함)
+festival_df['주요연령대'] = (
+    festival_df[[f'연령대_{age}_합' for age in age_groups]]
+    .fillna(0)
+    .idxmax(axis=1)
+    .str.replace('연령대_', '', regex=False)
+    .str.replace('_합', '', regex=False)
+)
+
+# 3️⃣ 중간 계산 컬럼(연령대_*_합)은 정리해서 제거 가능
+festival_df.drop(columns=[f'연령대_{age}_합' for age in age_groups], inplace=True)
+
+# ✅ 결과 미리보기
+print(festival_df[['축제명', '주요성별', '주요연령대']].head())
+print('--------------------------------------------')
+print(festival_df[['축제명', '주요성별', '주요연령대']].tail())
+
+festival_df
+
+"""- 주요 고객층(성별+연령)"""
+
+# 남/여 각 연령대 컬럼 리스트
+gender_age_cols = [f'남성비율_{age}' for age in age_groups] + [f'여성비율_{age}' for age in age_groups]
+
+def find_key_customer(row):
+    # 해당 행에서 최대값을 가지는 컬럼 찾기
+    max_col = row[gender_age_cols].idxmax()
+
+    # 컬럼명에서 성별과 나이 추출
+    gender, age = max_col.split('_')
+
+    # 나이 표현
+    if age == '70세이상':
+        age_str = '70세 이상'
+    else:
+        age_str = age[:2] + '~' + age[2:]
+
+    return f"{gender} {age_str}"
+
+festival_df['주요고객층'] = festival_df.apply(find_key_customer, axis=1)
+
+# 결과 확인
+print(festival_df[['축제명', '주요고객층']].head())
+
+"""- 주요 방문자(현지인/외지인)"""
+
+# 연도별 현지인 방문자 수 합계
+local_cols = ['2018_(현지인)방문자수', '2019_(현지인)방문자수',
+              '2022_(현지인)방문자수', '2023_(현지인)방문자수',
+              '2024_(현지인)방문자수']
+
+# 연도별 외부 방문자 수 합계 (외지인 + 외국인)
+outside_cols = ['2018_(외지인)방문자수', '2019_(외지인)방문자수',
+                '2022_(외지인)방문자수', '2023_(외지인)방문자수',
+                '2024_(외지인)방문자수']
+
+foreign_cols = ['2018_(외국인)방문자수', '2019_(외국인)방문자수',
+                '2022_(외국인)방문자수', '2023_(외국인)방문자수',
+                '2024_(외국인)방문자수']
+
+festival_df['총현지인'] = festival_df[local_cols].sum(axis=1)
+festival_df['총외부방문자'] = festival_df[outside_cols + foreign_cols].sum(axis=1)
+
+# 주요 방문자 판단
+festival_df['주요방문자'] = np.where(
+    festival_df['총현지인'] >= festival_df['총외부방문자'],
+    '현지인',
+    '외부방문자'
+)
+
+# 중간 합계 컬럼 삭제
+festival_df.drop(columns=['총현지인', '총외부방문자'], inplace=True)
+
+# 결과 확인
+print(festival_df[['축제명', '주요방문자']])
+
+festival_df.columns
+
+"""- 축제 인기
+
+  - 전체 방문자수(전체방문자수)
+  - 일평균 방문자수
+  - 축제기간 내비게이션 검색량
+  - 축제기간 관광 소비
+
+  위 컬럼 이용해서 인기 계산
+
+  1) 연도별 데이터를 바탕으로 모든 지표를 계산
+  2) 각 연도별 지표를 표준화 -> 점수���하고 평균 내서 하나의 종합 '인기 점수'를 생성
+  3) 종합 인기 점수를 기준으로 '상/중/하' 등급 나눔
+"""
+
+import numpy as np
+from sklearn.preprocessing import MinMaxScaler
+
+# 1️⃣ 인기 지표 컬럼 정의 (연도별 방문자수, 일평균 방문자수, 검색량 등)
+years = ['2018', '2019', '2022', '2023', '2024']
+visitor_cols = [f'{year}_(전체)방문자수' for year in years]
+daily_avg_cols = [f'{year}_일평균 방문자수' for year in years]
+nav_cols = [f'{year}_축제기간_내비게이션 검색량' for year in years]
+
+# 2️⃣ 모든 지표를 합쳐서 새로운 점수 데이터프레임 생성
+score_df = festival_df[visitor_cols + daily_avg_cols + nav_cols].fillna(0)
+
+# 3️⃣ MinMaxScaler로 0~1로 정규화
+scaler = MinMaxScaler()
+score_scaled = scaler.fit_transform(score_df)
+
+# 4️⃣ 연도/지표별 점수 평균 내기
+festival_df['인기도_점수'] = score_scaled.mean(axis=1)
+
+# 5️⃣ 점수를 기준으로 등급 나누기 (상/중/하)
+festival_df['축제인기'] = pd.cut(
+    festival_df['인기도_점수'],
+    bins=[-0.01, 0.33, 0.66, 1.01],
+    labels=['하', '중', '상']
+)
+
+# ✅ 결과 미리보기
+print(festival_df[['축제명', '인기도_점수', '축제인기']])
+
+"""- 축제 인기도(상승/하락/미미)
+
+  - 연도별 변화율의 평균으로 인기도 상승/하락/미미 결정
+
+    - 평균이 양수 → 전체적으로 상승 추세
+
+    -  평균이 음수 → 전체적으로 하락 추세
+
+    - 평균이 거의 0 → 미미한 추세
+"""
+
+# 1️⃣ 연도별 인기 지표 컬럼들
+pop_cols = ['전체방문자수', '일평균 방문자수', '축제기간_내비게이션 검색량', '축제기간_관광소비']
+
+# 2️⃣ 연도 리스트 (데이터에 맞춰 조정)
+years = ['2018', '2019', '2022', '2023', '2024']
+
+# 3️⃣ 연도별 변화율 계산
+trend_list = []
+for idx, row in festival_df.iterrows():
+    change_rates = []
+    for col in pop_cols:
+        year_values = [row[f'{year}_{col}'] for year in years if f'{year}_{col}' in festival_df.columns]
+        # 연속된 연도 변화율 계산 ((이번연도-이전연도)/이전연도)
+        for i in range(1, len(year_values)):
+            prev = year_values[i-1]
+            curr = year_values[i]
+            if prev and not np.isnan(prev) and curr and not np.isnan(curr) and prev != 0:
+                rate = (curr - prev) / prev
+                change_rates.append(rate)
+    # 평균 변화율 계산
+    avg_rate = np.mean(change_rates) if change_rates else 0
+    # 상승/하락/미미 판단 (임계값 1% 사용)
+    if avg_rate > 0.01:
+        trend_list.append('상승')
+    elif avg_rate < -0.01:
+        trend_list.append('하락')
+    else:
+        trend_list.append('미미')
+
+# 4️⃣ 컬럼 추가
+festival_df['축제인기도'] = trend_list
+
+# ✅ 결과 확인
+print(festival_df[['축제명', '축제인기도']])
+
+festival_df
+
+# CSV로 저장
+festival_df.to_csv('festival_df_edit.csv', index=False, encoding='utf-8-sig')
+

기타/festival_df_second.py

@@ -0,0 +1,78 @@
+import pandas as pd
+import re
+
+# --- 1. 데이터 불러오기 ---
+# 3개의 통합 CSV 파일 경로를 지정합니다.
+path_indicators = 'C:/projects/shcard_2025_bigcontest/data/통합_문화관광축제_주요_지표.csv'
+path_demographics = 'C:/projects/shcard_2025_bigcontest/data/통합_성_연령별_내국인_방문자.csv'
+path_trend = 'C:/projects/shcard_2025_bigcontest/data/통합_연도별_방문자_추이.csv'
+
+df_indicators = pd.read_csv(path_indicators)
+df_demographics = pd.read_csv(path_demographics)
+df_trend = pd.read_csv(path_trend)
+print("✅ 3개의 통합 파일을 성공적으로 불러왔습니다.\n")
+
+
+# --- 2. 연도별 데이터를 Wide 형식으로 변환하는 함수 ---
+def pivot_by_year(df, index_col, year_col, drop_cols=None):
+    """연도별 데이터를 (년도)_(컬럼명) 형태로 변환하는 함수"""
+    if drop_cols:
+        df = df.drop(columns=drop_cols)
+    
+    df_wide = df.pivot_table(index=index_col, columns=year_col)
+    
+    # 멀티레벨 컬럼을 (년도)_(컬럼명) 형식으로 합치기
+    df_wide.columns = [f"{int(col[1])}_{col[0]}" for col in df_wide.columns]
+    return df_wide.reset_index()
+
+
+# --- 3. 각 데이터 정제 및 변환 ---
+
+# 3-1. '연도별 방문자 추이' 데이터 변환
+# 불필요하거나 중복될 수 있는 컬럼은 미리 제거
+trend_drop_cols = ['일평균 방문자수 증감률', '(이전)전체방문자', '(전체)방문자증감', '전년대비방문자증감비율']
+df_trend_wide = pivot_by_year(df_trend, '축제명', '개최년도', drop_cols=trend_drop_cols)
+print("✅ '연도별 방문자 추이' 데이터를 Wide 형태로 변환했습니다.")
+
+# 3-2. '주요 지표' 데이터 변환
+# '그룹명'과 '구분명'을 합쳐 새로운 컬럼 생성
+df_indicators['지표구분'] = df_indicators['그룹명'] + '_' + df_indicators['구분명']
+df_indicators_intermediate = df_indicators.pivot_table(
+    index=['축제명', '개최년도'], 
+    columns='지표구분', 
+    values='지표값'
+).reset_index()
+df_indicators_wide = pivot_by_year(df_indicators_intermediate, '축제명', '개최년도')
+print("✅ '주요 지표' 데이터를 Wide 형태로 변환했습니다.")
+
+# 3-3. '성_연령별 방문자' 데이터 변환 (이 데이터는 연도 정보가 없으므로 이전과 동일)
+df_demographics_wide = df_demographics.pivot_table(
+    index='축제명', 
+    columns='연령대', 
+    values=['남성비율', '여성비율']
+).reset_index()
+# 컬럼명 정리
+df_demographics_wide.columns = [f'{col[0]}_{col[1]}' if col[1] else col[0] for col in df_demographics_wide.columns]
+df_demographics_wide.columns = [re.sub(r'[^A-Za-z0-9_가-힣]', '', col) for col in df_demographics_wide.columns]
+print("✅ '성_연령별 방문자' 데이터를 Wide 형태로 변환했습니다.\n")
+
+
+# --- 4. 모든 Wide 데이터 병합 (Merging) ---
+# '성_연령별' 데이터를 기준으로 '연도별 추이'와 '주요 지표'를 합칩니다.
+# how='outer'는 한쪽에만 있는 축제 정보도 누락시키지 않기 위함입니다.
+final_df = pd.merge(df_demographics_wide, df_trend_wide, on='축제명', how='outer')
+final_df = pd.merge(final_df, df_indicators_wide, on='축제명', how='outer')
+print("✅ 모든 데이터를 하나의 DataFrame으로 최종 병합했습니다.")
+
+
+# --- 5. 결과 확인 및 저장 ---
+print("\n🎉 최종 통합 데이터(Wide) 샘플")
+# 축제명과 연도 관련 컬럼 일부만 샘플로 출력
+sample_cols = [col for col in final_df.columns if '2023' in col or '축제명' in col or '남성' in col]
+print(final_df[sample_cols].head())
+
+print(f"\n- 최종 데이터는 총 {len(final_df.columns)}개의 컬럼과 {len(final_df)}개의 행으로 구성됩니다.")
+
+# 최종 데이터를 새로운 CSV 파일로 저장
+final_df.to_csv('C:/projects/shcard_2025_bigcontest/data/festival_df.csv', index=False, encoding='utf-8-sig')
+print("\n💾 'festival_df.csv' 파일이 성공적으로 저장되었습니다.")