feat: 프로젝트 초기 구성 및 GraphRAG 테스트 파이프라인 연동

.env.example

@@ -0,0 +1,8 @@
+OPENAI_API_KEY=
+
+NEO4J_URI=
+NEO4J_USERNAME=
+NEO4J_CLIENT_ID=
+NEO4J_CLIENT_SECRET=
+# Hugging Face Spaces Deployment Settings
+HF_REPO=

.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: 소스코드 체크아웃
+        uses: actions/checkout@v4
+
+      - name: Python 3.10 환경 구성
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+          cache: "pip" # 의존성 설치 속도 가속
+
+      - name: 의존성 및 개발 도구 설치
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+          pip install ruff mypy pytest pytest-cov
+
+      - name: 코드 스타일 및 린트 검사 (Ruff)
+        run: ruff check .
+
+      - name: 정적 타입 검사 (MyPy)
+        run: mypy src/ --ignore-missing-imports
+
+      - name: 테스트 실행 (통합 테스트 자동 Skip 포함)
+        run: pytest tests/ -v
+
+      - name: 테스트 커버리지 리포트 생성
+        run: pytest --cov=src --cov-fail-under=20
+
+      - name: 미사용 코드 검사 (Vulture)
+        run: |
+          pip install vulture
+          vulture src/ --min-confidence 80

.github/workflows/deploy.yml

@@ -0,0 +1,29 @@
+name: Sync to Hugging Face Spaces
+
+on:
+  push:
+    branches: [main]
+  # 수동 실행 허용
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Source Code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          lfs: true
+
+      - name: Push and Sync to Hugging Face
+        env:
+          # GitHub Repository Secrets에 저장된 변수들을 환경변수로 로드합니다.
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+          HF_REPO: ${{ secrets.HF_REPO }}
+        run: |
+          # 1. Hugging Face Spaces 저장소를 동적 환경변수 기반 원격 추가
+          git remote add hf https://huggingface.co/spaces/$HF_REPO || true
+          
+          # 2. 강제 동기화 푸시 (인증 패스워드 자리에 HF_TOKEN 주입)
+          git push --force https://user:$HF_TOKEN@huggingface.co/spaces/$HF_REPO main

.gitignore

@@ -0,0 +1,79 @@
+# ──────────────────────────────────────────
+# 환경변수 / 시크릿
+# ──────────────────────────────────────────
+.env
+.env.*
+!.env.example
+
+# ──────────────────────────────────────────
+# Python 가상환경
+# ──────────────────────────────────────────
+.venv/
+venv/
+env/
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.egg-info/
+dist/
+build/
+
+# ──────────────────────────────────────────
+# Jupyter Notebook 체크포인트
+# ──────────────────────────────────────────
+.ipynb_checkpoints/
+*/.ipynb_checkpoints/
+
+# ──────────────────────────────────────────
+# 수집 결과 데이터 (엑셀, CSV)
+# 크롤링 결과는 git으로 관리하지 않음
+# ──────────────────────────────────────────
+Articles_*.xlsx
+Articles_*.csv
+*.xlsx
+*.csv
+
+# ──────────────────────────────────────────
+# macOS 시스템 파일
+# ──────────────────────────────────────────
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# ──────────────────────────────────────────
+# IDE / 에디터 설정
+# ──────────────────────────────────────────
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# ──────────────────────────────────────────
+# 로그 / 임시 파일
+# ──────────────────────────────────────────
+*.log
+*.tmp
+*.bak
+*.pyc
+
+# ──────────────────────────────────────────
+# 임시 패치 스크립트 (작업 후 삭제해야 할 파일들)
+# ──────────────────────────────────────────
+patch_*.py
+add_viz_cell.py
+create_fingraph.py
+rebuild_*.py
+sync_*.py
+modify_*.py
+force_write_*.py
+
+# ──────────────────────────────────────────
+# 참고 자료
+# ──────────────────────────────────────────
+references
+
+# ──────────────────────────────────────────
+# 로컬 그래프 백업 데이터 (보안/용량 사유로 제외)
+# ──────────────────────────────────────────
+graph_backup.json

.pre-commit-config.yaml

@@ -0,0 +1,13 @@
+repos:
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  # Ruff version.
+  rev: v0.15.13
+  hooks:
+    # Run the linter.
+    - id: ruff-check
+    # Run the formatter.
+    - id: ruff-format
+-   repo: https://github.com/pre-commit/mirrors-mypy
+    rev: ''  # Use the sha / tag you want to point at
+    hooks:
+    -   id: mypy      # 타입 검사

AGENTS.md

@@ -0,0 +1,95 @@
+###### 참고: https://wikidocs.net/340866
+
+# AGENTS.md
+
+## 프로젝트 개요
+- 목적: 
+- 언어: Python 3.10
+- 기술스택: GraphRAG, LangChain, LangGraph, Neo4j, HugingFace, Gradio
+
+## 디렉토리 구조
+FinNode/
+├── app.py                  # Gradio + LangGraph 챗봇 (HF 배포 진입점)
+├── src/
+│   ├── references/         # 참고용 노트북 (수정 금지)
+│   ├── utils/              # 순수 함수만 (텍스트 전처리 등)
+│   ├── graphBuilder/
+│   │   ├── scrapping/      # 뉴스 크롤링
+│   │   │   ├── finScrapping.py
+│   │   │   └── Articles_*.xlsx
+│   │   └── neo4j/          # 그래프 적재
+│   │       └── finGraph.py
+│   └── retrieval/          # GraphRAG 검색
+│       └── finRetrieval.py
+├── Dockerfile
+├── requirements.txt
+├── .env.example
+├── AGENTS.md
+├── README.md
+└── .github/workflows/deploy.yml
+
+## 코드 규칙
+- 함수명: snake_case
+- 클래스명: PascalCase
+- 변수명: camelCase
+- 한 함수는 하나의 역할만 수행한다
+- 타입 힌트 필수
+
+## 절대 금지
+- 'src/references/' 파일 수정 금지(참고자료)
+
+## COMMIT 규칙
+- 커밋 메시지: 'feat:', 'fix:', 'refactor:' 접두사 사용
+- push 하나에 하나의 변경만
+- 테스트 없는 push는 올리지 않는다
+
+## 테스트
+- 테스트 파일 위치: 'tests/' 디렉토리
+- 실행 명령: 'pytest tests/'
+- 반드시 예시 입력으로 테스트한다
+
+### 테스트 케이스로 기대 동작 명시
+이 프로젝트는 기능의 안정성을 위해 아래의 두 가지 수준의 테스트 코드가 필수적으로 통과해야 합니다.
+
+#### 1. 단위 테스트 (Unit Test) - 예시: `chunk_text`
+외부 의존성(DB, API) 없이 텍스트 전처리 로직이 완벽히 작동하는지 검증합니다.
+
+```python
+# tests/test_chunk_text.py
+def test_chunk_text_empty_returns_empty_list():
+    assert chunk_text("") == []
+
+def test_chunk_text_short_text_returns_single_chunk():
+    result = chunk_text("짧은 텍스트", size=500, overlap=50)
+    assert len(result) == 1
+
+def test_chunk_text_long_text_splits_into_multiple_chunks():
+    result = chunk_text("가" * 1000, size=500, overlap=50)
+    assert len(result) >= 2
+```
+
+#### 2. 통합 및 RAG 시나리오 테스트 (Integration Test) - 예시: `GraphRAG`
+실제 뉴스 지식 그래프가 빌드된 후, 임의의 최신 데이터를 동적으로 탐색하여 포트폴리오 수준의 완성도 높은 답변을 도출하는지 검증합니다.
+
+```python
+# tests/test_retrieval.py
+def test_portfolio_showcase_aggregation_query():
+    """
+    [포트폴리오 핵심 골드 시나리오]
+    특정 기업 고정 없이, '금융AI' 분야의 적극적인 기업 TOP 3와 대표 서비스를 
+    그래프 탐색을 통해 완벽한 근거(출처)와 함께 응답하는지 검증합니다.
+    """
+    showcase_query = "최근 수집된 뉴스에서 금융AI(AIField) 분야에 가장 적극적으로 기술을 개발하고 있는 기업 TOP 3와 그 기업들이 개발한 대표 서비스를 알려줘."
+    response = graphrag.search(query_text=showcase_query)
+    
+    assert response is not None
+    assert len(response.answer.strip()) > 0
+    # 출처 표기 및 랭킹 구조화 지침 준수 여부 검증
+    assert any(indicator in response.answer for indicator in ["1.", "TOP", "기사", "출처"]) # 일종의 skill
+```
+
+## 자동 검사
+- 커밋 전 `pre-commit` 자동 실행
+- `ruff`, `mypy` 검사 통과 필수
+- 검사 실패 시 커밋 불가
+

