fix: resolve mypy type error in LazyGraphRAG and Gradio caching crash

AGENTS.md

@@ -46,6 +46,23 @@ FinGraph/
 - 'src/references/' 파일 수정 금지(참고자료)
 - Neo4j 드라이버 연결 시 `NEO4J_USERNAME`, `NEO4J_PASSWORD`만을 요구하거나 사용하는 방식의 옛날 코드 작성 절대 금지 (Connection Client Credentials 병행 매핑 필수)
 
+## 🚨 재발 방지 및 치명적 안티 패턴 금지 (Recurring Issues Prevention)
+이 프로젝트에서 3회 이상 반복적으로 발생하여 전체 파이프라인(로컬, CI, 프로덕션)을 붕괴시켰던 핵심 장애들을 영구적으로 차단하기 위한 필수 규칙 및 방어 테스트입니다.
+
+- **1. Import-Time DB Connection 절대 금지 (CI 크래시 방지)**
+  - **원인**: 모듈 전역 범위(Global Scope)에서 데이터베이스를 즉시 연결(`driver = get_neo4j_driver()`)하여, GitHub Actions(CI)나 `pytest`가 테스트를 수집(`import`)하기만 해도 접속 불가 에러(`Connection refused`)로 뻗어버리는 문제 3회 이상 발생.
+  - **규칙**: 모듈 임포트 시점에는 절대 DB와 통신하지 말 것. RAG 인스턴스는 반드시 `LazyGraphRAG` 프록시 패턴을 사용하여 실제 쿼리(`search`) 호출 시점에 단 1회 지연 초기화(`_init_once()`) 되도록 설계해야 함. `finGraph.py` 역시 전역이 아닌 `main()` 내부에서 드라이버를 런타임 초기화할 것.
+  - **방어 테스트**: `python -c "import src.retrieval.finRetrieval"` 및 `python -c "import src.graphBuilder.neo4j.finGraph"` 명령을 실행했을 때, DB 연결 시도 없이 즉각 0.1초 만에 정상 종료되는지 점검 후 커밋할 것.
+
+- **2. 프로덕션 Fail-Fast 자가 진단 필수 (침묵의 런타임 에러 방지)**
+  - **원인**: 허깅페이스(HF Spaces) 배포 시 DB 연결 환경 변수가 누락되었음에도 불구하고 웹 앱은 정상적으로 켜진 척(Running) 하다가, 사용자가 처음 질문을 던진 순간 500 내부 에러를 뿜으며 뻗어버리는 심각한 운영 장애 발생.
+  - **규칙**: 배포 진입점(`app.py`) 구동 시점에는 지연 초기화를 무시하고 강제로 즉시 연결(`graphrag._init_once()`)을 시도하여, 실패 시 앱 구동 자체를 실패시키는 `Fail-Fast` 자가 진단 코드를 `app.py` 상단에 반드시 유지할 것.
+
+- **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 하나에 하나의 변경만

app.py

@@ -150,10 +150,11 @@ with gr.Blocks(
             "어떤 기업이 LLM 기술을 개발하나요?",
             "최근 AI 관련 뉴스 기사를 요약해줘",
         ],
+        cache_examples=False,
         retry_btn=None,
         undo_btn="↩️ 되돌리기",
         clear_btn="🗑️ 대화 초기화",
     )
 
 if __name__ == "__main__":
-    demo.launch()
+    demo.launch(server_name="0.0.0.0", server_port=7860)

src/retrieval/finRetrieval.py

@@ -240,6 +240,7 @@ class LazyGraphRAG:
 
     def search(self, *args: Any, **kwargs: Any) -> Any:
         self._init_once()
+        assert self._graphrag is not None
         return self._graphrag.search(*args, **kwargs)
 
     def __getattr__(self, name: str) -> Any: