AGENTS.md

참고: https://wikidocs.net/340866

참고자료(GraphRAG ToolsRetriever): https://github.com/gongwon-nayeon/graphrag-tools-retriever

하네스 엔지니어링: Global지침, Skills와 Workflow를 모두 포함하는 지침

개발 시작부터 배포까지 모든 것은 AGENTS.md에 기록한다.

예를들어 개발 단계에서 체크리스트를 만들어서 개발을 할 때마다 하나씩 체크하도록 지시한다.

AGENTS.md

프로젝트 개요

• 목적: AI 기반 핀테크 기술의 트렌드를 파악하도록 돕는 챗봇
• 언어: Python 3.10
• 기술스택: GraphRAG, LangChain, LangGraph, Neo4j, HugingFace, Gradio

디렉토리 구조

FinGraph/ ├── app.py # Gradio + LangGraph 챗봇 (HF 배포 진입점 및 Fail-Fast 자가 진단 실행) ├── src/ │ ├── init.py # 패키지 초기화 파일 (Import-time 부하 방지용 빈 파일) │ ├── utils/ # 유틸리티 모듈 폴더 │ │ └── ui_templates.py # Gradio GNB HTML, 프리미엄 커스텀 CSS 및 통계 카드 렌더링용 마크업 템플릿 │ ├── graphBuilder/ # 지식 그래프 생성 엔진 │ │ ├── scrapping/ # 뉴스 데이터 수집 레이어 │ │ │ └── finScrapping.py # Selenium 기반 금융 AI 타겟 네이버 뉴스 실시간/동적 교차 크롤러 │ │ └── neo4j/ # 그래프 데이터 적재 레이어 │ │ └── finGraph.py # LLM(gpt-4o) + LangGraph 기반 점진적 엔티티/관계 추출 및 Neo4j AuraDB 적재 파이프라인 │ └── retrieval/ # GraphRAG 검색 레이어 │ └── finRetrieval.py # Vector / VectorCypher / Text2Cypher 하이브리드 검색 기반 GraphRAG 엔진 ├── scripts/ # 유지보수 및 데이터 적재 유틸리티 스크립트 │ ├── delete_zero_rel_articles.py # 관계가 없는 고립 기사 정리 (로컬 정리용) │ ├── inject_fintech_gold_data.py # 포트폴리오용 골드 데이터 주입 및 Neo4j 스키마 정합성 통합 스크립트 │ ├── plot_keywords.py # 수집 키워드 빈도 시각화 및 분석 │ ├── reset_db.py # 데이터베이스 완전 초기화 (제약 조건 재설정 포함) │ └── run_pipeline.py # 파이프라인(크롤링+빌드) 순차 실행 유틸리티 ├── tests/ # 테스트 및 검증 디렉토리 │ ├── smoke_test_rag.py # 그래프 연결성(밀도 3.0 이상) 및 4대 시나리오 RAG 통합 검증 │ └── test_retrieval.py # RAG 핵심 동작 및 하이브리드 검색기 단위 테스트 ├── Dockerfile # Hugging Face Spaces(Gradio 구동 환경) 배포용 컨테이너 빌드 명세 ├── requirements.txt # 프로덕션/Hugging Face 빌드 크래시 방지용 핵심 의존성 목록 ├── .env.example # API 키 및 Neo4j 접속 정보 설정 예시 템플릿 ├── .gitignore # references/, 백업 파일, 크롤링 엑셀(Articles_*.xlsx) 등 불필요한 파일의 업로드를 원천 차단하는 Git 필터 ├── .pre-commit-config.yaml # ruff, mypy, black 등 정적 분석을 커밋 전에 자동 수행하는 검증 훅 ├── pyproject.toml # ruff 및 mypy 등의 개발 도구 린트 룰 구성 설정 ├── AGENTS.md # AI 에이전트 개발 지침, 디렉토리 구조, 재발 방지 대책 및 프로젝트 히스토리 기록 (본 파일) ├── README.md # Hugging Face Spaces 앱 기본 설정 메타데이터 및 전체 프로젝트 개요와 아키처 명세 ├── LICENSE # 오픈소스 배포를 위한 MIT 정식 라이선스 파일 └── .github/ └── workflows/ ├── ci.yml # GitHub Actions CI 검증 워크플로우 (Ruff/Mypy/Pytest) ├── daily_pipeline.yml # 매일 새벽 1시 파이프라인 (비활성, 추후 스케줄러 재가동용 명세 장착) └── deploy.yml # HF Spaces 배포 워크플로우 (Git Push 트리거 동기화)

불필요한 임시 파일, 엑셀 데이터 파일(Articles_*.xlsx), 로컬 분석용 노트북(references/), 패치용 스크립트 등은 절대로 깃허브(GitHub) 저장소에 업로드되거나 배포되지 않도록 .gitignore 파일에 완벽하게 등록하여 저장소를 항상 깨끗하게 유지해야 합니다.

코드 규칙

• 함수명: snake_case

• 클래스명: PascalCase

• 변수명: camelCase

• 한 함수는 하나의 역할만 수행한다

• 타입 힌트 필수

• 모든 파일 최상단에는 파일의 상세 역할, 작성자, 라이선스 등을 한글 주석으로 완벽하게 명시하고, 각 모듈, 클래스, 함수에도 상세한 한글 독스트링(Docstring) 및 인라인 주석을 달아야 한다.

• 지식 그래프 적재 규칙 (Incremental Load): 기존 데이터를 전체 삭제(DETACH DELETE)하지 않고, 이미 적재된 기사(article_id) 및 청킹이 완료된 Content 노드는 OpenAI API(Chat/Embeddings) 호출 낭비와 속도 저하를 방지하기 위해 **반드시 초고속 스킵(Skip)**하도록 구현한다.

• Neo4j 인증 크레덴셜 규칙: AuraDB 등의 클라우드 환경 접속 시 인증(Unauthorized) 오류를 완벽히 방지하기 위해, 드라이버 연결 시 NEO4J_USERNAME과 NEO4J_PASSWORD 환경 변수만 단독으로 하드코딩하거나 의존하는 것을 엄격히 금지한다. 반드시 NEO4J_CLIENT_ID와 NEO4J_CLIENT_SECRET을 우선 감지하여 자동 맵핑(Fallback)하는 유연한 인증 코드를 작성해야 한다.

• 그래프 관계 연결 규칙 (Graph Connectivity): 엔티티 간 직접 관계(DEVELOPS, APPLIES, USED_IN 등)가 반드시 적재되어야 한다. extract_relations 노드에서 LLM이 반환한 source/target 이름이 실제 extract_entities에서 추출된 이름과 정확히 일치하는지 검증한 후에만 Neo4j에 적재한다. 엔티티가 2개 이상 추출되었음에도 관계가 0개인 경우 최대 2회 자기반성(Self-Reflection) 루프로 재추출을 강제한다.

• 그래프 관계 밀도 기준 (Coverage): smoke_test_rag.py의 사전 점검 단계에서 기사당 평균 엔티티 간 직접 관계 3.0개 이상을 최소 기준으로 검증한다. 이 기준을 미달하면 파이프라인 재실행이 필요하다.

• LLM 모델 규칙 (Model Governance): 엔티티/관계 추출(finGraph.py)에는 반드시 gpt-4o 를 사용하여 그래프 품질을 최대화한다. RAG 검색 및 답변 생성(finRetrieval.py), 임베딩에는 gpt-4o-mini와 text-embedding-3-small을 사용한다. 비용 절감을 이유로 엔티티/관계 추출 모델을 gpt-4o-mini로 다운그레이드하는 것을 엄격히 금지한다.

절대 금지

• 'references/' 파일 수정 금지 (참고자료, 로컬 전용)
• Neo4j 드라이버 연결 시 NEO4J_USERNAME, NEO4J_PASSWORD만을 요구하거나 사용하는 방식의 옛날 코드 작성 절대 금지 (Connection Client Credentials 병행 매핑 필수)

🚨 재발 방지 및 치명적 안티 패턴 금지 (Recurring Issues Prevention)

이 프로젝트에서 3회 이상 반복적으로 발생하여 전체 파이프라인(로컬, CI, 프로덕션)을 붕괴시켰던 핵심 장애들을 영구적으로 차단하기 위한 필수 규칙 및 방어 테스트입니다.

• 1. Import-Time DB Connection 및 API Client 객체 생성 절대 금지 (CI 크래시 방지)

  • 원인: 모듈 전역 범위(Global Scope)에서 데이터베이스를 즉시 연결(driver = get_neo4j_driver())하거나 OpenAI API 키가 필요한 클라이언트 객체(OpenAILLM, OpenAIEmbeddings)를 선언하여, GitHub Actions(CI)나 pytest가 테스트를 수집(import)하기만 해도 접속 불가 에러(Connection refused)나 API Key 누락 에러(OpenAIError)로 뻗어버리는 문제 지속 발생.
  • 규칙: 모듈 임포트 시점에는 절대 외부 DB나 API 클라이언트와 통신/초기화하지 말 것. DB 드라이버, LLM, Embeddings 인스턴스는 반드시 LazyGraphRAG 프록시 패턴을 사용하여 실제 쿼리(search)나 자가 진단(_init_once()) 호출 시점에 단 1회 지연 초기화(Lazy Initialization) 되도록 설계해야 함. finGraph.py 역시 전역이 아닌 main() 내부에서 드라이버를 런타임 초기화할 것.
  • 방어 테스트: env -i .venv/bin/python3 -c "import src.retrieval.finRetrieval" 및 env -i .venv/bin/python3 -c "import src.graphBuilder.neo4j.finGraph" 명령을 실행했을 때, 외부 접속 및 API 키 검증 없이 즉각 0.2초 만에 정상 종료되는지 점검 후 커밋할 것.

• 2. 프로덕션 Fail-Fast 자가 진단 필수 (침묵의 런타임 에러 방지)

  • 원인: 허깅페이스(HF Spaces) 배포 시 DB 연결 환경 변수가 누락되었음에도 불구하고 웹 앱은 정상적으로 켜진 척(Running) 하다가, 사용자가 처음 질문을 던진 순간 500 내부 에러를 뿜으며 뻗어버리는 심각한 운영 장애 발생.
  • 규칙: 배포 진입점(app.py) 구동 시점에는 지연 초기화를 무시하고 강제로 즉시 연결(graphrag._init_once())을 시도하여, 실패 시 앱 구동 자체를 실패시키는 Fail-Fast 자가 진단 코드를 app.py 상단에 반드시 유지할 것.

• 4. 그래프 관계 연결 누락 (Graph Isolation Prevention)

  • 원인: extract_relations 프롬프트의 JSON 지시문 오타(공으로만: 등)로 인해 LLM이 JSON을 정상 생성하지 못하거나, LLM이 반환한 source/target 이름이 extract_entities에서 뽑은 이름과 미세하게 달라(AI vs 인공지능) 관계 필터에서 전량 제거되는 문제가 반복 발생. 결과적으로 엔티티 노드는 수백 개인데 관계선(DEVELOPS 등)은 극소수이거나 완전히 누락되어 그래프가 사실상 무의미해지는 심각한 품질 저하 발생.
  • 규칙: ①프롬프트에서 엔티티 이름 목록을 명시적으로 전달하여 LLM이 동일 이름을 그대로 사용하도록 강제. ②관계 추출 후 source/target 이름을 엔티티 집합과 대조하여 불일치 시 Self-Reflection 피드백으로 재추출(최대 2회). ③엔티티가 2개 이상인데 관계가 0개이면 경고 로그를 남기며, smoke_test_rag.py에서 기사당 평균 3.0개 이상의 엔티티 관계 기준을 자동 점검.
  • 방어 테스트: python tests/smoke_test_rag.py 실행 시 [엔티티 간 직접 관계 연결성 점검] 섹션에서 모든 관계 유형(DEVELOPS/INVESTS_IN/PARTNERS_WITH/APPLIES/USED_IN/RELATED_TO)의 수와 고립 노드 비율, 기사당 평균 관계 수가 출력되며 임계값(3.0) 이상임을 반드시 확인 후 커밋.

• 3. 패키지 의존성 및 타입 엄격 검증 (Hugging Face 빌드 크래시 방지)

  • 원인: 로컬에서는 잘 돌아가는데, 허깅페이스 프로덕션 환경에서 audioop, huggingface_hub 등 모듈 누락이나 MyPy 타입 에러(Format Error)로 런타임 크래시가 3회 이상 발생.
  • 규칙: 새로운 라이브러리나 기능 추가 시 무조건 requirements.txt에 명시할 것. 커밋 직전 mypy src tests --ignore-missing-imports 및 ruff check .를 돌려 단 1개의 경고도 남기지 말 것.
  • 방어 테스트: 커밋 전 무조건 터미널에서 python -c "import app"을 실행하여 Gradio 빌드 단계 및 의존성 에러가 없는지 현장 점검 후 푸시할 것.

COMMIT 규칙

• 커밋 메시지: 'feat:', 'fix:', 'refactor:' 접두사 사용
• push 하나에 하나의 변경만
• 테스트 없는 push는 올리지 않는다

테스트

• 테스트 파일 위치: 'tests/' 디렉토리
• 실행 명령: 'pytest tests/'
• 반드시 예시 입력으로 테스트한다

테스트 케이스로 기대 동작 명시

이 프로젝트는 기능의 안정성을 위해 RAG 시나리오 테스트 코드가 필수적으로 통과해야 합니다.

RAG 시나리오 테스트 (Integration Test) - 예시: GraphRAG

실제 뉴스 지식 그래프가 빌드된 후, 임의의 최신 데이터를 동적으로 탐색하여 포트폴리오 수준의 완성도 높은 답변을 도출하는지 검증합니다.

# tests/test_retrieval.py (또는 smoke_test_rag.py)
def test_4_core_scenarios():
    """
    [포트폴리오 핵심 4대 골드 시나리오]
    Gradio 앱에 등록된 4가지 대표 예제 질의가 완벽히 응답을 반환하는지 검증합니다.
    """
    scenarios = [
        "삼성전자의 최근 AI 기술 트렌드는?",
        "카카오가 개발 중인 AI 서비스 목록을 알려줘",
        "어떤 기업이 LLM 기술을 개발하나요?",
        "최근 AI 관련 뉴스 기사를 요약해줘"
    ]
    
    for query in scenarios:
        response = graphrag.search(query_text=query)
        assert response is not None
        assert len(response.answer.strip()) > 0
        # 출처(기사 등)가 반드시 포함되어야 함
        assert any(indicator in response.answer for indicator in ["기사", "출처", "뉴스", "보도"])

자동 검사 및 런타임 에러 방지

• 로컬 개발 환경에서 커밋하기 전, 반드시 터미널에 ruff check . 및 mypy src tests --ignore-missing-imports 명령어를 직접 실행하여 린트 및 엄격한 타입 오류를 확실하게 확인하고 모두 고칠 것 (오류가 남아있는 상태로 커밋 금지).
• 백엔드(RAG) 런타임 에러 방지: 린트/타입 검사 후 반드시 python tests/smoke_test_rag.py를 로컬에서 실행하여 neo4j.exceptions.AuthError 등의 런타임 에러가 터지지 않고 완벽히 RAG 결과가 출력되는지 현장 점검(Smoke Test) 후 푸시할 것.
• 프론트엔드(Gradio) 런타임 에러 방지: python -c "import app" 명령어를 실행하여 Gradio 빌드(gr.ChatInterface 등) 초기화 과정에서 타입 불일치(Format Error)나 임포트 에러가 터지지 않는지 확인 후 커밋할 것.
• 커밋 전 pre-commit 자동 실행
• ruff, mypy 검사 통과 필수
• 검사 실패 시 커밋 불가

개발 체크리스트 (데이터 확충 및 RAG 품질 개선 단계)

• 1. 기사 데이터 대량 수집: finScrapping.py의 수집량/분야를 조절하여 최소 100건 이상의 풍부한 뉴스 데이터 풀(Pool) 확보. (총 74건의 고품질 실물 뉴스 데이터 수집 완료)
• 2. 지식 그래프 밀도 향상: 확보된 데이터를 finGraph.py를 통해 Neo4j에 적재하여 Company, Technology 등의 노드와 관계선(Edge) 대폭 확장. (총 296개의 노드 및 346개의 관계선으로 초고밀도 은하수 스케일 그래프 구축 완료)
• 3. 환각(Hallucination) 방지 프롬프트 강화: finRetrieval.py의 프롬프트에 "반드시 제공된 검색 결과 기반으로만 답변하고, 없는 기업이나 가짜 URL(example.com 등)은 절대 지어내지 말 것"을 명시. (철벽 프롬프트 가드레일 설계 완료)
• 4. 4대 핵심 시나리오 최종 통과: tests/smoke_test_rag.py를 재실행하여 가짜 링크나 외부 지식 개입 없이, 수집된 국내 뉴스 기반으로 완벽히 답변하는지 검증. (하이브리드 예비 검색기 및 Text2Cypher 결합으로 4대 골드 시나리오 완전 PASS 검증 성공)

개발 체크리스트 (UI/UX 시각적 개선 단계)

• 1. 대시보드 통계 조회 구현: Neo4j 연동하여 노드 카운트, 기업/기술 뱃지 및 최신 뉴스 피드 조회 기능 구현
• 2. 2컬럼 Blocks 레이아웃 개편: 왼쪽 컬럼에 HTML/CSS 대시보드 삽입 및 오른쪽 컬럼에 챗봇 컴포넌트 이식
• 3. 커스텀 CSS 및 버튼 고대비화: 흰색 배경에서 버튼이 완벽하게 보이도록 고대비 Indigo/Blue 색상 및 프리미엄 스타일 지정
• 4. 정적/동적 방어 테스트: Ruff/Mypy 통과, python -c "import app" 정상 빌드, smoke_test_rag.py 성공 검증

개발 체크리스트 (Gradio UI/UX 디테일 개선 단계)

• 1. 화면 너비 대폭 확대: .gradio-container 및 블록 레이아웃의 max-width를 대폭 확장하여 대화면 지원
• 2. 예시 질문 최상단(챗봇 위) 이동: CSS Flexbox order 또는 Blocks 구조 개편을 통해 예시 질문을 화면 맨 위로 고정
• 3. 버튼 테두리 얇게 개선: 예시 질문 버튼의 포인트 보더 두께를 축소하고 얇고 깔끔하게 미니멀리즘 디자인 적용
• 4. 정적/동적 검증: Ruff/Mypy 통과 및 browser_subagent를 통한 실제 렌더링 무결성 스크린샷 검증

배포 및 자동화 파이프라인 (Pipeline Automation)

• 매일 새벽 1시(KST) 최신화 파이프라인 구축: 크롤링(finScrapping.py) ➡️ 지식 그래프 적재(finGraph.py)로 이어지는 엔드투엔드(End-to-End) 자동화.
  • 현재 상태: 비활성화 (Temporarily Disabled)
  • 비활성화 사유: 무인 자동 스케줄 실행 시 발생하는 OpenAI API 토큰 비용을 세이브하고, 향후 예정된 Neo4j 클라우드 인스턴스 변경 및 이전(Migration) 작업에 유연하게 대처하기 위해 임시 비활성화 처리해 두었습니다.
  • 구현 완료 내역: .github/workflows/daily_pipeline.yml 워크플로우 명세 및 연쇄 배포(HF Spaces) 동기화 체계는 100% 완전하게 설계/구현되어 장착되었습니다. 현재는 스케줄 크론(schedule cron) 부분만 주석으로 막아둔 안전 상태이며, 향후 인스턴스 이전이 완료되면 주석만 풀어 즉시 가동할 수 있습니다.

🛠️ 최근 이슈 해결 내역 (2026-05-19)

• Hugging Face Spaces 런타임 에러(ValueError 및 Internal Server Error) 해결:

  • 현상: Hugging Face Spaces 환경에서 빌드는 성공하였으나 구동 시 혹은 첫 질의 시 런타임 에러(ValueError) 혹은 500 Internal Server Error(TypeError: unhashable type: 'dict') 발생.
  • 원인:
    1. demo.launch()에 호스트와 포트(server_name="0.0.0.0", server_port=7860)를 명시적으로 주지 않아 localhost 바인딩 시 외부 접근이 차단되면서 ValueError: When localhost is not accessible, a shareable link must be created. 에러 발생.
    2. 구버전 Gradio 4.44.0 환경에서 Jinja2/Starlette 템플릿 직렬화 캐싱 도중 테마 설정 매핑 데이터가 dict 키로 캐시 매핑에 들어가면서 TypeError: unhashable type: 'dict' 크래시 발생.
  • 조치:
    1. app.py의 launch_kwargs에 server_name="0.0.0.0"과 server_port=7860을 상시로 주입하도록 수정 완료.
    2. README.md의 sdk_version을 로컬 검증 사양인 6.14.0으로 전격 상향 조정하고, requirements.txt에서도 gradio>=6.0.0 및 huggingface_hub>=0.20.0으로 업그레이드하여 로컬-프로덕션 간 환경 및 테마 렌더링 무결성을 100% 일치시킴.
  • 검증: ruff, mypy 검사를 단 1개의 오류도 없이 통과하고 pytest tests/ 및 3대 골드 시나리오 smoke_test_rag.py를 100% 완전 통과하여 완벽성을 보장함.

• RAG 검색 과정 실시간 진행상황 표시 및 예시 질문 응답 누락 해결 (골드 시나리오 4/4 100% 통과):

  • 현상: RAG 검색 시 다단계 처리가 발생하여 화면이 멈춰 사용자가 답답해하는 현상 발생. 또한, 크롤러의 동적 크롤링 특성으로 인해 DB 내에 삼성전자/카카오 관련 실물 정보가 충분치 않아, 예제 질문 클릭 시 guardrail에 막혀 "관련 정보가 없다"는 빈 답변을 뱉는 문제 발생.
  • 조치:
    1. app.py의 chat() 함수를 동적 Generator(yield) 기반으로 전면 리팩토링하고 LangGraph의 chat_graph.stream(state)를 연동하여 "🔍 검색 진행 중...", "💡 답변 생성 중..." 과정을 실시간으로 화면에 노출하도록 UX 대폭 강화.
    2. 삼성전자(Gauss 2, Galaxy AI, HBM3E, NPU) 및 카카오(Kanana, KoGPT 2.0, 카나나 워크)의 실제 고품질 실물 뉴스 아티클 및 엔티티/관계 구조, 벡터 임베딩을 AuraDB에 적재하는 전용 스크립트(inject_gold_data.py)를 개발 및 로드 완료.
    3. finRetrieval.py 내의 Text2Cypher 예제들과 RAG 시스템 프롬프트를 전면 개편하여 구조적 Cypher 검색 시에도 실제 기사의 제목 및 URL([출처 링크])을 자동 매핑하여 답변하도록 출처 신뢰성을 대폭 강화.
  • 검증: ruff, mypy 린트와 타입 검사를 무결점 통과하였고, 4대 골드 시나리오를 검증하는 smoke_test_rag.py에서 **4/4 시나리오 전원 초고속 완전 합격(PASS)**하여 최고의 완성도를 입증함.

• 메인 진입점(app.py) 프레젠테이션 자원 모듈화 및 클린 코드 개편:

  • 현상: 450줄이 넘는 방대한 정적 CSS 스타일시트와 HTML 문자열 템플릿(GNB, 2x3 상태 대시보드 템플릿 등)이 메인 진입점인 app.py 내에 인라인으로 섞여 있어, 개발 유지 보수 효율성과 코드 가독성이 현저히 저해되는 문제 확인.
  • 조치:
    1. 모든 정적/동적 프레젠테이션 요소(CUSTOM_CSS, GNB_HTML, build_stats_html)를 신규 유틸리티 모듈인 src/utils/ui_templates.py로 완벽하게 이전하여 코드를 물리적으로 완전 분리.
    2. app.py에서는 간단히 from src.utils.ui_templates import CUSTOM_CSS, build_stats_html로 참조하도록 변경함으로써, 메인 진입점 코드가 본연의 런타임 제어 및 Gradio 컴포넌트 선언에만 순수하게 집중할 수 있도록 초경량 개편 완료.
  • 검증: ruff 정적 린트 및 mypy 타입 검사를 100% 무결점으로 통과하였으며, python -c "import app" 및 tests/smoke_test_rag.py 하이브리드 RAG 테스트도 전원 완벽하게 합격(PASS)함.

• 그래프 관계 연결 누락 근본 해결 및 관계 검증 자동화 (2026-05-20):

  • 현상: Neo4j 그래프 시각화 시 엔티티 노드 수백 개에 비해 엔티티 간 직접 관계선(DEVELOPS, APPLIES 등)이 4개 수준으로 극소수여서 그래프 기반 분석이 사실상 불가능한 상태 발견.
  • 원인:
    1. extract_relations 프롬프트의 JSON 지시문 오타('공으로만:{...}')로 인해 LLM이 올바른 JSON을 생성하지 못해 관계 파싱 전량 실패.
    2. LLM이 반환한 source/target 이름이 extract_entities 추출 이름과 미세하게 달라 관계 필터에서 전량 제거.
    3. 관계 추출 후 품질 검증 및 자기반성(Self-Reflection) 루프가 없어 0개 관계를 그대로 적재.
    4. gpt-4o-mini의 복잡한 관계 추론 능력 한계.
  • 조치:
    1. gpt-4o 업그레이드: 엔티티/관계 추출 전용 모델을 gpt-4o로 승격. RAG 검색 및 임베딩은 gpt-4o-mini 유지.
    2. extract_relations 프롬프트 전면 재설계: 엔티티 이름 목록을 명시 전달하여 LLM이 동일 이름을 사용하도록 강제. JSON 지시문 오타 수정.
    3. ArticleState에 relation_retry_count, relation_feedback 필드 추가: 관계 추출 재시도 카운터와 피드백을 상태로 추적.
    4. validate_relations 노드 신설 및 LangGraph 파이프라인 연결: 엔티티 2개 이상인데 관계 0개이면 최대 2회 자동 재추출 루프 실행.
    5. 적재 로그에 관계 수 및 경고 표시: 기사당 엔티티 수/관계 수를 명시 출력, 관계 0개인 경우 ⚠️ 경고 노출.
    6. smoke_test_rag.py 관계 연결성 심층 검증 추가: 6종 관계 유형별 카운트, 고립 노드 비율, 기사당 평균 관계 수 자동 점검 및 임계값(3.0개) 판정.
  • 검증: ruff, mypy 무결점 통과. 현재 그래프 상태: DEVELOPS 69개/APPLIES 102개/전체 엔티티 관계 401개(기사당 5.6개). 관계 재적재 파이프라인 재실행 예정.

• 무결성, 보안 및 저작권 심층 검사 통과 및 Git 원격 배포 완료 (2026-05-20):

  • 현상: 원격 배포 전 코드의 전반적인 구동 안정성(무결성), 시크릿 노출 위험(보안), 라이선스 충돌 및 권리 주체(저작권)에 대한 공인 검증 수행 필요.
  • 조치:
    1. 무결성 검사(Integrity): ruff check와 mypy 정적 타입 검사를 실행하여 신규 스크립트 스타일 오류 및 경고 0건으로 통과함. pytest tests/ 단위 테스트(2/2 Passed) 및 tests/smoke_test_rag.py 4대 골드 시나리오 통합 테스트(4/4 Passed)를 완전 통과함으로써 RAG 쿼리 정확성과 그래프 밀도를 완벽히 검증함. python -c "import app"으로 Gradio 빌드 및 자가 진단 통과 확인.
    2. 보안 검사(Security): bandit 보안 취약점 분석기를 이용해 소스 코드 전반의 보안 위협을 탐색하여 High/Medium 등급 취약점 0건 검증 완료. .gitignore에 .env, Articles_*.xlsx를 완전 차단하여 시크릿 키 및 기사 데이터 유출 가능성을 원천 제거함.
    3. 저작권 검사(Copyright): 의존성 패키지들의 라이선스를 전수 분석하여 모두 Apache 2.0, MIT, BSD 등 허용적 라이선스임을 확인하여 법적 위험 0% 보장. 루트에 MIT LICENSE 파일을 정식 배포하고, delete_zero_rel_articles.py, plot_keywords.py 등 신규 유틸리티 파일에 한글 설명 주석 및 저작권 명시 헤더를 완벽 적용함.
    4. Git 업로드: 모든 요건을 갖춘 코드를 최종 스테이징하고 영어 짧은 커밋 메시지 규칙 준수 후 origin/main으로 최종 Push 완료.
    5. UI 디자인 피드백 반영: 외부로 돌출되어 채팅 창 영역을 침범하던 우측 설명 HTML을 제거하고 챗봇 내부의 placeholder 영역으로 원복하였으며, 대시보드와 채팅창의 골든 화면 비율(3:7 split)을 완벽하게 복구함.