Dockerfile

@@ -0,0 +1,39 @@
+# Base image with Python 3.10
+FROM python:3.10-slim
+
+# Install system dependencies including Chrome (Chromium) and ChromeDriver for Selenium
+RUN apt-get update && apt-get install -y \
+    wget \
+    gnupg \
+    unzip \
+    curl \
+    chromium \
+    chromium-driver \
+    && rm -rf /var/lib/apt/lists/*
+
+# Set working directory inside container
+WORKDIR /app
+
+# Create a non-root user (UID 1000) for Hugging Face Spaces compatibility
+RUN useradd -m -u 1000 user
+RUN chown user:user /app
+USER user
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH \
+    CHROME_BIN=/usr/bin/chromium \
+    CHROMEDRIVER_PATH=/usr/bin/chromedriver \
+    PYTHONPATH=/app
+
+# Copy requirements and install python dependencies
+COPY --chown=user web_app/requirements.txt /app/requirements.txt
+RUN pip install --no-cache-dir --upgrade -r /app/requirements.txt
+
+# Copy all essential packages into container working directory
+COPY --chown=user pipeline /app/pipeline
+COPY --chown=user web_app /app/web_app
+
+# Expose standard Hugging Face Space port
+EXPOSE 7860
+
+# Run Streamlit on port 7860 and address 0.0.0.0 (app.py is inside web_app/)
+CMD ["streamlit", "run", "web_app/app.py", "--server.port", "7860", "--server.address", "0.0.0.0"]

README.md

@@ -0,0 +1,124 @@
+# FinNode 🕸️
+
+**Neo4j GraphRAG 기반 AI 뉴스 지식 그래프 플랫폼**
+
+[![Python](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://www.python.org/)
+[![Neo4j](https://img.shields.io/badge/Neo4j-AuraDB-blue.svg)](https://neo4j.com/)
+[![LangGraph](https://img.shields.io/badge/LangGraph-Pipeline-orange.svg)](https://langchain.com/)
+[![Gradio](https://img.shields.io/badge/Gradio-UI-red.svg)](https://gradio.app/)
+[![CI](https://github.com/yuje/FinGraph/actions/workflows/ci.yml/badge.svg)](https://github.com/yuje/FinGraph/actions/workflows/ci.yml)
+
+---
+
+## 📝 보고서
+> [최종 기획안 및 프로젝트 보고서 (업데이트 예정)]()
+
+## 🎥 시연 영상
+> [서비스 시연 영상 링크 (업데이트 예정)]()
+
+---
+
+## 1. 프로젝트 배경 및 목적
+최신 AI 기술과 핀테크 트렌드는 빠르게 변화하며, 일반적인 RAG(검색 증강 생성) 기술만으로는 여러 뉴스 기사에 흩어져 있는 **'기업-기술-서비스' 간의 복잡한 관계**를 파악하기 어렵습니다. 
+
+**FinNode**는 네이버 뉴스에서 AI 관련 기사를 실시간으로 수집하고, **LangGraph 파이프라인**을 통해 엔티티와 관계를 자동 추출하여 **Neo4j 지식 그래프**에 적재합니다. 이를 기반으로 Vector 및 Cypher 복합 검색(GraphRAG)을 수행하여, 단순한 문서 검색을 넘어 **"현재 금융AI 분야에서 가장 적극적인 기업과 기술 트렌드"**를 완벽한 근거와 함께 추론하고 답변하는 차세대 챗봇 시스템입니다.
+
+---
+
+## 2. 시스템 아키텍처
+
+```text
+[Naver News] 
+     │ Selenium 크롤링
+     ▼
+[LangGraph Pipeline] (gpt-4o-mini)
+  check_ai ──(AI 아님)──▶ 스킵
+     │ (AI 관련)
+     ▼
+  extract_entities
+     │
+     ▼
+  extract_relations
+     │
+     ▼
+[Neo4j AuraDB]
+  Article / Content / AICompany / AITechnology / AIService / AIField / Media
+     │
+     ▼
+[GraphRAG ToolsRetriever] ──▶ gpt-4o 최종 답변 생성
+     │
+     ▼
+[Gradio 챗봇 UI (Hugging Face Spaces 배포)]
+```
+
+---
+
+## 3. 주요 기능
+
+- **실시간 뉴스 크롤링**: Selenium 헤드리스 브라우저로 네이버 뉴스 카테고리별 기사 자동 수집
+- **LangGraph AI 파이프라인**: 수집된 기사를 3단계 자동 분석 (`판별` → `엔티티 추출` → `관계 추출`)
+- **Neo4j 지식 그래프 적재**: 추출된 엔티티(Company, Tech, Service 등)와 관계를 MERGE 트랜잭션으로 중복 없이 DB 적재
+- **GraphRAG 챗봇**: 3가지 Retriever를 통합한 ToolsRetriever 기반 자연어 질의응답
+  - `Vector Retriever`: 본문 청크 의미 유사도 검색
+  - `VectorCypher Retriever`: 벡터 검색 후 해당 기사의 연관 그래프(기업·기술·서비스) 반환 (트렌드 분석에 최적화)
+  - `Text2Cypher Retriever`: 자연어 → Cypher 쿼리 자동 변환 및 데이터 집계
+
+---
+
+## 4. 기술 스택
+
+- **Language**: Python 3.10
+- **AI / LLM**: LangChain, LangGraph, OpenAI (`gpt-4o`, `text-embedding-3-small`)
+- **Database**: Neo4j (AuraDB Cloud)
+- **Web / Crawling**: Gradio, Selenium, Pandas
+- **CI/CD**: GitHub Actions, Hugging Face Spaces
+
+---
+
+## 5. 그래프 스키마
+
+### 노드 및 관계
+| 구분 | 내용 |
+|------|-----------|
+| **노드 (Nodes)** | `Article`, `Content`, `AICompany`, `AITechnology`, `AIService`, `AIField`, `Media`, `Category` |
+| **관계 (Edges)** | `HAS_CHUNK`, `PUBLISHED`, `BELONGS_TO`, `MENTIONS`, `DEVELOPS`, `INVESTS_IN`, `PARTNERS_WITH`, `APPLIES`, `USED_IN`, `RELATED_TO` |
+
+---
+
+## 6. 설치 및 실행 가이드
+
+### 사전 준비
+- Python 3.10+
+- Neo4j AuraDB 인스턴스 (또는 로컬 Neo4j)
+- OpenAI API Key
+
+### 로컬 실행
+```bash
+# 1. 저장소 클론
+git clone https://github.com/yuje/FinGraph.git
+cd FinGraph
+
+# 2. 가상환경 생성 및 의존성 설치
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+
+# 3. 환경 변수 설정
+cp .env.example .env
+# .env 파일에 OpenAI Key, Neo4j 접속 정보 입력
+
+# 4. Gradio 앱 실행
+python app.py
+```
+브라우저에서 `http://localhost:7860` 접속
+
+---
+
+## 7. 배포 (Hugging Face Spaces)
+
+GitHub → Hugging Face Spaces 자동 배포가 `deploy.yml`을 통해 설정되어 있습니다.
+`main` 브랜치에 Push 시 자동으로 동기화됩니다.
+
+1. **Hugging Face 토큰 발급**: Settings → Tokens에서 Write 권한 토큰 생성
+2. **GitHub Secrets 등록**: `HF_TOKEN`, `HF_REPO` (예: yuje/FinNode) 등록
+3. **HF Space Secrets 등록**: `.env` 항목(OpenAI, Neo4j 키) 동일하게 등록

app.py

@@ -0,0 +1,146 @@
+"""
+app.py — FinNode GraphRAG 챗봇
+================================
+Hugging Face Spaces 배포 진입점.
+Gradio ChatInterface + LangGraph 기반 대화 흐름 제어.
+
+실행:
+    python app.py
+"""
+
+import os
+import dotenv
+import gradio as gr
+from typing import TypedDict, List
+from langgraph.graph import StateGraph, END
+from src.retrieval.finRetrieval import graphrag
+
+dotenv.load_dotenv()
+
+# ──────────────────────────────────────────
+# 1. LangGraph 챗봇 State 정의
+# ──────────────────────────────────────────
+
+class ChatState(TypedDict):
+    question: str        # 사용자 질문
+    history: List[dict]  # 대화 히스토리 [{"role": "user"/"assistant", "content": "..."}]
+    context: str         # GraphRAG 검색 결과
+    answer: str          # 최종 답변
+
+
+# ──────────────────────────────────────────
+# 2. LangGraph 노드 정의
+# ──────────────────────────────────────────
+
+def retrieve_node(state: ChatState) -> ChatState:
+    """Node 1: GraphRAG로 관련 컨텍스트 검색"""
+    try:
+        result = graphrag.search(query_text=state["question"])
+        context = result.answer  # GraphRAG가 이미 답변을 완성하므로 바로 사용
+    except Exception as e:
+        context = f"[검색 오류: {e}]"
+    return {**state, "context": context}
+
+
+def generate_node(state: ChatState) -> ChatState:
+    """Node 2: 대화 히스토리를 고려하여 최종 답변 생성
+    
+    GraphRAG가 이미 검색 + 생성을 처리하므로,
+    여기서는 히스토리 기반 후처리나 추가 포맷팅만 수행합니다.
+    """
+    # GraphRAG 결과를 바로 답변으로 사용
+    # (히스토리 기반 후속 질문 처리가 필요하면 이 노드를 확장하세요)
+    answer = state["context"] if state["context"] else "관련 정보를 찾을 수 없습니다."
+    return {**state, "answer": answer}
+
+
+# ──────────────────────────────────────────
+# 3. LangGraph 워크플로우 컴파일
+# ──────────────────────────────────────────
+
+builder = StateGraph(ChatState)
+builder.add_node("retrieve", retrieve_node)
+builder.add_node("generate", generate_node)
+builder.set_entry_point("retrieve")
+builder.add_edge("retrieve", "generate")
+builder.add_edge("generate", END)
+
+chat_graph = builder.compile()
+
+
+# ──────────────────────────────────────────
+# 4. Gradio 연동 함수
+# ──────────────────────────────────────────
+
+def chat(message: str, history: list) -> str:
+    """Gradio ChatInterface가 호출하는 함수.
+
+    Args:
+        message: 사용자 입력 메시지
+        history: Gradio가 관리하는 대화 히스토리
+                 [{"role": "user"/"assistant", "content": "..."}] 형식
+
+    Returns:
+        str: 챗봇 답변
+    """
+    if not message.strip():
+        return "질문을 입력해 주세요."
+
+    # Gradio history → LangGraph state 형식으로 변환
+    state: ChatState = {
+        "question": message,
+        "history": history,
+        "context": "",
+        "answer": "",
+    }
+
+    result = chat_graph.invoke(state)
+    return result["answer"]
+
+
+# ──────────────────────────────────────────
+# 5. Gradio UI 구성
+# ──────────────────────────────────────────
+
+with gr.Blocks(
+    title="FinNode — AI 기업 트렌드 분석 챗봇",
+    theme=gr.themes.Soft(primary_hue="indigo"),
+) as demo:
+    gr.Markdown(
+        """
+        # 🔗 FinNode — AI 기업 트렌드 분석 챗봇
+        > 최신 AI 뉴스를 기반으로 구축된 지식 그래프(GraphRAG)에서 답변합니다.
+
+        **예시 질문**
+        - 삼성전자의 최근 AI 기술 트렌드는?
+        - 카카오가 개발 중인 AI 서비스 목록을 알려줘
+        - 어떤 기업이 LLM 기술을 개발하나요?
+        - 최근 AI 관련 뉴스 기사를 요약해줘
+        """
+    )
+
+    chatbot = gr.ChatInterface(
+        fn=chat,
+        type="messages",          # Gradio 4.x 이상 표준 형식
+        chatbot=gr.Chatbot(
+            height=500,
+            placeholder="질문을 입력하면 지식 그래프에서 답변을 찾아드립니다.",
+        ),
+        textbox=gr.Textbox(
+            placeholder="예: 네이버의 AI 기술 트렌드는 무엇인가요?",
+            container=False,
+            scale=7,
+        ),
+        examples=[
+            "삼성전자의 최근 AI 기술 트렌드는?",
+            "카카오가 개발 중인 AI 서비스 목록을 알려줘",
+            "어떤 기업이 LLM 기술을 개발하나요?",
+            "최근 AI 관련 뉴스 기사를 요약해줘",
+        ],
+        retry_btn=None,
+        undo_btn="↩️ 되돌리기",
+        clear_btn="🗑️ 대화 초기화",
+    )
+
+if __name__ == "__main__":
+    demo.launch()

pyproject.toml

@@ -0,0 +1,24 @@
+# pyproject.toml
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle 기본 규칙
+    "F",   # pyflakes (미사용 변수 등)
+    "I",   # isort (import 정렬)
+    "N",   # 네이밍 규칙
+]
+ignore = []
+
+# 절대 import만 허용 (상대 import 금지)
+[tool.ruff.lint.flake8-tidy-imports]
+ban-relative-imports = "all"
+
+# vulture로 사용하지 않는 코드 확인
+[tool.vulture]
+min_confidence = 80
+paths = ["src/"]
+ignore_names = ["test_*", "setUp", "tearDown"]

requirements.txt

@@ -0,0 +1,16 @@
+# GraphRAG 핵심
+neo4j-graphrag[openai]
+langchain-openai
+langgraph
+
+# Gradio UI (HF Spaces 배포)
+gradio>=4.0.0
+
+# 데이터 크롤링 및 처리
+selenium
+webdriver-manager
+pandas
+openpyxl
+
+# 환경변수 관리
+python-dotenv

run_pipeline.py

@@ -0,0 +1,61 @@
+import json
+from pipeline.workflow import pipeline
+from pipeline.db_writer import write_graph_to_neo4j, chunk_and_embed_article
+
+def run_test():
+    # 1. 모의 테스트용 뉴스 기사 데이터 준비
+    test_article = {
+        "article_id": "TEST_ART_999",
+        "title": "OpenAI, 차세대 인공지능 GPT-5 전격 공개 및 금융AI 적용 선언",
+        "content": (
+            "인공지능 대표 기업 OpenAI가 새로운 초지능 언어 모델인 GPT-5를 전격 발표했습니다. "
+            "이번 모델은 고도의 금융분야 추론 능력을 극대화하여 다양한 금융AI(Financial AI) 시스템에 즉각 적용(APPLIES)됩니다. "
+            "OpenAI는 이를 위해 글로벌 대형 금융사인 골드만삭스와 전략적 파트너십(PARTNERS_WITH)을 체결하고 상용 솔루션을 공동 공급하기로 합의했습니다."
+        ),
+        "url": "https://example.com/news/gpt5-finance",
+        "published_date": "2026-05-19 09:30",
+        "source": "테크파이낸셜"
+    }
+
+    print("==================================================")
+    print("🚀 [1/3] LangGraph AI 분석 엔진 가동 (nodes.py)")
+    print("==================================================")
+    
+    # 2. LangGraph 상태 초기화 및 파이프라인 구동
+    initial_state = {
+        "article_id": test_article["article_id"],
+        "title": test_article["title"],
+        "text": test_article["title"] + "\n" + test_article["content"],
+        "is_ai_related": False,
+        "entities": [],
+        "relations": []
+    }
+    
+    # 컴파일된 파이프라인 가동
+    output_state = pipeline.invoke(initial_state)
+    
+    print(f"👉 AI 뉴스 여부 판별: {output_state['is_ai_related']}")
+    print(f"👉 추출된 지식 엔티티 목록 (총 {len(output_state['entities'])}개):")
+    print(json.dumps(output_state['entities'], indent=2, ensure_ascii=False))
+    print(f"👉 추출된 엔티티 간 관계선 목록 (총 {len(output_state['relations'])}개):")
+    print(json.dumps(output_state['relations'], indent=2, ensure_ascii=False))
+    
+    # 3. 데이터베이스 적재 실행
+    if output_state['is_ai_related']:
+        print("\n==================================================")
+        print("💾 [2/3] Neo4j AuraDB 지식 그래프 노드 및 관계선 적재")
+        print("==================================================")
+        write_graph_to_neo4j(test_article, output_state['entities'], output_state['relations'])
+        print("✅ 지식 그래프 적재 완료 (MERGE 트랜잭션 성공)")
+        
+        print("\n==================================================")
+        print("🧠 [3/3] 본문 청킹 및 OpenAI text-embedding-3-small 벡터화")
+        print("==================================================")
+        chunk_and_embed_article(test_article)
+        print("✅ 벡터 적재 완료 (HAS_CHUNK 노드 매핑 성공)")
+        print("\n🎉 모든 파이프라인 단독 구동 테스트가 완벽히 성공했습니다!")
+    else:
+        print("\n⏭️ AI 관련 기사가 아니므로 그래프 상세 분석 및 벡터 적재를 건너뜁니다.")
+
+if __name__ == "__main__":
+    run_test()

src/graphBuilder/neo4j/finGraph.py

@@ -0,0 +1,279 @@
+"""
+finGraph.py — AI 뉴스 지식 그래프 빌더
+=====================================
+실행 순서:
+  1. finScrapping.py 실행 → Articles_*.xlsx 생성
+  2. 이 파일 실행 → Neo4j에 엔티티/관계/벡터 적재
+
+노드:   AICompany, AITechnology, AIService, AIField, Article, Content, Media
+관계:   DEVELOPS, INVESTS_IN, PARTNERS_WITH, APPLIES, USED_IN, RELATED_TO,
+        MENTIONS, HAS_CHUNK, PUBLISHED
+"""
+
+import os
+import glob
+import json
+import pandas as pd
+import neo4j
+import dotenv
+from typing import TypedDict, List, Dict
+from langchain_openai import ChatOpenAI
+from langgraph.graph import StateGraph, END
+from neo4j_graphrag.llm import OpenAILLM
+from neo4j_graphrag.embeddings.openai import OpenAIEmbeddings
+from neo4j_graphrag.indexes import create_vector_index
+
+dotenv.load_dotenv()
+
+URI      = os.getenv("NEO4J_URI", "neo4j://localhost:7687")
+AUTH     = (os.getenv("NEO4J_USERNAME", "neo4j"), os.getenv("NEO4J_PASSWORD", "password"))
+driver   = neo4j.GraphDatabase.driver(URI, auth=AUTH)
+
+chat_llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
+rag_llm  = OpenAILLM(model_name="gpt-4o", model_params={"temperature": 0})
+embedder = OpenAIEmbeddings(model="text-embedding-3-small")
+
+INDEX_NAME = "content_vector_index"
+
+# ──────────────────────────────────────────
+# 1. LangGraph 파이프라인 정의 (엔티티/관계 추출)
+# ──────────────────────────────────────────
+
+class ArticleState(TypedDict):
+    article_id: str
+    title: str
+    text: str
+    is_ai_related: bool
+    entities: List[Dict]
+    relations: List[Dict]
+
+
+def check_ai_relevance(state: ArticleState) -> ArticleState:
+    """Node 1: AI 관련 여부 판별"""
+    prompt = (
+        "다음 기사가 AI(인공지능) 기술·기업·서비스와 관련 있으면 yes, 아니면 no로만 답하세요.\n\n"
+        f"{state['text'][:400]}\n\n답변(yes/no):"
+    )
+    res = chat_llm.invoke(prompt)
+    return {**state, "is_ai_related": res.content.strip().lower().startswith("yes")}
+
+
+def extract_entities(state: ArticleState) -> ArticleState:
+    """Node 2: 엔티티 추출"""
+    prompt = f"""다음 AI 뉴스에서 엔티티를 추출하세요.
+엔티티 유형:
+- AICompany: 기업/기관 (예: 삼성전자, OpenAI)
+- AITechnology: AI 기술 (예: 대규모언어모델, 강화학습)
+- AIService: 서비스/제품 (예: ChatGPT, HyperCLOVA X)
+- AIField: 적용 분야 (예: 금융AI, AI 반도체)
+
+제목: {state['title']}
+본문: {state['text'][:900]}
+
+JSON으로만 응답:{{"entities":[{{"name":"...","type":"AICompany|AITechnology|AIService|AIField","description":"..."}}]}}"""
+    res = chat_llm.invoke(prompt)
+    try:
+        raw = res.content.strip()
+        if "```" in raw:
+            raw = raw.split("```")[1].lstrip("json")
+        entities = json.loads(raw).get("entities", [])
+    except Exception:
+        entities = []
+    return {**state, "entities": entities}
+
+
+def extract_relations(state: ArticleState) -> ArticleState:
+    """Node 3: 관계 추출"""
+    if not state["entities"]:
+        return {**state, "relations": []}
+    elist = "\n".join([f"- {e['name']} ({e['type']})" for e in state["entities"]])
+    prompt = (
+        f"엔티티 목록:\n{elist}\n\n"
+        "관계 유형: DEVELOPS, INVESTS_IN, PARTNERS_WITH, APPLIES, USED_IN, RELATED_TO\n"
+        f"본문: {state['text'][:700]}\n\n"
+        '공으로만:{"relations":[{"source":"...","relation":"...","target":"..."}]}'
+    )
+    res = chat_llm.invoke(prompt)
+    try:
+        raw = res.content.strip()
+        if "```" in raw:
+            raw = raw.split("```")[1].lstrip("json")
+        relations = json.loads(raw).get("relations", [])
+        names = {e["name"] for e in state["entities"]}
+        relations = [r for r in relations if r.get("source") in names and r.get("target") in names]
+    except Exception:
+        relations = []
+    return {**state, "relations": relations}
+
+
+def route_after_check(state: ArticleState) -> str:
+    return "extract_entities" if state["is_ai_related"] else END
+
+
+builder = StateGraph(ArticleState)
+builder.add_node("check_ai", check_ai_relevance)
+builder.add_node("extract_entities", extract_entities)
+builder.add_node("extract_relations", extract_relations)
+builder.set_entry_point("check_ai")
+builder.add_conditional_edges("check_ai", route_after_check)
+builder.add_edge("extract_entities", "extract_relations")
+builder.add_edge("extract_relations", END)
+pipeline = builder.compile()
+
+
+# ──────────────────────────────────────────
+# 2. Neo4j 스키마 초기화 및 적재 함수
+# ──────────────────────────────────────────
+
+ENTITY_TYPE_MAP = {
+    "AICompany": "AICompany",
+    "AITechnology": "AITechnology",
+    "AIService": "AIService",
+    "AIField": "AIField",
+}
+
+
+def setup_schema(tx) -> None:
+    constraints = [
+        "CREATE CONSTRAINT IF NOT EXISTS FOR (n:AICompany)    REQUIRE n.name IS UNIQUE",
+        "CREATE CONSTRAINT IF NOT EXISTS FOR (n:AITechnology)  REQUIRE n.name IS UNIQUE",
+        "CREATE CONSTRAINT IF NOT EXISTS FOR (n:AIService)     REQUIRE n.name IS UNIQUE",
+        "CREATE CONSTRAINT IF NOT EXISTS FOR (n:AIField)       REQUIRE n.name IS UNIQUE",
+        "CREATE CONSTRAINT IF NOT EXISTS FOR (n:Article)       REQUIRE n.article_id IS UNIQUE",
+        "CREATE CONSTRAINT IF NOT EXISTS FOR (n:Content)       REQUIRE n.content_id IS UNIQUE",
+        "CREATE CONSTRAINT IF NOT EXISTS FOR (n:Media)         REQUIRE n.name IS UNIQUE",
+    ]
+    for c in constraints:
+        try:
+            tx.run(c)
+        except Exception:
+            pass
+
+
+def upsert_entity(tx, e: Dict) -> None:
+    ntype = ENTITY_TYPE_MAP.get(e.get("type", "AICompany"), "AICompany")
+    tx.run(
+        f"MERGE (n:{ntype} {{name:$name}}) "
+        "ON CREATE SET n.description=$desc "
+        "ON MATCH  SET n.description=COALESCE(n.description,$desc)",
+        name=e["name"], desc=e.get("description", ""),
+    )
+
+
+def upsert_relation(tx, r: Dict) -> None:
+    rel = r.get("relation", "RELATED_TO").upper().replace(" ", "_")
+    allowed = {"DEVELOPS", "INVESTS_IN", "PARTNERS_WITH", "APPLIES", "USED_IN", "RELATED_TO"}
+    if rel not in allowed:
+        return
+    try:
+        tx.run(
+            f"MATCH (s {{name:$src}}) MATCH (t {{name:$tgt}}) MERGE (s)-[:{rel}]->(t)",
+            src=r["source"], tgt=r["target"],
+        )
+    except Exception:
+        pass
+
+
+def upsert_article_and_mentions(tx, row: pd.Series, entities: List[Dict]) -> None:
+    tx.run(
+        "MERGE (a:Article {article_id:$aid}) "
+        "SET a.title=$title, a.url=$url, a.published_date=$date",
+        aid=row.get("article_id", ""), title=row.get("title", ""),
+        url=row.get("url", ""), date=str(row.get("published_date", "")),
+    )
+    if pd.notna(row.get("source", "")):
+        tx.run(
+            "MERGE (m:Media {name:$src}) "
+            "WITH m MATCH (a:Article {article_id:$aid}) MERGE (m)-[:PUBLISHED]->(a)",
+            src=row["source"], aid=row.get("article_id", ""),
+        )
+    for e in entities:
+        ntype = ENTITY_TYPE_MAP.get(e.get("type", "AICompany"), "AICompany")
+        try:
+            tx.run(
+                f"MATCH (a:Article {{article_id:$aid}}) "
+                f"MATCH (n:{ntype} {{name:$name}}) MERGE (a)-[:MENTIONS]->(n)",
+                aid=row.get("article_id", ""), name=e["name"],
+            )
+        except Exception:
+            pass
+
+
+def chunk_text(text: str, size: int = 500, overlap: int = 50) -> List[str]:
+    if not text or pd.isna(text):
+        return []
+    text = str(text)
+    return [
+        text[i:i + size].strip()
+        for i in range(0, len(text), size - overlap)
+        if text[i:i + size].strip()
+    ]
+
+
+# ──────────────────────────────────────────
+# 3. 메인 실행 (스크립트로 직접 호출 시)
+# ──────────────────────────────────────────
+
+def main() -> None:
+    # 최신 엑셀 로드
+    xlsx_files = sorted(glob.glob("Articles_*.xlsx"))
+    if not xlsx_files:
+        raise FileNotFoundError("Articles_*.xlsx 파일이 없습니다. finScrapping.py를 먼저 실행하세요.")
+    latest_file = xlsx_files[-1]
+    df = pd.read_excel(latest_file)
+    print(f"✅ 로드 완료: {latest_file} ({len(df)}건)")
+
+    # Neo4j 초기화
+    with driver.session() as s:
+        s.execute_write(lambda tx: tx.run("MATCH (n) DETACH DELETE n"))
+        s.execute_write(setup_schema)
+    print("✅ Neo4j 초기화 완료")
+
+    # 엔티티/관계 추출 및 적재
+    print(f"총 {len(df)}건 처리 시작...")
+    for idx, row in df.iterrows():
+        aid   = str(row.get("article_id", f"ART_{idx}"))
+        title = str(row.get("title", ""))
+        text  = title + "\n" + str(row.get("content", ""))
+        state: ArticleState = dict(
+            article_id=aid, title=title, text=text,
+            is_ai_related=False, entities=[], relations=[],
+        )
+        out = pipeline.invoke(state)
+        if out["is_ai_related"]:
+            with driver.session() as s:
+                for e in out["entities"]:
+                    s.execute_write(upsert_entity, e)
+                for r in out["relations"]:
+                    s.execute_write(upsert_relation, r)
+                s.execute_write(upsert_article_and_mentions, row, out["entities"])
+            print(f"  ✅ [{idx+1}/{len(df)}] {title[:35]}... | 엔티티: {[e['name'] for e in out['entities'][:4]]}")
+        else:
+            print(f"  ⏭️  [{idx+1}/{len(df)}] AI 비관련: {title[:35]}...")
+    print("\n✅ 엔티티/관계 추출 및 Neo4j 적재 완료")
+
+    # Content 청킹 + 임베딩
+    print("Content 노드 생성 및 임베딩 시작...")
+    for idx, row in df.iterrows():
+        aid    = str(row.get("article_id", f"ART_{idx}"))
+        chunks = chunk_text(str(row.get("content", "")))
+        with driver.session() as s:
+            for i, chunk in enumerate(chunks):
+                cid = f"{aid}_chunk_{i}"
+                vec = embedder.embed_query(chunk)
+                s.run(
+                    "MERGE (c:Content {content_id:$cid}) "
+                    "SET c.chunk=$chunk, c.article_id=$aid, c.chunk_index=$i, c.embedding=$vec "
+                    "WITH c MATCH (a:Article {article_id:$aid}) MERGE (a)-[:HAS_CHUNK]->(c)",
+                    cid=cid, chunk=chunk, aid=aid, i=i, vec=vec,
+                )
+    print("✅ Content 노드 임베딩 완료")
+
+    # 벡터 인덱스 생성
+    create_vector_index(driver, INDEX_NAME, label="Content",
+                        embedding_property="embedding", dimensions=1536, similarity_fn="cosine")
+    print(f"✅ 벡터 인덱스 [{INDEX_NAME}] 생성 완료")
+
+
+if __name__ == "__main__":
+    main()

src/graphBuilder/scrapping/finScrapping.py

@@ -0,0 +1,235 @@
+
+
+
+from selenium import webdriver
+from selenium.webdriver.common.by import By
+from webdriver_manager.chrome import ChromeDriverManager
+from selenium.webdriver.chrome.service import Service
+import pandas as pd
+import time
+from datetime import datetime
+import re
+from collections import Counter
+
+# 수집 대상 카테고리
+categories = {
+    '경제': 'https://news.naver.com/section/101',
+    'IT/과학': 'https://news.naver.com/section/105',
+}
+NUM_ARTICLES_PER_CATEGORY = 80
+
+# AI 핀테크 키워드 (FinNode 프로젝트 전용)
+FINTECH_AI_KEYWORDS = [
+    # AI 기술
+    'AI', '인공지능', '생성형 AI', '대규모언어모델',
+    # AI 핀테크 (금융)
+    '핀테크',
+]
+
+print('[INIT] ChromeDriver 초기화 중...')
+service = Service(ChromeDriverManager().install())
+options = webdriver.ChromeOptions()
+options.add_argument('--no-sandbox')
+options.add_argument('--disable-dev-shm-usage')
+driver = webdriver.Chrome(service=service, options=options)
+print('[INIT] ✅ 브라우저 실행 완료')
+
+def get_article_links(driver, category_url, num_articles):
+    print(f'  [LINK] 페이지 이동: {category_url}')
+    driver.get(category_url)
+    time.sleep(3)
+    print(f'  [LINK] 로드 완료 (title: {driver.title})')
+
+    article_links = []
+    selectors = [
+        'a.sa_text_title', 'a.sa_text_lede', 'a.sa_text_strong',
+        '.sa_text a', '.cluster_text_headline a', '.cluster_text_lede a'
+    ]
+
+    for selector in selectors:
+        elements = driver.find_elements(By.CSS_SELECTOR, selector)
+        print(f"  [LINK] 셀렉터 '{selector}' -> {len(elements)}개 발견")
+        for element in elements:
+            url = element.get_attribute('href')
+            if (url and 'news.naver.com' in url and '/article/' in url
+                    and '/comment/' not in url and url not in article_links):
+                article_links.append(url)
+                if len(article_links) >= num_articles:
+                    break
+        if len(article_links) >= num_articles:
+            break
+
+    print(f'  [LINK] ✅ 총 {len(article_links)}개 링크 확보\n')
+    return article_links[:num_articles]
+
+def parse_article_detail(driver, article_url, category):
+    driver.get(article_url)
+    time.sleep(1.5)
+    article_data = {
+        'article_id': '', 'title': '', 'content': '', 'url': article_url,
+        'published_date': '', 'source': '', 'author': '', 'category': category
+    }
+    try:
+        match = re.search(r'article/(\d+)/(\d+)', article_url)
+        article_data['article_id'] = (
+            f"ART_{match.group(1)}_{match.group(2)}" if match
+            else f"ART_{datetime.now().strftime('%Y%m%d%H%M%S')}"
+        )
+        for sel in ['#title_area span', '#ct .media_end_head_headline',
+                    '.media_end_head_headline', 'h2#title_area', '.news_end_title']:
+            try:
+                el = driver.find_element(By.CSS_SELECTOR, sel)
+                if el.text.strip():
+                    article_data['title'] = el.text.strip(); break
+            except: continue
+        for sel in ['#dic_area', 'article#dic_area',
+                    '.go_trans._article_content', '._article_body_contents']:
+            try:
+                el = driver.find_element(By.CSS_SELECTOR, sel)
+                if el.text.strip():
+                    article_data['content'] = el.text.strip(); break
+            except: continue
+        try:
+            el = driver.find_element(By.CSS_SELECTOR, 'a.media_end_head_top_logo img')
+            article_data['source'] = el.get_attribute('alt')
+        except:
+            try:
+                el = driver.find_element(By.CSS_SELECTOR, '.media_end_head_top_logo_text')
+                article_data['source'] = el.text.strip()
+            except: pass
+        try:
+            el = driver.find_element(By.CSS_SELECTOR,
+                'span.media_end_head_info_datestamp_time, span[data-date-time]')
+            article_data['published_date'] = (el.get_attribute('data-date-time') or el.text).strip()
+        except:
+            article_data['published_date'] = datetime.now().strftime('%Y-%m-%d %H:%M')
+        try:
+            el = driver.find_element(By.CSS_SELECTOR,
+                'em.media_end_head_journalist_name, span.byline_s')
+            article_data['author'] = el.text.strip()
+        except: pass
+    except Exception as e:
+        print(f'    [PARSE] ⚠️  파싱 오류: {e}')
+    return article_data
+
+# ── 1단계: 전체 기사 수집 ──
+all_articles = []
+category_stats = {}
+
+for category_name, category_url in categories.items():
+    print(f"\n{'='*60}")
+    print(f'[CRAWL] [{category_name}] 카테고리 수집 시작')
+    print(f"{'='*60}")
+
+    article_links = get_article_links(driver, category_url, NUM_ARTICLES_PER_CATEGORY)
+
+    cat_ok, cat_fail = 0, 0
+    for idx, article_url in enumerate(article_links, 1):
+        print(f'  [PARSE] ({idx}/{len(article_links)}) {article_url[:70]}...')
+        article_data = parse_article_detail(driver, article_url, category_name)
+
+        if article_data['title'] and article_data['content']:
+            all_articles.append(article_data)
+            cat_ok += 1
+            print(f"    ✅ {article_data['title'][:40]}...")
+            print(f"       언론사: {article_data['source']} | 날짜: {article_data['published_date']}")
+        else:
+            cat_fail += 1
+            missing = [x for x, v in [('제목', article_data['title']), ('본문', article_data['content'])] if not v]
+            print(f"    ❌ 파싱실패 ({', '.join(missing)} 없음)")
+        time.sleep(0.5)
+
+    category_stats[category_name] = {'ok': cat_ok, 'fail': cat_fail}
+    print(f"\n  [CRAWL] [{category_name}] 완료: 성공 {cat_ok}개 / 실패 {cat_fail}개")
+
+driver.quit()
+print(f'\n[DONE] 브라우저 종료')
+print(f"\n{'='*60}")
+print(f'[SUMMARY] 수집 결과 요약')
+print(f"{'='*60}")
+for cat, s in category_stats.items():
+    print(f'  {cat}: 성공 {s["ok"]}건 / 실패 {s["fail"]}건')
+print(f'  전체 수집: {len(all_articles)}건')
+
+df_all = pd.DataFrame(all_articles)
+df_all
+
+
+
+
+# ── 2단계: AI 핀테크 키워드 필터링 ──
+print(f"\n{'='*60}")
+print('[FILTER] AI 핀테크 키워드 필터링 시작')
+print(f"{'='*60}")
+
+filtered_articles = []
+for _, row in df_all.iterrows():
+    text = f"{row['title']} {row['content']}"
+    matched = [kw for kw in FINTECH_AI_KEYWORDS if kw.replace(" ", "") in text.replace(" ", "")]
+    if matched:
+        row_dict = row.to_dict()
+        row_dict['matched_keywords'] = ', '.join(matched)
+        filtered_articles.append(row_dict)
+
+df_filtered = pd.DataFrame(filtered_articles)
+
+print(f'  전체 수집: {len(df_all)}건')
+print(f'  AI 핀테크 관련: {len(df_filtered)}건 ({len(df_filtered)/max(len(df_all),1)*100:.1f}%)')
+print(f'\n  [키워드별 매칭 현황]')
+all_kw = [kw for row in filtered_articles for kw in row['matched_keywords'].split(', ')]
+kw_counts = Counter(all_kw)
+for kw in FINTECH_AI_KEYWORDS:
+    print(f'    {kw}: {kw_counts.get(kw, 0)}건')
+
+df_filtered
+
+# ── 3단계: 저장 ──
+output_filename = f"Articles_{datetime.now().strftime('%Y%m%d_%H%M%S')}.xlsx"
+df_filtered.to_excel(output_filename, index=False, engine='openpyxl')
+print(f'[SAVE] ✅ 저장 완료: {output_filename}')
+print(f'[SAVE]    - AI 핀테크 기사: {len(df_filtered)}건')
+
+
+
+
+# ── 4단계: 키워드 빈도 시각화 ──
+import matplotlib.pyplot as plt
+import platform
+from collections import Counter
+
+# 폰트 깨짐 방지 (Mac 환경: AppleGothic)
+if platform.system() == 'Darwin':
+    plt.rc('font', family='AppleGothic')
+plt.rcParams['axes.unicode_minus'] = False
+
+if not filtered_articles:
+    print('시각화할 데이터가 없습니다.')
+else:
+    # 빈도수 계산
+    all_kw = [kw for row in filtered_articles for kw in row['matched_keywords'].split(', ')]
+    kw_counts = Counter(all_kw)
+    
+    # 📌 변경 포인트: FINTECH_AI_KEYWORDS 전체 목록을 순서대로 그래프에 강제 표시 (0건 포함)
+    keywords = FINTECH_AI_KEYWORDS
+    counts = [kw_counts.get(kw, 0) for kw in keywords]
+    
+    plt.figure(figsize=(12, 6))
+    
+    # 막대 그래프 생성
+    bars = plt.bar(keywords, counts, color='skyblue', edgecolor='white')
+    
+    # 막대 위에 숫자(빈도수) 표시
+    for bar in bars:
+        height = bar.get_height()
+        # 막대의 중앙(x), 막대의 높이(y) 위치에 텍스트를 배치
+        plt.text(bar.get_x() + bar.get_width() / 2.0, height, f'{height}', 
+                 ha='center', va='bottom', size=11, fontweight='bold', color='black')
+
+    plt.title('수집된 AI 핀테크 기사 키워드 출현 빈도 (전체)', fontsize=15, pad=15)
+    plt.xlabel('키워드', fontsize=12)
+    plt.ylabel('출현 횟수 (건)', fontsize=12)
+    plt.grid(axis='y', linestyle='--', alpha=0.7)
+    plt.xticks(rotation=45)
+    plt.tight_layout()
+    plt.show()
+

src/retrieval/finRetrieval.py

@@ -0,0 +1,179 @@
+"""
+finRetrieval.py — GraphRAG 검색 모듈
+=====================================
+app.py에서 import하여 Gradio 챗봇과 연동합니다.
+
+사용법:
+    from src.retrieval.finRetrieval import graphrag
+
+    response = graphrag.search(query_text="삼성전자 AI 서비스는?")
+    print(response.answer)
+"""
+
+import os
+import dotenv
+import neo4j
+from neo4j_graphrag.llm import OpenAILLM
+from neo4j_graphrag.embeddings.openai import OpenAIEmbeddings
+from neo4j_graphrag.retrievers import (
+    VectorRetriever,
+    VectorCypherRetriever,
+    Text2CypherRetriever,
+    ToolsRetriever,
+)
+from neo4j_graphrag.generation import RagTemplate, GraphRAG
+
+dotenv.load_dotenv()
+
+# ──────────────────────────────────────────
+# 1. DB / LLM / Embedder 초기화
+# ──────────────────────────────────────────
+
+URI      = os.getenv("NEO4J_URI", "neo4j://localhost:7687")
+AUTH     = (os.getenv("NEO4J_USERNAME", "neo4j"), os.getenv("NEO4J_PASSWORD", "password"))
+driver   = neo4j.GraphDatabase.driver(URI, auth=AUTH)
+
+rag_llm  = OpenAILLM(model_name="gpt-4o", model_params={"temperature": 0})
+embedder = OpenAIEmbeddings(model="text-embedding-3-small")
+
+INDEX_NAME = "content_vector_index"
+
+# ──────────────────────────────────────────
+# 2. Retriever 세 종류 초기화
+# ──────────────────────────────────────────
+
+# (1) 본문 청크 의미 유사도 검색
+vector_retriever = VectorRetriever(
+    driver=driver,
+    index_name=INDEX_NAME,
+    embedder=embedder,
+)
+
+# (2) 벡터 검색 후 그래프 탐색 (기업·기술·서비스 함께 반환)
+_retrieval_query = """
+MATCH (content:Content)<-[:HAS_CHUNK]-(article:Article)
+OPTIONAL MATCH (article)-[:MENTIONS]->(company:AICompany)
+OPTIONAL MATCH (company)-[:DEVELOPS]->(tech:AITechnology)
+OPTIONAL MATCH (company)-[:DEVELOPS]->(svc:AIService)
+OPTIONAL MATCH (article)-[:MENTIONS]->(field:AIField)
+RETURN
+    content.chunk          AS chunk,
+    article.title          AS article_title,
+    article.url            AS article_url,
+    article.published_date AS article_date,
+    collect(DISTINCT company.name) AS companies,
+    collect(DISTINCT tech.name)    AS technologies,
+    collect(DISTINCT svc.name)     AS services,
+    collect(DISTINCT field.name)   AS fields
+ORDER BY article.published_date DESC
+LIMIT 3
+"""
+
+vector_cypher_retriever = VectorCypherRetriever(
+    driver=driver,
+    index_name=INDEX_NAME,
+    retrieval_query=_retrieval_query,
+    embedder=embedder,
+)
+
+# (3) 자연어 → Cypher 자동 변환 검색
+def _get_schema() -> str:
+    with driver.session() as s:
+        nodes = s.run(
+            "CALL db.schema.nodeTypeProperties() "
+            "YIELD nodeType, propertyName "
+            "RETURN nodeType, collect(propertyName) as props"
+        ).data()
+        rels = s.run(
+            "MATCH (n)-[r]->(m) "
+            "RETURN DISTINCT labels(n)[0] as src, type(r) as rel, labels(m)[0] as tgt "
+            "LIMIT 30"
+        ).data()
+    txt = "=== Neo4j Schema ===\n노드:\n"
+    for n in nodes:
+        txt += f"- {n['nodeType']}: {n['props']}\n"
+    txt += "\n관계:\n"
+    for r in rels:
+        txt += f"- ({r['src']})-[:{r['rel']}]->({r['tgt']})\n"
+    return txt
+
+
+_examples = [
+    """USER INPUT: 카카오의 AI 서비스 목록을 알려주세요
+CYPHER QUERY:
+MATCH (c:AICompany {name:"카카오"})-[:DEVELOPS]->(s:AIService)
+RETURN s.name, s.description""",
+
+    """USER INPUT: 삼성전자가 개발 중인 AI 기술은?
+CYPHER QUERY:
+MATCH (c:AICompany {name:"삼성전자"})-[:DEVELOPS]->(t:AITechnology)
+RETURN t.name, t.description""",
+
+    """USER INPUT: 최근 AI 관련 기사 5개
+CYPHER QUERY:
+MATCH (a:Article)-[:MENTIONS]->(:AICompany)
+RETURN DISTINCT a.article_id, a.title, a.url, a.published_date
+ORDER BY a.published_date DESC LIMIT 5""",
+
+    """USER INPUT: 어떤 기업이 LLM 기술을 개발하나요?
+CYPHER QUERY:
+MATCH (c:AICompany)-[:DEVELOPS]->(t:AITechnology)
+WHERE t.name CONTAINS "언어모델" OR t.name CONTAINS "LLM"
+RETURN c.name, t.name""",
+]
+
+text2cypher_retriever = Text2CypherRetriever(
+    driver=driver,
+    llm=rag_llm,
+    neo4j_schema=_get_schema(),
+    examples=_examples,
+)
+
+# ──────────────────────────────────────────
+# 3. ToolsRetriever + GraphRAG 조립
+# ──────────────────────────────────────────
+
+tools_retriever = ToolsRetriever(
+    driver=driver,
+    llm=rag_llm,
+    tools=[
+        vector_retriever.convert_to_tool(
+            name="vector_retriever",
+            description="뉴스 본문의 의미(내용) 유사도 기반 검색. AI 기술·서비스 관련 텍스트를 찾을 때 사용.",
+        ),
+        vector_cypher_retriever.convert_to_tool(
+            name="vectorcypher_retriever",
+            description="벡터 검색 후 해당 기사에서 언급된 기업·기술·서비스 그래프를 함께 반환. 기업 AI 트렌드 분석에 최적.",
+        ),
+        text2cypher_retriever.convert_to_tool(
+            name="text2cypher_retriever",
+            description="자연어를 Cypher로 변환. 특정 기업 서비스 목록, 기술 보유 기업 등 구조적 질의에 사용.",
+        ),
+    ],
+)
+
+_prompt_template = RagTemplate(
+    template="""당신은 AI 기술 트렌드 분석 전문가입니다.
+취업 준비생이 기업 지원 동기를 작성할 수 있도록 해당 기업의 AI 서비스·기술 트렌드를 명확하게 설명해 주세요.
+
+질문: {query_text}
+
+검색된 정보:
+{context}
+
+답변 지침:
+1. 기업이 개발 중인 AI 기술과 서비스를 구체적으로 명시하세요.
+2. 뉴스 기사 제목과 URL을 근거로 포함하세요.
+3. 지원자가 어떤 서비스에 어떻게 기여할 수 있는지 시사점을 1~2줄 추가하세요.
+4. 검색 결과에 없는 내용은 추측하지 마세요.
+
+답변:""",
+    expected_inputs=["context", "query_text"],
+)
+
+# app.py에서 이 객체를 직접 import하여 사용합니다.
+graphrag = GraphRAG(
+    llm=rag_llm,
+    retriever=tools_retriever,
+    prompt_template=_prompt_template,
+)

tests/test_chunk_text.py

@@ -0,0 +1,15 @@
+from src.graphBuilder.neo4j.finGraph import chunk_text
+
+def test_chunk_text_empty_returns_empty_list():
+    assert chunk_text("") == []
+
+def test_chunk_text_none_returns_empty_list():
+    assert chunk_text(None) == []
+
+def test_chunk_text_short_text_returns_single_chunk():
+    result = chunk_text("짧은 텍스트", size=500, overlap=50)
+    assert len(result) == 1
+
+def test_chunk_text_long_text_splits_into_multiple_chunks():
+    result = chunk_text("가" * 1000, size=500, overlap=50)
+    assert len(result) >= 2

tests/test_retrieval.py

@@ -0,0 +1,40 @@
+import os
+import pytest
+from src.retrieval.finRetrieval import graphrag
+
+# API 키와 Neo4j 연결정보가 없을 경우 테스트를 건너뜁니다.
+has_credentials = (
+    os.getenv("OPENAI_API_KEY") is not None and 
+    os.getenv("NEO4J_URI") is not None
+)
+
+@pytest.mark.skipif(
+    not has_credentials, 
+    reason="OpenAI API Key 또는 Neo4j 연결 환경변수가 없으므로 통합 테스트를 건너뜁니다."
+)
+def test_portfolio_showcase_aggregation_query():
+    """
+    [포트폴리오 핵심 시나리오]
+    특정 기업을 지정하지 않고, 금융AI 분야의 최신 트렌드 기업 TOP 3와 대표 서비스를 
+    동적으로 그래프 탐색(GraphRAG)하여 올바른 형식으로 답변하는지 검증합니다.
+    """
+    showcase_query = (
+        "최근 수집된 뉴스에서 금융AI(AIField) 분야에 가장 적극적으로 기술을 개발하고 있는 "
+        "기업 TOP 3와 그 기업들이 개발한 대표 서비스를 알려줘."
+    )
+    
+    # GraphRAG 검색 및 생성 실행
+    response = graphrag.search(query_text=showcase_query)
+    
+    # 1. 응답 객체 및 속성 존재 여부 검증
+    assert response is not None
+    assert hasattr(response, "answer")
+    
+    # 2. 답변 텍스트 유효성 검증
+    answer = response.answer
+    assert len(answer.strip()) > 0
+    
+    # 3. 답변 형식 검증 (순위 구조나 출처 지침 준수 여부)
+    assert any(indicator in answer for indicator in ["1.", "첫째", "TOP", "기사", "출처"])
+    
+    print(f"\n✨ [포트폴리오 쇼케이스 RAG 결과]\n{answer}")