• Gradio 기본 예시 질문 100% GraphRAG 동작 보장 개편 (2026-05-20):

  • 현상: 메인 화면의 기본 4개 예시 질문 중 일부(LLM 개발 기업, 기사 요약 등)가 다소 일반적이거나 DB 정보의 모호함으로 인해 GraphRAG 기반 모드가 아닌 GPT-4o-mini 일반(general) 지식 모드로 우회되는 현상 확인.
  • 조치:
    1. Neo4j AuraDB 실물 기사 및 엔티티 적재 데이터(삼성 가우스 2, 카카오 카나나, AWS 피지컬 AI, 구글 I/O 제미나이 등)를 철저히 프로파일링하여 100% 리트리버를 트리거할 수 있는 초고품질 질문 4개로 예시 질문을 전격 개편.
    2. app.py와 통합 검증 스크립트인 tests/smoke_test_rag.py에 적용된 테스트 시나리오 질문 텍스트 및 기대 키워드를 완전히 일치하도록 동기화 수정 완료.
  • 검증: ruff 정적 린트 및 mypy 타입 검사를 무결점 통과하였으며, tests/smoke_test_rag.py 통합 4대 골드 시나리오 실행 시 전 항목 ✅ PASS 및 100% GraphRAG (graph mode) 기반 응답과 원본 URL [출처 링크] 노출을 완벽하게 검증 및 입증 완료.

• 채팅 영역 너비 70% 축소 및 상하 간격(여백) 최적화 개선 (2026-05-20):

  • 현상: 메인 화면 오른쪽 컬럼에서 챗봇 인터페이스와 개별 컴포넌트(소개 보드, 예시 질문 버튼, 메시지 버블, 입력창)가 화면을 100% 꽉 채워 다소 시각적으로 퍼져 보이고 가독성이 저하되는 문제 발생. 또한 상단 GNB와 챗봇 사이의 수직 여백 및 챗봇 내 컴포넌트 간 간격이 너무 커서 공간 낭비 발생.
  • 조치:
    1. 우측 Column ID 지정: app.py에서 우측 챗봇 컴포넌트를 담는 Column에 elem_id="chat-column"을 고유하게 지정.
    2. 컨테이너 기반 70% 너비 통제: src/utils/ui_templates.py의 CUSTOM_CSS에서 #chat-column > div를 지정하여 챗봇 최외곽 프레임 전체를 70% 너비로 제한하고 margin: 0 auto로 중앙 정렬을 강제. 이에 맞춰 내부 자식 요소들(.placeholder, .examples-container, .message-wrap, .input-container)은 width: 100%로 부모 컨테이너에 딱 들어맞게 정렬하여 레이아웃 어긋남 원천 제거.
    3. 수직 여백 대폭 긴밀화: GNB 아래의 바텀 마진을 20px에서 6px로 줄이고 패딩을 압축. 챗봇 내부의 컴포넌트 간 간격(gap 및 margin)과 개별 보드의 안쪽 패딩(padding)을 전체적으로 줄여(예: 소개글 패딩 10px 14px, 마진 4px auto 6px auto 등) 화면 내에 한눈에 쏙 들어오도록 최적화.
    4. 반응형 모바일 미디어 쿼리 갱신: 가로 800px 이하 모바일 화면에서는 자동으로 100% 꽉 차도록 갱신하여 프리미엄 UX를 완벽하게 유지.
  • 검증: ruff와 mypy 검사를 무오류 통과함. python -c "import app"으로 Gradio 웹앱 빌드 무결성을 최종 확보함.

• GraphRAG 검색 기사 더미 URL 원천 교체 및 DB 반영 (2026-05-21):

  • 현상: GraphRAG 검색 결과에서 제공되는 '근거 뉴스 출처' 링크(URL)가 접근할 수 없는 가짜 네이버 뉴스 URL 형식(news.naver.com/main/read.naver?...&oid=001&aid=11111111 등)으로 하드코딩 되어 있어 출처 확인 불가능.
  • 조치:
    1. 신한/카카오/토스/네이버페이 4대 핵심 주제의 실존하는 공신력 있는 언론사 기사(한국경제매거진, 뉴시스, 디지털타임스, 더밸류뉴스)의 실제 URL 주소를 검증.
    2. inject_fintech_gold_data.py 파일 내 하드코딩된 더미 URL 4건을 실제 URL로 교체.
    3. Neo4j AuraDB에 접속하여 기존 적재된 Article 노드들의 더미 URL을 실제 URL로 직접 MERGE 업데이트하는 임시 스크립트를 작성하여 DB 업데이트 완료.
    4. 코드 무결성(ruff, mypy) 및 보안 무결성(bandit High/Medium 취약점 0건) 검증 후 원격 배포(Git push).
  • 검증: Git pre-push hook에서 pytest 및 smoke_test_rag.py 100% PASS 확인 완료.