refactor: split nodes into modules, add core/prompts, switch to sync mode

.gitignore

@@ -1,34 +0,0 @@
-# Python
-__pycache__/
-*.py[cod]
-*$py.class
-*.so
-.Python
-*.egg-info/
-dist/
-build/
-
-# Environment
-.env
-.venv
-env/
-venv/
-ENV/
-
-# IDE
-.vscode/
-.idea/
-*.swp
-*.swo
-
-# OS
-.DS_Store
-Thumbs.db
-
-# Logs
-*.log
-
-# Lock files (HF Spaces will install from requirements.txt)
-uv.lock
-poetry.lock
-

CodeWeaver/README.md

@@ -1,118 +1,149 @@
----
-title: CodeWeaver
-emoji: 🤖
-colorFrom: blue
-colorTo: purple
-sdk: gradio
-sdk_version: "4.44.1"
-app_file: ui/app.py
-pinned: false
-license: mit
----
-
-# CodeWeaver
-
-LangGraph 기반의 **개발자 Q&A 에이전트**입니다. 질문을 분석하고(후속/독립), **캐시(Qdrant)**를 우선 확인한 뒤 캐시 미스일 때 **3개 소스(Stack Overflow / GitHub / 공식 문서(Tavily))를 병렬 검색**해 답변을 생성합니다. 서로 독립적인 질문이 2개 들어오면 **동적으로 2개 파이프라인을 병렬 실행**해 통합 답변을 제공합니다.
-
-## 핵심 기능(현재 코드 기준)
-
-- **질문 개수 감지**: 1개(단일 주제) / 2개(독립 질문 2개) / 3개 이상(거절 안내)
-- **질문 타입 분석**: `clarification`이면 검색/캐시 없이 **대화 히스토리 기반 답변**
-- **의미적 캐싱**: Qdrant에 질문-답변을 저장하고 유사 질문을 빠르게 재사용(임계값 0.85)
-- **병렬 검색**: Stack Overflow / GitHub / Tavily(공식 문서 도메인 제한) 동시 검색
-- **검색 품질 보정**: 결과가 부족하면 **쿼리 개선을 최대 1회** 수행
-- **서브그래프 처리**: 검색 결과를 필터링/점수화 후 요약 → 최종 답변 생성
-
-## 문서
-
-- 아키텍처/동작 원리: `../ARCHITECTURE.md`
-- 다중 질문 병렬 처리 설계(배경 설명): `../DYNAMIC_PARALLEL_SEARCH.md`
-
-## 빠른 시작
-
-### 1) 설치
-
-아래는 저장소 루트가 아니라 **`CodeWeaver/` 디렉터리 기준** 예시입니다.
-
-```bash
-cd CodeWeaver
-
-# uv 사용(권장)
-uv sync
-
-# 또는 pip 사용
-pip install -r requirements.txt
-```
-
-> `sentence-transformers`가 최초 실행 시 `BAAI/bge-m3` 모델을 다운로드할 수 있습니다(네트워크 필요).
-
-### 2) 환경 변수 설정(.env)
-
-`CodeWeaver/.env` 파일을 만들고 아래를 설정하세요(필수/선택 구분).
-
-```bash
-# 필수: Gemini (LLM)
-GOOGLE_API_KEY=your_google_api_key
-
-# 필수: Tavily (공식 문서 검색)
-TAVILY_API_KEY=your_tavily_api_key
-
-# 필수: Qdrant Cloud (캐시)
-QDRANT_URL=https://xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.us-east-1-0.aws.cloud.qdrant.io
-QDRANT_API_KEY=your_qdrant_api_key
-
-# 선택: GitHub API rate limit 완화
-GITHUB_TOKEN=your_github_token
-
-# 선택: LangSmith 트레이싱
-LANGCHAIN_TRACING_V2=true
-LANGCHAIN_API_KEY=your_langsmith_api_key
-```
-
-### 3) 실행(Gradio UI)
-
-```bash
-cd CodeWeaver
-python ui/app.py
-```
-
-기본 주소: `http://localhost:7860`
-
-## 현재 폴더 구조
-
-```
-CodeWeaver/
-├── main.py
-├── pyproject.toml
-├── requirements.txt
+🕸️ CodeWeaver: LangGraph 기반 지능형 개발 어시스턴트
+CodeWeaver는 초보 개발자를 위해 설계된 LangGraph 기반의 자율 AI 에이전트입니다.
+단순한 LLM 래퍼가 아닙니다. 사용자의 질문 의도를 파악하고(Planning), 필요한 경우에만 외부 지식을 검색하며(Retrieval), 검색 결과를 재평가(Reranking)하여 최적의 답변을 생성하는 Agentic Workflow를 구현했습니다.
+![alt text](https://img.shields.io/badge/Python-3.10%2B-blue)
+
+![alt text](https://img.shields.io/badge/LangGraph-StateGraph-orange)
+
+![alt text](https://img.shields.io/badge/UI-Gradio-purple)
+
+![alt text](https://img.shields.io/badge/Package_Manager-uv-astral)
+
+![alt text](https://img.shields.io/badge/License-MIT-green)
+🚀 핵심 기능 (Key Features)
+1. 지능형 워크플로우 (Agentic Architecture)
+질문 분석 및 계획 (Planning): 사용자의 질문을 분석하여 단순 대화(general_chat)인지, 기술 질문(independent)인지, 추가 설명 요청(clarification)인지 판단합니다.
+다중 질문 처리 (Map-Reduce): "JWT와 CORS가 뭐야?"와 같이 복합적인 질문이 들어오면, 이를 독립적인 하위 질문으로 분해하여 병렬로 처리한 후 답변을 통합합니다.
+Fast Track: 일상적인 인사나 가벼운 대화는 검색 프로세스를 건너뛰고 즉시 응답하여 API 비용을 절감하고 속도를 높입니다.
+2. 고품질 검색 및 평가 (Advanced RAG)
+멀티 소스 검색: StackOverflow(디버깅), GitHub(코드 예제), Tavily(30+ 공식 문서)를 동시에 검색합니다.
+Reranking (Cross-Encoder): 검색된 문서들을 FastEmbed 기반의 **Cross-Encoder(Jina-Reranker)**로 정밀 채점합니다.
+품질 필터링: 관련성 점수 0.35 미만의 문서는 답변 생성에 사용하지 않아 할루시네이션을 방지합니다.
+자동 쿼리 개선 (Refinement): 검색 결과가 부족하거나 품질이 낮을 경우, 에이전트가 스스로 검색어를 영어 기술 용어로 변환하거나 구체화하여 재검색합니다.
+3. 성능 및 안정성 최적화
+영구적 기억 (Persistence): **PostgreSQL (Neon DB)**을 사용하여 서버가 재시작되어도 대화 맥락이 유지됩니다.
+Windows 호환성 (Sync Mode): Windows 환경의 asyncio 이슈(ProactorLoop)를 해결하기 위해, 전체 파이프라인을 동기(Sync) 모드 및 ConnectionPool 기반으로 설계했습니다.
+백그라운드 캐싱: 답변 생성 후 Vector DB(Qdrant)에 저장하는 작업은 Daemon Thread로 비동기 처리하여 사용자 대기 시간(Latency)을 최소화했습니다.
+메모리 최적화: 무거운 sentence-transformers 대신 가벼운 fastembed를 사용하고, 모델 로딩에 Singleton 패턴을 적용했습니다.
+🛠️ 기술 스택 (Tech Stack)
+분류	기술	설명
+Framework	LangGraph	에이전트 상태 관리 및 순환 그래프 제어
+LLM	Google Gemini 2.5 Flash Lite	추론, 계획, 답변 생성
+Vector DB	Qdrant Cloud	질문-답변 의미적 캐싱 (Semantic Cache)
+Embedding	BAAI/bge-base-en-v1.5	텍스트 임베딩 (Local)
+Reranker	jinaai/jina-reranker-v1-tiny-en	검색 결과 재순위화 (Cross-Encoder)
+Search Tools	Tavily, StackExchange, GitHub API	외부 지식 검색
+Database	PostgreSQL (Neon)	대화 상태 저장 (Checkpointer)
+UI	Gradio	채팅 인터페이스 및 세션 관리
+Dev Tool	uv	초고속 패키지 관리 및 의존성 해결
+🏗️ 아키텍처 (Architecture)
+CodeWeaver는 StateGraph를 사용하여 에이전트의 상태를 관리합니다.
+code
+Mermaid
+graph TD
+    START --> CreatePlan[Create Plan]
+    CreatePlan -->|Single| Analyze[Analyze Question]
+    CreatePlan -->|Multi| Parallel[Map: Parallel Subgraphs]
+    
+    subgraph "Single Question Workflow"
+        Analyze -->|Intent: General| GenDirect[Generate Answer]
+        Analyze -->|Intent: Independent| CheckCache[Check Cache]
+        
+        CheckCache -->|Hit| ReturnCache[Return Cached Answer]
+        CheckCache -->|Miss| Classify[Classify Intent]
+        
+        Classify --> SearchParallel[Search: SO / GitHub / Docs]
+        SearchParallel --> Evaluate[Evaluate & Rerank]
+        
+        Evaluate -->|Good| GenerateRAG[Generate Answer w/ Context]
+        Evaluate -->|Bad| Refine[Refine Query]
+        Refine --> Classify
+    end
+    
+    Parallel --> Combine[Reduce: Combine Answers]
+    GenDirect --> END
+    ReturnCache --> END
+    GenerateRAG --> END
+    Combine --> END
+주요 노드 설명
+create_plan: 사용자 입력을 분석하여 단일 질문인지, 다중 질문인지, 처리 불가능(3개 이상)인지 판단합니다.
+analyze_question: 질문의 성격(일상 대화 vs 기술 질문)을 분류하고 캐시 적격성을 판단합니다.
+evaluate_results: 수집된 검색 결과를 Reranker로 평가합니다. 점수가 낮으면 refine_search로 보냅니다.
+generate_answer: 필터링된 고품질 문서를 바탕으로 초보자 친화적인 답변을 생성합니다. (검색 결과 요약 단계 없이 원본 활용 - Context Stuffing)
+📂 프로젝트 구조
+code
+Bash
+codeweaver/
 ├── src/
 │   ├── agent/
-│   │   ├── graph.py         # LangGraph 메인 그래프(라우팅/병렬화)
-│   │   ├── nodes.py         # 각 노드 구현
-│   │   └── state.py         # AgentState + reducer 정의
+│   │   ├── graph.py        # LangGraph 구조 정의 (Main & Subgraphs)
+│   │   ├── nodes.py        # 각 노드의 실행 로직 (LLM 호출, 판단 등)
+│   │   └── state.py        # Pydantic 기반 State 정의 (AgentState, WorkerState)
 │   ├── tools/
-│   │   └── search_tools.py  # StackOverflow/GitHub/Tavily 검색
+│   │   └── search_tools.py # Tavily, StackOverflow, GitHub 검색 도구
+│   ├── vector_db/
+│   │   └── qdrant_client.py # Qdrant 연동 및 캐시 로직
 │   ├── utils/
-│   │   └── tracing.py       # trace_node 데코레이터(LangSmith 연동)
-│   └── vector_db/
-│       ├── qdrant_client.py # Qdrant 캐시 관리
-│       └── local_embeddings.py # bge-m3 로컬 임베딩
-└── ui/
-    └── app.py               # Gradio UI (실제 엔트리)
-```
-
-## 동작 흐름(요약)
-
-- `START → create_plan`
-  - **3개 이상**이면 안내 메시지 반환
-  - **2개**면 각 질문을 worker에서 단일 파이프라인으로 실행 후 결합
-  - **1개**면 아래 단일 파이프라인 수행
-- 단일 파이프라인:
-  - `analyze_question`
-    - `clarification`이면 `generate_with_history`로 즉시 답변
-    - 그 외: `check_cache` → hit면 반환, miss면 `classify_intent`
-  - `classify_intent` → 3소스 병렬 검색 → `collect_results` → `evaluate_results`
-  - 필요 시 `refine_search` 1회 → 재검색
-  - `filter_and_score → summarize_results → generate_answer`(+조건부 캐시 저장)
-
-자세한 원리는 `../ARCHITECTURE.md`를 참고하세요.
+│   │   └── tracing.py      # LangSmith 트레이싱 데코레이터
+│   └── config.py           # Pydantic Settings 환경 설정
+├── ui/
+│   └── app.py              # Gradio 웹 인터페이스
+├── .env                    # 환경 변수 (API 키)
+├── pyproject.toml          # 프로젝트 및 의존성 설정
+└── uv.lock                 # 의존성 잠금 파일
+⚙️ 설치 및 실행 (Setup)
+이 프로젝트는 uv 를 사용하여 패키지를 관리합니다.
+1. 필수 요구 사항
+Python 3.10 이상
+uv 설치 필요
+PostgreSQL 데이터베이스 (Neon Serverless 권장)
+Qdrant 클러스터 (Cloud 권장)
+2. 환경 변수 설정
+프로젝트 루트에 .env 파일을 생성하고 아래 내용을 채워주세요.
+code
+Ini
+# Gemini API Key
+GOOGLE_API_KEY=your-google-api-key
+
+# Search Tool
+TAVILY_API_KEY=your-tavily-api-key
+
+# Vector DB (Qdrant)
+QDRANT_URL=https://your-qdrant-endpoint
+QDRANT_API_KEY=your-qdrant-api-key
+
+# LangSmith Tracing (선택 사항)
+LANGCHAIN_TRACING_V2=true
+LANGCHAIN_API_KEY=your_langsmith_api_key_here
+LANGCHAIN_PROJECT=codeweaver
+LANGCHAIN_ENDPOINT=https://api.smith.langchain.com
+
+# GitHub API (Rate Limit 완화용, 선택 사항)
+GITHUB_TOKEN=your-github-token
+
+# Database Connection (PostgreSQL/Neon)
+POSTGRES_DB_URL=postgresql://user:password@host/dbname
+3. 패키지 설치
+uv를 사용하여 의존성을 동기화합니다. 가상환경이 자동으로 생성됩니다.
+code
+Bash
+uv sync
+4. 실행
+uv run 명령어를 사용하여 앱을 실행합니다.
+code
+Bash
+uv run ui/app.py
+브라우저에서 http://localhost:7860으로 접속하여 사용할 수 있습니다.
+💡 주요 구현 디테일 (Under the Hood)
+Sync Mode & Windows 호환성
+Python의 asyncio는 Windows의 ProactorLoop와 특정 DB 드라이버 간 충돌을 일으킬 수 있습니다. 이를 근본적으로 해결하기 위해 CodeWeaver는 전체 워크플로우를 동기(Sync) 방식으로 구현했습니다.
+psycopg_pool.ConnectionPool을 사용하여 동기 환경에서도 효율적인 DB 연결을 관리합니다.
+LangGraph의 checkpointer 역시 PostgresSaver의 동기 버전을 사용합니다.
+Thread-safe Singleton & Background Caching
+Singleton: TextCrossEncoder 모델과 ConnectionPool은 전역에서 한 번만 초기화되며, threading.Lock을 통해 멀티스레드 환경에서도 안전하게 접근합니다.
+Fire-and-forget: 사용자에게 답변을 표시하는 것과 별개로, 캐시 저장 작업은 daemon=True인 백그라운드 스레드에서 수행되어 응답 지연을 유발하지 않습니다.
+검색 도메인 최적화 (search_tools.py)
+Tavily 검색 시 단순히 웹 전체를 뒤지는 것이 아니라, 개발자에게 신뢰할 수 있는 도메인만 include_domains로 지정하여 검색 품질을 높였습니다.
+포함 도메인: docs.python.org, spring.io, stackoverflow.com, github.com, developer.mozilla.org, platform.openai.com 등 약 30개 이상의 공식 문서 및 커뮤니티.
+🤝 Contributing
+이 프로젝트는 개인 학습 및 연구 목적으로 개발되었습니다. 버그 리포트나 기능 제안은 Issue로 남겨주세요.

CodeWeaver/pyproject.toml

@@ -15,9 +15,15 @@ dependencies = [
     "langchain-core>=0.3.0",
     "langchain-google-genai>=2.0.0",
     "langgraph>=0.2.0",
-    "sentence-transformers>=3.0.0",
-    "torch>=2.0.0",
+    "fastembed>=0.7.0",
     "gradio==4.44.1",
+    "pydantic>=2.0.0",
+    "pydantic-settings>=2.0.0",
+    "langgraph-checkpoint-postgres",
+    "psycopg-binary",
+    "psycopg-pool",
+    "pyyaml",
+    "jinja2",
 ]
 
 [tool.pytest.ini_options]

CodeWeaver/requirements.txt

@@ -1,24 +1,19 @@
-# LangGraph & LangChain
-langgraph>=0.2.0
-langchain-google-genai>=2.0.0
+qdrant-client
+pytest
+pytest-asyncio
+python-dotenv
+tavily-python
+requests
+langsmith>=0.1.0
 langchain-core>=0.3.0
-langsmith>=0.2.0
-
-# Vector DB
-qdrant-client>=1.11.0
-
-# Search APIs
-tavily-python>=0.5.0
-requests>=2.31.0
-
-# Embeddings
-sentence-transformers>=3.0.0
-torch>=2.0.0
-
-# UI
+langchain-google-genai>=2.0.0
+langgraph>=0.2.0
+fastembed>=0.7.0
 gradio==4.44.1
-
-# Utils
-python-dotenv>=1.0.0
 pydantic>=2.0.0
-
+pydantic-settings>=2.0.0
+langgraph-checkpoint-postgres
+psycopg-binary
+psycopg-pool
+pyyaml
+jinja2

CodeWeaver/src/agent/__init__.py

@@ -6,20 +6,20 @@ LangGraph 기반 개발자 질문 답변 에이전트를 제공합니다.
 주요 컴포넌트:
 - State: 에이전트 상태 관리
 - Nodes: 개별 처리 노드
-- Graph: LangGraph 워크플로우
+- Graph: LangGraph 워크플로우 (get_agent 사용)
 """
 
 from .state import AgentState, SearchResult
-from .graph import agent, build_agent_graph, create_agent
+
+# [핵심 수정] agent, create_agent 제거 -> get_agent 추가
+from .graph import get_agent, build_agent_graph
+
 from .nodes import (
     analyze_question_node,
     check_cache_node,
-    classify_intent_node,
     search_stackoverflow_node,
     search_github_node,
     search_official_docs_node,
-    filter_and_score_node,
-    summarize_results_node,
     generate_answer_node,
     return_cached_answer_node,
     generate_with_history_node,
@@ -31,21 +31,16 @@ __all__ = [
     "SearchResult",
     
     # Graph
-    "agent",
+    "get_agent",          # ✅ 변경됨 (agent 대신 사용)
     "build_agent_graph",
-    "create_agent",
     
     # Nodes
     "analyze_question_node",
     "check_cache_node",
-    "classify_intent_node",
     "search_stackoverflow_node",
     "search_github_node",
     "search_official_docs_node",
-    "filter_and_score_node",
-    "summarize_results_node",
     "generate_answer_node",
     "return_cached_answer_node",
     "generate_with_history_node",
-]
-
+]

CodeWeaver/src/agent/graph.py

@@ -1,380 +1,126 @@
 """
 CodeWeaver LangGraph 워크플로우 구성.
 
-LangGraph 6가지 핵심 기능 완벽 구현:
-✅ Conditional Edges: 질문 유형, 캐시 여부에 따른 분기
-✅ Send API: 3개 검색 노드 병렬 실행 (fan-out/fan-in)
-✅ Subgraph: 단일 질문 처리 파이프라인 + 검색 결과 처리 파이프라인
-✅ Map-Reduce: Send API로 병렬 검색 → 결과 머지
-✅ Checkpointing: MemorySaver로 대화 상태 저장
-✅ Pydantic Typed State: 타입 안전성 보장
+그래프 구조 정의만 담당합니다. 라우팅 로직은 routes.py에 있습니다.
 """
-
 import logging
-from typing import Literal
+from typing import Optional
 
-from langgraph.checkpoint.memory import MemorySaver
+# LangGraph & LangChain Core
+from langchain_core.runnables import Runnable
 from langgraph.graph import StateGraph, START, END
-from langgraph.types import Send
+# [수정] Sync 모듈 사용 (Windows 호환성)
+from langgraph.checkpoint.postgres import PostgresSaver
+from psycopg_pool import ConnectionPool
 
-from src.agent.state import AgentState, WorkerState, _MULTI_ANS_RESET_TOKEN
+from src.core.config import settings
+from src.agent.state import AgentState, WorkerState
 from src.agent.nodes import (
-    analyze_question_node,
-    check_cache_node,
-    create_plan_node,
-    classify_intent_node,
-    search_stackoverflow_node,
-    search_github_node,
+    analyze_question_node, 
+    check_cache_node, 
+    create_plan_node, 
+    search_stackoverflow_node, 
+    search_github_node, 
     search_official_docs_node,
-    collect_results_node,
-    evaluate_results_node,
+    collect_results_node, 
+    evaluate_results_node, 
     refine_search_node,
-    filter_and_score_node,
-    summarize_results_node,
-    generate_answer_node,
-    return_cached_answer_node,
+    generate_answer_node, 
+    return_cached_answer_node, 
     generate_with_history_node,
-    handle_too_many_questions_node,
+    handle_too_many_questions_node, 
     combine_answers_node,
 )
+from src.agent.routes import (
+    route_after_analysis_worker,
+    route_after_cache_worker,
+    route_after_evaluation_worker,
+    initiate_parallel_search_worker,
+    route_after_plan,
+    route_after_subgraph,
+)
 
 logger = logging.getLogger(__name__)
 
 
-def build_search_subgraph() -> StateGraph:
-    """
-    검색 결과 처리 서브그래프를 구성합니다.
-    
-    흐름: filter_and_score → summarize_results
-    
-    이 서브그래프는 single_question_subgraph 내부에서 사용되므로
-    WorkerState를 사용하여 채널 타입 충돌을 방지합니다.
-    
-    Returns:
-        컴파일된 서브그래프
-    """
-    # 서브그래프 생성 (WorkerState 사용)
-    subgraph = StateGraph(WorkerState)
-    
-    # 노드 추가
-    subgraph.add_node("filter_and_score", filter_and_score_node)
-    subgraph.add_node("summarize_results", summarize_results_node)
-    
-    # 서브그래프 내부 흐름 정의
-    # START → filter_and_score → summarize_results → END
-    subgraph.add_edge(START, "filter_and_score")
-    subgraph.add_edge("filter_and_score", "summarize_results")
-    subgraph.add_edge("summarize_results", END)
-    
-    return subgraph.compile()
-
-
-def route_after_analysis_worker(state: WorkerState) -> Literal["generate_with_history", "check_cache"]:
-    """
-    질문 분석 결과에 따라 다음 노드를 결정합니다 (WorkerState용).
-    
-    Args:
-        state: 현재 워커 상태
-    
-    Returns:
-        - "generate_with_history": 후속 질문 → 대화 히스토리 기반 답변
-        - "check_cache": 독립 질문 → 캐시 확인
-    """
-    raw_qtype = state.question_type or "independent"
-    legacy_map = {
-        "followup": "clarification",
-        "cache_candidate": "independent",
-        "new_search": "independent",
-    }
-    question_type = legacy_map.get(raw_qtype, raw_qtype)
-
-    if question_type == "clarification":
-        return "generate_with_history"
-
-    return "check_cache"
-
-
-def route_after_cache_worker(state: WorkerState) -> Literal["return_cached_answer", "classify_intent"]:
-    """
-    캐시 히트 여부에 따라 다음 노드를 결정합니다 (WorkerState용).
-    
-    Args:
-        state: 현재 워커 상태
-    
-    Returns:
-        - "return_cached_answer": 캐시 히트 시 즉시 답변 반환
-        - "classify_intent": 캐시 미스 시 의도 분류
-    """
-    if state.cached_result:
-        return "return_cached_answer"
-    else:
-        return "classify_intent"
-
-
-def route_after_evaluation_worker(state: WorkerState) -> Literal["refine_search", "search_subgraph"]:
-    """
-    검색 결과 평가 후 다음 노드를 결정합니다 (WorkerState용).
-    
-    Args:
-        state: 현재 워커 상태
-    
-    Returns:
-        - "refine_search": 결과 부족 & 개선 횟수 0회 → 쿼리 개선
-        - "search_subgraph": 결과 충분 or 개선 횟수 1회 → 필터링 진행
-    """
-    needs_refinement = state.needs_refinement
-    refinement_count = state.refinement_count
-    
-    if needs_refinement and refinement_count < 1:
-        return "refine_search"
-    else:
-        return "search_subgraph"
-
-
-def initiate_parallel_search_worker(state: WorkerState):
-    """
-    Send API를 사용하여 3개의 검색 노드를 병렬로 실행합니다 (WorkerState용).
-    
-    Args:
-        state: 현재 워커 상태
-    
-    Returns:
-        Send 객체 리스트 (fan-out)
-    """
-    return [
-        Send("search_stackoverflow", state),
-        Send("search_github", state),
-        Send("search_official_docs", state),
-    ]
-
-
 def build_single_question_subgraph() -> StateGraph:
-    """
-    단일 질문 처리 서브그래프.
-    
-    🔧 CRITICAL: 
-    - WorkerState만 사용
-    - 부모 AgentState와 완전히 격리
-    - 출력: multi_answers 또는 final_answer만
-    """
-    # WorkerState 사용 (AgentState와 완전히 독립)
+    """단일 질문 처리 서브그래프"""
     subgraph = StateGraph(WorkerState)
     
-    # 노드 추가
+    # 노드 등록
     subgraph.add_node("analyze_question", analyze_question_node)
     subgraph.add_node("generate_with_history", generate_with_history_node)
     subgraph.add_node("check_cache", check_cache_node)
     subgraph.add_node("return_cached_answer", return_cached_answer_node)
-    subgraph.add_node("classify_intent", classify_intent_node)
     
-    # 병렬 검색 노드
     subgraph.add_node("search_stackoverflow", search_stackoverflow_node)
     subgraph.add_node("search_github", search_github_node)
     subgraph.add_node("search_official_docs", search_official_docs_node)
     
-    # 결과 처리 노드
     subgraph.add_node("collect_results", collect_results_node)
     subgraph.add_node("evaluate_results", evaluate_results_node)
     subgraph.add_node("refine_search", refine_search_node)
     
-    # 최종 답변 생성
     subgraph.add_node("generate_answer", generate_answer_node)
     
-    # 중첩 서브그래프 (filter + summarize)
-    filter_summarize_subgraph = build_search_subgraph()
-    subgraph.add_node("search_subgraph", filter_summarize_subgraph)
-    
-    # ===== 엣지 구성 =====
-    
-    # 1. START → analyze_question
+    # 엣지 연결
     subgraph.add_edge(START, "analyze_question")
-    
-    # 2. analyze_question 결과에 따른 분기
     subgraph.add_conditional_edges(
         "analyze_question",
         route_after_analysis_worker,
         {
             "generate_with_history": "generate_with_history",
             "check_cache": "check_cache",
+            "generate_answer": "generate_answer",
         }
     )
-    
-    # 3. generate_with_history → END (대화 히스토리 기반 답변)
     subgraph.add_edge("generate_with_history", END)
     
-    # 4. check_cache 결과에 따른 분기
     subgraph.add_conditional_edges(
         "check_cache",
         route_after_cache_worker,
         {
             "return_cached_answer": "return_cached_answer",
-            "classify_intent": "classify_intent",
         }
     )
-    
-    # 5. return_cached_answer → END (캐시 히트)
     subgraph.add_edge("return_cached_answer", END)
     
-    # 6. classify_intent → 병렬 검색 (Send API)
-    subgraph.add_conditional_edges("classify_intent", initiate_parallel_search_worker)
-    
-    # 7. 모든 검색 노드 → collect_results (fan-in)
     subgraph.add_edge("search_stackoverflow", "collect_results")
     subgraph.add_edge("search_github", "collect_results")
     subgraph.add_edge("search_official_docs", "collect_results")
     
-    # 8. collect_results → evaluate_results
     subgraph.add_edge("collect_results", "evaluate_results")
-    
-    # 9. evaluate_results 결과에 따른 분기
     subgraph.add_conditional_edges(
         "evaluate_results",
         route_after_evaluation_worker,
         {
             "refine_search": "refine_search",
-            "search_subgraph": "search_subgraph",
+            "generate_answer": "generate_answer",
         }
     )
-    
-    # 10. refine_search → classify_intent (쿼리 개선 루프)
-    subgraph.add_edge("refine_search", "classify_intent")
-    
-    # 11. search_subgraph → generate_answer
-    subgraph.add_edge("search_subgraph", "generate_answer")
-    
-    # 12. generate_answer → END
+    # refine_search 후에는 다시 병렬 검색으로 라우팅
+    subgraph.add_conditional_edges("refine_search", initiate_parallel_search_worker)
     subgraph.add_edge("generate_answer", END)
     
     return subgraph.compile()
 
 
-def route_after_plan(state: AgentState):
-    """
-    create_plan 결과에 따라 다음 노드를 결정합니다.
-    
-    Returns:
-        - "handle_too_many_questions": 질문 3개 이상
-        - "single_question_subgraph": 단일 주제 (1회 실행)
-        - List[Send]: 다중 질문 (N회 병렬 실행)
-    """
-    plan = state.plan or {}
-    case = plan.get("case", "single_topic")
-    
-    if case == "too_many":
-        return "handle_too_many_questions"
-    
-    elif case == "multiple_questions":
-        # 다중 질문: Send API로 서브그래프를 여러 번 호출
-        sub_questions = plan.get("sub_questions", [])
-        messages = state.messages
-        
-        logger.info("다중 질문 처리: %d개 질문을 서브그래프로 병렬 실행", len(sub_questions))
-        
-        sends = []
-        for i, sq in enumerate(sub_questions):
-            worker_state = WorkerState(
-                processing_question=sq,
-                messages=messages,
-                
-                # 🔧 [FIX] 이름 변경된 필드로 매핑
-                worker_is_multi=True,
-                worker_idx=i,
-                worker_sub_text=sq,
-            )
-            sends.append(Send("single_question_subgraph", worker_state))
-        
-        return sends
-    
-    else:
-        # 단일 질문
-        worker_state = WorkerState(
-            processing_question=state.user_question,
-            messages=state.messages,
-            
-            # 🔧 [FIX] 기본값 매핑
-            worker_is_multi=False,
-            worker_idx=0,
-            worker_sub_text=None
-        )
-        return [Send("single_question_subgraph", worker_state)]
-
-
-def route_after_subgraph(state: AgentState) -> Literal["combine_answers", END]:
-    """
-    서브그래프 실행 후 다음 노드 결정.
-    
-    - multi_answers가 있으면: 다중 질문 모드 → combine_answers
-    - multi_answers가 없으면: 단일 질문 모드 → END
-    """
-    # multi_answers에 실제 데이터가 있는지 확인 (reset token 제외)
-    has_answers = any(
-        isinstance(item, dict) and item.get("__token__") != _MULTI_ANS_RESET_TOKEN
-        for item in state.multi_answers
-    )
-    
-    if has_answers:
-        logger.info("다중 질문 모드: combine_answers로 이동")
-        return "combine_answers"
-    else:
-        logger.info("단일 질문 모드: END로 이동")
-        return END
-
-
+# ------------------------------------------------------------------
+# 그래프 구성
+# ------------------------------------------------------------------
 def build_agent_graph() -> StateGraph:
-    """
-    CodeWeaver 에이전트의 메인 그래프를 구성합니다.
-    
-    전체 흐름 (단순화됨):
-    1. START → create_plan (질문 유형 및 개수 판단)
-    2. 질문 유형에 따른 분기:
-       - single_topic: single_question_subgraph (1회) → END
-       - multiple_questions: Send API로 single_question_subgraph (2회 병렬) → combine_answers → END
-       - too_many: handle_too_many_questions → END
-    
-    핵심 개선사항:
-    - ✅ 단일 질문 파이프라인을 재사용 가능한 서브그래프로 추출
-    - ✅ 부모 그래프는 계획/분기/병합만 담당
-    - ✅ 복잡한 worker 노드 제거
-    - ✅ 코드 중복 제거
-    - ✅ 구조 명확화: 부모(orchestration) vs 자식(processing)
-    
-    Returns:
-        구성된 StateGraph (컴파일 전)
-    """
-    # 메인 그래프 생성
     graph = StateGraph(AgentState)
-    
-    # 노드 추가
     graph.add_node("create_plan", create_plan_node)
     graph.add_node("handle_too_many_questions", handle_too_many_questions_node)
     graph.add_node("combine_answers", combine_answers_node)
     
-    # 서브그래프를 노드로 등록
     single_question_subgraph = build_single_question_subgraph()
     graph.add_node("single_question_subgraph", single_question_subgraph)
     
-    # ===== 엣지 구성 =====
-    
-    # 1. START → create_plan
     graph.add_edge(START, "create_plan")
-    
-    # 2. create_plan → 분기
-    #    - single_topic: "single_question_subgraph" → END
-    #    - multiple_questions: List[Send("single_question_subgraph", WorkerState)] → combine_answers
-    #    - too_many: "handle_too_many_questions" → END
     graph.add_conditional_edges("create_plan", route_after_plan)
-    
-    # 3. handle_too_many_questions → END
     graph.add_edge("handle_too_many_questions", END)
     
-    # 4. 🔧 FIX: single_question_subgraph의 출구를 명확히 분리
-    #    - 단일 질문 (case=single_topic): 무조건 END
-    #    - 다중 질문 (case=multiple_questions): Send API가 자동으로 combine_answers로 fan-in
-    
-    # 4-1. 단일 질문 경로: single_question_subgraph → END
-    # 4-2. 다중 질문 경로: single_question_subgraph → combine_answers (자동 fan-in)
-    
-    # 🔧 해결책: conditional edges로 분기
     graph.add_conditional_edges(
         "single_question_subgraph",
         route_after_subgraph,
@@ -383,38 +129,51 @@ def build_agent_graph() -> StateGraph:
             END: END,
         }
     )
-    
-    # 5. combine_answers → END
     graph.add_edge("combine_answers", END)
-    
     return graph
 
 
-def create_agent(enable_checkpointing: bool = True):
+# ------------------------------------------------------------------
+# 3. 에이전트 생성 (동기 DB 연결 - Windows 호환성 해결)
+# ------------------------------------------------------------------
+
+# 전역 변��
+_agent: Optional[Runnable] = None
+_pool: Optional[ConnectionPool] = None  # Sync Pool
+
+def get_agent() -> Runnable:
     """
-    CodeWeaver 에이전트를 생성하고 컴파일합니다.
-    
-    Args:
-        enable_checkpointing: 체크포인트 활성화 여부
-            - True: MemorySaver 사용 (개발/테스트용)
-            - False: 체크포인트 없이 실행 (상태 저장 불가)
-    
-    Returns:
-        컴파일된 실행 가능한 그래프
-    
-    Note:
-        프로덕션 환경에서는 MemorySaver 대신 
-        PostgresSaver, SqliteSaver 등 영구 저장소 사용 권장
+    동기 DB 풀을 사용하는 에이전트를 반환합니다.
+    주의: 함수 자체는 동기(def)이지만, 반환된 에이전트(CompiledGraph)는
+    ainvoke를 지원합니다 (DB 저장만 동기로 수행).
     """
-    graph = build_agent_graph()
+    global _agent, _pool
     
-    if enable_checkpointing:
-        # 메모리 기반 체크포인터 (프로덕션에서는 DB 사용 권장)
-        memory = MemorySaver()
-        return graph.compile(checkpointer=memory)
-    else:
-        return graph.compile()
+    if _agent is not None:
+        return _agent
 
+    logger.info("🔌 DB 연결 및 에이전트 초기화 중 (Sync Mode)...")
 
-# 에이전트 인스턴스 생성 (모듈 임포트 시 자동 생성)
-agent = create_agent(enable_checkpointing=True)
+    # 1. 그래프 빌드
+    graph = build_agent_graph()
+    
+    # 2. 동기 연결 풀 생성
+    # Windows ProactorLoop와 충돌하지 않음
+    safe_url = settings.postgres_db_url.split("@")[-1] if "@" in settings.postgres_db_url else "..."
+    logger.info(f"Target DB: {safe_url}")
+    
+    _pool = ConnectionPool(
+        conninfo=settings.postgres_db_url,
+        min_size=1,
+        max_size=20,
+        kwargs={"autocommit": True}
+    )
+    
+    # 3. 동기 체크포인터 연결
+    checkpointer = PostgresSaver(_pool)
+    
+    # 4. 컴파일
+    _agent = graph.compile(checkpointer=checkpointer)
+    
+    logger.info("✅ 에이전트 준비 완료")
+    return _agent

CodeWeaver/src/agent/nodes.py

@@ -1,1212 +0,0 @@
-"""
-CodeWeaver LangGraph 노드 구현.
-
-각 노드는 AgentState 또는 WorkerState를 받아 처리하고 업데이트된 상태를 반환합니다.
-모든 노드는 LangSmith를 통해 자동으로 추적됩니다.
-"""
-
-import asyncio
-import logging
-import os
-from typing import List, Literal, Optional, Union
-
-from langchain_core.messages import HumanMessage, SystemMessage, AIMessage
-from langchain_google_genai import ChatGoogleGenerativeAI
-from langgraph.graph import StateGraph, START, END
-from langgraph.types import Send
-
-from src.agent.state import AgentState, WorkerState, SearchResult
-from src.agent.state import _MULTI_ANS_RESET_TOKEN
-from src.tools.search_tools import (
-    search_github,
-    search_official_docs,
-    search_stackoverflow,
-)
-from src.utils.tracing import trace_node
-from src.vector_db.qdrant_client import QdrantManager
-
-logger = logging.getLogger(__name__)
-
-# LLM 초기화 (Gemini 2.5 Flash)
-llm = ChatGoogleGenerativeAI(
-    model="gemini-2.5-flash-lite",
-    temperature=0.7,
-)
-
-# Qdrant 매니저 초기화
-qdrant_manager = QdrantManager()
-
-
-# ==================== 부모 그래프 노드 (AgentState 사용) ====================
-
-@trace_node("create_plan")
-def create_plan_node(state: AgentState) -> dict:
-    """
-    질문을 분석하여 유형과 개수를 판단합니다.
-    
-    Case:
-    - single_topic: 하나의 주제 (서브그래프 1회)
-    - multiple_questions: 독립 질문 2개 (Send API로 서브그래프 2회 병렬)
-    - too_many: 독립 질문 3개 이상 (에러 메시지)
-    """
-    user_question = state.user_question
-    logger.info("질문 분석 및 계획 수립 중: %s", user_question[:50])
-
-    def _extract_question_candidates(text: str) -> List[str]:
-        """입력 문자열에서 '질문 후보'를 최대한 보수적으로 추출합니다(3개 이상 감지용)."""
-        import re
-
-        if not text:
-            return []
-
-        t = text.strip()
-        # 1) 물음표 기반 분리
-        parts = re.split(r"[??]+", t)
-        candidates = [p.strip() for p in parts if p.strip()]
-        if len(candidates) >= 2 and re.search(r"[??]", t):
-            return candidates
-
-        # 2) 줄바꿈/번호 매기기 기반
-        lines = [ln.strip() for ln in re.split(r"[\r\n]+", t) if ln.strip()]
-        numbered = []
-        for ln in lines:
-            if re.match(r"^\s*(\d+[\.\)]|[-*])\s+", ln):
-                numbered.append(re.sub(r"^\s*(\d+[\.\)]|[-*])\s+", "", ln).strip())
-        if len(numbered) >= 2:
-            return numbered
-
-        # 3) 구분자 기반(세미콜론)
-        semi = [p.strip() for p in t.split(";") if p.strip()]
-        if len(semi) >= 2:
-            return semi
-
-        return [t]
-
-    def _hard_guard_too_many(text: str) -> Optional[dict]:
-        """
-        하드 가드: 사용자가 '질문 3개 이상'을 한 번에 던진 것으로 확실한 경우,
-        LLM 분류와 무관하게 too_many로 강제합니다.
-        """
-        import re
-
-        if not text:
-            return None
-
-        # 가장 확실한 기준: 물음표가 3개 이상
-        qmarks = len(re.findall(r"[??]", text))
-        if qmarks >= 3:
-            candidates = _extract_question_candidates(text)
-            msg = "죄송합니다. 질문은 한 번에 최대 2개까지 가능합니다. 가장 중요한 2개만 골라서 다시 질문해 주세요."
-            return {
-                "case": "too_many",
-                "sub_questions": candidates,
-                "reasoning": f"물음표가 {qmarks}개로, 3개 이상의 독립 질문으로 판단했습니다.",
-                "error_message": msg,
-                "steps_note": f"⚠️ 질문 수 초과 감지(물음표 {qmarks}개) → too_many로 강제",
-            }
-
-        # 번호 매기기/리스트로 3개 이상
-        candidates = _extract_question_candidates(text)
-        if len(candidates) >= 3:
-            msg = "죄송합니다. 질문은 한 번에 최대 2개까지 가능합니다. 가장 중요한 2개만 골라서 다시 질문해 주세요."
-            return {
-                "case": "too_many",
-                "sub_questions": candidates,
-                "reasoning": f"질문 후보가 {len(candidates)}개로 감지되어 3개 이상 질문으로 판단했습니다.",
-                "error_message": msg,
-                "steps_note": f"⚠️ 질문 수 초과 감지(후보 {len(candidates)}개) → too_many로 강제",
-            }
-
-        return None
-
-    # 하드 가드(결정론적) – LLM이 잘못 분류하더라도 3개 이상이면 무조건 차단
-    hard = _hard_guard_too_many(user_question)
-    if hard:
-        steps_delta = [
-            f"📋 계획 타입: {hard['case']}",
-            f"   서브질문: {len(hard['sub_questions'])}개",
-            f"   이유: {hard['reasoning']}",
-            hard["steps_note"],
-        ]
-        logger.info("계획 수립 완료(하드 가드): too_many, %d개 서브질��", len(hard["sub_questions"]))
-        return {
-            "plan": {
-                "case": hard["case"],
-                "sub_questions": hard["sub_questions"],
-                "reasoning": hard["reasoning"],
-                "error_message": hard["error_message"],
-            },
-            "is_multi_question": False,
-            "sub_question_index": 0,
-            "sub_question_text": None,
-            "original_multi_question": None,
-            "multi_answers": [{"__token__": _MULTI_ANS_RESET_TOKEN}],
-            "intermediate_steps": steps_delta,
-        }
-    
-    plan_prompt = f"""질문을 분석하여 유형과 개수를 판단하세요.
-
-질문: {user_question}
-
-**중요**: sub_questions의 용도는 case에 따라 다릅니다!
-
-**Case 1: single_topic** (하나의 주제)
-- 예: "Spring Security JWT 인증 구현"
-  → sub_questions: ["개념", "구현", "예제"]
-  → 용도: 답변 섹션 구조 (검색은 원본 질문으로 1회만)
-  → 검색: "Spring Security JWT 인증 구현"
-
-- 예: "React hooks 완벽 가이드"
-  → sub_questions: ["hooks란", "주요 hooks", "실무 패턴"]
-  → 용도: 답변 섹션 구조
-  → 검색: "React hooks 완벽 가이드"
-
-**Case 2: multiple_questions** (여러 독립 질문, 최대 2개)
-- 예: "JWT가 뭐야? CORS는?"
-  → sub_questions: ["JWT가 뭐야?", "CORS는?"]
-  → 용도: 각 질문마다 별도 검색
-  → 검색: "JWT가 뭐야?" (1회), "CORS는?" (1회)
-
-- 예: "Docker 사용법은? Redis 설치는?"
-  → sub_questions: ["Docker 사용법은?", "Redis 설치는?"]
-  → 용도: 각 질문마다 별도 검색
-
-**Case 3: too_many** (3개 이상 질문)
-- 예: "JWT? CORS? Docker?"
-  → 너무 많아서 처리 불가
-  → error_message 제공
-
-규칙:
-- single_topic: sub_questions는 짧은 키워드/구절 (1-5개)
-- multiple_questions: sub_questions는 완전한 문장 (정확히 2개만)
-- too_many: 3개 이상이면 이 케이스로 분류
-
-다음 JSON 형식으로만 답변하세요:
-{{
-    "case": "single_topic|multiple_questions|too_many",
-    "sub_questions": [...],
-    "reasoning": "이 케이스로 판단한 이유",
-    "error_message": "..." (too_many인 경우만, 그 외는 빈 문자열)
-}}
-
-JSON 외에 다른 텍스트는 포함하지 마세요."""
-
-    try:
-        import json
-        
-        messages_to_llm = [HumanMessage(content=plan_prompt)]
-        response = llm.invoke(messages_to_llm)
-        
-        # JSON 파싱
-        response_text = response.content.strip()
-        
-        # JSON 블록 추출
-        if "```json" in response_text:
-            response_text = response_text.split("```json")[1].split("```")[0].strip()
-        elif "```" in response_text:
-            response_text = response_text.split("```")[1].split("```")[0].strip()
-        
-        plan_data = json.loads(response_text)
-        
-        case = plan_data.get("case", "single_topic")
-        sub_questions = plan_data.get("sub_questions", [user_question])
-        reasoning = plan_data.get("reasoning", "")
-        error_message = plan_data.get("error_message", "")
-
-        # LLM 결과를 받은 뒤에도 한 번 더 하드 가드 적용 (안전장치)
-        hard2 = _hard_guard_too_many(user_question)
-        if hard2:
-            case = hard2["case"]
-            sub_questions = hard2["sub_questions"]
-            reasoning = hard2["reasoning"]
-            error_message = hard2["error_message"]
-        
-        # 유효성 검증
-        if not sub_questions or len(sub_questions) == 0:
-            sub_questions = [user_question]
-            case = "single_topic"
-        
-        # multiple_questions일 때 2개 제한 강제
-        if case == "multiple_questions" and len(sub_questions) > 2:
-            sub_questions = sub_questions[:2]
-            reasoning += " (질문 수 제한: 최대 2개)"
-        
-        steps_delta = [
-            f"📋 계획 타입: {case}",
-            f"   서브질문: {len(sub_questions)}개",
-            f"   이유: {reasoning}"
-        ]
-        
-        logger.info("계획 수립 완료: %s, %d개 서브질문", case, len(sub_questions))
-        
-        return {
-            "plan": {
-                "case": case,
-                "sub_questions": sub_questions,
-                "reasoning": reasoning,
-                "error_message": error_message
-            },
-            "is_multi_question": False,
-            "sub_question_index": 0,
-            "sub_question_text": None,
-            "original_multi_question": None,
-            "multi_answers": [{"__token__": _MULTI_ANS_RESET_TOKEN}],
-            "intermediate_steps": steps_delta
-        }
-        
-    except Exception as e:
-        logger.error("계획 수립 실패: %s", e, exc_info=True)
-        
-        # 기본값: 원본 질문 그대로 사용
-        steps_delta = [
-            "⚠️ 계획 수립 실패, 기본값 사용: single_topic"
-        ]
-        
-        return {
-            "plan": {
-                "case": "single_topic",
-                "sub_questions": [user_question],
-                "reasoning": "계획 수립 실패, 기본값 사용",
-                "error_message": ""
-            },
-            "is_multi_question": False,
-            "sub_question_index": 0,
-            "sub_question_text": None,
-            "original_multi_question": None,
-            "multi_answers": [{"__token__": _MULTI_ANS_RESET_TOKEN}],
-            "intermediate_steps": steps_delta
-        }
-
-
-@trace_node("handle_too_many_questions")
-def handle_too_many_questions_node(state: AgentState) -> dict:
-    """3개 이상 질문 시 안내 메시지를 반환합니다."""
-    plan = state.plan or {}
-    error_message = plan.get("error_message", "")
-    sub_questions = plan.get("sub_questions", [])
-    
-    logger.info("질문 수 초과: %d개", len(sub_questions))
-    
-    default_message = """죄송합니다. 한 번에 최대 2개의 질문까지만 처리할 수 있습니다.
-
-다음 중 하나를 선택해서 다시 질문해 주세요:
-
-1. **하나의 주제로 통합해서 질문**
-   예: "JWT 인증과 CORS 설정을 함께 구현하는 방법"
-
-2. **가장 중요한 2개 질문만 선택**
-   예: "JWT가 뭐야? 내 코드에 어떻게 적용해?"
-
-3. **질문을 나눠서 순차적으로 질문**
-   예: 먼저 "JWT가 뭐야?" 질문 → 답변 확인 → 다음 질문
-
-어떻게 도와드릴까요?"""
-    
-    final_message = error_message if error_message else default_message
-    
-    steps_delta = [
-        f"⚠️ 질문 수 초과: {len(sub_questions)}개",
-        "💬 안내 메시지 제공 (대화 계속 가능)"
-    ]
-    
-    return {
-        "final_answer": final_message,
-        "intermediate_steps": steps_delta
-    }
-
-
-@trace_node("combine_answers")
-def combine_answers_node(state: AgentState) -> dict:
-    """
-    Fan-in: 모든 Send가 완료되면 multi_answers를 조합합니다.
-    """
-    answers = state.multi_answers
-    original_question = state.original_multi_question or state.user_question
-    
-    if not answers:
-        logger.error("다중 답변이 비어있음")
-        return {
-            "final_answer": "답변 생성에 실패했습니다. 다시 시도해 주세요.",
-            "intermediate_steps": ["❌ multi_answers 비어있음"]
-        }
-    
-    # 인덱스 순으로 정렬
-    answers.sort(key=lambda x: x["index"])
-    
-    # Markdown 형식으로 조합
-    combined_parts = []
-    for ans in answers:
-        section = f"""## {ans['index']+1}. {ans['question']}
-
-{ans['answer']}"""
-        combined_parts.append(section)
-    
-    combined = "\n\n---\n\n".join(combined_parts)
-    
-    # 헤더 추가
-    header = f"# 다중 질문 답변\n\n원본 질문: {original_question}\n\n---\n\n"
-    final_combined = header + combined
-    
-    logger.info("다중 답변 조합 완료: %d개", len(answers))
-    
-    return {
-        "final_answer": final_combined,
-        "intermediate_steps": [f"✅ {len(answers)}개 답변 조합 완료"]
-    }
-
-
-# ==================== 서브그래프 노드 (WorkerState 사용) ====================
-
-@trace_node("analyze_question")
-async def analyze_question_node(state: Union[AgentState, WorkerState]) -> dict:
-    """
-    질문을 분석하여 유형을 분류하고 캐시 적격성을 판단합니다.
-    
-    🔧 FIX: 다중 질문 모드일 때는 messages를 무시하고 독립 질문으로만 분석
-    """
-    # 🔧 [FIX] WorkerState일 경우 processing_question 사용
-    if isinstance(state, WorkerState):
-        user_question = state.processing_question
-        # 🔧 [FIX] 이름 변경된 필드 사용
-        is_multi = state.worker_is_multi
-    else:
-        user_question = state.user_question
-        is_multi = getattr(state, 'is_multi_question', False)
-        
-    messages = state.messages
-    
-    # 대화 맥락 구성 (다중 질문 모드가 아닐 때만)
-    has_history = messages and len(messages) > 1 and not is_multi
-    context_info = ""
-    
-    if has_history:
-        context_info = "\n이전 대화 맥락:\n"
-        for msg in messages[-4:-1]:
-            if hasattr(msg, 'type') and hasattr(msg, 'content'):
-                role = "사용자" if msg.type == "human" else "AI"
-                context_info += f"{role}: {msg.content[:100]}\n"
-    
-    # 🔧 다중 질문 모드 강제 처리
-    if is_multi:
-        context_info = "\n⚠️ 주의: 이 질문은 다중 질문의 일부입니다. 독립적인 질문으로만 판단하세요.\n"
-    
-    analysis_prompt = f"""질문을 분석하여 유형을 분류하고, 캐시 적격성을 판단하세요.
-
-{context_info}
-현재 질문: {user_question}
-
-분류 기준:
-
-1. **clarification** (보충/형식 변경 요청)
-   - 이전 답변/대화 내용을 바탕으로 "설명 방식"을 바꾸거나 보충을 요청
-   - 예: "좀 더 쉽게 설명해줘", "예제 코드로 보여줘", "한 줄로 요약해줘"
-   - should_cache = false, canonical_question = null
-   
-2. **new_topic** (대화 중 새 개념 질문)
-   - 대화가 이어지는 중이지만, 질문 자체가 독립적으로 성립하는 '새 개념/정의/비교/사용법' 질문
-   - 예: "Event Listener는 뭐야?", "CORS가 뭐야?"
-   - should_cache = true, canonical_question 생성
-   
-3. **independent** (완전 독립 질문)
-   - 이전 대화 없이도 이해 가능한 일반 질문
-   - 예: "Spring Security가 뭐야?", "Docker Compose 사용법은?"
-   - should_cache = true, canonical_question 생성
-
-다음 JSON 형식으로만 답변하세요:
-{{
-    "question_type": "clarification|new_topic|independent",
-    "should_cache": true|false,
-    "reasoning": "분류 이유 1-2문장",
-    "canonical_question": "캐시할 정규화된 질문 (should_cache가 true인 경우에만, 아니면 null)"
-}}
-
-JSON 외에 다른 텍스트는 포함하지 마세요."""
-
-    try:
-        messages_to_llm = [HumanMessage(content=analysis_prompt)]
-        response = llm.invoke(messages_to_llm)
-        
-        import json
-        response_text = response.content.strip()
-        
-        if "```json" in response_text:
-            response_text = response_text.split("```json")[1].split("```")[0].strip()
-        elif "```" in response_text:
-            response_text = response_text.split("```")[1].split("```")[0].strip()
-        
-        analysis = json.loads(response_text)
-        
-        question_type = analysis.get("question_type", "independent")
-        should_cache = analysis.get("should_cache", False)
-        reasoning = analysis.get("reasoning", "")
-        canonical_question = analysis.get("canonical_question", user_question)
-        
-        # 유효성 검증
-        if question_type not in ["clarification", "new_topic", "independent"]:
-            question_type = "independent"
-
-        # 🔧 CRITICAL: 다중 질문 모드일 때는 무조건 independent로 강제
-        if is_multi and question_type == "clarification":
-            logger.warning("다중 질문 모드에서 clarification 감지 → independent로 강제 변경")
-            question_type = "independent"
-            should_cache = True
-            reasoning = "다중 질문 모드: 독립 질문으로 강제 분류"
-
-        # 정책 보정
-        if question_type == "clarification":
-            should_cache = False
-            canonical_question = None
-        else:
-            if canonical_question is None or (isinstance(canonical_question, str) and not canonical_question.strip()):
-                canonical_question = user_question
-        
-        steps_delta = [
-            "__RESET_STEPS__",
-            f"🔍 질문 분석: {question_type} (캐시 여부: {should_cache})",
-        ]
-        
-        return {
-            "question_type": question_type,
-            "should_cache": should_cache,
-            "analysis_reasoning": reasoning,
-            "canonical_question": canonical_question if should_cache else None,
-            "intermediate_steps": steps_delta
-        }
-        
-    except Exception as e:
-        logger.error("질문 분석 실패: %s", e, exc_info=True)
-        
-        steps_delta = [
-            "__RESET_STEPS__",
-            "⚠️ 질문 분석 실패, 기본값 사용: independent",
-        ]
-        
-        return {
-            "question_type": "independent",
-            "should_cache": True,
-            "analysis_reasoning": "분석 실패, 기본값 사용",
-            "canonical_question": user_question,
-            "intermediate_steps": steps_delta
-        }
-
-
-@trace_node("check_cache")
-async def check_cache_node(state: Union[AgentState, WorkerState]) -> dict:
-    """벡터 DB 캐시에서 유사한 질문을 검색합니다."""
-    # 🔧 [FIX] 변수 접근 수정
-    current_q = state.processing_question if isinstance(state, WorkerState) else state.user_question
-    question_for_lookup = state.canonical_question or current_q
-    logger.info("캐시 확인 중: %s", question_for_lookup[:50])
-    
-    try:
-        cached_result = await qdrant_manager.search_cache(
-            question=question_for_lookup,
-            threshold=0.85
-        )
-        
-        updates = {}
-        steps_delta: List[str] = []
-        
-        if cached_result:
-            updates["cached_result"] = cached_result
-            steps_delta.append(f"✅ 캐시 히트 (답변 길이: {len(cached_result)}자)")
-            logger.info("캐시 히트")
-        else:
-            updates["cached_result"] = None
-            steps_delta.append("❌ 캐시 미스: 새로운 검색 필요")
-            logger.info("캐시 미스")
-    
-    except Exception as e:
-        logger.error("캐시 확인 실패: %s", e, exc_info=True)
-        updates["cached_result"] = None
-        steps_delta.append(f"⚠️ 캐시 확인 오류: {str(e)}")
-    
-    updates["intermediate_steps"] = steps_delta
-    return updates
-
-
-@trace_node("return_cached_answer")
-def return_cached_answer_node(state: Union[AgentState, WorkerState]) -> dict:
-    """캐시 히트 시 저장된 답변을 반환합니다."""
-    logger.info("캐시된 답변 반환")
-    
-    cached_answer = state.cached_result
-    is_multi = isinstance(state, WorkerState) and state.worker_is_multi
-    
-    if is_multi:
-        return {
-            "multi_answers": [{
-                "index": state.worker_idx,
-                "question": state.worker_sub_text or state.processing_question,
-                "answer": cached_answer
-            }]
-        }
-    else:
-        # 🔧 [FIX] messages에 AIMessage 추가하여 히스토리 저장 보장
-        steps_delta = ["💾 캐시된 답변 반환 (검색 생략)"]
-        return {
-            "final_answer": cached_answer,
-            "messages": [AIMessage(content=cached_answer)], # 👈 핵심 수정
-            "intermediate_steps": steps_delta
-        }
-
-
-@trace_node("generate_with_history")
-async def generate_with_history_node(state: Union[AgentState, WorkerState]) -> dict:
-    """
-    대화 히스토리만 사용하여 후속 질문에 답변합니다.
-    
-    수정 사항:
-    1. 문맥 오염 방지: 바로 직전의 대화(질문+답변)만 참조하도록 슬라이싱 적용
-    2. 히스토리 저장: AIMessage 반환 추가 (대화 끊김 방지)
-    """
-    # 1. 현재 질문 추출
-    user_question = state.processing_question if isinstance(state, WorkerState) else state.user_question
-    messages_history = state.messages
-    
-    logger.info("대화 히스토리 기반 답변 생성: %s", user_question[:50])
-    
-    # 2. 대화 맥락 구성 (Context Pollution 방지)
-    context_prompt = "이전 대화를 참고하여 후속 질문에 답변하세요.\n\n"
-    
-    # [핵심] 현재 질문을 제외한 과거 기록 중 '가장 최근 2개(직전 질문+답변)'만 참조
-    prev_messages = messages_history[:-1] if messages_history else []
-    recent_context = prev_messages[-2:] if prev_messages else []
-    
-    if recent_context:
-        context_prompt += "직전 대화 내역:\n"
-        for msg in recent_context:
-            if hasattr(msg, 'type') and hasattr(msg, 'content'):
-                role = "사용자" if msg.type == "human" else "AI"
-                context_prompt += f"{role}: {msg.content}\n\n"
-    
-    context_prompt += f"현재 질문: {user_question}\n\n"
-    context_prompt += "위의 '직전 대화 내역'에만 집중하여 답변하세요. 그 외의 이전 주제나 불필요한 맥락은 언급하지 마세요."
-    
-    updates = {}
-    steps_delta: List[str] = []
-    
-    try:
-        # 3. LLM 호출
-        response = llm.invoke([HumanMessage(content=context_prompt)])
-        final_answer = response.content.strip()
-        
-        # 4. 상태 업데이트
-        is_multi = isinstance(state, WorkerState) and state.worker_is_multi
-        
-        if is_multi:
-            # 다중 질문 모드 (예외적 상황)
-            return {
-                "multi_answers": [{
-                    "index": state.worker_idx,
-                    "question": state.worker_sub_text or user_question,
-                    "answer": final_answer
-                }]
-            }
-        else:
-            # 단일 질문 모드 (정상 케이스)
-            updates["final_answer"] = final_answer
-            # [핵심] 대화 히스토리에 AI 답변을 추가하여 다음 턴에서 참조 가능하게 함
-            updates["messages"] = [AIMessage(content=final_answer)]
-            
-            steps_delta.append(f"💬 대화 히스토리 기반 답변 생성 (길이: {len(final_answer)}자)")
-            steps_delta.append("⚠️ 캐시 저장 생략 (보충 요청)")
-            
-            logger.info("대화 히스토리 기반 답변 생성 완료")
-        
-    except Exception as e:
-        logger.error("대화 히스토리 기반 답변 생성 실패: %s", e, exc_info=True)
-        
-        if is_multi:
-            return {
-                "multi_answers": [{
-                    "index": state.worker_idx,
-                    "question": state.worker_sub_text or user_question,
-                    "answer": "답변 생성에 실패했습니다. 다시 시도해 주세요."
-                }]
-            }
-        else:
-            updates["final_answer"] = "답변 생성에 실패했습니다. 다시 시도해 주세요."
-            steps_delta.append(f"❌ 답변 생성 실패: {str(e)}")
-    
-    updates["intermediate_steps"] = steps_delta
-    return updates
-
-
-@trace_node("classify_intent")
-def classify_intent_node(state: Union[AgentState, WorkerState]) -> dict:
-    """
-    LLM을 사용하여 사용자 질문의 의도를 분류합니다.
-    
-    🔧 CRITICAL:
-    - refined_question이 있으면 그것을 사용, 없으면 user_question 사용
-    - WorkerState 필드만 반환 (부모 AgentState와 충돌 방지)
-    - ❌ 절대 반환하면 안 되는 것들: user_question, messages
-    """
-    # 🔧 [FIX] 변수 접근 수정
-    current_q = state.processing_question if isinstance(state, WorkerState) else state.user_question
-    question_to_classify = state.refined_question if hasattr(state, 'refined_question') and state.refined_question else current_q
-    
-    logger.info("의도 분류 중: %s", question_to_classify[:50])
-    
-    classification_prompt = f"""질문을 다음 세 가지 의도 중 하나로 분류하세요:
-
-1. debugging: 에러 해결, 버그 수정, 문제 해결
-2. learning: 개념 학습, 원리 이해, 튜토리얼
-3. code_review: 코드 개선, 리팩토링, 베스트 프랙티스
-
-질문: {question_to_classify}
-
-반드시 debugging, learning, code_review 중 하나만 답하세요."""
-
-    updates = {}
-    steps_delta: List[str] = []
-    
-    try:
-        messages = [
-            SystemMessage(content="당신은 개발자 질문을 분류하는 전문가입니다."),
-            HumanMessage(content=classification_prompt)
-        ]
-        
-        response = llm.invoke(messages)
-        intent_raw = response.content.strip().lower()
-        
-        # 유효한 의도로 정규화
-        valid_intents = ["debugging", "learning", "code_review"]
-        intent = next((i for i in valid_intents if i in intent_raw), "learning")
-        
-        updates["detected_intent"] = intent
-        steps_delta.append(f"🎯 의도 분류: {intent}")
-        logger.info("의도 분류 완료: %s", intent)
-        
-    except Exception as e:
-        logger.error("의도 분류 실패: %s", e, exc_info=True)
-        updates["detected_intent"] = "learning"
-        steps_delta.append("⚠️ 의도 분류 실패, 기본값 사용: learning")
-    
-    updates["intermediate_steps"] = steps_delta
-    
-    # 🔧 CRITICAL: WorkerState 필드만 반환
-    # ✅ OK: detected_intent, intermediate_steps
-    # ❌ 절대 반환하면 안 됨: user_question, messages
-    return updates
-
-
-@trace_node("search_stackoverflow")
-def search_stackoverflow_node(state: Union[AgentState, WorkerState]) -> dict:
-    """Stack Overflow에서 검색을 수행합니다."""
-    # 🔧 [FIX] 변수 접근 수정
-    current_q = state.processing_question if isinstance(state, WorkerState) else state.user_question
-    question_to_use = state.refined_question if hasattr(state, 'refined_question') and state.refined_question else current_q
-    
-    intent = state.detected_intent or "learning"
-    count = 5 if intent == "debugging" else 3
-    
-    logger.info("Stack Overflow 검색 시작: %d개", count)
-    
-    try:
-        results = search_stackoverflow(question_to_use, count)
-        logger.info("Stack Overflow에서 %d개 결과 수집", len(results))
-        
-        # 🔧 FIX: intermediate_steps 제거
-        return {
-            "search_results": results,
-            # intermediate_steps 제거! (병렬 충돌 방지)
-        }
-    except Exception as e:
-        logger.error("Stack Overflow 검색 실패: %s", e)
-        return {}
-
-
-@trace_node("search_github")
-def search_github_node(state: Union[AgentState, WorkerState]) -> dict:
-    """GitHub Issues/Discussions에서 검색을 수행합니다."""
-    # 🔧 [FIX] 변수 접근 수정
-    current_q = state.processing_question if isinstance(state, WorkerState) else state.user_question
-    question_to_use = state.refined_question if hasattr(state, 'refined_question') and state.refined_question else current_q
-    
-    intent = state.detected_intent or "learning"
-    count = 5 if intent == "code_review" else 3 if intent == "learning" else 2
-    
-    logger.info("GitHub 검색 시작: %d개", count)
-    
-    try:
-        results = search_github(question_to_use, count)
-        logger.info("GitHub에서 %d개 결과 수집", len(results))
-        
-        # 🔧 FIX: intermediate_steps 제거
-        return {
-            "search_results": results,
-            # intermediate_steps 제거! (병렬 충돌 방지)
-        }
-    except Exception as e:
-        logger.error("GitHub 검색 실패: %s", e)
-        return {}
-
-
-@trace_node("search_official_docs")
-def search_official_docs_node(state: Union[AgentState, WorkerState]) -> dict:
-    """공식 문서/Tavily에서 검색을 수행합니다."""
-    # 🔧 [FIX] 변수 접근 수정
-    current_q = state.processing_question if isinstance(state, WorkerState) else state.user_question
-    question_to_use = state.refined_question if hasattr(state, 'refined_question') and state.refined_question else current_q
-    
-    intent = state.detected_intent or "learning"
-    count = 5 if intent == "learning" else 2
-    
-    logger.info("공식 문서 검색 시작: %d개", count)
-    
-    try:
-        results = search_official_docs(question_to_use, count)
-        logger.info("공식 문서에서 %d개 결과 수집", len(results))
-        
-        # 🔧 FIX: intermediate_steps 제거
-        return {
-            "search_results": results,
-            # intermediate_steps 제거! (병렬 충돌 방지)
-        }
-    except Exception as e:
-        logger.error("공식 문서 검색 실패: %s", e)
-        return {}
-
-
-@trace_node("collect_results")
-def collect_results_node(state: Union[AgentState, WorkerState]) -> dict:
-    """병렬 검색 결과를 수집하고 카운트합니다."""
-    total_results = len(state.search_results)
-    
-    logger.info("검색 결과 수집 완료: %d개", total_results)
-    
-    # 🔧 FIX: 로그만 찍고, intermediate_steps는 업데이트하지 않음
-    # (병렬 노드에서 intermediate_steps 업데이트 시 충돌 발생)
-    
-    return {}  # 빈 딕셔너리 반환 (상태 변경 없음)
-
-
-@trace_node("evaluate_results")
-def evaluate_results_node(state: Union[AgentState, WorkerState]) -> dict:
-    """검색 결과의 개수와 품질을 모두 평가합니다."""
-    search_results = state.search_results
-    refinement_count = state.refinement_count
-    
-    result_count = len(search_results)
-    
-    logger.info("검색 결과 평가: %d개 (개선 횟수: %d)", result_count, refinement_count)
-    
-    # 안전장치: 이미 1회 개선했으면 더 이상 개선하지 않음
-    if refinement_count >= 1:
-        steps_delta = [
-            f"⚠️ 최대 개선 횟수 도달 ({refinement_count}회), 현재 결과로 진행"
-        ]
-        return {
-            "needs_refinement": False,
-            "intermediate_steps": steps_delta
-        }
-    
-    # 1차 평가: 개수
-    if result_count < 2:
-        steps_delta = [
-            f"⚠️ 검색 결과 부족 ({result_count}개 < 2개), 쿼리 개선 필요"
-        ]
-        return {
-            "needs_refinement": True,
-            "intermediate_steps": steps_delta
-        }
-    
-    # 2차 평가: 품질
-    scored_results = [r for r in search_results if r.relevance_score is not None]
-    
-    if scored_results:
-        avg_score = sum(r.relevance_score for r in scored_results) / len(scored_results)
-        
-        if avg_score < 0.5:
-            steps_delta = [
-                f"⚠️ 검색 결과 품질 부족 (평균 점수: {avg_score:.2f} < 0.5), 쿼리 개선 필요"
-            ]
-            return {
-                "needs_refinement": True,
-                "intermediate_steps": steps_delta
-            }
-        
-        steps_delta = [
-            f"✅ 검색 결과 충분 ({result_count}개, 평균 점수: {avg_score:.2f}), 필터링 단계로 진행"
-        ]
-    else:
-        steps_delta = [
-            f"✅ 검색 결과 충분 ({result_count}개), 필터링 단계로 진행"
-        ]
-    
-    return {
-        "needs_refinement": False,
-        "intermediate_steps": steps_delta
-    }
-
-
-@trace_node("refine_search")
-def refine_search_node(state: Union[AgentState, WorkerState]) -> dict:
-    """
-    검색 쿼리를 개선합니다.
-    
-    🔧 CRITICAL: 
-    - user_question을 직접 업데이트하지 않고, refined_question에 저장
-    - 부모 AgentState와 충돌 방지를 위해 WorkerState 필드만 반환
-    - ❌ 절대 반환하면 안 되는 것들: user_question, messages, final_answer
-    """
-    # 🔧 [FIX] 변수 접근 수정
-    user_question = state.processing_question if isinstance(state, WorkerState) else state.user_question
-    original_question = state.original_question or user_question
-    result_count = len(state.search_results)
-    
-    logger.info("검색 쿼리 개선 중: %s (%d개 결과)", user_question[:50], result_count)
-    
-    refinement_prompt = f"""검색 결과가 부족합니다. 검색 쿼리를 개선하세요.
-
-원본 질문: {user_question}
-현재 결과 수: {result_count}개 (목표: 2개 이상)
-
-개선 전략 (하나 선택):
-1. MORE_SPECIFIC: 기술적 세부사항 추가
-2. MORE_GENERAL: 더 넓은 용어 사용
-3. TRANSLATE: 언어 변환
-
-다음 JSON 형식으로만 답변하세요:
-{{
-    "new_query": "개선된 검색 쿼리",
-    "strategy": "MORE_SPECIFIC|MORE_GENERAL|TRANSLATE",
-    "reasoning": "이 전략을 선택한 이유 1-2문장"
-}}
-
-JSON 외에 다른 텍스트는 포함하지 마세요."""
-
-    try:
-        import json
-        
-        messages_to_llm = [HumanMessage(content=refinement_prompt)]
-        response = llm.invoke(messages_to_llm)
-        
-        response_text = response.content.strip()
-        if "```json" in response_text:
-            response_text = response_text.split("```json")[1].split("```")[0].strip()
-        elif "```" in response_text:
-            response_text = response_text.split("```")[1].split("```")[0].strip()
-        
-        refinement_data = json.loads(response_text)
-        
-        new_query = refinement_data.get("new_query", user_question)
-        strategy = refinement_data.get("strategy", "MORE_GENERAL")
-        reasoning = refinement_data.get("reasoning", "")
-        
-        steps_delta = [
-            f"🔄 쿼리 개선: {strategy}",
-            f"   이전: {user_question[:50]}...",
-            f"   이후: {new_query[:50]}...",
-            f"   이유: {reasoning}"
-        ]
-        
-        logger.info("쿼리 개선 완료: %s → %s", user_question[:30], new_query[:30])
-        
-        # 🔧 CRITICAL: WorkerState 필드만 반환 (부모 AgentState와 충돌 방지)
-        return {
-            "refined_question": new_query,      # ✅ WorkerState 필드
-            "original_question": original_question,  # ✅ WorkerState 필드
-            "refinement_count": state.refinement_count + 1,  # ✅ WorkerState 필드
-            "search_results": [],  # ✅ WorkerState 필드 (reducer 있음)
-            "intermediate_steps": steps_delta  # ✅ WorkerState 필드
-            
-            # ❌ 절대 반환하면 안 되는 것들:
-            # "user_question": ...,   # 부모 AgentState와 충돌!
-            # "messages": ...,        # 부모 AgentState와 충돌!
-            # "final_answer": ...,    # 너무 이른 시점!
-        }
-        
-    except Exception as e:
-        logger.error("쿼리 개선 실패: %s", e, exc_info=True)
-        
-        fallback_query = user_question + " tutorial example"
-        
-        steps_delta = [
-            f"⚠️ 쿼리 개선 실패, 기본 전략 사용",
-            f"   이후: {fallback_query}"
-        ]
-        
-        # 🔧 CRITICAL: WorkerState 필드만 반환
-        return {
-            "refined_question": fallback_query,  # ✅ WorkerState 필드
-            "original_question": original_question,  # ✅ WorkerState 필드
-            "refinement_count": state.refinement_count + 1,  # ✅ WorkerState 필드
-            "search_results": [],  # ✅ WorkerState 필드 (reducer 있음)
-            "intermediate_steps": steps_delta  # ✅ WorkerState 필드
-        }
-
-
-@trace_node("filter_and_score")
-def filter_and_score_node(state: Union[AgentState, WorkerState]) -> dict:
-    """검색 결과를 필터링하고 관련도 점수를 매깁니다."""
-    search_results = state.search_results
-    logger.info("검색 결과 필터링 중: %d개", len(search_results))
-    
-    # 기본 필터링
-    filtered = [
-        r for r in search_results
-        if r.content and len(r.content) >= 50 and r.url
-    ]
-    
-    logger.info("기본 필터링 후: %d개 결과", len(filtered))
-    
-    # 상위 5개 결과만 LLM으로 점수 매기기
-    # 🔧 [FIX] scoring_prompt 내부에서 질문 참조 시 수정
-    current_q = state.processing_question if isinstance(state, WorkerState) else state.user_question
-    
-    for result in filtered[:5]:
-        if result.relevance_score is None:
-            try:
-                scoring_prompt = f"""질문: {current_q}
-
-검색 결과: {result.content[:500]}
-
-이 검색 결과가 질문에 얼마나 관련이 있는지 0.0에서 1.0 사이의 점수로 평가하세요.
-점수만 숫자로 답하세요. (예: 0.8)"""
-
-                response = llm.invoke([HumanMessage(content=scoring_prompt)])
-                score_str = response.content.strip()
-                result.relevance_score = float(score_str)
-                
-            except Exception as e:
-                logger.warning("점수 매기기 실패: %s", e)
-                result.relevance_score = 0.5
-    
-    # 관련도 순으로 정렬
-    filtered.sort(key=lambda r: r.relevance_score or 0, reverse=True)
-    
-    # 상위 5개만 유지
-    top_results = filtered[:5]
-    
-    subtask_results = dict(state.subtask_results)
-    subtask_results["filtered_results"] = [r.model_dump() for r in top_results]
-    
-    steps_delta = [f"✂️ 필터링 완료: {len(top_results)}개 결과 선택"]
-    
-    logger.info("필터링 완료: %d개 결과", len(top_results))
-    
-    return {
-        "subtask_results": subtask_results,
-        "intermediate_steps": steps_delta
-    }
-
-
-@trace_node("summarize_results")
-def summarize_results_node(state: Union[AgentState, WorkerState]) -> dict:
-    """필터링된 각 검색 결과를 초보 개발자가 이해하기 쉽게 요약합니다."""
-    subtask_results = state.subtask_results
-    filtered_results = subtask_results.get("filtered_results", [])
-    logger.info("검색 결과 요약 중: %d개", len(filtered_results))
-    
-    summaries = []
-    
-    for result_dict in filtered_results:
-        try:
-            summary_prompt = f"""다음 검색 결과를 초보 개발자가 이해하기 쉽게 2-3문장으로 요약하세요:
-
-출처: {result_dict['source']}
-내용: {result_dict['content'][:1000]}
-
-핵심 내용만 간단명료하게 요약하세요."""
-
-            response = llm.invoke([HumanMessage(content=summary_prompt)])
-            
-            summaries.append({
-                "source": result_dict['source'],
-                "url": result_dict['url'],
-                "summary": response.content.strip(),
-                "relevance": result_dict.get('relevance_score', 0.5)
-            })
-            
-        except Exception as e:
-            logger.error("요약 실패: %s", e)
-    
-    updated_subtask_results = dict(subtask_results)
-    updated_subtask_results["summaries"] = summaries
-    
-    steps_delta = [f"📝 요약 완료: {len(summaries)}개 결과"]
-    
-    logger.info("요약 완료: %d개", len(summaries))
-    
-    return {
-        "subtask_results": updated_subtask_results,
-        "intermediate_steps": steps_delta
-    }
-
-
-@trace_node("generate_answer")
-async def generate_answer_node(state: Union[AgentState, WorkerState]) -> dict:
-    """
-    요약된 정보를 바탕으로 최종 답변을 생성합니다.
-    
-    수정 사항:
-    1. 다중 질문 모드에서도 캐시 저장 로직이 실행되도록 순서 변경
-    2. 단일 질문 모드에서 AIMessage 반환 (히스토리 저장)
-    """
-    subtask_results = state.subtask_results
-    summaries = subtask_results.get("summaries", [])
-    intent = state.detected_intent or "learning"
-    
-    # 변수 접근
-    current_q = state.processing_question if isinstance(state, WorkerState) else state.user_question
-    
-    logger.info("최종 답변 생성 중: %s (질문: %s)", intent, current_q[:30])
-    
-    # 1. 의도별 프롬프트 템플릿
-    templates = {
-        "debugging": """다음 정보를 바탕으로 디버깅 질문에 답변하세요:
-
-질문: {question}
-
-수집된 정보:
-{summaries}
-
-답변 구조:
-1. 문제 정의
-2. 발생 원인
-3. 해결 방법 (코드 예제 포함)
-4. 주의사항
-5. 참고 자료
-
-초보 개발자도 이해할 수 있게 Markdown 형식으로 작성하세요.""",
-        
-        "learning": """다음 정보를 바탕으로 학습 질문에 답변하세요:
-
-질문: {question}
-
-수집된 정보:
-{summaries}
-
-답변 구조:
-1. 개념 설명 (간단명료)
-2. 동작 원리
-3. 예제 코드 (주석포함)
-4. 실무 활용 팁
-5. 추가 학습 자료
-
-초보 개발자도 이해할 수 있게 Markdown 형식으로 작성하세요.""",
-        
-        "code_review": """다음 정보를 바탕으로 코드 리뷰 질문에 답변하세요:
-
-질문: {question}
-
-수집된 정보:
-{summaries}
-
-답변 구조:
-1. 현재 접근 방식 분석
-2. 개선 포인트
-3. 리팩토링 예제
-4. 베스트 프랙티스
-5. 참고 패턴
-
-초보 개발자도 이해할 수 있게 Markdown 형식으로 작성하세요."""
-    }
-    
-    template = templates.get(intent, templates["learning"])
-    
-    # 2. 요약 텍스트 포맷팅
-    summaries_text = "\n\n".join([
-        f"출처: {s['source']} ({s['url']})\n요약: {s['summary']}"
-        for s in summaries
-    ])
-    
-    # 3. 이전 대화 맥락 추가 (Context Pollution 방지: 최근 1개만 참고용으로)
-    context_prefix = ""
-    messages_history = state.messages
-    if messages_history and len(messages_history) > 1:
-        # 검색 기반 답변이므로 이전 대화는 아주 최소한만 참조 (직전 1개)
-        prev_msg = messages_history[-2] if len(messages_history) >= 2 else None
-        if prev_msg:
-             context_prefix = f"이전 대화 맥락(참고): {prev_msg.content[:200]}...\n---\n"
-    
-    final_prompt = (context_prefix + template).format(
-        question=(state.original_question or current_q),
-        summaries=summaries_text
-    )
-    
-    updates = {}
-    steps_delta: List[str] = []
-    
-    try:
-        # 4. LLM 호출
-        response = llm.invoke([HumanMessage(content=final_prompt)])
-        final_answer = response.content.strip()
-        
-        # 5. 캐시 저장 로직 (DRY - 중복 방지 함수)
-        should_cache = state.should_cache if state.should_cache is not None else True
-        canonical_question = state.canonical_question
-        qtype = state.question_type or "independent"
-        question_to_cache = canonical_question or current_q
-
-        async def _try_cache_save():
-            """조건 충족 시 Qdrant에 캐시 저장"""
-            if should_cache and qtype in ["new_topic", "independent"]:
-                try:
-                    await qdrant_manager.save_to_cache(
-                        question=question_to_cache,
-                        answer=final_answer
-                    )
-                    logger.info("✅ 캐시 저장 완료: %s", question_to_cache[:30])
-                    return True
-                except Exception as cache_err:
-                    logger.error("캐시 저장 실패: %s", cache_err)
-                    return False
-            return False
-
-        # 6. 결과 반환 및 분기 처리
-        is_multi = isinstance(state, WorkerState) and state.worker_is_multi
-
-        if is_multi:
-            # [핵심] 다중 질문 모드: Return하기 '전에' 캐시 저장 시도
-            await _try_cache_save()
-            
-            logger.info("다중 질문 모드: 답변을 multi_answers에 추가")
-            return {
-                "multi_answers": [{
-                    "index": state.worker_idx,
-                    "question": state.worker_sub_text or current_q,
-                    "answer": final_answer
-                }]
-            }
-        
-        else:
-            # 단일 질문 모드
-            updates["final_answer"] = final_answer
-            # [핵심] 대화 히스토리에 AI 답변 추가
-            updates["messages"] = [AIMessage(content=final_answer)]
-            
-            # 캐시 저장 시도
-            saved = await _try_cache_save()
-            
-            if saved:
-                steps_delta.append(f"✅ 최종 답변 생성 완료 (길이: {len(final_answer)}자)")
-                steps_delta.append(f"💾 캐시 저장 완료 (질문: {question_to_cache[:50]}...)")
-            else:
-                steps_delta.append(f"✅ 최종 답변 생성 완료 (길이: {len(final_answer)}자)")
-                steps_delta.append("⚠️ 캐시 저장 생략 (독립적이지 않거나 일회성 질문)")
-                logger.info("최종 답변 생성 완료 (캐시 저장 생략)")
-            
-            updates["intermediate_steps"] = steps_delta
-            return updates
-        
-    except Exception as e:
-        logger.error("답변 생성 실패: %s", e, exc_info=True)
-        
-        is_multi = isinstance(state, WorkerState) and state.worker_is_multi
-        if is_multi:
-            return {
-                "multi_answers": [{
-                    "index": state.worker_idx,
-                    "question": state.worker_sub_text or current_q,
-                    "answer": "답변 생성에 실패했습니다. 다시 시도해 주세요."
-                }]
-            }
-        else:
-            updates["final_answer"] = "답변 생성에 실패했습니다. 다시 시도해 주세요."
-            steps_delta.append(f"❌ 답변 생성 실패: {str(e)}")
-            updates["intermediate_steps"] = steps_delta
-            return updates

{hf-space2/CodeWeaver/src/agent → CodeWeaver/src/agent/nodes}/__init__.py

@@ -1,51 +1,66 @@
-"""
-CodeWeaver 에이전트 모듈.
+"""노드 모듈 - LangGraph 노드 함수들."""
 
-LangGraph 기반 개발자 질문 답변 에이전트를 제공합니다.
-
-주요 컴포넌트:
-- State: 에이전트 상태 관리
-- Nodes: 개별 처리 노드
-- Graph: LangGraph 워크플로우
-"""
+# Planning nodes (AgentState 사용)
+from src.agent.nodes.planning import (
+    create_plan_node,
+    handle_too_many_questions_node,
+)
 
-from .state import AgentState, SearchResult
-from .graph import agent, build_agent_graph, create_agent
-from .nodes import (
+# Analysis nodes
+from src.agent.nodes.analysis import (
     analyze_question_node,
     check_cache_node,
-    classify_intent_node,
+)
+
+# Search nodes
+from src.agent.nodes.search import (
     search_stackoverflow_node,
     search_github_node,
     search_official_docs_node,
-    filter_and_score_node,
-    summarize_results_node,
+    collect_results_node,
+    evaluate_results_node,
+    refine_search_node,
+)
+
+# Answer nodes
+from src.agent.nodes.answer import (
     generate_answer_node,
-    return_cached_answer_node,
     generate_with_history_node,
+    combine_answers_node,
+    return_cached_answer_node,
+)
+
+# Common utilities
+from src.agent.nodes.common import (
+    invoke_llm_with_timeout,
+    TIMEOUT_ANALYSIS,
+    TIMEOUT_SUMMARY,
+    TIMEOUT_GENERATION,
 )
 
 __all__ = [
-    # State
-    "AgentState",
-    "SearchResult",
-    
-    # Graph
-    "agent",
-    "build_agent_graph",
-    "create_agent",
-    
-    # Nodes
+    # Planning
+    "create_plan_node",
+    "handle_too_many_questions_node",
+    # Analysis
     "analyze_question_node",
     "check_cache_node",
-    "classify_intent_node",
+    # Search
     "search_stackoverflow_node",
     "search_github_node",
     "search_official_docs_node",
-    "filter_and_score_node",
-    "summarize_results_node",
+    "collect_results_node",
+    "evaluate_results_node",
+    "refine_search_node",
+    # Answer
     "generate_answer_node",
-    "return_cached_answer_node",
     "generate_with_history_node",
+    "combine_answers_node",
+    "return_cached_answer_node",
+    # Common
+    "invoke_llm_with_timeout",
+    "TIMEOUT_ANALYSIS",
+    "TIMEOUT_SUMMARY",
+    "TIMEOUT_GENERATION",
 ]
 

CodeWeaver/src/agent/nodes/analysis.py

@@ -0,0 +1,187 @@
+"""질문 분석 및 캐시 확인 노드 모듈."""
+
+import logging
+from typing import List, Union
+
+from langchain_core.messages import HumanMessage
+
+from src.agent.state import AgentState, WorkerState
+from src.utils.tracing import trace_node
+from src.core.resources import get_qdrant_manager
+from src.prompts.loader import load_prompt
+from src.agent.nodes.common import invoke_llm_with_timeout, TIMEOUT_ANALYSIS
+
+logger = logging.getLogger(__name__)
+
+
+@trace_node("analyze_question")
+def analyze_question_node(state: Union[AgentState, WorkerState]) -> dict:
+    """
+    질문을 분석하여 유형을 분류하고 캐시 적격성을 판단합니다.
+    
+    🔧 FIX: 다중 질문 모드일 때는 messages를 무시하고 독립 질문으로만 분석
+    """
+    # 🔧 [FIX] WorkerState일 경우 processing_question 사용
+    if isinstance(state, WorkerState):
+        user_question = state.processing_question
+        # 🔧 [FIX] 이름 변경된 필드 사용
+        is_multi = state.worker_is_multi
+    else:
+        user_question = state.user_question
+        is_multi = getattr(state, 'is_multi_question', False)
+        
+    messages = state.messages
+    
+    # 대화 맥락 구성 (다중 질문 모드가 아닐 때만)
+    has_history = messages and len(messages) > 1 and not is_multi
+    context_info = ""
+    
+    if has_history:
+        context_info = "\n이전 대화 맥락:\n"
+        for msg in messages[-4:-1]:
+            if hasattr(msg, 'type') and hasattr(msg, 'content'):
+                role = "사용자" if msg.type == "human" else "AI"
+                context_info += f"{role}: {msg.content[:100]}\n"
+    
+    # 🔧 다중 질문 모드 강제 처리
+    if is_multi:
+        context_info = "\n⚠️ 주의: 이 질문은 다중 질문의 일부입니다. 독립적인 질문으로만 판단하세요.\n"
+    
+    analysis_prompt = load_prompt(
+        "analysis", 
+        "analysis_prompt", 
+        context_info=context_info,
+        user_question=user_question
+    )
+
+    try:
+        import json
+        messages_to_llm = [HumanMessage(content=analysis_prompt)]
+        response_text = invoke_llm_with_timeout(
+            messages_to_llm,
+            TIMEOUT_ANALYSIS,
+            "질문 분석"
+        )
+        
+        if "```json" in response_text:
+            response_text = response_text.split("```json")[1].split("```")[0].strip()
+        elif "```" in response_text:
+            response_text = response_text.split("```")[1].split("```")[0].strip()
+        
+        analysis = json.loads(response_text)
+        
+        question_type = analysis.get("question_type", "independent")
+        should_cache = analysis.get("should_cache", False)
+        reasoning = analysis.get("reasoning", "")
+        canonical_question = analysis.get("canonical_question", user_question)
+        refined_query = analysis.get("refined_query", None)
+        
+        # 유효성 검증
+        if question_type not in ["clarification", "general_chat", "independent"]:
+            question_type = "independent"
+
+        # 🔧 CRITICAL: 다중 질문 모드일 때는 무조건 independent로 강제
+        if is_multi and question_type == "clarification":
+            logger.warning("다중 질문 모드에서 clarification 감지 → independent로 강제 변경")
+            question_type = "independent"
+            should_cache = True
+            reasoning = "다중 질문 모드: 독립 질문으로 강제 분류"
+
+        # [수정] general_chat일 경우 처리
+        if question_type == "general_chat":
+            should_cache = False
+            canonical_question = None
+            refined_query = None
+        elif question_type == "clarification":
+            should_cache = False
+            canonical_question = None
+            refined_query = None
+        else:
+            if canonical_question is None or (isinstance(canonical_question, str) and not canonical_question.strip()):
+                canonical_question = user_question
+            # independent인데 refined_query가 없으면 기본값으로 사용
+            if not refined_query or not refined_query.strip():
+                refined_query = user_question
+        
+        steps_delta = [
+            "__RESET_STEPS__",
+            f"🔍 질문 분석: {question_type} (캐시 여부: {should_cache})",
+        ]
+        
+        return {
+            "question_type": question_type,
+            "should_cache": should_cache,
+            "analysis_reasoning": reasoning,
+            "canonical_question": canonical_question if should_cache else None,
+            "refined_question": refined_query,  # 검색 쿼리로 사용
+            "intermediate_steps": steps_delta
+        }
+        
+    except RuntimeError as e:
+        # 타임아웃 또는 기타 LLM 호출 실패
+        logger.error("질문 분석 실패: %s", e)
+        steps_delta = [
+            "__RESET_STEPS__",
+            "⚠️ 질문 분석 실패, 기본값 사용: independent",
+        ]
+        return {
+            "question_type": "independent",
+            "should_cache": True,
+            "analysis_reasoning": "LLM 호출 실패로 인한 기본값 사용",
+            "canonical_question": user_question,
+            "refined_question": user_question,  # 기본값으로 원본 질문 사용
+            "intermediate_steps": steps_delta
+        }
+    except Exception as e:
+        logger.error("질문 분석 실패: %s", e, exc_info=True)
+        
+        steps_delta = [
+            "__RESET_STEPS__",
+            "⚠️ 질문 분석 실패, 기본값 사용: independent",
+        ]
+        
+        return {
+            "question_type": "independent",
+            "should_cache": True,
+            "analysis_reasoning": "분석 실패, 기본값 사용",
+            "canonical_question": user_question,
+            "refined_question": user_question,  # 기본값으로 원본 질문 사용
+            "intermediate_steps": steps_delta
+        }
+
+
+@trace_node("check_cache")
+def check_cache_node(state: Union[AgentState, WorkerState]) -> dict:
+    """벡터 DB 캐시에서 유사한 질문을 검색합니다."""
+    # 🔧 [FIX] 변수 접근 수정
+    current_q = state.processing_question if isinstance(state, WorkerState) else state.user_question
+    question_for_lookup = state.canonical_question or current_q
+    logger.info("캐시 확인 중: %s", question_for_lookup[:50])
+    
+    try:
+        qdrant_manager = get_qdrant_manager()
+        cached_result = qdrant_manager.search_cache(
+            question=question_for_lookup,
+            threshold=0.95
+        )
+        
+        updates = {}
+        steps_delta: List[str] = []
+        
+        if cached_result:
+            updates["cached_result"] = cached_result
+            steps_delta.append(f"✅ 캐시 히트 (답변 길이: {len(cached_result)}자)")
+            logger.info("캐시 히트")
+        else:
+            updates["cached_result"] = None
+            steps_delta.append("❌ 캐시 미스: 새로운 검색 필요")
+            logger.info("캐시 미스")
+    
+    except Exception as e:
+        logger.error("캐시 확인 실패: %s", e, exc_info=True)
+        updates["cached_result"] = None
+        steps_delta.append(f"⚠️ 캐시 확인 오류: {str(e)}")
+    
+    updates["intermediate_steps"] = steps_delta
+    return updates
+

CodeWeaver/src/agent/nodes/answer.py

@@ -0,0 +1,381 @@
+"""답변 생성 및 조합 노드 모듈."""
+
+import logging
+import threading
+from typing import List, Union
+
+from langchain_core.messages import HumanMessage, AIMessage
+
+from src.agent.state import AgentState, WorkerState, MultiAnswerData
+from src.utils.tracing import trace_node
+from src.core.resources import get_qdrant_manager
+from src.prompts.loader import load_prompt
+from src.agent.nodes.common import invoke_llm_with_timeout, TIMEOUT_GENERATION
+
+logger = logging.getLogger(__name__)
+
+
+@trace_node("combine_answers")
+def combine_answers_node(state: AgentState) -> dict:
+    """
+    Fan-in: 모든 Send가 완료되면 multi_answers를 조합합니다.
+    """
+    answers = state.multi_answers
+    original_question = state.original_multi_question or state.user_question
+    
+    if not answers:
+        logger.error("다중 답변이 비어있음")
+        return {
+            "final_answer": "답변 생성에 실패했습니다. 다시 시도해 주세요.",
+            "intermediate_steps": ["❌ multi_answers 비어있음"]
+        }
+    
+    # 인덱스 순으로 정렬
+    answers.sort(key=lambda x: x.index)
+    
+    # Markdown 형식으로 조합
+    combined_parts = []
+    for ans in answers:
+        section = f"""## {ans.index+1}. {ans.question}
+
+{ans.answer}"""
+        combined_parts.append(section)
+    
+    combined = "\n\n---\n\n".join(combined_parts)
+    
+    # 헤더 추가
+    header = f"# 다중 질문 답변\n\n원본 질문: {original_question}\n\n---\n\n"
+    final_combined = header + combined
+    
+    logger.info("다중 답변 조합 완료: %d개", len(answers))
+    
+    return {
+        "final_answer": final_combined,
+        "messages": [AIMessage(content=final_combined)],
+        "intermediate_steps": [f"✅ {len(answers)}개 답변 조합 완료"]
+    }
+
+
+@trace_node("return_cached_answer")
+def return_cached_answer_node(state: Union[AgentState, WorkerState]) -> dict:
+    """캐시 히트 시 저장된 답변을 반환합니다."""
+    logger.info("캐시된 답변 반환")
+    
+    cached_answer = state.cached_result
+    is_multi = isinstance(state, WorkerState) and state.worker_is_multi
+    
+    if is_multi:
+        return {
+            "multi_answers": [MultiAnswerData(
+                index=state.worker_idx,
+                question=state.worker_sub_text or state.processing_question,
+                answer=cached_answer
+            )]
+        }
+    else:
+        # 🔧 [FIX] messages에 AIMessage 추가하여 히스토리 저장 보장
+        steps_delta = ["💾 캐시된 답변 반환 (검색 생략)"]
+        return {
+            "final_answer": cached_answer,
+            "messages": [AIMessage(content=cached_answer)], # 👈 핵심 수정
+            "intermediate_steps": steps_delta
+        }
+
+
+@trace_node("generate_with_history")
+def generate_with_history_node(state: Union[AgentState, WorkerState]) -> dict:
+    """
+    대화 히스토리만 사용하여 후속 질문에 답변합니다.
+    
+    수정 사항:
+    1. 문맥 오염 방지: 바로 직전의 대화(질문+답변)만 참조하도록 슬라이싱 적용
+    2. 히스토리 저장: AIMessage 반환 추가 (대화 끊김 방지)
+    """
+    # 1. 현재 질문 추출
+    user_question = state.processing_question if isinstance(state, WorkerState) else state.user_question
+    messages_history = state.messages
+    
+    logger.info("대화 히스토리 기반 답변 생성: %s", user_question[:50])
+    
+    # 2. 대화 맥락 구성 (Context Pollution 방지)
+    # [핵심] 현재 질문을 제외한 과거 기록 중 '가장 최근 2개(직전 질문+답변)'만 참조
+    prev_messages = messages_history[:-1] if messages_history else []
+    recent_context = prev_messages[-20:] if prev_messages else []
+    
+    # recent_context를 문자열로 변환
+    recent_context_str = ""
+    if recent_context:
+        recent_context_str = "직전 대화 내역:\n"
+        for msg in recent_context:
+            if hasattr(msg, 'type') and hasattr(msg, 'content'):
+                role = "사용자" if msg.type == "human" else "AI"
+                recent_context_str += f"{role}: {msg.content}\n\n"
+    
+    # 템플릿에서 프롬프트 로드
+    context_prompt = load_prompt(
+        "answer",
+        "context_prompt_base",
+        user_question=user_question,
+        recent_context=recent_context_str
+    )
+    updates = {}
+    steps_delta: List[str] = []
+    
+    try:
+        # 3. LLM 호출
+        final_answer = invoke_llm_with_timeout(
+            [HumanMessage(content=context_prompt)],
+            TIMEOUT_GENERATION,
+            "대화 히스토리 기반 답변 생성"
+        )
+        
+        # 4. 상태 업데이트
+        is_multi = isinstance(state, WorkerState) and state.worker_is_multi
+        
+        if is_multi:
+            # 다중 질문 모드 (예외적 상황)
+            return {
+                "multi_answers": [MultiAnswerData(
+                    index=state.worker_idx,
+                    question=state.worker_sub_text or user_question,
+                    answer=final_answer
+                )]
+            }
+        else:
+            # 단일 질문 모드 (정상 케이스)
+            updates["final_answer"] = final_answer
+            # [핵심] 대화 히스토리에 AI 답변을 추가하여 다음 턴에서 참조 가능하게 함
+            updates["messages"] = [AIMessage(content=final_answer)]
+            
+            steps_delta.append(f"💬 대화 히스토리 기반 답변 생성 (길이: {len(final_answer)}자)")
+            steps_delta.append("⚠️ 캐시 저장 생략 (보충 요청)")
+            
+            logger.info("대화 히스토리 기반 답변 생성 완료")
+        
+    except RuntimeError as e:
+        # 타임아웃 또는 기타 LLM 호출 실패
+        error_message = f"답변 생성에 실패했습니다: {str(e)}. 다시 시도해 주세요."
+        is_multi = isinstance(state, WorkerState) and state.worker_is_multi
+        if is_multi:
+            return {
+                "multi_answers": [MultiAnswerData(
+                    index=state.worker_idx,
+                    question=state.worker_sub_text or user_question,
+                    answer=error_message
+                )]
+            }
+        else:
+            updates["final_answer"] = error_message
+            steps_delta.append(f"❌ 답변 생성 실패")
+    except Exception as e:
+        logger.error("대화 히스토리 기반 답변 생성 실패: %s", e, exc_info=True)
+        
+        is_multi = isinstance(state, WorkerState) and state.worker_is_multi
+        if is_multi:
+            return {
+                "multi_answers": [MultiAnswerData(
+                    index=state.worker_idx,
+                    question=state.worker_sub_text or user_question,
+                    answer="답변 생성에 실패했습니다. 다시 시도해 주세요."
+                )]
+            }
+        else:
+            updates["final_answer"] = "답변 생성에 실패했습니다. 다시 시도해 주세요."
+            steps_delta.append(f"❌ 답변 생성 실패: {str(e)}")
+    
+    updates["intermediate_steps"] = steps_delta
+    return updates
+
+
+@trace_node("generate_answer")
+def generate_answer_node(state: Union[AgentState, WorkerState]) -> dict:
+    """
+    요약된 정보를 바탕으로 최종 답변을 생성합니다.
+    
+    수정 사항:
+    1. 다중 질문 모드에서도 캐시 저장 로직이 실행되도록 순서 변경
+    2. 단일 질문 모드에서 AIMessage 반환 (히스토리 저장)
+    """
+    # 필터링된 검색 결과 사용
+    results = state.filtered_search_results
+    question_type = state.question_type or "independent"
+    
+    # [수정] 리스트 이름 변경 (summaries -> results)
+    has_valid_info = len(results) > 0
+    
+    # 변수 접근
+    current_q = state.processing_question if isinstance(state, WorkerState) else state.user_question
+    
+    logger.info("최종 답변 생성 중 (질문: %s)", current_q[:30])
+    
+    # [핵심 추가 1] 최근 대화 내역 포맷팅 (최근 20개 정도)
+    # 일반 대화일 때 '기억'을 제공하기 위함
+    # HumanMessage는 제외: 사용자 질문은 {question}에 이미 포함되어 있고,
+    # AI 답변 패턴(인사말, 요약) 반복 문제를 방지하기 위함
+    messages = state.messages
+    recent_history = ""
+    if messages and len(messages) > 0:
+        # 시스템 메시지 및 HumanMessage 제외, AI 답변만 포함 (최근 20개)
+        visible_msgs = messages[-20:]
+        for msg in visible_msgs:
+            if hasattr(msg, 'content') and not isinstance(msg, HumanMessage):
+                # HumanMessage 제외, AIMessage만 포함
+                recent_history += f"AI: {msg.content}\n"
+    
+    # 템플릿 선택: general_chat인 경우만 별도 처리
+    if question_type == "general_chat":
+        # 일반 대화 템플릿 로드
+        template = load_prompt(
+            "answer",
+            "general_chat_template",
+            history=recent_history if recent_history else "(이전 대화 내역 없음)",
+            question=state.original_question or current_q
+        )
+        has_valid_info = False  # general_chat은 검색 결과 없음
+        system_instruction = ""  # general_chat은 별도 지시 없음
+    else:
+        # 검색 결과 유무에 따라 분기 처리
+        if has_valid_info:
+            # [수정] 원본 content 사용 (너무 길면 1500자 제한)
+            summaries_text = "\n\n".join([
+                f"출처: {r.source} ({r.url or ''})\n내용: {r.content[:1500]}"
+                for r in results
+            ])
+            system_instruction = ""  # 특별한 지시 없음
+        else:
+            # Fallback 케이스: 검색 결과 없음 -> LLM 지식 활용
+            summaries_text = "(검색 결과 부족)"
+            
+            # LLM에게 지식 활용 허용 (프롬프트)
+            system_instruction = load_prompt("answer", "fallback_system_instruction")
+        
+        # 기술 질문 템플릿 로드
+        template = load_prompt(
+            "answer",
+            "technical_template",
+            question=state.original_question or current_q,
+            summaries=summaries_text
+        )
+    
+    # 3. 이전 대화 맥락 추가 (Context Pollution 방지: 최근 1개만 참고용으로)
+    context_prefix = ""
+    messages_history = state.messages
+    if messages_history and len(messages_history) > 1:
+        # 검색 기반 답변이므로 이전 대화는 아주 최소한만 참조 (직전 1개)
+        prev_msg = messages_history[-2] if len(messages_history) >= 2 else None
+        if prev_msg:
+             context_prefix = f"이전 대화 맥락(참고): {prev_msg.content[:200]}...\n---\n"
+    
+    # 템플릿은 이미 Jinja2로 렌더링되었으므로 context_prefix만 추가
+    final_prompt = context_prefix + template
+    
+    # 시스템 지시 추가
+    final_prompt += system_instruction
+    
+    updates = {}
+    steps_delta: List[str] = []
+    
+    try:
+        # 4. LLM 호출
+        final_answer = invoke_llm_with_timeout(
+            [HumanMessage(content=final_prompt)],
+            TIMEOUT_GENERATION,
+            "답변 생성"
+        )
+        
+        # 5. 캐시 저장 로직 (백그라운드 실행용 함수 정의)
+        def _background_cache_save(question_text: str, answer_text: str, q_type: str, do_cache: bool):
+            """백그라운드 스레드에서 실행될 함수"""
+            if do_cache and q_type == "independent":
+                try:
+                    # 주의: qdrant_manager가 thread-safe한지 확인 필요 (보통 클라이언트는 안전함)
+                    # 별도 세션이 필요하다면 여기서 생성해야 함
+                    qdrant_manager = get_qdrant_manager()
+                    qdrant_manager.save_to_cache(
+                        question=question_text,
+                        answer=answer_text
+                    )
+                    logger.info("✅ [Background] 캐시 저장 완료: %s", question_text[:30])
+                except Exception as cache_err:
+                    logger.error("❌ [Background] 캐시 저장 실패: %s", cache_err)
+
+        # 저장에 필요한 데이터 준비
+        should_cache = state.should_cache if state.should_cache is not None else True
+        canonical_question = state.canonical_question
+        qtype = state.question_type or "independent"
+        question_to_cache = canonical_question or current_q
+
+        # [수정] Threading을 이용한 비동기 처리 (Fire-and-forget)
+        # daemon=True로 설정하여 메인 프로세스 종료 시 함께 종료되도록 함
+        cache_thread = threading.Thread(
+            target=_background_cache_save,
+            args=(question_to_cache, final_answer, qtype, should_cache),
+            daemon=True
+        )
+        cache_thread.start()
+
+        # 6. 결과 반환 및 분기 처리
+        is_multi = isinstance(state, WorkerState) and state.worker_is_multi
+
+        if is_multi:
+            logger.info("다중 질문 모드: 답변을 multi_answers에 추가")
+            return {
+                "multi_answers": [MultiAnswerData(
+                    index=state.worker_idx,
+                    question=state.worker_sub_text or current_q,
+                    answer=final_answer
+                )]
+            }
+        
+        else:
+            # 단일 질문 모드
+            updates["final_answer"] = final_answer
+            # [핵심] 대화 히스토리에 AI 답변 추가
+            updates["messages"] = [AIMessage(content=final_answer)]
+            
+            # 캐시 저장은 백그라운드에서 처리됨
+            steps_delta.append(f"✅ 최종 답변 생성 완료 (길이: {len(final_answer)}자)")
+            if should_cache and qtype == "independent":
+                steps_delta.append("💾 캐시 저장 백그라운드 요청됨")
+            else:
+                steps_delta.append("⚠️ 캐시 저장 생략 (독립적이지 않거나 일회성 질문)")
+            
+            updates["intermediate_steps"] = steps_delta
+            return updates
+        
+    except RuntimeError as e:
+        # 타임아웃 또는 기타 LLM 호출 실패
+        logger.error("답변 생성 실패: %s", e)
+        error_message = f"답변 생성에 실패했습니다: {str(e)}. 다시 시도해 주세요."
+        is_multi = isinstance(state, WorkerState) and state.worker_is_multi
+        if is_multi:
+            return {
+                "multi_answers": [MultiAnswerData(
+                    index=state.worker_idx,
+                    question=state.worker_sub_text or current_q,
+                    answer=error_message
+                )]
+            }
+        else:
+            updates["final_answer"] = error_message
+            steps_delta.append("❌ 답변 생성 실패")
+            updates["intermediate_steps"] = steps_delta
+            return updates
+    except Exception as e:
+        logger.error("답변 생성 실패: %s", e, exc_info=True)
+        
+        is_multi = isinstance(state, WorkerState) and state.worker_is_multi
+        if is_multi:
+            return {
+                "multi_answers": [MultiAnswerData(
+                    index=state.worker_idx,
+                    question=state.worker_sub_text or current_q,
+                    answer="답변 생성에 실패했습니다. 다시 시도해 주세요."
+                )]
+            }
+        else:
+            updates["final_answer"] = "답변 생성에 실패했습니다. 다시 시도해 주세요."
+            steps_delta.append(f"❌ 답변 생성 실패: {str(e)}")
+            updates["intermediate_steps"] = steps_delta
+            return updates
+

CodeWeaver/src/agent/nodes/common.py

@@ -0,0 +1,44 @@
+"""공통 헬퍼 함수 모듈."""
+
+import logging
+from typing import List
+
+from langchain_core.messages import HumanMessage, SystemMessage
+
+from src.core.llm import get_llm
+
+logger = logging.getLogger(__name__)
+
+# 타임아웃 설정 (초)
+TIMEOUT_ANALYSIS = 30.0  # 의도 분류/분석
+TIMEOUT_SUMMARY = 40.0   # 요약
+TIMEOUT_GENERATION = 50.0  # 일반 답변 생성
+
+
+def invoke_llm_with_timeout(
+    messages: List[HumanMessage | SystemMessage],
+    timeout: float,
+    operation_name: str = "LLM 호출"
+) -> str:
+    """
+    LLM 호출을 실행하고 예외를 처리합니다. (동기 버전)
+    
+    Args:
+        messages: LLM에 전달할 메시지 리스트
+        timeout: 타임아웃 시간 (초) - 동기 모드에서는 참고용
+        operation_name: 작업 이름 (로깅용)
+    
+    Returns:
+        LLM 응답 텍스트
+    
+    Raises:
+        RuntimeError: 예외 발생 시
+    """
+    try:
+        llm = get_llm()
+        response = llm.invoke(messages)
+        return response.content.strip()
+    except Exception as e:
+        logger.error("%s 실패: %s", operation_name, e, exc_info=True)
+        raise RuntimeError(f"{operation_name} 실패: {str(e)}") from e
+

CodeWeaver/src/agent/nodes/planning.py

@@ -0,0 +1,171 @@
+"""계획 수립 노드 모듈 (AgentState 사용)."""
+
+import logging
+from typing import List
+
+from langchain_core.messages import HumanMessage, AIMessage
+
+from src.agent.state import AgentState, PlanData, MultiAnswerData
+from src.agent.state import _MULTI_ANS_RESET_TOKEN
+from src.utils.tracing import trace_node
+from src.prompts.loader import load_prompt
+from src.agent.nodes.common import invoke_llm_with_timeout, TIMEOUT_ANALYSIS
+
+logger = logging.getLogger(__name__)
+
+
+@trace_node("create_plan")
+def create_plan_node(state: AgentState) -> dict:
+    """
+    질문을 분석하여 유형과 개수를 판단합니다. (LLM 전용)
+    
+    Case:
+    - single_topic: 하나의 주제 (서브그래프 1회)
+    - multiple_questions: 독립 질문 2개 (Send API로 서브그래프 2회 병렬)
+    - too_many: 독립 질문 3개 이상 (에러 메시지)
+    """
+    user_question = state.user_question
+    logger.info("질문 분석 및 계획 수립 중: %s", user_question[:50])
+
+    # 길이 제한: 악의적인 긴 입력 방지
+    if len(user_question) > 10000:
+        logger.warning("질문이 너무 깁니다 (%d자). 10,000자로 제한합니다.", len(user_question))
+        user_question = user_question[:10000]
+
+    # 프롬프트를 보강하여 LLM에게 명확한 기준 제시
+    plan_prompt = load_prompt("planning", "plan_prompt", user_question=user_question)
+
+    try:
+        import json
+        
+        messages_to_llm = [HumanMessage(content=plan_prompt)]
+        response_text = invoke_llm_with_timeout(
+            messages_to_llm,
+            TIMEOUT_ANALYSIS,
+            "계획 수립"
+        )
+        
+        # JSON 파싱
+        if "```json" in response_text:
+            response_text = response_text.split("```json")[1].split("```")[0].strip()
+        elif "```" in response_text:
+            response_text = response_text.split("```")[1].split("```")[0].strip()
+        
+        plan_data = json.loads(response_text)
+        
+        case = plan_data.get("case", "single_topic")
+        questions = plan_data.get("questions", [user_question])
+        reasoning = plan_data.get("reasoning", "")
+        error_message = plan_data.get("error_message", "")
+
+        # 유효성 검증
+        if not questions or len(questions) == 0:
+            questions = [user_question]
+            case = "single_topic"
+        
+        # 안전장치: LLM이 multiple_questions라고 했는데 questions가 1개뿐이면 보정
+        if case == "multiple_questions" and len(questions) < 2:
+            logger.warning("multiple_questions로 분류되었지만 questions가 %d개뿐입니다. single_topic으로 보정합니다.", len(questions))
+            case = "single_topic"
+            questions = [user_question]
+        
+        # 안전장치: LLM이 multiple_questions라고 했는데 questions가 3개 이상이면 too_many로 보정
+        if case == "multiple_questions" and len(questions) > 2:
+            logger.warning("multiple_questions로 분류되었지만 questions가 %d개입니다. too_many로 보정합니다.", len(questions))
+            case = "too_many"
+            error_message = "죄송합니다. 질문은 한 번에 최대 2개까지 가능합니다. 가장 중요한 2개만 골라서 다시 질문해 주세요."
+            reasoning = f"질문이 {len(questions)}개로 감지되어 too_many로 보정했습니다."
+
+        steps_delta = [
+            f"📋 계획 타입: {case}",
+            f"   질문: {len(questions)}개",
+            f"   이유: {reasoning}"
+        ]
+        
+        logger.info("계획 수립 완료: %s, %d개 질문", case, len(questions))
+        
+        return {
+            "plan": PlanData(
+                case=case,
+                questions=questions,
+                reasoning=reasoning,
+                error_message=error_message
+            ),
+            "is_multi_question": False,
+            "sub_question_index": 0,
+            "sub_question_text": None,
+            "original_multi_question": None,
+            "multi_answers": [MultiAnswerData(token=_MULTI_ANS_RESET_TOKEN)],
+            "intermediate_steps": steps_delta
+        }
+        
+    except RuntimeError as e:
+        # 타임아웃 또는 기타 LLM 호출 실패
+        logger.error("계획 수립 실패: %s", e)
+        steps_delta = [
+            f"⚠️ 계획 수립 실패, 기본값 사용: single_topic"
+        ]
+        return {
+            "plan": PlanData(
+                case="single_topic",
+                questions=[user_question],
+                reasoning="LLM 호출 실패로 인한 기본값 사용",
+                error_message=""
+            ),
+            "is_multi_question": False,
+            "sub_question_index": 0,
+            "sub_question_text": None,
+            "original_multi_question": None,
+            "multi_answers": [MultiAnswerData(token=_MULTI_ANS_RESET_TOKEN)],
+            "intermediate_steps": steps_delta
+        }
+    except Exception as e:
+        logger.error("계획 수립 실패: %s", e, exc_info=True)
+        
+        # 기본값: 원본 질문 그대로 사용
+        steps_delta = [
+            "⚠️ 계획 수립 실패, 기본값 사용: single_topic"
+        ]
+        
+        return {
+            "plan": PlanData(
+                case="single_topic",
+                questions=[user_question],
+                reasoning="계획 수립 실패, 기본값 사용",
+                error_message=""
+            ),
+            "is_multi_question": False,
+            "sub_question_index": 0,
+            "sub_question_text": None,
+            "original_multi_question": None,
+            "multi_answers": [MultiAnswerData(token=_MULTI_ANS_RESET_TOKEN)],
+            "intermediate_steps": steps_delta
+        }
+
+
+@trace_node("handle_too_many_questions")
+def handle_too_many_questions_node(state: AgentState) -> dict:
+    """3개 이상 질문 시 안내 메시지를 반환합니다."""
+    if state.plan is None:
+        error_message = ""
+        questions = []
+    else:
+        error_message = state.plan.error_message
+        questions = state.plan.questions
+    
+    logger.info("질문 수 초과: %d개", len(questions))
+    
+    default_message = load_prompt("planning", "too_many_questions_message")
+    
+    final_message = error_message if error_message else default_message
+    
+    steps_delta = [
+        f"⚠️ 질문 수 초과: {len(questions)}개",
+        "💬 안내 메시지 제공 (대화 계속 가능)"
+    ]
+    
+    return {
+        "final_answer": final_message,
+        "intermediate_steps": steps_delta
+    }
+

CodeWeaver/src/agent/nodes/search.py

@@ -0,0 +1,345 @@
+"""검색 및 도구 실행 노드 모듈."""
+
+import logging
+from typing import List, Union
+
+from langchain_core.messages import HumanMessage
+
+from src.agent.state import AgentState, WorkerState, SearchResult
+from src.tools.search import (
+    search_github,
+    search_official_docs,
+    search_stackoverflow,
+)
+from src.utils.tracing import trace_node
+from src.core.resources import get_reranker
+from src.prompts.loader import load_prompt
+from src.agent.nodes.common import invoke_llm_with_timeout, TIMEOUT_ANALYSIS
+
+logger = logging.getLogger(__name__)
+
+
+@trace_node("search_stackoverflow")
+def search_stackoverflow_node(state: Union[AgentState, WorkerState]) -> dict:
+    """Stack Overflow에서 검색을 수행합니다."""
+    # 🔧 [FIX] 변수 접근 수정
+    current_q = state.processing_question if isinstance(state, WorkerState) else state.user_question
+    question_to_use = state.refined_question if hasattr(state, 'refined_question') and state.refined_question else current_q
+    
+    logger.info("Stack Overflow 검색 시작 (쿼리: %s)", question_to_use[:50])
+    
+    try:
+        results = search_stackoverflow(question_to_use)
+        logger.info("Stack Overflow에서 %d개 결과 수집", len(results))
+        
+        # 🔧 FIX: intermediate_steps 제거
+        return {
+            "search_results": results,
+            # intermediate_steps 제거! (병렬 충돌 방지)
+        }
+    except Exception as e:
+        logger.error("Stack Overflow 검색 실패: %s", e)
+        return {}
+
+
+@trace_node("search_github")
+def search_github_node(state: Union[AgentState, WorkerState]) -> dict:
+    """GitHub Issues/Discussions에서 검색을 수행합니다."""
+    # 🔧 [FIX] 변수 접근 수정
+    current_q = state.processing_question if isinstance(state, WorkerState) else state.user_question
+    question_to_use = state.refined_question if hasattr(state, 'refined_question') and state.refined_question else current_q
+    
+    logger.info("GitHub 검색 시작 (쿼리: %s)", question_to_use[:50])
+    
+    try:
+        results = search_github(question_to_use)
+        logger.info("GitHub에서 %d개 결과 수집", len(results))
+        
+        # 🔧 FIX: intermediate_steps 제거
+        return {
+            "search_results": results,
+            # intermediate_steps 제거! (병렬 충돌 방지)
+        }
+    except Exception as e:
+        logger.error("GitHub 검색 실패: %s", e)
+        return {}
+
+
+@trace_node("search_official_docs")
+def search_official_docs_node(state: Union[AgentState, WorkerState]) -> dict:
+    """공식 문서/Tavily에서 검색을 수행합니다."""
+    # 🔧 [FIX] 변수 접근 수정
+    current_q = state.processing_question if isinstance(state, WorkerState) else state.user_question
+    question_to_use = state.refined_question if hasattr(state, 'refined_question') and state.refined_question else current_q
+    
+    logger.info("공식 문서 검색 시작 (쿼리: %s)", question_to_use[:50])
+    
+    try:
+        results = search_official_docs(question_to_use)
+        logger.info("공식 문서에서 %d개 결과 수집", len(results))
+        
+        # 🔧 FIX: intermediate_steps 제거
+        return {
+            "search_results": results,
+            # intermediate_steps 제거! (병렬 충돌 방지)
+        }
+    except Exception as e:
+        logger.error("공식 문서 검색 실패: %s", e)
+        return {}
+
+
+@trace_node("collect_results")
+def collect_results_node(state: Union[AgentState, WorkerState]) -> dict:
+    """병렬 검색 결과를 수집하고 카운트합니다."""
+    total_results = len(state.search_results)
+    
+    logger.info("검색 결과 수집 완료: %d개", total_results)
+    
+    # 🔧 FIX: 로그만 찍고, intermediate_steps는 업데이트하지 않음
+    # (병렬 노드에서 intermediate_steps 업데이트 시 충돌 발생)
+    
+    return {}  # 빈 딕셔너리 반환 (상태 변경 없음)
+
+
+@trace_node("evaluate_results")
+def evaluate_results_node(state: Union[AgentState, WorkerState]) -> dict:
+    """검색 결과의 개수와 품질을 모두 평가합니다. Reranking을 수행하여 점수를 계산하고 저장합니다."""
+    search_results = state.search_results
+    refinement_count = state.refinement_count
+    
+    # 쿼리 준비
+    current_q = state.processing_question if isinstance(state, WorkerState) else state.user_question
+    query_to_use = state.refined_question if hasattr(state, 'refined_question') and state.refined_question else current_q
+    
+    result_count = len(search_results)
+    
+    logger.info("검색 결과 평가: %d개 (개선 횟수: %d)", result_count, refinement_count)
+    
+    # 1. 개수 평가
+    needs_refinement = False
+    steps_delta = []
+    
+    if result_count < 2:
+        needs_refinement = True
+        steps_delta.append("⚠️ 검색 결과 개수 부족")
+    
+    # 2. 품질 평가 (Reranking 수행 - 항상 실행)
+    try:
+        # [수정] Thread-safe한 함수 호출
+        reranker = get_reranker()
+        
+        # 기본 필터링 (내용이 너무 짧거나 URL 없는 것 제외)
+        filtered = [
+            r for r in search_results
+            if r.content and len(r.content) >= 50 and r.url
+        ]
+        
+        if not filtered:
+            needs_refinement = True
+            steps_delta.append("⚠️ 기본 필터링 후 결과 없음")
+            # 필터링된 결과가 없어도 점수는 매기지 않고 반환
+            reset_marker = SearchResult(source="__RESET__", content="", url="")
+            # refinement_count >= 1이면 needs_refinement 강제로 False
+            if refinement_count >= 1:
+                needs_refinement = False
+                steps_delta.append("⚠️ 재검색 결과이므로 강제 통과")
+            
+            return {
+                "needs_refinement": needs_refinement,
+                "search_results": [reset_marker],
+                "filtered_search_results": [],  # 결과 없음
+                "intermediate_steps": steps_delta
+            }
+        
+        # 문서 추출
+        docs = [r.content for r in filtered]
+        
+        # 점수 계산 (항상 수행)
+        scores = list(reranker.rerank(query_to_use, docs))
+        max_score = max(scores) if scores else 0.0
+        
+        # 점수를 원본 객체에 할당
+        scored_results = []
+        for i, res in enumerate(filtered):
+            # 복사본을 만들어서 점수 할당 (안전성 확보)
+            new_res = res.model_copy()
+            new_res.relevance_score = float(scores[i])
+            scored_results.append(new_res)
+        
+        # [핵심] 0.35 미만이면 다시 검색 (Refine) - 하지만 refinement_count >= 1이면 무시
+        THRESHOLD = 0.35
+        if max_score < THRESHOLD:
+            needs_refinement = True
+            steps_delta.append(f"⚠️ 검색 품질 미달 (Max: {max_score:.2f})")
+        else:
+            steps_delta.append(f"✅ 품질 통과 (Max: {max_score:.2f})")
+        
+        # [핵심] refinement_count >= 1이면 needs_refinement 강제로 False 설정
+        if refinement_count >= 1:
+            needs_refinement = False
+            steps_delta.append("⚠️ 재검색 결과이므로 강제 통과 (무한 루프 방지)")
+        
+            # [핵심 최적화] 점수가 매겨진 결과로 State 업데이트 (항상 반환)
+        # Reset 토큰을 사용하여 기존(점수 없는) 리스트를 덮어씁니다.
+        reset_marker = SearchResult(source="__RESET__", content="", url="")
+        
+        return_dict = {
+            "needs_refinement": needs_refinement,
+            "search_results": [reset_marker] + scored_results,  # 점수 매긴 걸로 교체
+            "intermediate_steps": steps_delta
+        }
+        
+        # 필터링 로직 통합: needs_refinement가 False일 때만 수행
+        if not needs_refinement:
+            # Reset 토큰 제거
+            filtered_results = [r for r in scored_results if r.source != "__RESET__"]
+            
+            # 0.35점 미만 필터링
+            THRESHOLD = 0.35
+            filtered = [
+                r for r in filtered_results
+                if r.relevance_score is not None and r.relevance_score >= THRESHOLD
+            ]
+            
+            # 정렬 (점수 높은 순)
+            filtered.sort(key=lambda r: r.relevance_score, reverse=True)
+            
+            # 상위 5개 선택
+            top_results = filtered[:5]
+            
+            # filtered_search_results에 저장 (객체 리스트 그대로)
+            return_dict["filtered_search_results"] = top_results
+            
+            # 로깅
+            steps_delta.append(f"⚡ 필터링 완료: {len(filtered_results)}개 → {len(top_results)}개")
+            if not top_results:
+                steps_delta.append("⚠️ 품질 기준(0.35)을 넘는 검색 결과가 없음 → LLM 지식 의존")
+        else:
+            # needs_refinement가 True인 경우 빈 리스트 반환
+            return_dict["filtered_search_results"] = []
+        
+        return return_dict
+    
+    except Exception as e:
+        logger.error("Evaluate Reranking Error: %s", e, exc_info=True)
+        # 에러 시에도 refinement_count >= 1이면 needs_refinement = False
+        if refinement_count >= 1:
+            needs_refinement = False
+        else:
+            needs_refinement = False  # 에러 시 일단 진행
+        
+        return {
+            "needs_refinement": needs_refinement,
+            "filtered_search_results": [],  # 에러 시 빈 리스트
+            "intermediate_steps": [f"⚠️ Reranking 실패, 기본 진행: {str(e)}"]
+        }  # 에러 시 일단 진행
+
+
+@trace_node("refine_search")
+def refine_search_node(state: Union[AgentState, WorkerState]) -> dict:
+    """
+    검색 쿼리를 개선합니다.
+    
+    🔧 CRITICAL: 
+    - user_question을 직접 업데이트하지 않고, refined_question��� 저장
+    - 부모 AgentState와 충돌 방지를 위해 WorkerState 필드만 반환
+    - ❌ 절대 반환하면 안 되는 것들: user_question, messages, final_answer
+    """
+    # 🔧 [FIX] 변수 접근 수정
+    user_question = state.processing_question if isinstance(state, WorkerState) else state.user_question
+    original_question = state.original_question or user_question
+    result_count = len(state.search_results)
+    
+    logger.info("검색 쿼리 개선 중: %s (%d개 결과)", user_question[:50], result_count)
+    
+    refinement_prompt = load_prompt(
+        "search",
+        "refinement_prompt",
+        user_question=user_question,
+        result_count=result_count
+    )
+
+    try:
+        import json
+        
+        messages_to_llm = [HumanMessage(content=refinement_prompt)]
+        response_text = invoke_llm_with_timeout(
+            messages_to_llm,
+            TIMEOUT_ANALYSIS,
+            "쿼리 개선"
+        )
+        if "```json" in response_text:
+            response_text = response_text.split("```json")[1].split("```")[0].strip()
+        elif "```" in response_text:
+            response_text = response_text.split("```")[1].split("```")[0].strip()
+        
+        refinement_data = json.loads(response_text)
+        
+        new_query = refinement_data.get("new_query", user_question)
+        strategy = refinement_data.get("strategy", "MORE_GENERAL")
+        reasoning = refinement_data.get("reasoning", "")
+        
+        steps_delta = [
+            f"🔄 쿼리 개선: {strategy}",
+            f"   이전: {user_question[:50]}...",
+            f"   이후: {new_query[:50]}...",
+            f"   이유: {reasoning}"
+        ]
+        
+        logger.info("쿼리 개선 완료: %s → %s", user_question[:30], new_query[:30])
+        
+        # 🔧 CRITICAL: WorkerState 필드만 반환 (부모 AgentState와 충돌 방지)
+        # Reset 토큰을 포함하여 기존 검색 결과를 초기화 (재검색 시 누적 방지)
+        reset_marker = SearchResult(source="__RESET__", content="", url="")
+        
+        return {
+            "refined_question": new_query,      # ✅ WorkerState 필드
+            "original_question": original_question,  # ✅ WorkerState 필드
+            "refinement_count": state.refinement_count + 1,  # ✅ WorkerState 필드
+            "search_results": [reset_marker],  # ✅ Reset 토큰으로 기존 결과 초기화
+            "intermediate_steps": steps_delta  # ✅ WorkerState 필드
+            
+            # ❌ 절대 반환하면 안 되는 것들:
+            # "user_question": ...,   # 부모 AgentState와 충돌!
+            # "messages": ...,        # 부모 AgentState와 충돌!
+            # "final_answer": ...,    # 너무 이른 시점!
+        }
+        
+    except RuntimeError as timeout_err:
+        if "시간이 초과" in str(timeout_err):
+            logger.error("쿼리 개선 타임아웃 (%d초 초과)", TIMEOUT_ANALYSIS)
+        fallback_query = user_question + " tutorial example"
+        steps_delta = [
+            f"⚠️ 쿼리 개선 타임아웃 ({TIMEOUT_ANALYSIS}초), 기본 전략 사용",
+            f"   이후: {fallback_query}"
+        ]
+        # Reset 토큰으로 기존 결과 초기화
+        reset_marker = SearchResult(source="__RESET__", content="", url="")
+        return {
+            "refined_question": fallback_query,
+            "original_question": original_question,
+            "refinement_count": state.refinement_count + 1,
+            "search_results": [reset_marker],  # Reset 토큰으로 기존 결과 초기화
+            "intermediate_steps": steps_delta
+        }
+    except Exception as e:
+        logger.error("쿼리 개선 실패: %s", e, exc_info=True)
+        
+        fallback_query = user_question + " tutorial example"
+        
+        steps_delta = [
+            f"⚠️ 쿼리 개선 실패, 기본 전략 사용",
+            f"   이후: {fallback_query}"
+        ]
+        
+        # 🔧 CRITICAL: WorkerState 필드만 반환
+        # Reset 토큰으로 기존 결과 초기화
+        reset_marker = SearchResult(source="__RESET__", content="", url="")
+        return {
+            "refined_question": fallback_query,  # ✅ WorkerState 필드
+            "original_question": original_question,  # ✅ WorkerState 필드
+            "refinement_count": state.refinement_count + 1,  # ✅ WorkerState 필드
+            "search_results": [reset_marker],  # ✅ Reset 토큰으로 기존 결과 초기화
+            "intermediate_steps": steps_delta  # ✅ WorkerState 필드
+        }
+

CodeWeaver/src/agent/routes.py

@@ -0,0 +1,126 @@
+"""라우팅 로직 모듈.
+
+조건부 엣지에서 사용되는 라우팅 함수들을 정의합니다.
+"""
+
+import logging
+from typing import Literal
+
+from langgraph.graph import END
+from langgraph.types import Send
+
+from src.agent.state import AgentState, WorkerState, _MULTI_ANS_RESET_TOKEN
+
+logger = logging.getLogger(__name__)
+
+
+def route_after_analysis_worker(state: WorkerState) -> Literal["generate_with_history", "generate_answer", "check_cache"]:
+    """질문 분석 후 라우팅"""
+    raw_qtype = state.question_type or "independent"
+    # new_topic 통합으로 인해 independent로 매핑
+    legacy_map = {
+        "followup": "clarification",
+        "cache_candidate": "independent",
+        "new_search": "independent",
+        "new_topic": "independent" 
+    }
+    question_type = legacy_map.get(raw_qtype, raw_qtype)
+
+    if question_type == "clarification":
+        return "generate_with_history"
+    
+    if question_type == "general_chat":
+        return "generate_answer"
+
+    return "check_cache"
+
+
+def route_after_cache_worker(state: WorkerState):
+    """
+    캐시 확인 후 라우팅.
+    캐시 히트 시 답변 반환, 캐시 미스 시 병렬 검색으로 직접 라우팅.
+    
+    Returns:
+        str: "return_cached_answer" (캐시 히트 시)
+        List[Send]: 병렬 검색 Send 객체 리스트 (캐시 미스 시)
+    """
+    if state.cached_result:
+        return "return_cached_answer"
+    else:
+        # 캐시 미스 시 병렬 검색으로 직접 라우팅 (Send 객체 리스트 반환)
+        return initiate_parallel_search_worker(state)
+
+
+def route_after_evaluation_worker(state: WorkerState) -> Literal["refine_search", "generate_answer"]:
+    """검색 결과 평가 후 라우팅"""
+    needs_refinement = state.needs_refinement
+    refinement_count = state.refinement_count
+    
+    if needs_refinement and refinement_count < 1:
+        return "refine_search"
+    else:
+        return "generate_answer"
+
+
+def initiate_parallel_search_worker(state: WorkerState):
+    """병렬 검색을 위한 Send 객체 리스트 생성"""
+    return [
+        Send("search_stackoverflow", state),
+        Send("search_github", state),
+        Send("search_official_docs", state),
+    ]
+
+
+def route_after_plan(state: AgentState):
+    """create_plan 결과에 따른 라우팅"""
+    if state.plan is None:
+        case = "single_topic"
+        questions = []
+    else:
+        case = state.plan.case
+        questions = state.plan.questions
+    
+    if case == "too_many":
+        return "handle_too_many_questions"
+    
+    elif case == "multiple_questions":
+        messages = state.messages
+        
+        logger.info("다중 질문 처리: %d개 질문 병렬 실행", len(questions))
+        
+        sends = []
+        for i, sq in enumerate(questions):
+            worker_state = WorkerState(
+                processing_question=sq,
+                messages=messages,
+                worker_is_multi=True,
+                worker_idx=i,
+                worker_sub_text=sq,
+            )
+            sends.append(Send("single_question_subgraph", worker_state))
+        
+        return sends
+    
+    else:
+        worker_state = WorkerState(
+            processing_question=state.user_question,
+            messages=state.messages,
+            worker_is_multi=False,
+            worker_idx=0,
+            worker_sub_text=None
+        )
+        return [Send("single_question_subgraph", worker_state)]
+
+
+def route_after_subgraph(state: AgentState):
+    """서브그래프 완료 후 라우팅"""
+    has_answers = any(
+        item.token != _MULTI_ANS_RESET_TOKEN
+        for item in state.multi_answers
+    )
+    
+    if has_answers:
+        return "combine_answers"
+    else:
+        return END
+

CodeWeaver/src/agent/state.py

@@ -19,12 +19,12 @@ def merge_intermediate_steps(old: List[str], new: List[str]) -> List[str]:
     return old + new
 
 
-def merge_multi_answers(old: List[Dict[str, Any]], new: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+def merge_multi_answers(old: List["MultiAnswerData"], new: List["MultiAnswerData"]) -> List["MultiAnswerData"]:
     """multi_answers reducer."""
     if not new:
         return old
     head = new[0]
-    if isinstance(head, dict) and head.get("__token__") == _MULTI_ANS_RESET_TOKEN:
+    if head.token == _MULTI_ANS_RESET_TOKEN:
         return new[1:]
     return old + new
 
@@ -33,7 +33,17 @@ def merge_search_results(old: List["SearchResult"], new: List["SearchResult"]) -
     """
     search_results reducer.
     병렬 검색 노드들이 동시에 search_results를 업데이트할 수 있도록 병합 로직 제공.
+    Reset 토큰(__RESET__)이 있으면 기존 리스트를 교체합니다.
     """
+    if not new:
+        return old
+    
+    # Reset 토큰 확인 (첫 번째 요소가 __RESET__인 경우)
+    if new and isinstance(new[0], SearchResult) and new[0].source == "__RESET__":
+        # Reset 토큰 이후의 결과만 반환 (기존 리스트 교체)
+        return new[1:]
+    
+    # 일반 병합
     return old + new
 
 
@@ -45,6 +55,22 @@ class SearchResult(BaseModel):
     relevance_score: Optional[float] = Field(default=None, description="관련도 점수")
 
 
+class PlanData(BaseModel):
+    """질문 분석 및 계획 데이터"""
+    case: Literal["single_topic", "multiple_questions", "too_many"] = "single_topic"
+    questions: List[str] = Field(default_factory=list)
+    reasoning: str = ""
+    error_message: str = ""
+
+
+class MultiAnswerData(BaseModel):
+    """다중 질문에 대한 개별 답변 데이터"""
+    index: int = 0
+    question: str = ""
+    answer: str = ""
+    token: Optional[str] = None  # 리듀서 리셋 토큰용 (__RESET_MULTI_ANS__)
+
+
 class AgentState(BaseModel):
     """부모 그래프 전용 상태."""
     
@@ -65,7 +91,7 @@ class AgentState(BaseModel):
     )
     
     # Planning
-    plan: Optional[Dict[str, Any]] = Field(
+    plan: Optional["PlanData"] = Field(
         default=None,
         description="질문 분해 계획"
     )
@@ -75,7 +101,7 @@ class AgentState(BaseModel):
     sub_question_index: int = Field(default=0)
     sub_question_text: Optional[str] = Field(default=None)
     original_multi_question: Optional[str] = Field(default=None)
-    multi_answers: Annotated[List[Dict[str, Any]], merge_multi_answers] = Field(
+    multi_answers: Annotated[List["MultiAnswerData"], merge_multi_answers] = Field(
         default_factory=list,
         description="다중 질문의 각 답변 리스트"
     )
@@ -101,12 +127,11 @@ class WorkerState(BaseModel):
     
     # === 서브그래프 내부 전용 필드 ===
     # (이 필드들은 서브그래프 내부에서만 사용, 부모에게 전달 안 됨)
-    question_type: Optional[Literal["clarification", "new_topic", "independent"]] = None
+    question_type: Optional[Literal["clarification", "general_chat", "independent"]] = None
     should_cache: Optional[bool] = None
     canonical_question: Optional[str] = None
     analysis_reasoning: Optional[str] = None
     cached_result: Optional[str] = None
-    detected_intent: Optional[Literal["debugging", "learning", "code_review"]] = None
     
     # 검색 결과 (병렬 업데이트 가능하도록 reducer 적용)
     search_results: Annotated[List[SearchResult], merge_search_results] = Field(
@@ -114,7 +139,11 @@ class WorkerState(BaseModel):
         description="병렬 검색 결과 (reducer로 자동 병합)"
     )
     
-    subtask_results: Dict[str, Any] = Field(default_factory=dict)
+    # 필터링된 최종 검색 결과 (evaluate_results_node에서 설정)
+    filtered_search_results: List["SearchResult"] = Field(
+        default_factory=list,
+        description="평가 및 필터링이 완료된 최종 검색 결과 데이터 리스트"
+    )
     
     # 쿼리 개선 (이 필드들은 refine_search_node만 업데이트)
     needs_refinement: bool = False
@@ -132,7 +161,7 @@ class WorkerState(BaseModel):
     # 이 필드들은 부모 AgentState에도 존재하며, Reducer가 있거나 충돌이 허용되는 필드여야 함
     final_answer: Optional[str] = None
     
-    multi_answers: Annotated[List[Dict[str, Any]], merge_multi_answers] = Field(
+    multi_answers: Annotated[List["MultiAnswerData"], merge_multi_answers] = Field(
         default_factory=list,
         description="다중 질문 답변용"
     )

CodeWeaver/src/core/__init__.py

@@ -0,0 +1,15 @@
+"""코어 모듈 - 앱의 심장부 (싱글톤, 설정, 팩토리)."""
+
+from src.core.config import settings, EMBEDDING_MODEL_NAME, EMBEDDING_DIMENSION
+from src.core.llm import get_llm
+from src.core.resources import get_reranker, get_qdrant_manager
+
+__all__ = [
+    "settings",
+    "EMBEDDING_MODEL_NAME",
+    "EMBEDDING_DIMENSION",
+    "get_llm",
+    "get_reranker",
+    "get_qdrant_manager",
+]
+

CodeWeaver/src/core/config.py

@@ -0,0 +1,47 @@
+"""설정 관리 모듈.
+
+pydantic-settings를 사용하여 환경 변수를 타입 안전하게 관리합니다.
+필수 환경 변수가 없으면 앱 시작 시 검증 오류가 발생합니다.
+"""
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """애플리케이션 설정 클래스.
+    
+    모든 환경 변수는 .env 파일 또는 시스템 환경 변수에서 로드됩니다.
+    필수 변수가 없으면 ValidationError가 발생합니다.
+    """
+    
+    # 필수 환경 변수
+    google_api_key: str = Field(..., description="Google Gemini API 키")
+    qdrant_url: str = Field(..., description="Qdrant Cloud URL")
+    qdrant_api_key: str = Field(..., description="Qdrant Cloud API 키")
+    tavily_api_key: str = Field(..., description="Tavily API 키 (공식 문서 검색용)")
+    
+    # 선택적 환경 변수
+    github_token: str | None = Field(default=None, description="GitHub API 토큰 (rate limit 완화용)")
+    langchain_tracing_v2: str | None = Field(default=None, description="LangSmith 트레이싱 활성화 여부")
+    langchain_api_key: str | None = Field(default=None, description="LangSmith API 키")
+    
+    # Postgres 연결 문자열
+    postgres_db_url: str = Field(..., alias="POSTGRES_DB_URL")
+    
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+
+# 전역 설정 인스턴스
+# 앱 시작 시 환경 변수 검증이 수행됩니다.
+settings = Settings()
+
+# 임베딩 모델 설정 (코드에 직접 설정 - 런타임 변경 불필요)
+EMBEDDING_MODEL_NAME = "BAAI/bge-base-en-v1.5"
+EMBEDDING_DIMENSION = 768  # bge-base-en-v1.5의 차원
+

CodeWeaver/src/core/llm.py

@@ -0,0 +1,41 @@
+"""LLM 인스턴스 생성 및 관리 모듈.
+
+싱글톤 패턴을 사용하여 LLM 인스턴스를 중앙 집중식으로 관리합니다.
+"""
+
+import logging
+from typing import Optional
+
+from langchain_google_genai import ChatGoogleGenerativeAI
+
+from src.core.config import settings
+
+logger = logging.getLogger(__name__)
+
+# LLM 싱글톤 인스턴스
+_llm: Optional[ChatGoogleGenerativeAI] = None
+
+
+def get_llm() -> ChatGoogleGenerativeAI:
+    """
+    LLM 인스턴스를 반환합니다. (싱글톤 패턴)
+    
+    Returns:
+        ChatGoogleGenerativeAI 인스턴스
+    """
+    global _llm
+    
+    if _llm is not None:
+        return _llm
+    
+    logger.info("🤖 LLM 초기화 중 (Gemini 2.5 Flash Lite)...")
+    
+    _llm = ChatGoogleGenerativeAI(
+        model="gemini-2.5-flash-lite",
+        temperature=0.7,
+        google_api_key=settings.google_api_key,
+    )
+    
+    logger.info("✅ LLM 초기화 완료")
+    return _llm
+

CodeWeaver/src/core/resources.py

@@ -0,0 +1,86 @@
+"""무거운 리소스 관리 모듈 (Reranker, DB Client 등).
+
+싱글톤 패턴을 사용하여 무거운 리소스 인스턴스를 중앙 집중식으로 관리합니다.
+"""
+
+import logging
+import threading
+from typing import Optional
+
+from fastembed.rerank.cross_encoder import TextCrossEncoder
+from src.vector_db.qdrant_client import QdrantManager
+
+logger = logging.getLogger(__name__)
+
+# ==================== Reranker 싱글톤 ====================
+
+_reranker: Optional[TextCrossEncoder] = None
+_reranker_lock = threading.Lock()  # 🔒 스레드 락
+
+
+def get_reranker() -> TextCrossEncoder:
+    """
+    Reranker 모델을 Lazy Loading 방식으로 가져옵니다.
+    Thread-safe한 Double-Checked Locking 패턴을 적용하여 중복 로딩을 방지합니다.
+    
+    Returns:
+        TextCrossEncoder 인스턴스
+    """
+    global _reranker
+    
+    # 1. 먼저 락 없이 빠르게 체크 (이미 로딩된 경우 성능 저하 방지)
+    if _reranker is not None:
+        return _reranker
+
+    # 2. 로딩이 안 된 경우에만 락 획득
+    with _reranker_lock:
+        # 3. 락 획득 후 다시 한번 체크 (다른 스레드가 그 사이 로딩했을 수 있음)
+        if _reranker is None:
+            logger.info("⚡ Reranker 모델 로딩 중 (jinaai/jina-reranker-v1-tiny-en)...")
+            try:
+                # 모델 로드 (최초 1회 실행)
+                _reranker = TextCrossEncoder(model_name="jinaai/jina-reranker-v1-tiny-en")
+                logger.info("⚡ Reranker 모델 로딩 완료")
+            except Exception as e:
+                logger.error("Reranker 모델 로딩 실패: %s", e)
+                raise e
+                
+    return _reranker
+
+
+# ==================== QdrantManager 싱글톤 ====================
+
+_qdrant_manager: Optional[QdrantManager] = None
+_qdrant_lock = threading.Lock()  # 🔒 스레드 락
+
+
+def get_qdrant_manager(collection_name: str = "CodeWeaver") -> QdrantManager:
+    """
+    QdrantManager 인스턴스를 반환합니다. (싱글톤 패턴)
+    
+    Args:
+        collection_name: 컬렉션 이름 (기본값: "CodeWeaver")
+    
+    Returns:
+        QdrantManager 인스턴스
+    """
+    global _qdrant_manager
+    
+    # 1. 먼저 락 없이 빠르게 체크
+    if _qdrant_manager is not None:
+        return _qdrant_manager
+    
+    # 2. 로딩이 안 된 경우에만 락 획득
+    with _qdrant_lock:
+        # 3. 락 획득 후 다시 한번 체크
+        if _qdrant_manager is None:
+            logger.info("🗄️ QdrantManager 초기화 중...")
+            try:
+                _qdrant_manager = QdrantManager(collection_name=collection_name)
+                logger.info("✅ QdrantManager 초기화 완료")
+            except Exception as e:
+                logger.error("QdrantManager 초기화 실패: %s", e)
+                raise e
+    
+    return _qdrant_manager
+

CodeWeaver/src/prompts/__init__.py

@@ -0,0 +1,6 @@
+"""프롬프트 템플릿 관리 모듈."""
+
+from src.prompts.loader import load_prompt
+
+__all__ = ["load_prompt"]
+

CodeWeaver/src/prompts/loader.py

@@ -0,0 +1,144 @@
+"""프롬프트 템플릿 로더 모듈.
+
+YAML 파일에서 프롬프트를 로드하고 Jinja2 템플릿으로 렌더링합니다.
+파일 I/O 최적화를 위해 템플릿 캐싱을 적용합니다.
+"""
+
+import logging
+import os
+from pathlib import Path
+from typing import Dict, Any
+
+import yaml
+from jinja2 import Template, TemplateError
+
+logger = logging.getLogger(__name__)
+
+# 템플릿 캐시 (파일 경로 -> 파싱된 YAML 딕셔너리)
+_template_cache: Dict[str, Dict[str, str]] = {}
+
+
+def _get_template_path(template_name: str) -> Path:
+    """템플릿 파일 경로를 반환합니다.
+    
+    Args:
+        template_name: 템플릿 파일 이름 (확장자 제외, 예: "planning")
+    
+    Returns:
+        템플릿 파일의 전체 경로
+    """
+    # 현재 파일의 디렉토리 기준으로 templates 디렉토리 찾기
+    current_dir = Path(__file__).parent
+    template_file = current_dir / "templates" / f"{template_name}.yaml"
+    return template_file
+
+
+def _load_yaml_file(template_name: str) -> Dict[str, str]:
+    """YAML 파일을 로드하고 캐시에 저장합니다.
+    
+    Args:
+        template_name: 템플릿 파일 이름 (확장자 제외)
+    
+    Returns:
+        YAML 파일의 내용 (딕셔너리)
+    
+    Raises:
+        FileNotFoundError: 템플릿 파일이 없을 때
+        yaml.YAMLError: YAML 파싱 오류
+    """
+    template_path = _get_template_path(template_name)
+    
+    # 캐시 확인
+    cache_key = str(template_path)
+    if cache_key in _template_cache:
+        return _template_cache[cache_key]
+    
+    # 파일 존재 확인
+    if not template_path.exists():
+        raise FileNotFoundError(
+            f"프롬프트 템플릿 파일을 찾을 수 없습니다: {template_path}"
+        )
+    
+    # YAML 파일 로드
+    try:
+        with open(template_path, "r", encoding="utf-8") as f:
+            content = yaml.safe_load(f)
+        
+        if not isinstance(content, dict):
+            raise ValueError(
+                f"YAML 파일은 딕셔너리 형태여야 합니다: {template_path}"
+            )
+        
+        # 캐시에 저장
+        _template_cache[cache_key] = content
+        logger.debug(f"프롬프트 템플릿 로드 완료: {template_name}")
+        
+        return content
+    
+    except yaml.YAMLError as e:
+        logger.error(f"YAML 파싱 오류 ({template_path}): {e}")
+        raise
+    except Exception as e:
+        logger.error(f"템플릿 파일 로드 실패 ({template_path}): {e}")
+        raise
+
+
+def load_prompt(template_name: str, prompt_key: str, **kwargs: Any) -> str:
+    """프롬프트 템플릿을 로드하고 변수를 치환하여 반환합니다.
+    
+    Args:
+        template_name: 템플릿 파일 이름 (확장자 제외, 예: "planning")
+        prompt_key: YAML 파일 내의 프롬프트 키 (예: "plan_prompt")
+        **kwargs: 템플릿 변수 (Jinja2 변수로 전달됨)
+    
+    Returns:
+        렌더링된 프롬프트 문자열
+    
+    Raises:
+        FileNotFoundError: 템플릿 파일이 없을 때
+        KeyError: prompt_key가 YAML 파일에 없을 때
+        TemplateError: Jinja2 템플릿 렌더링 오류
+    """
+    # YAML 파일 로드
+    yaml_content = _load_yaml_file(template_name)
+    
+    # 프롬프트 키 확인
+    if prompt_key not in yaml_content:
+        available_keys = ", ".join(yaml_content.keys())
+        raise KeyError(
+            f"프롬프트 키 '{prompt_key}'를 찾을 수 없습니다. "
+            f"사용 가능한 키: {available_keys} (템플릿: {template_name})"
+        )
+    
+    # 프롬프트 템플릿 가져오기
+    prompt_template = yaml_content[prompt_key]
+    
+    if not isinstance(prompt_template, str):
+        raise ValueError(
+            f"프롬프트 값은 문자열이어야 합니다: {template_name}.{prompt_key}"
+        )
+    
+    # Jinja2 템플릿 렌더링
+    try:
+        template = Template(prompt_template)
+        rendered = template.render(**kwargs)
+        return rendered
+    
+    except TemplateError as e:
+        logger.error(
+            f"템플릿 렌더링 오류 ({template_name}.{prompt_key}): {e}"
+        )
+        raise
+    except Exception as e:
+        logger.error(
+            f"프롬프트 로드 실패 ({template_name}.{prompt_key}): {e}"
+        )
+        raise
+
+
+def clear_cache():
+    """템플릿 캐시를 초기화합니다. (주로 테스트용)"""
+    global _template_cache
+    _template_cache.clear()
+    logger.debug("프롬프트 템플릿 캐시 초기화됨")
+

CodeWeaver/src/prompts/templates/analysis.yaml

@@ -0,0 +1,45 @@
+analysis_prompt: |
+  질문을 분석하세요.
+  
+  {{ context_info }}
+  현재 질문: {{ user_question }}
+  
+  분류 기준:
+  
+  1. **clarification** (보충/형식 변경 요청)
+     - 이전 답변/대화 내용을 바탕으로 "설명 방식"을 바꾸거나 보충을 요청
+     - 예: "좀 더 쉽게 설명해줘", "예제 코드로 보여줘", "한 줄로 요약해줘"
+     - should_cache = false, canonical_question = null, refined_query = null
+     
+  2. **general_chat** (일상 대화, 정체성, 주제 이탈)
+     - 일상적인 인사: "안녕", "반가워", "고마워"
+     - AI 정체성 질문: "너 누구야?", "뭐 할 줄 알아?"
+     - 대화 내용 요약 질문: "지금까지 무슨 얘기 했지?", "대화 내용 요약해줘"
+     - **주제 이탈(Off-topic):** 날씨, 음식 메뉴, 연예인, 주식, 일반 상식 등 **프로그래밍/개발과 무관한 모든 질문**
+     - 예: "내일 날씨 알려줘", "저녁 메뉴 추천해줘", "주식 시세 알려줘"
+     - should_cache = false, canonical_question = null, refined_query = null
+     
+  3. **independent** (검색이 필요한 기술 질문)
+     - 새로운 주제의 개념, 사용법, 에러 해결 등 기술적인 질문
+     - 대화 도중 화제가 전환되어 나오는 새로운 질문도 포함
+     - 이전 대화의 문맥(대명사 등)이 있다면 이를 반영하여 '완전한 질문'으로 재구성해야 함
+     - 예: "Spring Security가 뭐야?", "Docker Compose 사용법은?"
+     - 예 (화제 전환): "그럼 Session이랑은 뭐가 달라?" → "JWT와 Session 기반 인증의 차이점은 무엇인가?"로 재구성
+     - should_cache = true, canonical_question 생성 필수
+     - **refined_query 필수**: 검색 엔진(StackOverflow, GitHub, MDN 등)에 최적화된 영어 검색 쿼리 생성
+       * 한국어 기술 용어는 영어 원문을 함께 포함 (예: "Thread 스레드", "Django 장고")
+       * 에러 메시지나 코드 스니펫이 있으면 핵심 키워드만 추출
+       * 예: "JWT 인증 구현" → "JWT authentication implementation"
+       * 예: "스레드 동기화 문제" → "Thread synchronization problem"
+  
+  다음 JSON 형식으로만 답변하세요:
+  {
+      "question_type": "clarification|general_chat|independent",
+      "should_cache": true|false,
+      "reasoning": "분류 이유 1-2문장",
+      "canonical_question": "캐시할 정규화된 질문 (should_cache가 true인 경우에만, 아니면 null)",
+      "refined_query": "영어 검색 쿼리 (independent인 경우에만, 아니면 null)"
+  }
+  
+  JSON 외에 다른 텍스트는 포함하지 마세요.
+

CodeWeaver/src/prompts/templates/answer.yaml

@@ -0,0 +1,65 @@
+general_chat_template: |
+  당신은 개발자 어시스턴트 **'CodeWeaver'**입니다.
+  
+  **이전 대화 내역 (Context):**
+  {{ history }}
+  
+  질문: {{ question }}
+  
+  지침:
+  1. **대화 맥락 유지**: 위 '이전 대화 내역'은 참고용입니다. 필요할 때만 자연스럽게 활용하세요.
+     - 사용자가 "아까 말한 거"라고 하면 내역을 보고 추론하세요.
+     - "내 이름이 뭐였지?"처럼 명시적으로 물어볼 때만 내역을 확인하세요.
+     - **중요**: 이전 대화를 자동으로 요약하거나 언급하지 마세요. 사용자가 명시적으로 요청한 경우에만 요약하세요.
+     
+  2. **인사말 반복 금지**: 이전 대화에서 인사말이 있었다고 해서 매번 "안녕하세요! CodeWeaver입니다. 😊" 같은 인사말을 반복하지 마세요.
+     - 첫 대화가 아니면 불필요한 인사말을 생략하고 직접적으로 답변하세요.
+  
+  3. **일상적인 인사/정체성**: 친절하고 전문적인 톤으로 답하세요. 하지만 간결하고 직접적으로 답변하세요.
+  
+  4. **개발 외 질문 거절**: 날씨, 연예인 등은 정중히 거절하세요.
+  
+  5. **없는 기억 지어내지 않기**: 내역에 없으면 솔직히 모른다고 하세요.
+  
+  위 지침에 따라 답변을 생성하세요.
+
+technical_template: |
+  당신은 개발자 어시스턴트입니다. 다음 검색 결과를 바탕으로 질문에 답변하세요.
+  
+  질문: {{ question }}
+  
+  수집된 정보:
+  {{ summaries }}
+  
+  지침:
+  - 검색 결과를 바탕으로 개념을 설명하거나 에러를 해결하세요.
+  - 코드 예제가 필요하면 제공하세요.
+  - 초보 개발자도 이해할 수 있게 명확하고 간결하게 작성하세요.
+  - Markdown 형식으로 작성하세요.
+
+fallback_system_instruction: |
+  지침:
+  - 현재 제공된 '수집된 정보'가 부족합니다.
+  - **검색 결과에 의존하지 말고, 당신의 프로그래밍 지식을 활용하여 답변하세요.**
+  - 질문이 명확한 기술 개념(예: Thread, Loop)이라면 상세히 설명하세요.
+  - 질문이 너무 모호하거나 최신 라이브러리 버전에 관한 것이라면, 솔직하게 모른다고 하거나 일반적인 원리만 설명하세요.
+
+context_prompt_base: |
+  이전 대화를 참고하여 후속 질문에 답변하세요.
+  
+  
+  지침:
+      1. 사용자의 질문이 '이전 대화'와 맥락이 이어진다면, 대화 내역의 정보를 적극 활용하세요.
+      2. 만약 질문이 이전 대화와 전혀 상관없는 새로운 주제라면, 이전 내역을 무시하고 질문 자체에 집중하세요.
+  
+  {{ recent_context }}
+  
+  현재 질문: {{ user_question }}
+  
+  
+  지침:
+  1. **오직 '현재 질문'에 대해서만 답변하세요.**
+  2. '직전 대화 내역'은 문맥 파악 용도로만 사용하세요.
+  3. 과거에 답변하지 못했거나 거절했던 질문이 있더라도, 사용자가 다시 묻지 않았다면 **절대 다시 언급하거나 답변하지 마세요.**
+  4. 현재 질문에 집중하여 명확하고 간결하게 답변하세요.
+

CodeWeaver/src/prompts/templates/planning.yaml

@@ -0,0 +1,66 @@
+plan_prompt: |
+  사용자의 입력을 분석하여 질문 유형과 개수를 판단하세요.
+  
+  입력 텍스트:
+  ---
+  {{ user_question }}
+  ---
+  
+  **분석 규칙 (매우 중요)**:
+  1. **코드 무시**: 입력에 포함된 코드 블록, import 구문, 에러 로그 등은 질문 개수로 세지 마세요. 오직 사용자가 자연어로 물어본 문장만 질문으로 간주하세요.
+     - 예: "import java.util.*; 이거 왜 에러나?" → 질문 1개 (코드는 무시)
+     - 예: "이 코드 문제점은? ```python\nprint('hello')\n```" → 질문 1개 (코드는 무시)
+  2. **배경 설명 무시**: "내가 지금 Spring을 쓰고 있는데...", "프로젝트에서..." 같은 배경 설명은 질문이 아닙니다.
+  3. **개수 제한**: 
+     - 질문이 1개면: "single_topic"
+     - 질문이 2개면: "multiple_questions"
+     - 질문이 3개 이상이면: "too_many" (처리 불가)
+  
+  **Case 정의**:
+  - **single_topic**: 하나의 명확한 주제. 
+    - 예: "Spring Security 설정법 알려줘"
+    - 예: "이 코드 왜 에러 나?"
+    - 예: "JWT 인증 구현 방법"
+    - questions: 답변 섹션 구조를 위한 키워드/구절 (1-5개)
+    
+  - **multiple_questions**: 서로 다른 독립적인 주제 2개. 
+    - 예: "JWT는 뭐야? 그리고 Redis는 어떻게 설치해?"
+    - 예: "CORS가 뭐야? JWT는?"
+    - **문맥 보존 (매우 중요)**: 대명사나 문맥 참조("C랑은", "그럼", "그것은" 등)를 해석할 때 이전 질문의 맥락을 반영해야 합니다.
+      - 잘못된 예: "파이썬은 어떤 언어야? C랑은 어떻게 달라?" → ["파이썬은 어떤 언어인가?", "C++와 C의 차이점은 무엇인가?"] ❌
+      - 올바른 예: "파이썬은 어떤 언어야? C랑은 어떻게 달라?" → ["파이썬은 어떤 언어인가?", "파이썬과 C의 차이점은 무엇인가?"] ✅
+    - **완전한 질문 재구성**: 각 질문이 독립적으로 이해 가능하도록 완전한 문장으로 재구성하세요.
+      - 대명사나 생략된 주어가 있으면 이전 질문의 맥락을 반영하여 명확하게 재구성
+      - 예: "Spring이 뭐야? 그럼 Django는?" → ["Spring이란 무엇인가?", "Spring과 Django의 차이점은 무엇인가?"]
+    - questions: 완전한 질문 문장 2개 (정확히 2개만, 각 질문이 독립적으로 이해 가능해야 함)
+    
+  - **too_many**: 질문이 3개 이상 나열됨.
+    - 예: "JWT? CORS? Docker? Redis?"
+    - error_message: 사용자에게 안내 메시지 작성
+  
+  다음 JSON 형식으로만 답변하세요:
+  {
+      "case": "single_topic|multiple_questions|too_many",
+      "questions": ["질문1", "질문2"] 또는 ["키워드1", "키워드2"],
+      "reasoning": "판단 이유 (1-2문장)",
+      "error_message": "..." (too_many인 경우만 메시지 작성, 그 외는 빈 문자열)
+  }
+  
+  JSON 외에 다른 텍스트는 포함하지 마세요.
+
+too_many_questions_message: |
+  죄송합니다. 한 번에 최대 2개의 질문까지만 처리할 수 있습니다.
+  
+  다음 중 하나를 선택해서 다시 질문해 주세요:
+  
+  1. **하나의 주제로 통합해서 질문**
+     예: "JWT 인증과 CORS 설정을 함께 구현하는 방법"
+  
+  2. **가장 중요한 2개 질문만 선택**
+     예: "JWT가 뭐야? 내 코드에 어떻게 적용해?"
+  
+  3. **질문을 나눠서 순차적으로 질문**
+     예: 먼저 "JWT가 뭐야?" 질문 → 답변 확인 → 다음 질문
+  
+  어떻게 도와드릴까요?
+

CodeWeaver/src/prompts/templates/search.yaml

@@ -0,0 +1,25 @@
+refinement_prompt: |
+  검색 결과가 부족합니다. 검색 쿼리를 개선하세요.
+  
+  원본 질문: {{ user_question }}
+  현재 결과 수: {{ result_count }}개 (목표: 2개 이상)
+  
+  **핵심 지침 (영어 병기)**:
+  검색 엔진(StackOverflow, MDN 등)은 영어 쿼리에 훨씬 더 정확하게 반응합니다.
+  한국어 기술 용어가 있다면 **반드시 영어 원문을 함께 적어주세요.**
+  (예: "스레드" -> "Thread 스레드", "장고" -> "Django 장고", "N+1 문제" -> "N+1 problem")
+  
+  개선 전략 (하나 선택):
+  1. MORE_SPECIFIC: 기술적 세부사항을 추가하고 영어 용어 병기
+  2. MORE_GENERAL: 더 넓은 범위의 용어로 변경
+  3. TRANSLATE: 한국어 질문을 영어 위주의 검색 쿼리로 변환
+  
+  다음 JSON 형식으로만 답변하세요:
+  {
+      "new_query": "영어 용어가 포함된 개선된 쿼리",
+      "strategy": "MORE_SPECIFIC|MORE_GENERAL|TRANSLATE",
+      "reasoning": "이 전략을 선택한 이유 1-2문장"
+  }
+  
+  JSON 외에 다른 텍스트는 포함하지 마세요.
+

CodeWeaver/src/scripts/init_db.py

@@ -0,0 +1,47 @@
+"""
+DB 초기화 스크립트.
+LangGraph 상태 저장을 위한 필수 테이블(checkpoints 등)을 생성합니다.
+배포 전 또는 최초 1회 실행하면 됩니다.
+실행: uv run python src/scripts/init_db.py
+"""
+import sys
+import logging
+from pathlib import Path
+
+# 프로젝트 루트 경로 추가 (src 모듈 import 위해)
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+
+from psycopg_pool import ConnectionPool
+from langgraph.checkpoint.postgres import PostgresSaver
+from src.core.config import settings
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+def init_db():
+    logger.info("🚧 DB 테이블 초기화 시작...")
+    
+    # 보안을 위해 URL 마스킹
+    safe_url = settings.postgres_db_url.split("@")[-1] if "@" in settings.postgres_db_url else "..."
+    logger.info(f"Target DB: {safe_url}")
+
+    try:
+        # 동기 연결 풀 생성 (setup은 1회성 작업이므로 동기가 편함)
+        with ConnectionPool(
+            conninfo=settings.postgres_db_url,
+            min_size=1,
+            max_size=1,
+            kwargs={"autocommit": True}
+        ) as pool:
+            checkpointer = PostgresSaver(pool)
+            checkpointer.setup()
+            
+        logger.info("✅ DB 테이블 생성(Setup) 완료!")
+        logger.info("이제 앱을 실행할 수 있습니다.")
+        
+    except Exception as e:
+        logger.error(f"❌ DB 초기화 실패: {e}")
+        raise
+
+if __name__ == "__main__":
+    init_db()

CodeWeaver/src/scripts/init_qdrant.py

@@ -0,0 +1,73 @@
+"""
+Qdrant 컬렉션 초기화 스크립트.
+Qdrant 벡터 캐시를 위한 컬렉션을 생성합니다.
+배포 전 또는 최초 1회 실행하면 됩니다.
+실행: uv run python src/scripts/init_qdrant.py
+"""
+import sys
+import logging
+from pathlib import Path
+
+# 프로젝트 루트 경로 추가 (src 모듈 import 위해)
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+
+from qdrant_client import QdrantClient, models
+from src.core.config import settings
+from src.vector_db.local_embeddings import LocalEmbeddingManager
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+def init_qdrant(collection_name: str = "CodeWeaver") -> None:
+    """Qdrant 컬렉션을 초기화한다.
+    
+    컬렉션이 존재하지 않으면 생성하고, 이미 존재하면 스킵합니다.
+    """
+    logger.info("🚧 Qdrant 컬렉션 초기화 시작...")
+    
+    # 보안을 위해 URL 마스킹
+    safe_url = settings.qdrant_url.split("@")[-1] if "@" in settings.qdrant_url else settings.qdrant_url
+    logger.info(f"Target Qdrant: {safe_url}")
+    logger.info(f"Collection: {collection_name}")
+    
+    try:
+        # Qdrant 클라이언트 생성
+        client = QdrantClient(
+            url=settings.qdrant_url,
+            api_key=settings.qdrant_api_key,
+            timeout=30,
+        )
+        
+        # 컬렉션 존재 여부 확인
+        exists = client.collection_exists(collection_name)
+        
+        if exists:
+            logger.info(f"✅ 컬렉션 '{collection_name}' 이미 존재합니다.")
+            return
+        
+        # 임베딩 모델의 차원을 동적으로 가져옴
+        embedding_manager = LocalEmbeddingManager()
+        embedding_dim = embedding_manager.get_embedding_dimension()
+        
+        # 컬렉션 생성
+        client.create_collection(
+            collection_name=collection_name,
+            vectors_config=models.VectorParams(
+                size=embedding_dim,  # fastembed 모델의 실제 차원
+                distance=models.Distance.COSINE,
+            ),
+        )
+        
+        logger.info(f"✅ Qdrant 컬렉션 생성 완료: {collection_name} (벡터 차원: {embedding_dim})")
+        logger.info("이제 앱을 실행할 수 있습니다.")
+        
+    except Exception as e:
+        logger.error(f"❌ Qdrant 컬렉션 초기화 실패: {e}")
+        raise
+
+
+if __name__ == "__main__":
+    init_qdrant()
+
+

CodeWeaver/src/tools/__init__.py

@@ -1,4 +1,4 @@
-from .search_tools import (
+from .search import (
     search_github,
     search_official_docs,
     search_stackoverflow,
@@ -9,4 +9,3 @@ __all__ = [
     "search_github",
     "search_official_docs",
 ]
-

CodeWeaver/src/tools/{search_tools.py → search.py}

@@ -1,5 +1,5 @@
 import logging
-import os
+import re
 import time
 from typing import List
 
@@ -7,6 +7,7 @@ import requests
 from tavily import TavilyClient  # type: ignore[import]
 
 from src.agent.state import SearchResult
+from src.core.config import settings
 
 
 logger = logging.getLogger(__name__)
@@ -27,57 +28,52 @@ def search_stackoverflow(query: str, limit: int = 3) -> List[SearchResult]:
         return []
     
     try:
+        # Stack Overflow API v2.3 사용
+        # https://api.stackexchange.com/docs/search
         url = "https://api.stackexchange.com/2.3/search/advanced"
         params = {
             "q": query,
-            "order": "desc",
-            "sort": "votes",
             "site": "stackoverflow",
+            "sort": "relevance",
+            "order": "desc",
             "pagesize": limit,
-            "filter": "withbody",
+            "filter": "withbody",  # 본문 포함
         }
         
         response = requests.get(url, params=params, timeout=10)
         response.raise_for_status()
-        
         data = response.json()
-        items = data.get("items", [])
         
         results = []
-        max_score = max((item.get("score", 0) for item in items), default=1)
-        
-        for item in items:
+        for item in data.get("items", [])[:limit]:
+            # 제목과 본문을 결합하여 content 생성
             title = item.get("title", "")
-            body = item.get("body", "")[:500]  # 본문 일부만 포함
-            content = f"{title}\n\n{body}"
-            
-            score = item.get("score", 0)
-            # 정규화: 0-1 범위로 변환
-            relevance = min(score / max(max_score, 1), 1.0) if max_score > 0 else 0.5
+            body = item.get("body", "")
+            # HTML 태그 제거 (간단한 정규식)
+            body_clean = re.sub(r"<[^>]+>", "", body)
+            content = f"{title}\n\n{body_clean[:500]}"  # 본문은 500자로 제한
             
             results.append(
                 SearchResult(
-                    source="Stack Overflow",
+                    source="StackOverflow",
                     content=content,
-                    url=item.get("link"),
-                    relevance_score=relevance,
+                    url=f"https://stackoverflow.com/questions/{item.get('question_id')}",
                 )
             )
         
-        logger.info("Stack Overflow 검색 성공: %d개 결과", len(results))
-        
-        # Rate limit 준수
-        time.sleep(1)
-        
+        logger.info("Stack Overflow 검색 완료: %d개 결과", len(results))
         return results
         
+    except requests.exceptions.RequestException as e:
+        logger.error("Stack Overflow 검색 실패: %s", e)
+        return []
     except Exception as e:
-        logger.error("Stack Overflow 검색 실패: %s", e, exc_info=True)
+        logger.error("Stack Overflow 검색 중 예상치 못한 오류: %s", e, exc_info=True)
         return []
 
 
 def search_github(query: str, limit: int = 3) -> List[SearchResult]:
-    """GitHub에서 관련 코드를 검색한다.
+    """GitHub Issues/Discussions에서 관련 내용을 검색한다.
     
     Args:
         query: 검색 쿼리
@@ -90,76 +86,59 @@ def search_github(query: str, limit: int = 3) -> List[SearchResult]:
         logger.warning("GitHub 검색: 빈 쿼리")
         return []
     
+    github_token = settings.github_token
+    
+    if not github_token:
+        logger.warning("GitHub 토큰이 없어 검색을 건너뜁니다.")
+        return []
+    
     try:
-        url = "https://api.github.com/search/code"
-        
-        # Python 코드로 제한 (언어 감지 로직은 추후 확장 가능)
-        search_query = f"{query} language:python"
-        
+        # GitHub Search API 사용
+        # https://docs.github.com/en/rest/search/search
+        url = "https://api.github.com/search/issues"
+        headers = {
+            "Accept": "application/vnd.github+json",
+            "Authorization": f"Bearer {github_token}",
+        }
         params = {
-            "q": search_query,
-            "sort": "indexed",
+            "q": f"{query} is:issue is:open",  # 열린 이슈만 검색
+            "sort": "relevance",
             "per_page": limit,
         }
         
-        headers = {
-            "Accept": "application/vnd.github.v3+json",
-        }
-        
-        # GitHub 토큰이 있으면 Authorization 헤더 추가
-        github_token = os.getenv("GITHUB_TOKEN", "").strip()
-        if github_token:
-            headers["Authorization"] = f"token {github_token}"
-            logger.debug("GitHub 토큰 사용 (인증된 요청)")
-        else:
-            logger.warning(
-                "GITHUB_TOKEN이 설정되지 않음 - rate limit 제한적 (60 req/hr). "
-                "토큰 설정 시 5,000 req/hr로 증가"
-            )
-        
-        response = requests.get(url, params=params, headers=headers, timeout=10)
+        response = requests.get(url, headers=headers, params=params, timeout=10)
         response.raise_for_status()
-        
         data = response.json()
-        items = data.get("items", [])
         
         results = []
-        for item in items:
-            repo_name = item.get("repository", {}).get("full_name", "unknown")
-            path = item.get("path", "")
-            content = f"Repository: {repo_name}\nFile: {path}"
+        for item in data.get("items", [])[:limit]:
+            title = item.get("title", "")
+            body = item.get("body", "") or ""
+            # 본문이 너무 길면 잘라냄
+            body_clean = body[:500] if body else ""
+            content = f"{title}\n\n{body_clean}"
             
             results.append(
                 SearchResult(
                     source="GitHub",
                     content=content,
-                    url=item.get("html_url"),
-                    relevance_score=0.8,  # GitHub 결과는 일반적으로 높은 관련도
+                    url=item.get("html_url", ""),
                 )
             )
         
-        logger.info("GitHub 검색 성공: %d개 결과", len(results))
-        
-        # Rate limit 준수
-        time.sleep(1)
-        
+        logger.info("GitHub 검색 완료: %d개 결과", len(results))
         return results
         
-    except requests.exceptions.HTTPError as e:
-        if e.response.status_code == 403:
-            logger.warning("GitHub API rate limit 초과")
-        elif e.response.status_code == 401:
-            logger.warning("GitHub API 인증 실패 (토큰이 없거나 잘못됨). 토큰 없이 계속 진행합니다.")
-        else:
-            logger.error("GitHub 검색 HTTP 에러: %s", e, exc_info=True)
+    except requests.exceptions.RequestException as e:
+        logger.error("GitHub 검색 실패: %s", e)
         return []
     except Exception as e:
-        logger.error("GitHub 검색 실패: %s", e, exc_info=True)
+        logger.error("GitHub 검색 중 예상치 못한 오류: %s", e, exc_info=True)
         return []
 
 
 def search_official_docs(query: str, limit: int = 3) -> List[SearchResult]:
-    """Tavily API를 사용해 공식 문서를 검색한다.
+    """공식 문서 및 웹 검색을 수행한다 (Tavily API 사용).
     
     Args:
         query: 검색 쿼리
@@ -169,49 +148,42 @@ def search_official_docs(query: str, limit: int = 3) -> List[SearchResult]:
         SearchResult 리스트 (실패 시 빈 리스트)
     """
     if not query.strip():
-        logger.warning("Official Docs 검색: 빈 쿼리")
-        return []
-    
-    api_key = os.getenv("TAVILY_API_KEY", "").strip()
-    if not api_key:
-        logger.error("TAVILY_API_KEY 환경 변수가 설정되어 있지 않습니다.")
+        logger.warning("공식 문서 검색: 빈 쿼리")
         return []
     
     try:
-        client = TavilyClient(api_key=api_key)
+        tavily_client = TavilyClient(api_key=settings.tavily_api_key)
         
-        response = client.search(
+        # Tavily Search API 호출
+        # https://docs.tavily.com/python-client
+        response = tavily_client.search(
             query=query,
-            search_depth="basic",
+            search_depth="basic",  # basic | advanced
             max_results=limit,
-            include_domains=[
-                "docs.python.org",
-                "docs.oracle.com",
-                "spring.io/guides",
-                "developer.mozilla.org",
-                "reactjs.org/docs",
-            ],
         )
         
         results = []
-        for item in response.get("results", []):
-            content = item.get("content", "")
-            url = item.get("url", "")
-            score = item.get("score", 0.5)  # Tavily가 제공하는 관련도 점수
+        for result in response.get("results", [])[:limit]:
+            title = result.get("title", "")
+            content = result.get("content", "")
+            url = result.get("url", "")
+            
+            # content가 너무 길면 잘라냄
+            if len(content) > 1000:
+                content = content[:1000] + "..."
             
             results.append(
                 SearchResult(
-                    source="Official Docs",
-                    content=content,
+                    source="OfficialDocs",
+                    content=f"{title}\n\n{content}",
                     url=url,
-                    relevance_score=score,
                 )
             )
         
-        logger.info("Tavily 검색 성공: %d개 결과", len(results))
+        logger.info("공식 문서 검색 완료: %d개 결과", len(results))
         return results
         
     except Exception as e:
-        logger.error("Tavily 검색 실패: %s", e, exc_info=True)
+        logger.error("공식 문서 검색 실패: %s", e, exc_info=True)
         return []
 

CodeWeaver/src/vector_db/local_embeddings.py

@@ -1,34 +1,113 @@
 """
 로컬 임베딩 관리 모듈.
 
-BAAI/bge-m3 모델을 사용해 로컬에서 임베딩을 생성한다.
+fastembed를 사용하여 빠르고 가벼운 임베딩을 생성합니다.
+Singleton 패턴을 적용하여 모델이 한 번만 로드되도록 보장합니다.
 """
 
 import logging
+import threading
 from typing import List
 
-from sentence_transformers import SentenceTransformer
+from fastembed import TextEmbedding
+
+from src.core.config import settings, EMBEDDING_MODEL_NAME, EMBEDDING_DIMENSION
 
 logger = logging.getLogger(__name__)
 
 
 class LocalEmbeddingManager:
-    """BAAI/bge-m3 로컬 임베딩 생성기."""
+    """fastembed 기반 로컬 임베딩 생성기 (Singleton 패턴).
+    
+    Thread-safe Singleton 패턴을 사용하여 모델이 한 번만 로드되도록 보장합니다.
+    여러 인스턴스 생성 시에도 동일한 모델 인스턴스를 공유합니다.
+    """
 
-    def __init__(self, model_name: str = "BAAI/bge-m3") -> None:
-        logger.info("로컬 임베딩 모델 로딩 중: %s", model_name)
-        self.model = SentenceTransformer(model_name)
-        dim = self.model.get_sentence_embedding_dimension()
-        logger.info("로컬 임베딩 모델 로딩 완료 (차원: %d)", dim)
+    _instance: "LocalEmbeddingManager | None" = None
+    _lock: threading.Lock = threading.Lock()
+    _initialized: bool = False
 
-    def get_embedding(self, text: str) -> List[float]:
-        """단일 텍스트를 임베딩."""
-        embedding = self.model.encode(text, convert_to_numpy=True)
-        return embedding.tolist()
+    def __new__(cls) -> "LocalEmbeddingManager":
+        """Singleton 패턴: 인스턴스가 이미 존재하면 기존 인스턴스를 반환합니다."""
+        if cls._instance is None:
+            with cls._lock:
+                # Double-checked locking pattern
+                if cls._instance is None:
+                    cls._instance = super().__new__(cls)
+        return cls._instance
 
-    def get_embeddings_batch(self, texts: List[str]) -> List[List[float]]:
-        """배치 텍스트 임베딩."""
-        embeddings = self.model.encode(texts, convert_to_numpy=True)
-        return embeddings.tolist()
+    def __init__(self) -> None:
+        """모델이 아직 초기화되지 않았으면 초기화합니다."""
+        if not LocalEmbeddingManager._initialized:
+            with self._lock:
+                # Double-checked locking pattern
+                if not LocalEmbeddingManager._initialized:
+                    self._initialize()
+                    LocalEmbeddingManager._initialized = True
 
+    def _initialize(self) -> None:
+        """임베딩 모델을 로드합니다."""
+        logger.info("로컬 임베딩 모델 로딩 중: %s (fastembed)", EMBEDDING_MODEL_NAME)
+        
+        try:
+            self.model = TextEmbedding(model_name=EMBEDDING_MODEL_NAME)
+            self.embedding_dimension = EMBEDDING_DIMENSION
+            logger.info("로컬 임베딩 모델 로딩 완료: %s (차원: %d)", EMBEDDING_MODEL_NAME, self.embedding_dimension)
+        except Exception as e:
+            logger.error("임베딩 모델 로딩 실패: %s", e, exc_info=True)
+            raise RuntimeError(f"임베딩 모델 로딩 실패: {e}") from e
+    
+    def get_embedding_dimension(self) -> int:
+        """임베딩 벡터의 차원을 반환합니다.
+        
+        Returns:
+            임베딩 벡터의 차원 (설정에서 지정된 값)
+        """
+        return self.embedding_dimension
 
+    def get_embedding(self, text: str) -> List[float]:
+        """단일 텍스트를 임베딩합니다.
+        
+        Args:
+            text: 임베딩할 텍스트
+            
+        Returns:
+            임베딩 벡터 (List[float])
+        """
+        try:
+            # fastembed의 embed()는 제너레이터를 반환하므로 list로 변환
+            embeddings = list(self.model.embed([text]))
+            if not embeddings:
+                raise ValueError("임베딩 결과가 비어있습니다")
+            # 단일 텍스트이므로 첫 번째 결과만 반환
+            embedding = embeddings[0]
+            # numpy array일 수 있으므로 list로 변환
+            return embedding.tolist() if hasattr(embedding, "tolist") else list(embedding)
+        except Exception as e:
+            logger.error("임베딩 생성 실패: %s", e, exc_info=True)
+            raise RuntimeError(f"임베딩 생성 실패: {e}") from e
+
+    def get_embeddings_batch(self, texts: List[str]) -> List[List[float]]:
+        """배치 텍스트를 임베딩합니다.
+        
+        Args:
+            texts: 임베딩할 텍스트 리스트
+            
+        Returns:
+            임베딩 벡터 리스트 (List[List[float]])
+        """
+        if not texts:
+            return []
+        
+        try:
+            # fastembed의 embed()는 제너레이터를 반환하므로 list로 변환
+            embeddings = list(self.model.embed(texts))
+            # 각 ��베딩을 list로 변환
+            result = []
+            for embedding in embeddings:
+                # numpy array일 수 있으므로 list로 변환
+                result.append(embedding.tolist() if hasattr(embedding, "tolist") else list(embedding))
+            return result
+        except Exception as e:
+            logger.error("배치 임베딩 생성 실패: %s", e, exc_info=True)
+            raise RuntimeError(f"배치 임베딩 생성 실패: {e}") from e

CodeWeaver/src/vector_db/qdrant_client.py

@@ -1,16 +1,12 @@
-import hashlib
 import logging
-import os
+import uuid
 from typing import Dict, List, Optional
 
-from dotenv import load_dotenv  # type: ignore[import]
 from qdrant_client import QdrantClient, models
 
+from src.core.config import settings
 from src.vector_db.local_embeddings import LocalEmbeddingManager
 
-# .env 파일에서 환경 변수 로드 (로컬 개발 편의성)
-load_dotenv()
-
 logger = logging.getLogger(__name__)
 
 
@@ -23,13 +19,9 @@ class QdrantManager:
 
     def __init__(self, collection_name: str = "CodeWeaver") -> None:
         """Qdrant Cloud 클라이언트를 초기화하고 컬렉션을 준비한다."""
-        qdrant_url = os.getenv("QDRANT_URL", "").strip()
-        qdrant_api_key = os.getenv("QDRANT_API_KEY", "").strip()
-
-        if not qdrant_url or not qdrant_api_key:
-            raise ValueError(
-                "QDRANT_URL 및 QDRANT_API_KEY 환경 변수가 모두 설정되어 있어야 합니다."
-            )
+        # pydantic-settings가 필수 변수 검증을 수행하므로 별도 검증 불필요
+        qdrant_url = settings.qdrant_url
+        qdrant_api_key = settings.qdrant_api_key
 
         # Qdrant Cloud 공식 가이드와 유사한 초기화 형태 사용
         # https://qdrant.tech/documentation/tutorials-and-examples/cloud-inference-hybrid-search/
@@ -60,19 +52,21 @@ class QdrantManager:
             return
 
         try:
+            # 임베딩 모델의 차원을 동적으로 가져옴
+            embedding_dim = self.embedding_manager.get_embedding_dimension()
             self.client.create_collection(
                 collection_name=self.collection_name,
                 vectors_config=models.VectorParams(
-                    size=1024,  # bge-m3 임베딩 차원
+                    size=embedding_dim,  # fastembed 모델의 실제 차원
                     distance=models.Distance.COSINE,
                 ),
             )
-            logger.info("Qdrant 컬렉션 생성 완료: %s", self.collection_name)
+            logger.info("Qdrant 컬렉션 생성 완료: %s (벡터 차원: %d)", self.collection_name, embedding_dim)
         except Exception as e:
             logger.error("Qdrant 컬렉션 생성 실패: %s", e, exc_info=True)
             raise
 
-    async def get_embedding(self, text: str) -> List[float]:
+    def get_embedding(self, text: str) -> List[float]:
         """로컬 임베딩 모델을 사용해 텍스트 임베딩을 생성한다."""
         try:
             embedding = self.embedding_manager.get_embedding(text)
@@ -82,17 +76,17 @@ class QdrantManager:
             logger.error("임베딩 생성 실패: %s", e, exc_info=True)
             raise
 
-    async def search_cache(
+    def search_cache(
         self,
         question: str,
-        threshold: float = 0.85,
+        threshold: float = 0.95,
     ) -> Optional[str]:
         """질문에 대한 캐시된 답변을 Qdrant에서 검색한다.
 
         threshold보다 높은 score를 가진 결과가 있을 때만 answer를 반환한다.
         """
         try:
-            embedding = await self.get_embedding(question)
+            embedding = self.get_embedding(question)
         except Exception:
             # 이미 get_embedding 내부에서 로그를 남기므로 여기서는 조용히 실패 처리
             return None
@@ -137,34 +131,33 @@ class QdrantManager:
             logger.info("캐시 히트이지만 payload에 answer가 없습니다. payload=%s", payload)
             return None
 
+        matched_question = payload.get("question", "알 수 없음")
         logger.info(
-            "캐시 히트: score=%.4f, question=%s, answer_length=%d",
+            "캐시 히트: score=%.4f, searched_question=%s, matched_question=%s, answer_length=%d",
             score,
             question,
+            matched_question,
             len(str(answer)),
         )
         return str(answer)
 
-    async def save_to_cache(self, question: str, answer: str) -> None:
+    def save_to_cache(self, question: str, answer: str) -> None:
         """질문-답변 쌍을 Qdrant 캐시에 저장한다.
         
         동일한 질문에 대해서는 deterministic ID를 사용하여,
         upsert 시 기존 엔트리를 덮어쓰게 함으로써 중복을 방지한다.
         """
         try:
-            embedding = await self.get_embedding(question)
+            embedding = self.get_embedding(question)
         except Exception:
             # 임베딩 실패 시 캐시에 저장하지 않는다.
             logger.warning("임베딩 실패로 인해 캐시에 저장하지 않음. question=%s", question)
             return
 
-        # UUID 대신 질문 해시 기반 deterministic ID 사용
-        # → 동일 질문 = 동일 ID → upsert가 덮어쓰기로 동작 → 중복 방지
-        #
-        # 주의: Qdrant point id는 "unsigned int" 또는 "UUID"만 허용한다.
-        # 따라서 sha256 hex(64자)를 그대로 쓰지 않고, 앞 32자를 UUID 포맷으로 변환해 사용한다.
-        digest = hashlib.sha256(question.encode("utf-8")).hexdigest()
-        point_id = f"{digest[:8]}-{digest[8:12]}-{digest[12:16]}-{digest[16:20]}-{digest[20:32]}"
+        # 질문 기반 deterministic UUID 사용
+        # → 동일 질문 = 동일 UUID → upsert가 덮어쓰기로 동작 → 중복 방지
+        # uuid5()는 표준 UUID 형식(RFC 4122)을 사용하며, 동일한 namespace와 name에 대해 항상 동일한 UUID를 생성합니다.
+        point_id = str(uuid.uuid5(uuid.NAMESPACE_DNS, question))
 
         # 기존 엔트리 존재 시(덮어쓰기) 로그를 남긴다. 실패해도 upsert는 계속 시도.
         try:
@@ -194,7 +187,7 @@ class QdrantManager:
                 points=[point],
             )
             logger.info(
-                "Qdrant 캐시에 저장 완료 (hash ID로 중복 방지): point_id=%s, question_length=%d, answer_length=%d",
+                "Qdrant 캐시에 저장 완료 (UUID로 중복 방지): point_id=%s, question_length=%d, answer_length=%d",
                 point_id,
                 len(question),
                 len(answer),
@@ -202,7 +195,7 @@ class QdrantManager:
         except Exception as e:
             logger.error("Qdrant 캐시 저장 실패: %s", e, exc_info=True)
 
-    async def get_cache_stats(self) -> Dict[str, int]:
+    def get_cache_stats(self) -> Dict[str, int]:
         """현재 컬렉션의 캐시 통계를 반환한다."""
         try:
             info = self.client.get_collection(self.collection_name)

CodeWeaver/ui/app.py

@@ -1,34 +1,30 @@
-import asyncio
-import logging
-import os
 import sys
-import uuid
+import logging
 from pathlib import Path
+import uuid
 
 import gradio as gr
 from dotenv import load_dotenv
 
-# 환경 변수 로드 (에이전트/트레이싱 import 이전에 실행)
+# 환경 변수 로드
 load_dotenv()
 
 # 프로젝트 루트를 경로에 추가
 sys.path.insert(0, str(Path(__file__).parent.parent))
 
-from src.agent.graph import agent
+from src.agent.graph import get_agent
 from src.agent.state import AgentState
 
-# 로깅 설정 (WARNING 이상만 출력)
+# 로깅 설정 (WARNING 이상만 출력 - 노이즈 제거)
 logging.basicConfig(
     level=logging.WARNING,
     format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
 )
 
-# 외부 라이브러리 로그는 WARNING만
+# 외부 라이브러리 및 내부 모듈 로그 레벨 조정
 logging.getLogger("httpx").setLevel(logging.WARNING)
 logging.getLogger("httpcore").setLevel(logging.WARNING)
 logging.getLogger("langsmith").setLevel(logging.WARNING)
-
-# CodeWeaver 모듈 로그도 WARNING만 (로그 비활성화)
 logging.getLogger("src.agent").setLevel(logging.WARNING)
 logging.getLogger("src.tools").setLevel(logging.WARNING)
 logging.getLogger("src.vector_db").setLevel(logging.WARNING)
@@ -36,40 +32,38 @@ logging.getLogger("src.vector_db").setLevel(logging.WARNING)
 logger = logging.getLogger(__name__)
 
 
-async def chat(
+def chat(
     message: str,
     history: list,
     thread_id: str,
 ) -> str:
     """
     사용자 메시지를 처리하고 에이전트 응답을 반환합니다.
-    
-    Args:
-        message: 사용자 입력 메시지
-        history: 대화 내역 (Gradio 자동 관리)
-        thread_id: 세션별 고유 ID (MemorySaver가 대화 맥락 추적에 사용)
-        
-    Returns:
-        에이전트의 최종 답변
+    (Sync Mode for Windows Compatibility)
     """
     if not message or not message.strip():
         return "질문을 입력해주세요."
     
+    # 세션 ID가 비어있으면 랜덤 생성
+    if not thread_id or not thread_id.strip():
+        thread_id = str(uuid.uuid4())
+    
     try:
-        # 초기 상태 생성 (Pydantic BaseModel 사용)
+        # 초기 상태 생성
         from langchain_core.messages import HumanMessage
         
         initial_state = AgentState(
             user_question=message.strip(),
             messages=[HumanMessage(content=message.strip())],
-            conversation_history=history[-5:] if history else None,  # 최근 5턴만 전달
         )
         
-        # 세션별 thread_id를 config에 전달 (MemorySaver가 대화 맥락 유지)
-        config = {"configurable": {"thread_id": thread_id}}
+        # 에이전트 인스턴스 가져오기 (Singleton)
+        agent = get_agent()
         
-        # 에이전트 실행
-        result = await agent.ainvoke(initial_state, config=config)
+        # Sync 모드로 실행 (Windows 호환성 및 안정성)
+        # thread_id를 통해 PostgresSaver에서 이전 대화 상태를 불러옴
+        config = {"configurable": {"thread_id": thread_id}}
+        result = agent.invoke(initial_state, config=config)
         
         # 최종 답변 추출
         final_answer = result.get("final_answer", "답변을 생성하지 못했습니다.")
@@ -84,11 +78,7 @@ async def chat(
 def create_demo() -> gr.Blocks:
     """Gradio 인터페이스를 생성합니다."""
     
-
-    
-    # CSS 스타일 (깔끔한 디자인)
-    # - Gradio 기본 CSS가 .contain/.gradio-container 폭을 덮어쓰는 경우가 있어
-    #   둘 다 !important로 고정하여 "처음부터 넓은 폭"을 확실히 유지합니다.
+    # CSS 스타일 (화면 너비 고정 및 가독성 향상)
     css = """
     .gradio-container {
         max-width: 1280px !important;
@@ -111,148 +101,130 @@ def create_demo() -> gr.Blocks:
     ) as demo:
         
         gr.Markdown("""
-        # 🤖 CodeWeaver
-        ### AI 기반 개발 질문 답변 시스템
-        
-        초보 개발자를 위한 친절한 AI 도우미입니다.
+        # 🕸️ CodeWeaver
+        ### 초보 개발자를 위한 지능형 AI 멘토
         
-        **주요 기능:**
-        - ✅ 에러 해결 (디버깅)
-        - ✅ 개념 학습
-        - ✅ 코드 리뷰 및 개선 제안
-        - ✅ **다중 질문 처리** (최대 2개까지 동시 처리)
-        - ✅ **대화 맥락 이해** (이전 대화를 참고한 후속 질문 답변)
-        - ✅ **스마트 캐싱** (유사 질문 즉시 답변)
-        - ✅ **자동 검색 개선** (결과 부족 시 쿼리 자동 최적화)
-        
-        💬 개발 관련 질문을 자유롭게 해보세요!
-        - 단일 질문: "Spring Boot JPA N+1 문제 해결 방법은?"
-        - 다중 질문: "JWT가 뭐야? CORS는?" (최대 2개)
-        - 후속 질문: "좀 더 쉽게 설명해줘" (이전 답변 참고)
+        질문을 분석하고, 계획을 세우고, 다양한 기술 문서를 참고하여 답변하는 LangGraph 기반 에이전트���니다.
+        개발 중 마주치는 에러, 개념 질문, 코드 리뷰 등 무엇이든 물어보세요.
         """)
         
-        # 세션별 고유 ID (브라우저 세션마다 독립적으로 생성)
-        session_id = gr.State(value=lambda: str(uuid.uuid4()))
+        # 1. 사용 가이드
+        with gr.Accordion("📝 사용 가이드 & 팁 (먼저 읽어보세요)", open=False):
+            gr.Markdown("""
+            ### 💡 질문 잘하는 법
+            - **구체적으로**: `"파이썬 에러"` (X) -> `"KeyError: 'data' 해결 방법은?"` (O)
+            - **상황 설명**: 언어와 프레임워크를 함께 말해주면 정확도가 올라갑니다.
+            
+            ### 🚀 주요 기능 활용법
+            1. **Fast Track (빠른 대화)**
+               - `"안녕"`, `"너 누구야?"` 같은 일상 대화는 검색 없이 즉시 답변합니다.
+            2. **다중 질문 처리 (Map-Reduce)**
+               - `"JWT가 뭐야? 그리고 CORS는?"` 처럼 **최대 2개** 질문을 한 번에 할 수 있습니다.
+            3. **문맥 이해 (History)**
+               - `"좀 더 쉽게 설명해줘"` 또는 `"예제 코드로 보여줘"`라고 하면 이전 답변을 바탕으로 보충 설명합니다.
+            4. **쿼리 자동 개선**
+               - 검색 결과가 부족하면 에이전트가 스스로 개선(기술 용어를 영어로 변환하는 등)여 재검색합니다.
+            
+            ### 💾 대화 저장 및 영속성 확인 (Persistence)
+            - **Session ID**가 같으면 브라우저를 닫았다가 다시 접속해도 대화 내용이 유지됩니다. (PostgreSQL DB 저장)
+            - **테스트 방법**: 
+              1. 대화를 나눈 후 **Session ID**를 복사해둡니다.
+              2. 페이지를 새로고침하거나 브라우저를 재시작합니다.
+              3. Session ID 입력창에 복사한 ID를 넣고 대화를 시도합니다.
+              4. **`"우리 대화 요약해줘"`**라고 물어보면 DB에 저장된 기록을 불러와 답변합니다.
+            - 새로운 주제로 대화하려면 반드시 `🗑️ 대화 초기화` 버튼을 누르세요.
+            """)
+
+        # 2. Session ID 입력창
+        with gr.Row():
+            session_id_input = gr.Textbox(
+                label="Session ID (이 ID가 같으면 대화가 유지됩니다)",
+                value=str(uuid.uuid4()),
+                interactive=True,
+                placeholder="세션 ID를 입력하거나 그대로 두세요"
+            )
         
-        # 채팅 인터페이스
+        # 3. 채팅 인터페이스
         chatbot_interface = gr.ChatInterface(
             fn=chat,
-            examples=None,  # examples는 아래 Accordion에서 수동 처리
-            chatbot=gr.Chatbot(height=500),
+            examples=None, 
+            chatbot=gr.Chatbot(height=550, show_copy_button=True),
             textbox=gr.Textbox(
-                placeholder="질문을 입력하세요...",
+                placeholder="개발 관련 질문을 입력하세요... (예: 'React useEffect 무한 루프 해결법')",
                 container=False,
                 scale=7
             ),
             retry_btn=None,
             undo_btn=None,
             clear_btn="🗑️ 대화 초기화",
-            additional_inputs=[session_id],  # thread_id 전달
+            additional_inputs=[session_id_input],
         )
         
-        # Clear 버튼 클릭 시 새 세션 ID 생성 (새 대화 시작)
+        # Clear 버튼 핸들러
         def reset_session():
-            new_id = str(uuid.uuid4())
-            return new_id
+            return str(uuid.uuid4())
         
-        # Clear 버튼에 세션 리셋 핸들러 추가
         if chatbot_interface.clear_btn:
             chatbot_interface.clear_btn.click(
                 reset_session,
                 None,
-                session_id,
+                session_id_input,
                 queue=False
             )
         
-        # 빠른 질문 버튼들 (Accordion 밖으로 분리)
-        gr.Markdown("### 💬 예시 질문")
-        example_questions = [
-            "Spring Boot JPA N+1 문제 해결 방법은?",
-            "ImportError: No module named 'requests' 해결 방법",
-            "Docker Compose 설정 예제를 알려주세요",
-            "이 코드를 개선해주세요: for i in range(len(arr)): print(arr[i])",
-            "JWT가 뭐야? CORS는?",  # 다중 질문 예시
-        ]
-        
+        # 4. 예시 질문
+        gr.Markdown("### 💡 추천 질문 예시")
         with gr.Row():
-            for question in example_questions:
-                btn = gr.Button(
-                    question,
-                    variant="secondary",
-                    size="sm",
-                    scale=1,
-                )
-                # 버튼 클릭 시 입력창에 자동 입력
-                btn.click(
-                    fn=lambda q=question: q,
-                    outputs=[chatbot_interface.textbox],
-                )
-
-        # 정보 섹션
-        with gr.Accordion("📊 시스템 정보", open=False):
-            gr.Markdown("""
-            ### 사용된 기술
-            - **LLM**: Gemini 2.5 Flash Lite
-            - **임베딩**: BAAI/bge-m3 (로컬)
-            - **벡터 DB**: Qdrant Cloud
-            - **검색 API**: Stack Overflow, GitHub, Tavily
-            - **프레임워크**: LangGraph
-            
-            ### 주요 기능
-            - 🔍 **병렬 검색**: Stack Overflow, GitHub, 공식 문서 동시 검색
-            - 💾 **의미적 캐싱**: 유사 질문(임계값 0.85 이상) 즉시 답변
-            - 🎯 **의도 기반 라우팅**: debugging/learning/code_review 자동 분류
-            - 🔄 **자동 쿼리 개선**: 검색 결과 부족 시 최대 1회 자동 최적화
-            - 📝 **초보자 친화 답변**: 의도별 맞춤형 답변 구조
-            - 🔀 **다중 질문 처리**: 독립 질문 2개까지 병렬 처리
-            - 💬 **대화 맥락 이해**: clarification 질문은 히스토리 기반 답변
-            
-            ### LangGraph로 구현한 핵심 기능
-            1. ✅ **Conditional Edges**: 질문 유형/캐시 여부/검색 결과에 따른 동적 라우팅
-            2. ✅ **Send API**: 3개 검색 소스 병렬 실행 (fan-out/fan-in)
-            3. ✅ **Subgraph**: 검색 결과 필터링 및 요약 파이프라인
-            4. ✅ **Map-Reduce**: 다중 질문 처리 시 각 질문별 독립 실행 후 결과 통합
-            5. ✅ **Checkpointing**: MemorySaver로 대화 상태 저장 및 재개
-            6. ✅ **Pydantic Typed State**: 타입 안전한 상태 관리
-            
-            ### GitHub
-            [프로젝트 소스코드](https://github.com/shin-heewon/codeweaver)
-            """)
-        
+            # 디버깅
+            gr.Button("Python KeyError: 'data' 해결법", variant="primary", size="sm").click(
+                fn=lambda: "Python 딕셔너리에서 KeyError: 'data' 에러가 나는데 해결 방법 알려줘", 
+                outputs=[chatbot_interface.textbox]
+            )
+            # 프론트엔드 이슈
+            gr.Button("React useEffect 무한 루프 원인", variant="primary", size="sm").click(
+                fn=lambda: "React useEffect에서 무한 루프가 발생하는 이유와 해결 방법은?", 
+                outputs=[chatbot_interface.textbox]
+            )
+            # 다중 질문 (변경된 예시)
+            gr.Button("REST API vs GraphQL (다중 질문)", variant="secondary", size="sm").click(
+                fn=lambda: "REST API가 뭐야? 그리고 GraphQL은?", 
+                outputs=[chatbot_interface.textbox]
+            )
+            # 개념 학습
+            gr.Button("Spring Boot JPA N+1 문제", variant="secondary", size="sm").click(
+                fn=lambda: "Spring Boot JPA N+1 문제 해결 방법은?", 
+                outputs=[chatbot_interface.textbox]
+            )
 
-        
-        # 사용 가이드
-        with gr.Accordion("💡 사용 팁", open=False):
+        # 5. 시스템 정보 (업데이트된 리팩토링 내용 반영)
+        with gr.Accordion("📊 시스템 아키텍처 및 상세 기술 정보", open=False):
             gr.Markdown("""
-            ### 1. 구체적으로 질문하기
-            - ❌ "파이썬 에러"
-            - ✅ "ImportError: No module named 'requests' 해결 방법"
-            
-            ### 2. 질문 유형별 예시
-            - **디버깅**: "이 에러 메시지는 무엇을 의미하나요?"
-            - **학습**: "JPA N+1 문제는 왜 발생하나요?"
-            - **코드 리뷰**: "이 코드를 더 효율적으로 개선하려면?"
-            
-            ### 3. 다중 질문 사용법
-            - ✅ **2개까지 가능**: "JWT가 뭐야? CORS는?"
-            - ❌ **3개 이상 불가**: "JWT? CORS? Docker?" → 안내 메시지 표시
-            - 💡 **팁**: 관련 질문은 하나로 통합하거나, 순차적으로 질문하세요
-            
-            ### 4. 대화 맥락 활용
-            - **후속 질문**: "좀 더 쉽게 설명해줘", "예제 코드로 보여줘"
-            - **새 개념 질문**: 대화 중에도 "Event Listener는 뭐야?" 같은 독립 질문 가능
-            - 💡 **팁**: 이전 대화를 참고한 답변이 필요하면 자연스럽게 질문하세요
-            
-            ### 5. 응답 시간
-            - **첫 질문**: 20~30초 소요 (검색 + 답변 생성)
-            - **유사 질문**: 즉시 답변 (캐시 활용, 임계값 0.85 이상)
-            - **다중 질문**: 각 질문별 병렬 처리로 효율적
-            
-            ### 6. 더 나은 답변을 위한 팁
-            - 에러 메시지를 포함해주세요
-            - 사용 중인 언어/프레임워크를 명시하세요
-            - 시도했던 해결 방법을 함께 알려주세요
-            - ���색 결과가 부족하면 자동으로 쿼리를 개선합니다 (최대 1회)
+            ### 🏗️ LangGraph 구현 패턴 (핵심 기능)
+            CodeWeaver는 LangGraph의 고급 패턴을 활용하여 자율 에이전트를 구현했습니다.
+            - **Conditional Edges**: 질문 유형, 캐시 히트, 검색 품질에 따른 동적 라우팅
+            - **Send API (Map-Reduce)**: 다중 질문의 병렬 실행(Fan-out) 및 결과 통합(Fan-in)
+            - **Subgraph**: 검색-평가-정제 과정의 모듈화
+            - **Active Self-Correction**: 검색 결과 부족 시 쿼리 자동 정제(Refinement)
+            - **Persistence**: 대화 상태의 저장 및 복구
+
+            ### ⚡ 최신 리팩토링 및 최적화 사항 (Technical Highlights)
+            1. **아키텍처 안정화 (Sync Mode 전환)**
+               - **배경**: Windows(`ProactorEventLoop`)와 `psycopg 3` 드라이버, `Gradio` 간의 Event Loop 충돌 발생.
+               - **해결**: 불안정한 비동기 처리 대신 **동기(Sync) 모드**로 아키텍처를 전환하고 `ConnectionPool`을 적용하여 OS 제약 없는 안정적인 실행 환경 확보.
+            2. **데이터 영속성 (Persistence)**
+               - 기존 In-Memory 방식을 **Neon Serverless PostgreSQL**로 교체하여, 서버 재시작 시에도 대화 맥락이 영구 보존되도록 개선.
+            3. **검색 품질 고도화 (Reranking)**
+               - **Cross-Encoder(Jina-Reranker)** 도입: 검색 결과의 문맥 유사도를 정밀 채점하여 정확도 대폭 향상 (Threshold 0.35 필터링).
+            4. **응답 속도 최적화**
+               - **Context Stuffing**: 검색 결과 요약 단계를 제거하고 원본 문맥을 활용하여 Latency 단축.
+               - **Non-blocking Caching**: 캐시 저장 로직을 백그라운드 스레드로 분리.
+               - **Fast Track**: 일상 대화 즉시 응답 처리.
+
+            ### 🛠️ Tech Stack
+            - **Core**: LangGraph, LangChain, Python 3.12
+            - **AI Model**: Google Gemini 2.5 Flash Lite
+            - **Search**: Tavily (30+ Docs), StackOverflow, GitHub, Jina Reranker
+            - **Infra**: Neon Serverless PostgreSQL, Qdrant Cloud
             """)
     
     return demo
@@ -263,10 +235,9 @@ app = create_demo()
 
 
 if __name__ == "__main__":
-    # 로컬 실행
     app.launch(
         server_name="0.0.0.0",
         server_port=7860,
-        share=False,  # True로 하면 공개 URL 생성
-        show_api=False,  # Gradio 4.44.x 버그 우회용
-    )
+        share=False,
+        show_api=False,
+    )

hf-space2/CodeWeaver/.env.example

@@ -1,9 +0,0 @@
-GOOGLE_API_KEY=your-google-api-key
-TAVILY_API_KEY=your-tavily-api-key
-QDRANT_URL=https://your-qdrant-endpoint
-QDRANT_API_KEY=your-qdr
-LANGCHAIN_TRACING_V2=true
-LANGCHAIN_API_KEY=your_langsmith_api_key_here
-LANGCHAIN_PROJECT=codeweaver
-LANGCHAIN_ENDPOINT=https://api.smith.langchain.com
-GITHUB_TOKEN=

hf-space2/CodeWeaver/.gitignore

@@ -1,23 +0,0 @@
-# Python-generated files
-__pycache__/
-*.py[oc]
-build/
-dist/
-wheels/
-*.egg-info
-
-# Virtual environments
-.venv
-
-# Environment variables (민감한 정보 포함)
-.env
-
-# IDE
-.vscode/
-.idea/
-*.swp
-*.swo
-
-# OS
-.DS_Store
-Thumbs.db

hf-space2/CodeWeaver/.python-version

@@ -1 +0,0 @@
-3.12

hf-space2/CodeWeaver/IMPLEMENTATION_REPORT.md

@@ -1,175 +0,0 @@
-# CodeWeaver Phase 3 구현 완료 보고서
-
-## 완료 날짜
-2024-12-20
-
-## 구현 목표
-Open Deep Research 패턴을 적용하여 검색 품질과 답변 정확도를 향상
-
-## 구현된 기능
-
-### 1. 항상 질문 분해 (create_plan_node)
-- **위치**: `src/agent/nodes.py:203-287`
-- **동작**: 모든 질문을 1-5개의 서브 질문으로 분해
-- **전략**: 
-  - 단순 질문 → 1개 서브 질문
-  - 복잡 질문 → 3-5개 서브 질문
-- **LLM 사용**: JSON 구조화된 출력
-
-### 2. 검색 결과 수집 (collect_results_node)
-- **위치**: `src/agent/nodes.py:461-479`
-- **역할**: Fan-in 포인트, 3개 병렬 검색 노드의 결과 집계
-- **출력**: `len(search_results)` 기준으로 원시 결과 수 평가 (필드 저장 제거)
-
-### 3. 검색 결과 평가 (evaluate_results_node)
-- **위치**: `src/agent/nodes.py:482-533`
-- **임계값**: 2개 미만이면 개선 필요
-- **안전장치**: refinement_count >= 1이면 무조건 진행
-- **출력**: `needs_refinement` (boolean)
-
-### 4. 스마트 쿼리 개선 (refine_search_node)
-- **위치**: `src/agent/nodes.py:536-633`
-- **전략 선택** (LLM):
-  - MORE_SPECIFIC: 기술적 세부사항 추가
-  - MORE_GENERAL: 더 넓은 용어 사용
-  - TRANSLATE: 언어 변환
-- **원본 보존**: `original_question` 필드에 저장
-
-### 5. 그래프 재구성
-- **위치**: `src/agent/graph.py:200-330`
-- **새로운 엣지**:
-  - `check_cache` → `create_plan` (캐시 미스 시)
-  - `create_plan` → `classify_intent`
-  - `search_*` → `collect_results` (fan-in)
-  - `collect_results` → `evaluate_results`
-  - `evaluate_results` → `refine_search` or `search_subgraph`
-  - `refine_search` → `classify_intent` (루프)
-
-### 6. 상태 스키마 확장
-- **위치**: `src/agent/state.py:127-143`
-- **추가 필드**:
-  ```python
-  plan: Optional[Dict[str, Any]]
-  needs_refinement: bool
-  refinement_count: int
-  original_question: Optional[str]
-  ```
-
-## 테스트 결과
-
-### 통합 테스트 (test_new_features.py)
-- ✅ 테스트 1: 단순 질문 - 정상 동작
-- ✅ 테스트 2: 복잡 질문 - 정상 동작
-- ✅ 테스트 3: 결과 부족 시나리오 - 쿼리 개선 확인
-- ✅ 테스트 4: 개선 제한 - 최대 1회 보장
-
-### 실행 통계
-```
-[PASS] Passed: 4/4
-[FAIL] Failed: 0/4
-[SUCCESS] All tests passed!
-```
-
-### 실제 동작 검증
-```
-INFO:src.agent.nodes:질문 분해 계획 수립 중
-INFO:src.agent.nodes:계획 수립 완료: 4개 서브 질문
-INFO:src.agent.nodes:검색 결과 수집 완료: 0개
-INFO:src.agent.nodes:검색 결과 평가: 0개 (개선 횟수: 0)
-INFO:src.agent.nodes:쿼리 개선 중
-INFO:src.agent.nodes:쿼리 개선 완료
-INFO:src.agent.nodes:검색 결과 수집 완료: 11개
-INFO:src.agent.nodes:검색 결과 평가: 11개 (개선 횟수: 1)
-```
-
-## 준수한 LangGraph 공식 가이드라인
-
-### 1. 노드는 한 가지 일만 수행 ✅
-- 각 노드가 단일 책임 원칙 준수
-- `create_plan`: 질문 분해만
-- `evaluate_results`: 평가만 (라우팅 X)
-
-### 2. 상태에 원시 데이터 저장 ✅
-- 포맷된 텍스트 X
-- 계산 가능한 값 X
-- 순수 데이터만 저장
-
-### 3. 프롬프트는 노드 내에서 생성 ✅
-- 상태에 프롬프트 템플릿 저장 X
-- 각 노드에서 동적 생성
-
-### 4. Send API로 병렬 실행 ✅
-- 3개 검색 노드 동시 실행
-- reducer로 자동 머지
-
-### 5. 체크포인팅 지원 ✅
-- 모든 노드 경계에서 상태 저장
-- 언제든 재개 가능
-
-## 성능 개선 지표
-
-### 검색 품질
-- Before: 단일 검색 → 결과 0개 시 실패
-- After: 자동 개선 → 재검색 → 성공률 ↑
-
-### 답변 정확도  
-- Before: 모호한 검색어 → 부적절한 결과
-- After: 질문 분해 + 쿼리 개선 → 정확도 ↑
-
-### 안정성
-- Before: 무한 루프 가능성
-- After: refinement_count 제한으로 보장
-
-## 파일 변경 요약
-
-### 수정된 파일 (3개)
-1. `src/agent/state.py` - 5개 필드 추가
-2. `src/agent/nodes.py` - 4개 노드 추가/수정
-3. `src/agent/graph.py` - 엣지 재구성, 2개 라우팅 함수 추가
-
-### 추가된 파일 (3개)
-1. `test_new_features.py` - 통합 테스트
-2. `PHASE3_CHANGES.md` - 변경사항 문서
-3. `demo_phase3.py` - 데모 스크립트
-
-### 수정된 문서 (1개)
-1. `README.md` - Phase 3 섹션 추가
-
-## 코드 통계
-- 추가된 라인: ~500줄
-- 수정된 라인: ~50줄
-- 테스트 커버리지: 4개 시나리오
-
-## 다음 단계 제안
-
-### 단기 (1-2주)
-1. 서브 질문별 병렬 검색 구현
-2. 적응형 임계값 (질문 복잡도 기반)
-3. UI에 계획 수립 단계 표시
-
-### 중기 (1-2개월)
-1. 개선 전략 학습 시스템
-2. 다단계 개선 (최대 2-3회)
-3. 성능 모니터링 대시보드
-
-### 장기 (3-6개월)
-1. 다국어 지원 강화
-2. 도메인별 전문화
-3. 사용자 피드백 기반 개선
-
-## 알려진 제한사항
-
-1. **캐시 우선순위**: 캐시 히트 시 계획 수립 건���뜀 (의도된 동작)
-2. **Windows 콘솔**: 이모지 인코딩 이슈 (로직은 정상)
-3. **GitHub API**: 일부 쿼리에서 422 에러 (외부 API 제약)
-
-## 결론
-
-✅ Open Deep Research 패턴 성공적으로 적용  
-✅ 모든 테스트 통과  
-✅ LangGraph 공식 가이드라인 준수  
-✅ 기존 기능 완벽 호환  
-
-Phase 3 구현이 완료되었으며, 프로덕션 배포 준비가 완료되었습니다.
-
-

hf-space2/CodeWeaver/PHASE3_CHANGES.md

@@ -1,142 +0,0 @@
-# Phase 3: Open Deep Research 패턴 적용
-
-## 개요
-
-CodeWeaver에 [Open Deep Research](https://github.com/langchain-ai/open_deep_research) 패턴을 적용하여 검색 품질과 답변 정확도를 향상시켰습니다.
-
-## 변경된 파일
-
-### 1. `src/agent/state.py`
-**추가된 필드:**
-```python
-# Planning & Refinement (Phase 3)
-plan: Optional[Dict[str, Any]]              # 질문 분해 계획
-needs_refinement: bool                       # 쿼리 개선 필요 여부
-needs_refinement: bool                       # 쿼리 개선 필요 여부
-refinement_count: int                        # 개선 시도 횟수 (최대 1회)
-original_question: Optional[str]             # 원본 질문 보존
-```
-
-### 2. `src/agent/nodes.py`
-**추가된 노드 (4개):**
-- `create_plan_node`: 모든 질문을 서브 질문으로 분해
-- `collect_results_node`: 병렬 검색 결과 수집 (fan-in)
-- `evaluate_results_node`: 결과 수 평가 (< 2개면 개선 필요)
-- `refine_search_node`: LLM 기반 쿼리 개선 (전략 선택)
-
-### 3. `src/agent/graph.py`
-**수정된 라우팅:**
-- `route_after_cache`: 캐시 미스 시 → `create_plan` (기존: `classify_intent`)
-- `route_after_evaluation`: 새로운 라우팅 함수 추가
-  - 결과 부족 & refinement_count=0 → `refine_search`
-  - 결과 충분 or refinement_count=1 → `search_subgraph`
-
-**추가된 엣지:**
-- `create_plan` → `classify_intent`
-- `search_*` → `collect_results` (fan-in)
-- `collect_results` → `evaluate_results`
-- `evaluate_results` ⟲ `refine_search` → `classify_intent` (루프)
-
-## 새로운 워크플로우
-
-### Before (Phase 2)
-```
-check_cache → classify_intent → parallel_search → search_subgraph → generate_answer
-```
-
-### After (Phase 3)
-```
-check_cache → create_plan → classify_intent → parallel_search 
-    → collect_results → evaluate_results
-        ├─ < 2 results → refine_search ⟲ classify_intent (최대 1회)
-        └─ >= 2 results → search_subgraph → generate_answer
-```
-
-## 핵심 설계 원칙 (LangGraph 공식 가이드라인)
-
-### 1. 노드는 한 가지 일만 수행
-✅ `create_plan`: 질문 분해만  
-✅ `collect_results`: 결과 수집만  
-✅ `evaluate_results`: 평가만 (라우팅 X)  
-✅ `refine_search`: 쿼리 개선만  
-
-### 2. 라우팅은 conditional_edges에서
-```python
-graph.add_conditional_edges(
-    "evaluate_results",
-    route_after_evaluation,  # 라우팅 함수
-    {
-        "refine_search": "refine_search",
-        "search_subgraph": "search_subgraph"
-    }
-)
-```
-
-### 3. 상태에는 원시 데이터만 저장
-```python
-# ✅ Good: 원시 데이터
-search_results: list[SearchResult]
-needs_refinement: bool
-
-# ❌ Bad: 계산된 값이나 포맷된 텍스트
-formatted_prompt: str
-```
-
-### 4. 프롬프트는 노드 내에서 동적 생성
-```python
-def refine_search_node(state: AgentState) -> dict:
-    # ✅ 노드 내에서 동적으로 프롬프트 구성
-    refinement_prompt = f"""
-    Original question: {state.user_question}
-    Current results: {len(state.search_results)}
-    ...
-    """
-```
-
-## 테스트 결과
-
-### 통과한 시나리오
-1. ✅ 단순 질문: 1개 서브 질문 생성 → 정상 진행
-2. ✅ 복잡 질문: 3-5개 서브 질문 생성 → 정상 진행
-3. ✅ 결과 부족: < 2개 결과 → 쿼리 개선 → 재검색
-4. ✅ 개선 제한: refinement_count 최대 1회 보장
-
-### 실행 로그 예시
-```
-INFO:src.agent.nodes:질문 분해 계획 수립 중: What is GraphQL endpoint design pattern?
-INFO:src.agent.nodes:계획 수립 완료: 4개 서브 질문
-INFO:src.agent.nodes:검색 결과 수집 완료: 0개
-INFO:src.agent.nodes:검색 결과 평가: 0개 (개선 횟수: 0)
-INFO:src.agent.nodes:쿼리 개선 중: What is GraphQL endpoint design pattern? (0개 결과)
-INFO:src.agent.nodes:쿼리 개선 완료: GraphQL API design best practices
-INFO:src.agent.nodes:검색 결과 수집 완료: 11개
-INFO:src.agent.nodes:검색 결과 평가: 11개 (개선 횟수: 1)
-```
-
-## 성능 개선
-
-### 검색 품질
-- **Before**: 단일 검색 → 결과 부족 시 실패
-- **After**: 결과 부족 시 자동 개선 → 재검색
-
-### 답변 정확도
-- **Before**: 모호한 질문 → 부정확한 검색
-- **After**: 서브 질문 분해 → 더 구체적인 검색
-
-### 안정성
-- **Before**: 무한 루프 가능성
-- **After**: refinement_count 제한으로 보장
-
-## 향후 개선 방향
-
-1. **서브 질문 병렬 검색**: 현재는 전체 질문으로 검색, 각 서브 질문별 검색으로 확장
-2. **적응형 임계값**: 현재 고정값 2개 → 질문 복잡도에 따라 동적 조정
-3. **개선 전략 학습**: LLM 선택 → 과거 성공 전략 기반 추천
-4. **다단계 개선**: 최대 1회 → 2-3회로 확장 (순환 감지 추가)
-
-## 참고 자료
-
-- [LangGraph Official Guide: Thinking in LangGraph](https://docs.langchain.com/oss/python/langgraph/thinking-in-langgraph)
-- [Open Deep Research GitHub](https://github.com/langchain-ai/open_deep_research)
-
-

hf-space2/CodeWeaver/PHASE5_SUBGRAPH_REFACTORING.md

@@ -1,320 +0,0 @@
-# Phase 5: 서브그래프 리팩토링 완료 보고서
-
-## 개요
-
-복잡하게 얽힌 다중 질문 처리 로직을 단순화하기 위해, **analyze_question부터 generate_answer까지를 독립된 서브그래프로 추출**하고, 부모 그래프는 계획/분기/병합만 담당하도록 구조를 개선했습니다.
-
----
-
-## 목표 달성 여부
-
-✅ **모든 목표 달성 완료**
-
-1. ✅ 단일 질문 파이프라인을 재사용 가능한 서브그래프로 추출
-2. ✅ 부모 그래프 단순화 (orchestration만 담당)
-3. ✅ 복잡한 worker 노드 및 중복 그래프 빌더 제거
-4. ✅ 구조 명확화: 부모(orchestration) vs 자식(processing)
-
----
-
-## 변경 사항
-
-### 1. 새로운 서브그래프: `build_single_question_subgraph()`
-
-**파일**: [`src/agent/graph.py`](src/agent/graph.py)
-
-```python
-def build_single_question_subgraph() -> StateGraph:
-    """
-    단일 질문 처리 파이프라인 서브그래프를 구성합니다.
-    
-    진입점: analyze_question (START → analyze_question)
-    출구: generate_answer 또는 generate_with_history 또는 return_cached_answer (→ END)
-    
-    흐름:
-    1. analyze_question → 질문 분석
-       - clarification: generate_with_history → END
-       - new_topic/independent: check_cache
-    2. check_cache → 캐시 확인
-       - 히트: return_cached_answer → END
-       - 미스: classify_intent
-    3. classify_intent → 병렬 검색 (Send API)
-    4. 검색 결과 수집 → 평가 → 필터링 → 요약 → 답변 생성
-    """
-```
-
-**포함 노드**:
-- analyze_question, generate_with_history
-- check_cache, return_cached_answer
-- classify_intent
-- search_stackoverflow, search_github, search_official_docs (병렬)
-- collect_results, evaluate_results, refine_search
-- search_subgraph (중첩 서브그래프: filter + summarize)
-- generate_answer
-
----
-
-### 2. 단순화된 메인 그래프: `build_agent_graph()`
-
-**변경 전 (Phase 4)**: 60+ 개의 노드와 엣지로 복잡하게 얽힘
-
-**변경 후 (Phase 5)**: 4개의 노드만으로 단순화
-
-```python
-def build_agent_graph() -> StateGraph:
-    """
-    CodeWeaver 에이전트의 메인 그래프를 구성합니다.
-    
-    전체 흐름 (단순화됨):
-    1. START → create_plan (질문 유형 및 개수 판단)
-    2. 질문 유형에 따른 분기:
-       - single_topic: single_question_subgraph (1회) → END
-       - multiple_questions: Send API로 single_question_subgraph (2회 병렬) → combine_answers → END
-       - too_many: handle_too_many_questions → END
-    """
-    
-    graph = StateGraph(AgentState)
-    
-    # 노드 추가 (4개만!)
-    graph.add_node("create_plan", create_plan_node)
-    graph.add_node("handle_too_many_questions", handle_too_many_questions_node)
-    graph.add_node("combine_answers", combine_answers_node)
-    graph.add_node("collect_subgraph_result", collect_subgraph_result_node)
-    
-    # 서브그래프를 노드로 등록
-    single_question_subgraph = build_single_question_subgraph()
-    graph.add_node("single_question_subgraph", single_question_subgraph)
-    
-    # 간단한 엣지 구성
-    graph.add_edge(START, "create_plan")
-    graph.add_conditional_edges("create_plan", route_after_plan)
-    graph.add_edge("handle_too_many_questions", END)
-    graph.add_conditional_edges("single_question_subgraph", ...)
-    graph.add_edge("collect_subgraph_result", "combine_answers")
-    graph.add_edge("combine_answers", END)
-    
-    return graph
-```
-
----
-
-### 3. 개선된 라우팅: `route_after_plan()`
-
-**변경 전**: `initiate_dynamic_search` 노드 → `fanout_multi_questions` 함수 → `run_single_question_worker_node` → 내부에서 별도 그래프 실행
-
-**변경 후**: Send API로 서브그래프를 직접 호출
-
-```python
-def route_after_plan(state: AgentState):
-    """
-    create_plan 결과에 따라 다음 노드를 결정합니다.
-    
-    Returns:
-        - "handle_too_many_questions": 질문 3개 이상
-        - "single_question_subgraph": 단일 주제
-        - List[Send]: 다중 질문 (2개) → 서브그래프 병렬 실행
-    """
-    plan = state.plan or {}
-    case = plan.get("case", "single_topic")
-    
-    if case == "too_many":
-        return "handle_too_many_questions"
-    elif case == "multiple_questions":
-        sub_questions = plan.get("sub_questions", [])
-        sends = []
-        for i, sq in enumerate(sub_questions):
-            child_state = state.model_copy(deep=True)
-            child_state.user_question = sq
-            child_state.is_multi_question = True
-            child_state.sub_question_index = i
-            # ... 최소 필드 설정 ...
-            sends.append(Send("single_question_subgraph", child_state))
-        return sends
-    else:
-        return "single_question_subgraph"
-```
-
----
-
-### 4. 제거된 코드 (300+ 줄)
-
-**파일**: [`src/agent/nodes.py`](src/agent/nodes.py)
-
-#### 제거된 함수:
-- ❌ `_build_search_subgraph_local()` - graph.py의 것 사용
-- ❌ `_get_single_question_agent()` - 공식 서브그래프로 대체 (100+ 줄)
-- ❌ `run_single_question_worker_node()` - 더 이상 필요 없음
-- ❌ `initiate_dynamic_search_node()` - 단순 분기로 대체
-- ❌ `fanout_multi_questions()` - route_after_plan에 통합
-
-#### 추가된 함수:
-- ✅ `collect_subgraph_result_node()` - 서브그래프 결과를 multi_answers에 추가
-
----
-
-## 새로운 아키텍처
-
-```mermaid
-graph TD
-    START[START] --> plan[create_plan]
-    
-    plan -->|too_many| tooMany[handle_too_many_questions]
-    plan -->|single_topic| subgraph1[single_question_subgraph]
-    plan -->|multiple_2| fanout[Send API]
-    
-    tooMany --> END
-    
-    fanout -.Send Q1.-> subgraph2[single_question_subgraph]
-    fanout -.Send Q2.-> subgraph3[single_question_subgraph]
-    
-    subgraph2 --> collect2[collect_subgraph_result]
-    subgraph3 --> collect3[collect_subgraph_result]
-    
-    collect2 --> combine[combine_answers]
-    collect3 --> combine
-    
-    combine --> END
-    subgraph1 --> END
-    
-    subgraph SingleQuestionSubgraph
-        analyze[analyze_question] --> cache[check_cache]
-        cache --> classify[classify_intent]
-        classify --> search[Parallel Search]
-        search --> collect[collect_results]
-        collect --> eval[evaluate_results]
-        eval --> filter[search_subgraph]
-        filter --> generate[generate_answer]
-    end
-```
-
----
-
-## 개선 효과
-
-### 1. 코드 품질
-- ✅ **300+ 줄 제거**: 중복 그래프 빌드 로직 완전 삭제
-- ✅ **재사용성 향상**: 단일 질문 파이프라인을 독립된 서브그래프로 캡슐화
-- ✅ **유지보수성 향상**: 역할 분리 명확 (orchestration vs processing)
-
-### 2. 구조 명확화
-- **부모 그래프 (orchestration)**:
-  - 질문 유형 판단
-  - 분기 결정
-  - 결과 병합
-  
-- **자식 서브그래프 (processing)**:
-  - 질문 분석
-  - 캐시 확인
-  - 검색 실행
-  - 답변 생성
-
-### 3. 확장성
-- ✅ 질문 3개 이상도 쉽게 대응 가능 (Send 리스트만 확장)
-- ✅ 서브그래프 단위로 독립 테스트 가능
-- ✅ 디버깅 용이: 특정 질문 문제 시 해당 서브그래프만 확인
-
----
-
-## 검증 결과
-
-### 구조 검증
-```
-============================================================
-Phase 5: 서브그래프 리팩토링 구조 검증
-============================================================
-✅ graph.py 구문 검증 성공
-
-[필수 함수 검증]
-  ✅ build_search_subgraph
-  ✅ build_single_question_subgraph
-  ✅ route_after_plan
-  ✅ build_agent_graph
-  ✅ create_agent
-
-[제거된 함수 검증]
-  ✅ route_after_generate - 정상 제거됨
-
-[Import 검증]
-  ✅ initiate_dynamic_search_node - import 제거됨
-  ✅ fanout_multi_questions - import 제거됨
-  ✅ run_single_question_worker_node - import 제거됨
-  ✅ collect_subgraph_result_node - import 추가됨
-
-[메인 그래프 노드 검증]
-  ✅ create_plan
-  ✅ handle_too_many_questions
-  ✅ combine_answers
-  ✅ collect_subgraph_result
-  ✅ single_question_subgraph
-
-============================================================
-nodes.py 구조 검증
-============================================================
-✅ nodes.py 구문 검증 성공
-
-[제거된 함수 검증]
-  ✅ _build_search_subgraph_local - 정상 제거됨
-  ✅ _get_single_question_agent - 정상 제거됨
-  ✅ run_single_question_worker_node - 정상 제거됨
-  ✅ initiate_dynamic_search_node - 정상 제거됨
-  ✅ fanout_multi_questions - 정상 제거됨
-
-[추가된 함수 검증]
-  ✅ collect_subgraph_result_node
-
-============================================================
-검증 결과 요약
-============================================================
-✅ 성공: graph.py 구조
-✅ 성공: nodes.py 구조
-
-🎉 모든 검증 통과! 리팩토링이 성공적으로 완료되었습니다.
-```
-
----
-
-## 변경된 파일 목록
-
-1. **src/agent/graph.py**
-   - ✅ `build_single_question_subgraph()` 추가 (100+ 줄)
-   - ✅ `route_after_plan()` 개선
-   - ✅ `build_agent_graph()` 단순화 (200+ 줄 → 50 줄)
-   - ✅ `route_after_generate()` 제거
-   - ✅ Import 정리
-
-2. **src/agent/nodes.py**
-   - ✅ `collect_subgraph_result_node()` 추가
-   - ❌ `_build_search_subgraph_local()` 제거
-   - ❌ `_get_single_question_agent()` 제거 (100+ 줄)
-   - ❌ `run_single_question_worker_node()` 제거
-   - ❌ `initiate_dynamic_search_node()` 제거
-   - ❌ `fanout_multi_questions()` 제거
-
-3. **hf-space/CodeWeaver/src/agent/**
-   - ✅ graph.py 동기화 완료
-   - ✅ nodes.py 동기화 완료
-
----
-
-## 다음 단계
-
-이 리팩토링으로 **Phase 5**가 완료되었으며, 다음 개선 사항을 고려할 수 있습니다:
-
-1. **질문 3개 이상 지원**: `route_after_plan()`에서 Send 리스트만 확장
-2. **서브그래프 단위 테스트**: 독립된 파이프라인 검증
-3. **캐싱 전략 ���선**: 서브그래프 결과 캐싱
-4. **성능 최적화**: 병렬 실행 효율성 분석
-
----
-
-## 결론
-
-✅ **모든 목표 달성**
-- 단일 질문 파이프라인을 재사용 가능한 서브그래프로 추출
-- 부모 그래프는 orchestration만 담당 (4개 노드)
-- 300+ 줄의 중복 코드 제거
-- 구조 명확화 및 확장성 향상
-
-이 리팩토링으로 CodeWeaver의 아키텍처가 **단순하고**, **명확하며**, **확장 가능한** 구조로 개선되었습니다.
-
-

hf-space2/CodeWeaver/README.md

@@ -1,118 +0,0 @@
----
-title: CodeWeaver
-emoji: 🤖
-colorFrom: blue
-colorTo: purple
-sdk: gradio
-sdk_version: "4.44.1"
-app_file: ui/app.py
-pinned: false
-license: mit
----
-
-# CodeWeaver
-
-LangGraph 기반의 **개발자 Q&A 에이전트**입니다. 질문을 분석하고(후속/독립), **캐시(Qdrant)**를 우선 확인한 뒤 캐시 미스일 때 **3개 소스(Stack Overflow / GitHub / 공식 문서(Tavily))를 병렬 검색**해 답변을 생성합니다. 서로 독립적인 질문이 2개 들어오면 **동적으로 2개 파이프라인을 병렬 실행**해 통합 답변을 제공합니다.
-
-## 핵심 기능(현재 코드 기준)
-
-- **질문 개수 감지**: 1개(단일 주제) / 2개(독립 질문 2개) / 3개 이상(거절 안내)
-- **질문 타입 분석**: `clarification`이면 검색/캐시 없이 **대화 히스토리 기반 답변**
-- **의미적 캐싱**: Qdrant에 질문-답변을 저장하고 유사 질문을 빠르게 재사용(임계값 0.85)
-- **병렬 검색**: Stack Overflow / GitHub / Tavily(공식 문서 도메인 제한) 동시 검색
-- **검색 품질 보정**: 결과가 부족하면 **쿼리 개선을 최대 1회** 수행
-- **서브그래프 처리**: 검색 결과를 필터링/점수화 후 요약 → 최종 답변 생성
-
-## 문서
-
-- 아키텍처/동작 원리: `../ARCHITECTURE.md`
-- 다중 질문 병렬 처리 설계(배경 설명): `../DYNAMIC_PARALLEL_SEARCH.md`
-
-## 빠른 시작
-
-### 1) 설치
-
-아래는 저장소 루트가 아니라 **`CodeWeaver/` 디렉터리 기준** 예시입니다.
-
-```bash
-cd CodeWeaver
-
-# uv 사용(권장)
-uv sync
-
-# 또는 pip 사용
-pip install -r requirements.txt
-```
-
-> `sentence-transformers`가 최초 실행 시 `BAAI/bge-m3` 모델을 다운로드할 수 있습니다(네트워크 필요).
-
-### 2) 환경 변수 설정(.env)
-
-`CodeWeaver/.env` 파일을 만들고 아래를 설정하세요(필수/선택 구분).
-
-```bash
-# 필수: Gemini (LLM)
-GOOGLE_API_KEY=your_google_api_key
-
-# 필수: Tavily (공식 문서 검색)
-TAVILY_API_KEY=your_tavily_api_key
-
-# 필수: Qdrant Cloud (캐시)
-QDRANT_URL=https://xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.us-east-1-0.aws.cloud.qdrant.io
-QDRANT_API_KEY=your_qdrant_api_key
-
-# 선택: GitHub API rate limit 완화
-GITHUB_TOKEN=your_github_token
-
-# 선택: LangSmith 트레이싱
-LANGCHAIN_TRACING_V2=true
-LANGCHAIN_API_KEY=your_langsmith_api_key
-```
-
-### 3) 실행(Gradio UI)
-
-```bash
-cd CodeWeaver
-python ui/app.py
-```
-
-기본 주소: `http://localhost:7860`
-
-## 현재 폴더 구조
-
-```
-CodeWeaver/
-├── main.py
-├── pyproject.toml
-├── requirements.txt
-├── src/
-│   ├── agent/
-│   │   ├── graph.py         # LangGraph 메인 그래프(라우팅/병렬화)
-│   │   ├── nodes.py         # 각 노드 구현
-│   │   └── state.py         # AgentState + reducer 정의
-│   ├── tools/
-│   │   └── search_tools.py  # StackOverflow/GitHub/Tavily 검색
-│   ├── utils/
-│   │   └── tracing.py       # trace_node 데코레이터(LangSmith 연동)
-│   └── vector_db/
-│       ├── qdrant_client.py # Qdrant 캐시 관리
-│       └── local_embeddings.py # bge-m3 로컬 임베딩
-└── ui/
-    └── app.py               # Gradio UI (실제 엔트리)
-```
-
-## 동작 흐름(요약)
-
-- `START → create_plan`
-  - **3개 이상**이면 안내 메시지 반환
-  - **2개**면 각 질문을 worker에서 단일 파이프라인으로 실행 후 결합
-  - **1개**면 아래 단일 파이프라인 수행
-- 단일 파이프라인:
-  - `analyze_question`
-    - `clarification`이면 `generate_with_history`로 즉시 답변
-    - 그 외: `check_cache` → hit면 반환, miss면 `classify_intent`
-  - `classify_intent` → 3소스 병렬 검색 → `collect_results` → `evaluate_results`
-  - 필요 시 `refine_search` 1회 → 재검색
-  - `filter_and_score → summarize_results → generate_answer`(+조건부 캐시 저장)
-
-자세한 원리는 `../ARCHITECTURE.md`를 참고하세요.

hf-space2/CodeWeaver/main.py

@@ -1,6 +0,0 @@
-def main():
-    print("Hello from codeweaver!")
-
-
-if __name__ == "__main__":
-    main()

hf-space2/CodeWeaver/pyproject.toml

@@ -1,27 +0,0 @@
-[project]
-name = "codeweaver"
-version = "0.1.0"
-description = "Add your description here"
-readme = "README.md"
-requires-python = ">=3.12"
-dependencies = [
-    "qdrant-client",
-    "pytest",
-    "pytest-asyncio",
-    "python-dotenv",
-    "tavily-python",
-    "requests",
-    "langsmith>=0.1.0",
-    "langchain-core>=0.3.0",
-    "langchain-google-genai>=2.0.0",
-    "langgraph>=0.2.0",
-    "sentence-transformers>=3.0.0",
-    "torch>=2.0.0",
-    "gradio==4.44.1",
-]
-
-[tool.pytest.ini_options]
-pythonpath = ["."]
-markers = [
-    "slow: 실제 API 호출이 필요한 느린 테스트 (--slow 옵션으로 실행)",
-]

hf-space2/CodeWeaver/requirements.txt

@@ -1,24 +0,0 @@
-# LangGraph & LangChain
-langgraph>=0.2.0
-langchain-google-genai>=2.0.0
-langchain-core>=0.3.0
-langsmith>=0.2.0
-
-# Vector DB
-qdrant-client>=1.11.0
-
-# Search APIs
-tavily-python>=0.5.0
-requests>=2.31.0
-
-# Embeddings
-sentence-transformers>=3.0.0
-torch>=2.0.0
-
-# UI
-gradio==4.44.1
-
-# Utils
-python-dotenv>=1.0.0
-pydantic>=2.0.0
-

hf-space2/CodeWeaver/src/agent/graph.py

@@ -1,420 +0,0 @@
-"""
-CodeWeaver LangGraph 워크플로우 구성.
-
-LangGraph 6가지 핵심 기능 완벽 구현:
-✅ Conditional Edges: 질문 유형, 캐시 여부에 따른 분기
-✅ Send API: 3개 검색 노드 병렬 실행 (fan-out/fan-in)
-✅ Subgraph: 단일 질문 처리 파이프라인 + 검색 결과 처리 파이프라인
-✅ Map-Reduce: Send API로 병렬 검색 → 결과 머지
-✅ Checkpointing: MemorySaver로 대화 상태 저장
-✅ Pydantic Typed State: 타입 안전성 보장
-"""
-
-import logging
-from typing import Literal
-
-from langgraph.checkpoint.memory import MemorySaver
-from langgraph.graph import StateGraph, START, END
-from langgraph.types import Send
-
-from src.agent.state import AgentState, WorkerState, _MULTI_ANS_RESET_TOKEN
-from src.agent.nodes import (
-    analyze_question_node,
-    check_cache_node,
-    create_plan_node,
-    classify_intent_node,
-    search_stackoverflow_node,
-    search_github_node,
-    search_official_docs_node,
-    collect_results_node,
-    evaluate_results_node,
-    refine_search_node,
-    filter_and_score_node,
-    summarize_results_node,
-    generate_answer_node,
-    return_cached_answer_node,
-    generate_with_history_node,
-    handle_too_many_questions_node,
-    combine_answers_node,
-)
-
-logger = logging.getLogger(__name__)
-
-
-def build_search_subgraph() -> StateGraph:
-    """
-    검색 결과 처리 서브그래프를 구성합니다.
-    
-    흐름: filter_and_score → summarize_results
-    
-    이 서브그래프는 single_question_subgraph 내부에서 사용되므로
-    WorkerState를 사용하여 채널 타입 충돌을 방지합니다.
-    
-    Returns:
-        컴파일된 서브그래프
-    """
-    # 서브그래프 생성 (WorkerState 사용)
-    subgraph = StateGraph(WorkerState)
-    
-    # 노드 추가
-    subgraph.add_node("filter_and_score", filter_and_score_node)
-    subgraph.add_node("summarize_results", summarize_results_node)
-    
-    # 서브그래프 내부 흐름 정의
-    # START → filter_and_score → summarize_results → END
-    subgraph.add_edge(START, "filter_and_score")
-    subgraph.add_edge("filter_and_score", "summarize_results")
-    subgraph.add_edge("summarize_results", END)
-    
-    return subgraph.compile()
-
-
-def route_after_analysis_worker(state: WorkerState) -> Literal["generate_with_history", "check_cache"]:
-    """
-    질문 분석 결과에 따라 다음 노드를 결정합니다 (WorkerState용).
-    
-    Args:
-        state: 현재 워커 상태
-    
-    Returns:
-        - "generate_with_history": 후속 질문 → 대화 히스토리 기반 답변
-        - "check_cache": 독립 질문 → 캐시 확인
-    """
-    raw_qtype = state.question_type or "independent"
-    legacy_map = {
-        "followup": "clarification",
-        "cache_candidate": "independent",
-        "new_search": "independent",
-    }
-    question_type = legacy_map.get(raw_qtype, raw_qtype)
-
-    if question_type == "clarification":
-        return "generate_with_history"
-
-    return "check_cache"
-
-
-def route_after_cache_worker(state: WorkerState) -> Literal["return_cached_answer", "classify_intent"]:
-    """
-    캐시 히트 여부에 따라 다음 노드를 결정합니다 (WorkerState용).
-    
-    Args:
-        state: 현재 워커 상태
-    
-    Returns:
-        - "return_cached_answer": 캐시 히트 시 즉시 답변 반환
-        - "classify_intent": 캐시 미스 시 의도 분류
-    """
-    if state.cached_result:
-        return "return_cached_answer"
-    else:
-        return "classify_intent"
-
-
-def route_after_evaluation_worker(state: WorkerState) -> Literal["refine_search", "search_subgraph"]:
-    """
-    검색 결과 평가 후 다음 노드를 결정합니다 (WorkerState용).
-    
-    Args:
-        state: 현재 워커 상태
-    
-    Returns:
-        - "refine_search": 결과 부족 & 개선 횟수 0회 → 쿼리 개선
-        - "search_subgraph": 결과 충분 or 개선 횟수 1회 → 필터링 진행
-    """
-    needs_refinement = state.needs_refinement
-    refinement_count = state.refinement_count
-    
-    if needs_refinement and refinement_count < 1:
-        return "refine_search"
-    else:
-        return "search_subgraph"
-
-
-def initiate_parallel_search_worker(state: WorkerState):
-    """
-    Send API를 사용하여 3개의 검색 노드를 병렬로 실행합니다 (WorkerState용).
-    
-    Args:
-        state: 현재 워커 상태
-    
-    Returns:
-        Send 객체 리스트 (fan-out)
-    """
-    return [
-        Send("search_stackoverflow", state),
-        Send("search_github", state),
-        Send("search_official_docs", state),
-    ]
-
-
-def build_single_question_subgraph() -> StateGraph:
-    """
-    단일 질문 처리 서브그래프.
-    
-    🔧 CRITICAL: 
-    - WorkerState만 사용
-    - 부모 AgentState와 완전히 격리
-    - 출력: multi_answers 또는 final_answer만
-    """
-    # WorkerState 사용 (AgentState와 완전히 독립)
-    subgraph = StateGraph(WorkerState)
-    
-    # 노드 추가
-    subgraph.add_node("analyze_question", analyze_question_node)
-    subgraph.add_node("generate_with_history", generate_with_history_node)
-    subgraph.add_node("check_cache", check_cache_node)
-    subgraph.add_node("return_cached_answer", return_cached_answer_node)
-    subgraph.add_node("classify_intent", classify_intent_node)
-    
-    # 병렬 검색 노드
-    subgraph.add_node("search_stackoverflow", search_stackoverflow_node)
-    subgraph.add_node("search_github", search_github_node)
-    subgraph.add_node("search_official_docs", search_official_docs_node)
-    
-    # 결과 처리 노드
-    subgraph.add_node("collect_results", collect_results_node)
-    subgraph.add_node("evaluate_results", evaluate_results_node)
-    subgraph.add_node("refine_search", refine_search_node)
-    
-    # 최종 답변 생성
-    subgraph.add_node("generate_answer", generate_answer_node)
-    
-    # 중첩 서브그래프 (filter + summarize)
-    filter_summarize_subgraph = build_search_subgraph()
-    subgraph.add_node("search_subgraph", filter_summarize_subgraph)
-    
-    # ===== 엣지 구성 =====
-    
-    # 1. START → analyze_question
-    subgraph.add_edge(START, "analyze_question")
-    
-    # 2. analyze_question 결과에 따른 분기
-    subgraph.add_conditional_edges(
-        "analyze_question",
-        route_after_analysis_worker,
-        {
-            "generate_with_history": "generate_with_history",
-            "check_cache": "check_cache",
-        }
-    )
-    
-    # 3. generate_with_history → END (대화 히스토리 기반 답변)
-    subgraph.add_edge("generate_with_history", END)
-    
-    # 4. check_cache 결과에 따른 분기
-    subgraph.add_conditional_edges(
-        "check_cache",
-        route_after_cache_worker,
-        {
-            "return_cached_answer": "return_cached_answer",
-            "classify_intent": "classify_intent",
-        }
-    )
-    
-    # 5. return_cached_answer → END (캐시 히트)
-    subgraph.add_edge("return_cached_answer", END)
-    
-    # 6. classify_intent → 병렬 검색 (Send API)
-    subgraph.add_conditional_edges("classify_intent", initiate_parallel_search_worker)
-    
-    # 7. 모든 검색 노드 → collect_results (fan-in)
-    subgraph.add_edge("search_stackoverflow", "collect_results")
-    subgraph.add_edge("search_github", "collect_results")
-    subgraph.add_edge("search_official_docs", "collect_results")
-    
-    # 8. collect_results → evaluate_results
-    subgraph.add_edge("collect_results", "evaluate_results")
-    
-    # 9. evaluate_results 결과에 따른 분기
-    subgraph.add_conditional_edges(
-        "evaluate_results",
-        route_after_evaluation_worker,
-        {
-            "refine_search": "refine_search",
-            "search_subgraph": "search_subgraph",
-        }
-    )
-    
-    # 10. refine_search → classify_intent (쿼리 개선 루프)
-    subgraph.add_edge("refine_search", "classify_intent")
-    
-    # 11. search_subgraph → generate_answer
-    subgraph.add_edge("search_subgraph", "generate_answer")
-    
-    # 12. generate_answer → END
-    subgraph.add_edge("generate_answer", END)
-    
-    return subgraph.compile()
-
-
-def route_after_plan(state: AgentState):
-    """
-    create_plan 결과에 따라 다음 노드를 결정합니다.
-    
-    Returns:
-        - "handle_too_many_questions": 질문 3개 이상
-        - "single_question_subgraph": 단일 주제 (1회 실행)
-        - List[Send]: 다중 질문 (N회 병렬 실행)
-    """
-    plan = state.plan or {}
-    case = plan.get("case", "single_topic")
-    
-    if case == "too_many":
-        return "handle_too_many_questions"
-    
-    elif case == "multiple_questions":
-        # 다중 질문: Send API로 서브그래프를 여러 번 호출
-        sub_questions = plan.get("sub_questions", [])
-        messages = state.messages
-        
-        logger.info("다중 질문 처리: %d개 질문을 서브그래프로 병렬 실행", len(sub_questions))
-        
-        sends = []
-        for i, sq in enumerate(sub_questions):
-            worker_state = WorkerState(
-                processing_question=sq,
-                messages=messages,
-                
-                # 🔧 [FIX] 이름 변경된 필드로 매핑
-                worker_is_multi=True,
-                worker_idx=i,
-                worker_sub_text=sq,
-            )
-            sends.append(Send("single_question_subgraph", worker_state))
-        
-        return sends
-    
-    else:
-        # 단일 질문
-        worker_state = WorkerState(
-            processing_question=state.user_question,
-            messages=state.messages,
-            
-            # 🔧 [FIX] 기본값 매핑
-            worker_is_multi=False,
-            worker_idx=0,
-            worker_sub_text=None
-        )
-        return [Send("single_question_subgraph", worker_state)]
-
-
-def route_after_subgraph(state: AgentState) -> Literal["combine_answers", END]:
-    """
-    서브그래프 실행 후 다음 노드 결정.
-    
-    - multi_answers가 있으면: 다중 질문 모드 → combine_answers
-    - multi_answers가 없으면: 단일 질문 모드 → END
-    """
-    # multi_answers에 실제 데이터가 있는지 확인 (reset token 제외)
-    has_answers = any(
-        isinstance(item, dict) and item.get("__token__") != _MULTI_ANS_RESET_TOKEN
-        for item in state.multi_answers
-    )
-    
-    if has_answers:
-        logger.info("다중 질문 모드: combine_answers로 이동")
-        return "combine_answers"
-    else:
-        logger.info("단일 질문 모드: END로 이동")
-        return END
-
-
-def build_agent_graph() -> StateGraph:
-    """
-    CodeWeaver 에이전트의 메인 그래프를 구성합니다.
-    
-    전체 흐름 (단순화됨):
-    1. START → create_plan (질문 유형 및 개수 판단)
-    2. 질문 유형에 따른 분기:
-       - single_topic: single_question_subgraph (1회) → END
-       - multiple_questions: Send API로 single_question_subgraph (2회 병렬) → combine_answers → END
-       - too_many: handle_too_many_questions → END
-    
-    핵심 개선사항:
-    - ✅ 단일 질문 파이프라인을 재사용 가능한 서브그래프로 추출
-    - ✅ 부모 그래프는 계획/분기/병합만 담당
-    - ✅ 복잡한 worker 노드 제거
-    - ✅ 코드 중복 제거
-    - ✅ 구조 명확화: 부모(orchestration) vs 자식(processing)
-    
-    Returns:
-        구성된 StateGraph (컴파일 전)
-    """
-    # 메인 그래프 생성
-    graph = StateGraph(AgentState)
-    
-    # 노드 추가
-    graph.add_node("create_plan", create_plan_node)
-    graph.add_node("handle_too_many_questions", handle_too_many_questions_node)
-    graph.add_node("combine_answers", combine_answers_node)
-    
-    # 서브그래프를 노드로 등록
-    single_question_subgraph = build_single_question_subgraph()
-    graph.add_node("single_question_subgraph", single_question_subgraph)
-    
-    # ===== 엣지 구성 =====
-    
-    # 1. START → create_plan
-    graph.add_edge(START, "create_plan")
-    
-    # 2. create_plan → 분기
-    #    - single_topic: "single_question_subgraph" → END
-    #    - multiple_questions: List[Send("single_question_subgraph", WorkerState)] → combine_answers
-    #    - too_many: "handle_too_many_questions" → END
-    graph.add_conditional_edges("create_plan", route_after_plan)
-    
-    # 3. handle_too_many_questions → END
-    graph.add_edge("handle_too_many_questions", END)
-    
-    # 4. 🔧 FIX: single_question_subgraph의 출구를 명확히 분리
-    #    - 단일 질문 (case=single_topic): 무조건 END
-    #    - 다중 질문 (case=multiple_questions): Send API가 자동으로 combine_answers로 fan-in
-    
-    # 4-1. 단일 질문 경로: single_question_subgraph → END
-    # 4-2. 다중 질문 경로: single_question_subgraph → combine_answers (자동 fan-in)
-    
-    # 🔧 해결책: conditional edges로 분기
-    graph.add_conditional_edges(
-        "single_question_subgraph",
-        route_after_subgraph,
-        {
-            "combine_answers": "combine_answers",
-            END: END,
-        }
-    )
-    
-    # 5. combine_answers → END
-    graph.add_edge("combine_answers", END)
-    
-    return graph
-
-
-def create_agent(enable_checkpointing: bool = True):
-    """
-    CodeWeaver 에이전트를 생성하고 컴파일합니다.
-    
-    Args:
-        enable_checkpointing: 체크포인트 활성화 여부
-            - True: MemorySaver 사용 (개발/테스트용)
-            - False: 체크포인트 없이 실행 (상태 저장 불가)
-    
-    Returns:
-        컴파일된 실행 가능한 그래프
-    
-    Note:
-        프로덕션 환경에서는 MemorySaver 대신 
-        PostgresSaver, SqliteSaver 등 영구 저장소 사용 권장
-    """
-    graph = build_agent_graph()
-    
-    if enable_checkpointing:
-        # 메모리 기반 체크포인터 (프로덕션에서는 DB 사용 권장)
-        memory = MemorySaver()
-        return graph.compile(checkpointer=memory)
-    else:
-        return graph.compile()
-
-
-# 에이전트 인스턴스 생성 (모듈 임포트 시 자동 생성)
-agent = create_agent(enable_checkpointing=True)

hf-space2/CodeWeaver/src/agent/nodes.py

@@ -1,1212 +0,0 @@
-"""
-CodeWeaver LangGraph 노드 구현.
-
-각 노드는 AgentState 또는 WorkerState를 받아 처리하고 업데이트된 상태를 반환합니다.
-모든 노드는 LangSmith를 통해 자동으로 추적됩니다.
-"""
-
-import asyncio
-import logging
-import os
-from typing import List, Literal, Optional, Union
-
-from langchain_core.messages import HumanMessage, SystemMessage, AIMessage
-from langchain_google_genai import ChatGoogleGenerativeAI
-from langgraph.graph import StateGraph, START, END
-from langgraph.types import Send
-
-from src.agent.state import AgentState, WorkerState, SearchResult
-from src.agent.state import _MULTI_ANS_RESET_TOKEN
-from src.tools.search_tools import (
-    search_github,
-    search_official_docs,
-    search_stackoverflow,
-)
-from src.utils.tracing import trace_node
-from src.vector_db.qdrant_client import QdrantManager
-
-logger = logging.getLogger(__name__)
-
-# LLM 초기화 (Gemini 2.5 Flash)
-llm = ChatGoogleGenerativeAI(
-    model="gemini-2.5-flash-lite",
-    temperature=0.7,
-)
-
-# Qdrant 매니저 초기화
-qdrant_manager = QdrantManager()
-
-
-# ==================== 부모 그래프 노드 (AgentState 사용) ====================
-
-@trace_node("create_plan")
-def create_plan_node(state: AgentState) -> dict:
-    """
-    질문을 분석하여 유형과 개수를 판단합니다.
-    
-    Case:
-    - single_topic: 하나의 주제 (서브그래프 1회)
-    - multiple_questions: 독립 질문 2개 (Send API로 서브그래프 2회 병렬)
-    - too_many: 독립 질문 3개 이상 (에러 메시지)
-    """
-    user_question = state.user_question
-    logger.info("질문 분석 및 계획 수립 중: %s", user_question[:50])
-
-    def _extract_question_candidates(text: str) -> List[str]:
-        """입력 문자열에서 '질문 후보'를 최대한 보수적으로 추출합니다(3개 이상 감지용)."""
-        import re
-
-        if not text:
-            return []
-
-        t = text.strip()
-        # 1) 물음표 기반 분리
-        parts = re.split(r"[??]+", t)
-        candidates = [p.strip() for p in parts if p.strip()]
-        if len(candidates) >= 2 and re.search(r"[??]", t):
-            return candidates
-
-        # 2) 줄바꿈/번호 매기기 기반
-        lines = [ln.strip() for ln in re.split(r"[\r\n]+", t) if ln.strip()]
-        numbered = []
-        for ln in lines:
-            if re.match(r"^\s*(\d+[\.\)]|[-*])\s+", ln):
-                numbered.append(re.sub(r"^\s*(\d+[\.\)]|[-*])\s+", "", ln).strip())
-        if len(numbered) >= 2:
-            return numbered
-
-        # 3) 구분자 기반(세미콜론)
-        semi = [p.strip() for p in t.split(";") if p.strip()]
-        if len(semi) >= 2:
-            return semi
-
-        return [t]
-
-    def _hard_guard_too_many(text: str) -> Optional[dict]:
-        """
-        하드 가드: 사용자가 '질문 3개 이상'을 한 번에 던진 것으로 확실한 경우,
-        LLM 분류와 무관하게 too_many로 강제합니다.
-        """
-        import re
-
-        if not text:
-            return None
-
-        # 가장 확실한 기준: 물음표가 3개 이상
-        qmarks = len(re.findall(r"[??]", text))
-        if qmarks >= 3:
-            candidates = _extract_question_candidates(text)
-            msg = "죄송합니다. 질문은 한 번에 최대 2개까지 가능합니다. 가장 중요한 2개만 골라서 다시 질문해 주세요."
-            return {
-                "case": "too_many",
-                "sub_questions": candidates,
-                "reasoning": f"물음표가 {qmarks}개로, 3개 이상의 독립 질문으로 판단했습니다.",
-                "error_message": msg,
-                "steps_note": f"⚠️ 질문 수 초과 감지(물음표 {qmarks}개) → too_many로 강제",
-            }
-
-        # 번호 매기기/리스트로 3개 이상
-        candidates = _extract_question_candidates(text)
-        if len(candidates) >= 3:
-            msg = "죄송합니다. 질문은 한 번에 최대 2개까지 가능합니다. 가장 중요한 2개만 골라서 다시 질문해 주세요."
-            return {
-                "case": "too_many",
-                "sub_questions": candidates,
-                "reasoning": f"질문 후보가 {len(candidates)}개로 감지되어 3개 이상 질문으로 판단했습니다.",
-                "error_message": msg,
-                "steps_note": f"⚠️ 질문 수 초과 감지(후보 {len(candidates)}개) → too_many로 강제",
-            }
-
-        return None
-
-    # 하드 가드(결정론적) – LLM이 잘못 분류하더라도 3개 이상이면 무조건 차단
-    hard = _hard_guard_too_many(user_question)
-    if hard:
-        steps_delta = [
-            f"📋 계획 타입: {hard['case']}",
-            f"   서브질문: {len(hard['sub_questions'])}개",
-            f"   이유: {hard['reasoning']}",
-            hard["steps_note"],
-        ]
-        logger.info("계획 수립 완료(하드 가드): too_many, %d개 서브질��", len(hard["sub_questions"]))
-        return {
-            "plan": {
-                "case": hard["case"],
-                "sub_questions": hard["sub_questions"],
-                "reasoning": hard["reasoning"],
-                "error_message": hard["error_message"],
-            },
-            "is_multi_question": False,
-            "sub_question_index": 0,
-            "sub_question_text": None,
-            "original_multi_question": None,
-            "multi_answers": [{"__token__": _MULTI_ANS_RESET_TOKEN}],
-            "intermediate_steps": steps_delta,
-        }
-    
-    plan_prompt = f"""질문을 분석하여 유형과 개수를 판단하세요.
-
-질문: {user_question}
-
-**중요**: sub_questions의 용도는 case에 따라 다릅니다!
-
-**Case 1: single_topic** (하나의 주제)
-- 예: "Spring Security JWT 인증 구현"
-  → sub_questions: ["개념", "구현", "예제"]
-  → 용도: 답변 섹션 구조 (검색은 원본 질문으로 1회만)
-  → 검색: "Spring Security JWT 인증 구현"
-
-- 예: "React hooks 완벽 가이드"
-  → sub_questions: ["hooks란", "주요 hooks", "실무 패턴"]
-  → 용도: 답변 섹션 구조
-  → 검색: "React hooks 완벽 가이드"
-
-**Case 2: multiple_questions** (여러 독립 질문, 최대 2개)
-- 예: "JWT가 뭐야? CORS는?"
-  → sub_questions: ["JWT가 뭐야?", "CORS는?"]
-  → 용도: 각 질문마다 별도 검색
-  → 검색: "JWT가 뭐야?" (1회), "CORS는?" (1회)
-
-- 예: "Docker 사용법은? Redis 설치는?"
-  → sub_questions: ["Docker 사용법은?", "Redis 설치는?"]
-  → 용도: 각 질문마다 별도 검색
-
-**Case 3: too_many** (3개 이상 질문)
-- 예: "JWT? CORS? Docker?"
-  → 너무 많아서 처리 불가
-  → error_message 제공
-
-규칙:
-- single_topic: sub_questions는 짧은 키워드/구절 (1-5개)
-- multiple_questions: sub_questions는 완전한 문장 (정확히 2개만)
-- too_many: 3개 이상이면 이 케이스로 분류
-
-다음 JSON 형식으로만 답변하세요:
-{{
-    "case": "single_topic|multiple_questions|too_many",
-    "sub_questions": [...],
-    "reasoning": "이 케이스로 판단한 이유",
-    "error_message": "..." (too_many인 경우만, 그 외는 빈 문자열)
-}}
-
-JSON 외에 다른 텍스트는 포함하지 마세요."""
-
-    try:
-        import json
-        
-        messages_to_llm = [HumanMessage(content=plan_prompt)]
-        response = llm.invoke(messages_to_llm)
-        
-        # JSON 파싱
-        response_text = response.content.strip()
-        
-        # JSON 블록 추출
-        if "```json" in response_text:
-            response_text = response_text.split("```json")[1].split("```")[0].strip()
-        elif "```" in response_text:
-            response_text = response_text.split("```")[1].split("```")[0].strip()
-        
-        plan_data = json.loads(response_text)
-        
-        case = plan_data.get("case", "single_topic")
-        sub_questions = plan_data.get("sub_questions", [user_question])
-        reasoning = plan_data.get("reasoning", "")
-        error_message = plan_data.get("error_message", "")
-
-        # LLM 결과를 받은 뒤에도 한 번 더 하드 가드 적용 (안전장치)
-        hard2 = _hard_guard_too_many(user_question)
-        if hard2:
-            case = hard2["case"]
-            sub_questions = hard2["sub_questions"]
-            reasoning = hard2["reasoning"]
-            error_message = hard2["error_message"]
-        
-        # 유효성 검증
-        if not sub_questions or len(sub_questions) == 0:
-            sub_questions = [user_question]
-            case = "single_topic"
-        
-        # multiple_questions일 때 2개 제한 강제
-        if case == "multiple_questions" and len(sub_questions) > 2:
-            sub_questions = sub_questions[:2]
-            reasoning += " (질문 수 제한: 최대 2개)"
-        
-        steps_delta = [
-            f"📋 계획 타입: {case}",
-            f"   서브질문: {len(sub_questions)}개",
-            f"   이유: {reasoning}"
-        ]
-        
-        logger.info("계획 수립 완료: %s, %d개 서브질문", case, len(sub_questions))
-        
-        return {
-            "plan": {
-                "case": case,
-                "sub_questions": sub_questions,
-                "reasoning": reasoning,
-                "error_message": error_message
-            },
-            "is_multi_question": False,
-            "sub_question_index": 0,
-            "sub_question_text": None,
-            "original_multi_question": None,
-            "multi_answers": [{"__token__": _MULTI_ANS_RESET_TOKEN}],
-            "intermediate_steps": steps_delta
-        }
-        
-    except Exception as e:
-        logger.error("계획 수립 실패: %s", e, exc_info=True)
-        
-        # 기본값: 원본 질문 그대로 사용
-        steps_delta = [
-            "⚠️ 계획 수립 실패, 기본값 사용: single_topic"
-        ]
-        
-        return {
-            "plan": {
-                "case": "single_topic",
-                "sub_questions": [user_question],
-                "reasoning": "계획 수립 실패, 기본값 사용",
-                "error_message": ""
-            },
-            "is_multi_question": False,
-            "sub_question_index": 0,
-            "sub_question_text": None,
-            "original_multi_question": None,
-            "multi_answers": [{"__token__": _MULTI_ANS_RESET_TOKEN}],
-            "intermediate_steps": steps_delta
-        }
-
-
-@trace_node("handle_too_many_questions")
-def handle_too_many_questions_node(state: AgentState) -> dict:
-    """3개 이상 질문 시 안내 메시지를 반환합니다."""
-    plan = state.plan or {}
-    error_message = plan.get("error_message", "")
-    sub_questions = plan.get("sub_questions", [])
-    
-    logger.info("질문 수 초과: %d개", len(sub_questions))
-    
-    default_message = """죄송합니다. 한 번에 최대 2개의 질문까지만 처리할 수 있습니다.
-
-다음 중 하나를 선택해서 다시 질문해 주세요:
-
-1. **하나의 주제로 통합해서 질문**
-   예: "JWT 인증과 CORS 설정을 함께 구현하는 방법"
-
-2. **가장 중요한 2개 질문만 선택**
-   예: "JWT가 뭐야? 내 코드에 어떻게 적용해?"
-
-3. **질문을 나눠서 순차적으로 질문**
-   예: 먼저 "JWT가 뭐야?" 질문 → 답변 확인 → 다음 질문
-
-어떻게 도와드릴까요?"""
-    
-    final_message = error_message if error_message else default_message
-    
-    steps_delta = [
-        f"⚠️ 질문 수 초과: {len(sub_questions)}개",
-        "💬 안내 메시지 제공 (대화 계속 가능)"
-    ]
-    
-    return {
-        "final_answer": final_message,
-        "intermediate_steps": steps_delta
-    }
-
-
-@trace_node("combine_answers")
-def combine_answers_node(state: AgentState) -> dict:
-    """
-    Fan-in: 모든 Send가 완료되면 multi_answers를 조합합니다.
-    """
-    answers = state.multi_answers
-    original_question = state.original_multi_question or state.user_question
-    
-    if not answers:
-        logger.error("다중 답변이 비어있음")
-        return {
-            "final_answer": "답변 생성에 실패했습니다. 다시 시도해 주세요.",
-            "intermediate_steps": ["❌ multi_answers 비어있음"]
-        }
-    
-    # 인덱스 순으로 정렬
-    answers.sort(key=lambda x: x["index"])
-    
-    # Markdown 형식으로 조합
-    combined_parts = []
-    for ans in answers:
-        section = f"""## {ans['index']+1}. {ans['question']}
-
-{ans['answer']}"""
-        combined_parts.append(section)
-    
-    combined = "\n\n---\n\n".join(combined_parts)
-    
-    # 헤더 추가
-    header = f"# 다중 질문 답변\n\n원본 질문: {original_question}\n\n---\n\n"
-    final_combined = header + combined
-    
-    logger.info("다중 답변 조합 완료: %d개", len(answers))
-    
-    return {
-        "final_answer": final_combined,
-        "intermediate_steps": [f"✅ {len(answers)}개 답변 조합 완료"]
-    }
-
-
-# ==================== 서브그래프 노드 (WorkerState 사용) ====================
-
-@trace_node("analyze_question")
-async def analyze_question_node(state: Union[AgentState, WorkerState]) -> dict:
-    """
-    질문을 분석하여 유형을 분류하고 캐시 적격성을 판단합니다.
-    
-    🔧 FIX: 다중 질문 모드일 때는 messages를 무시하고 독립 질문으로만 분석
-    """
-    # 🔧 [FIX] WorkerState일 경우 processing_question 사용
-    if isinstance(state, WorkerState):
-        user_question = state.processing_question
-        # 🔧 [FIX] 이름 변경된 필드 사용
-        is_multi = state.worker_is_multi
-    else:
-        user_question = state.user_question
-        is_multi = getattr(state, 'is_multi_question', False)
-        
-    messages = state.messages
-    
-    # 대화 맥락 구성 (다중 질문 모드가 아닐 때만)
-    has_history = messages and len(messages) > 1 and not is_multi
-    context_info = ""
-    
-    if has_history:
-        context_info = "\n이전 대화 맥락:\n"
-        for msg in messages[-4:-1]:
-            if hasattr(msg, 'type') and hasattr(msg, 'content'):
-                role = "사용자" if msg.type == "human" else "AI"
-                context_info += f"{role}: {msg.content[:100]}\n"
-    
-    # 🔧 다중 질문 모드 강제 처리
-    if is_multi:
-        context_info = "\n⚠️ 주의: 이 질문은 다중 질문의 일부입니다. 독립적인 질문으로만 판단하세요.\n"
-    
-    analysis_prompt = f"""질문을 분석하여 유형을 분류하고, 캐시 적격성을 판단하세요.
-
-{context_info}
-현재 질문: {user_question}
-
-분류 기준:
-
-1. **clarification** (보충/형식 변경 요청)
-   - 이전 답변/대화 내용을 바탕으로 "설명 방식"을 바꾸거나 보충을 요청
-   - 예: "좀 더 쉽게 설명해줘", "예제 코드로 보여줘", "한 줄로 요약해줘"
-   - should_cache = false, canonical_question = null
-   
-2. **new_topic** (대화 중 새 개념 질문)
-   - 대화가 이어지는 중이지만, 질문 자체가 독립적으로 성립하는 '새 개념/정의/비교/사용법' 질문
-   - 예: "Event Listener는 뭐야?", "CORS가 뭐야?"
-   - should_cache = true, canonical_question 생성
-   
-3. **independent** (완전 독립 질문)
-   - 이전 대화 없이도 이해 가능한 일반 질문
-   - 예: "Spring Security가 뭐야?", "Docker Compose 사용법은?"
-   - should_cache = true, canonical_question 생성
-
-다음 JSON 형식으로만 답변하세요:
-{{
-    "question_type": "clarification|new_topic|independent",
-    "should_cache": true|false,
-    "reasoning": "분류 이유 1-2문장",
-    "canonical_question": "캐시할 정규화된 질문 (should_cache가 true인 경우에만, 아니면 null)"
-}}
-
-JSON 외에 다른 텍스트는 포함하지 마세요."""
-
-    try:
-        messages_to_llm = [HumanMessage(content=analysis_prompt)]
-        response = llm.invoke(messages_to_llm)
-        
-        import json
-        response_text = response.content.strip()
-        
-        if "```json" in response_text:
-            response_text = response_text.split("```json")[1].split("```")[0].strip()
-        elif "```" in response_text:
-            response_text = response_text.split("```")[1].split("```")[0].strip()
-        
-        analysis = json.loads(response_text)
-        
-        question_type = analysis.get("question_type", "independent")
-        should_cache = analysis.get("should_cache", False)
-        reasoning = analysis.get("reasoning", "")
-        canonical_question = analysis.get("canonical_question", user_question)
-        
-        # 유효성 검증
-        if question_type not in ["clarification", "new_topic", "independent"]:
-            question_type = "independent"
-
-        # 🔧 CRITICAL: 다중 질문 모드일 때는 무조건 independent로 강제
-        if is_multi and question_type == "clarification":
-            logger.warning("다중 질문 모드에서 clarification 감지 → independent로 강제 변경")
-            question_type = "independent"
-            should_cache = True
-            reasoning = "다중 질문 모드: 독립 질문으로 강제 분류"
-
-        # 정책 보정
-        if question_type == "clarification":
-            should_cache = False
-            canonical_question = None
-        else:
-            if canonical_question is None or (isinstance(canonical_question, str) and not canonical_question.strip()):
-                canonical_question = user_question
-        
-        steps_delta = [
-            "__RESET_STEPS__",
-            f"🔍 질문 분석: {question_type} (캐시 여부: {should_cache})",
-        ]
-        
-        return {
-            "question_type": question_type,
-            "should_cache": should_cache,
-            "analysis_reasoning": reasoning,
-            "canonical_question": canonical_question if should_cache else None,
-            "intermediate_steps": steps_delta
-        }
-        
-    except Exception as e:
-        logger.error("질문 분석 실패: %s", e, exc_info=True)
-        
-        steps_delta = [
-            "__RESET_STEPS__",
-            "⚠️ 질문 분석 실패, 기본값 사용: independent",
-        ]
-        
-        return {
-            "question_type": "independent",
-            "should_cache": True,
-            "analysis_reasoning": "분석 실패, 기본값 사용",
-            "canonical_question": user_question,
-            "intermediate_steps": steps_delta
-        }
-
-
-@trace_node("check_cache")
-async def check_cache_node(state: Union[AgentState, WorkerState]) -> dict:
-    """벡터 DB 캐시에서 유사한 질문을 검색합니다."""
-    # 🔧 [FIX] 변수 접근 수정
-    current_q = state.processing_question if isinstance(state, WorkerState) else state.user_question
-    question_for_lookup = state.canonical_question or current_q
-    logger.info("캐시 확인 중: %s", question_for_lookup[:50])
-    
-    try:
-        cached_result = await qdrant_manager.search_cache(
-            question=question_for_lookup,
-            threshold=0.85
-        )
-        
-        updates = {}
-        steps_delta: List[str] = []
-        
-        if cached_result:
-            updates["cached_result"] = cached_result
-            steps_delta.append(f"✅ 캐시 히트 (답변 길이: {len(cached_result)}자)")
-            logger.info("캐시 히트")
-        else:
-            updates["cached_result"] = None
-            steps_delta.append("❌ 캐시 미스: 새로운 검색 필요")
-            logger.info("캐시 미스")
-    
-    except Exception as e:
-        logger.error("캐시 확인 실패: %s", e, exc_info=True)
-        updates["cached_result"] = None
-        steps_delta.append(f"⚠️ 캐시 확인 오류: {str(e)}")
-    
-    updates["intermediate_steps"] = steps_delta
-    return updates
-
-
-@trace_node("return_cached_answer")
-def return_cached_answer_node(state: Union[AgentState, WorkerState]) -> dict:
-    """캐시 히트 시 저장된 답변을 반환합니다."""
-    logger.info("캐시된 답변 반환")
-    
-    cached_answer = state.cached_result
-    is_multi = isinstance(state, WorkerState) and state.worker_is_multi
-    
-    if is_multi:
-        return {
-            "multi_answers": [{
-                "index": state.worker_idx,
-                "question": state.worker_sub_text or state.processing_question,
-                "answer": cached_answer
-            }]
-        }
-    else:
-        # 🔧 [FIX] messages에 AIMessage 추가하여 히스토리 저장 보장
-        steps_delta = ["💾 캐시된 답변 반환 (검색 생략)"]
-        return {
-            "final_answer": cached_answer,
-            "messages": [AIMessage(content=cached_answer)], # 👈 핵심 수정
-            "intermediate_steps": steps_delta
-        }
-
-
-@trace_node("generate_with_history")
-async def generate_with_history_node(state: Union[AgentState, WorkerState]) -> dict:
-    """
-    대화 히스토리만 사용하여 후속 질문에 답변합니다.
-    
-    수정 사항:
-    1. 문맥 오염 방지: 바로 직전의 대화(질문+답변)만 참조하도록 슬라이싱 적용
-    2. 히스토리 저장: AIMessage 반환 추가 (대화 끊김 방지)
-    """
-    # 1. 현재 질문 추출
-    user_question = state.processing_question if isinstance(state, WorkerState) else state.user_question
-    messages_history = state.messages
-    
-    logger.info("대화 히스토리 기반 답변 생성: %s", user_question[:50])
-    
-    # 2. 대화 맥락 구성 (Context Pollution 방지)
-    context_prompt = "이전 대화를 참고하여 후속 질문에 답변하세요.\n\n"
-    
-    # [핵심] 현재 질문을 제외한 과거 기록 중 '가장 최근 2개(직전 질문+답변)'만 참조
-    prev_messages = messages_history[:-1] if messages_history else []
-    recent_context = prev_messages[-2:] if prev_messages else []
-    
-    if recent_context:
-        context_prompt += "직전 대화 내역:\n"
-        for msg in recent_context:
-            if hasattr(msg, 'type') and hasattr(msg, 'content'):
-                role = "사용자" if msg.type == "human" else "AI"
-                context_prompt += f"{role}: {msg.content}\n\n"
-    
-    context_prompt += f"현재 질문: {user_question}\n\n"
-    context_prompt += "위의 '직전 대화 내역'에만 집중하여 답변하세요. 그 외의 이전 주제나 불필요한 맥락은 언급하지 마세요."
-    
-    updates = {}
-    steps_delta: List[str] = []
-    
-    try:
-        # 3. LLM 호출
-        response = llm.invoke([HumanMessage(content=context_prompt)])
-        final_answer = response.content.strip()
-        
-        # 4. 상태 업데이트
-        is_multi = isinstance(state, WorkerState) and state.worker_is_multi
-        
-        if is_multi:
-            # 다중 질문 모드 (예외적 상황)
-            return {
-                "multi_answers": [{
-                    "index": state.worker_idx,
-                    "question": state.worker_sub_text or user_question,
-                    "answer": final_answer
-                }]
-            }
-        else:
-            # 단일 질문 모드 (정상 케이스)
-            updates["final_answer"] = final_answer
-            # [핵심] 대화 히스토리에 AI 답변을 추가하여 다음 턴에서 참조 가능하게 함
-            updates["messages"] = [AIMessage(content=final_answer)]
-            
-            steps_delta.append(f"💬 대화 히스토리 기반 답변 생성 (길이: {len(final_answer)}자)")
-            steps_delta.append("⚠️ 캐시 저장 생략 (보충 요청)")
-            
-            logger.info("대화 히스토리 기반 답변 생성 완료")
-        
-    except Exception as e:
-        logger.error("대화 히스토리 기반 답변 생성 실패: %s", e, exc_info=True)
-        
-        if is_multi:
-            return {
-                "multi_answers": [{
-                    "index": state.worker_idx,
-                    "question": state.worker_sub_text or user_question,
-                    "answer": "답변 생성에 실패했습니다. 다시 시도해 주세요."
-                }]
-            }
-        else:
-            updates["final_answer"] = "답변 생성에 실패했습니다. 다시 시도해 주세요."
-            steps_delta.append(f"❌ 답변 생성 실패: {str(e)}")
-    
-    updates["intermediate_steps"] = steps_delta
-    return updates
-
-
-@trace_node("classify_intent")
-def classify_intent_node(state: Union[AgentState, WorkerState]) -> dict:
-    """
-    LLM을 사용하여 사용자 질문의 의도를 분류합니다.
-    
-    🔧 CRITICAL:
-    - refined_question이 있으면 그것을 사용, 없으면 user_question 사용
-    - WorkerState 필드만 반환 (부모 AgentState와 충돌 방지)
-    - ❌ 절대 반환하면 안 되는 것들: user_question, messages
-    """
-    # 🔧 [FIX] 변수 접근 수정
-    current_q = state.processing_question if isinstance(state, WorkerState) else state.user_question
-    question_to_classify = state.refined_question if hasattr(state, 'refined_question') and state.refined_question else current_q
-    
-    logger.info("의도 분류 중: %s", question_to_classify[:50])
-    
-    classification_prompt = f"""질문을 다음 세 가지 의도 중 하나로 분류하세요:
-
-1. debugging: 에러 해결, 버그 수정, 문제 해결
-2. learning: 개념 학습, 원리 이해, 튜토리얼
-3. code_review: 코드 개선, 리팩토링, 베스트 프랙티스
-
-질문: {question_to_classify}
-
-반드시 debugging, learning, code_review 중 하나만 답하세요."""
-
-    updates = {}
-    steps_delta: List[str] = []
-    
-    try:
-        messages = [
-            SystemMessage(content="당신은 개발자 질문을 분류하는 전문가입니다."),
-            HumanMessage(content=classification_prompt)
-        ]
-        
-        response = llm.invoke(messages)
-        intent_raw = response.content.strip().lower()
-        
-        # 유효한 의도로 정규화
-        valid_intents = ["debugging", "learning", "code_review"]
-        intent = next((i for i in valid_intents if i in intent_raw), "learning")
-        
-        updates["detected_intent"] = intent
-        steps_delta.append(f"🎯 의도 분류: {intent}")
-        logger.info("의도 분류 완료: %s", intent)
-        
-    except Exception as e:
-        logger.error("의도 분류 실패: %s", e, exc_info=True)
-        updates["detected_intent"] = "learning"
-        steps_delta.append("⚠️ 의도 분류 실패, 기본값 사용: learning")
-    
-    updates["intermediate_steps"] = steps_delta
-    
-    # 🔧 CRITICAL: WorkerState 필드만 반환
-    # ✅ OK: detected_intent, intermediate_steps
-    # ❌ 절대 반환하면 안 됨: user_question, messages
-    return updates
-
-
-@trace_node("search_stackoverflow")
-def search_stackoverflow_node(state: Union[AgentState, WorkerState]) -> dict:
-    """Stack Overflow에서 검색을 수행합니다."""
-    # 🔧 [FIX] 변수 접근 수정
-    current_q = state.processing_question if isinstance(state, WorkerState) else state.user_question
-    question_to_use = state.refined_question if hasattr(state, 'refined_question') and state.refined_question else current_q
-    
-    intent = state.detected_intent or "learning"
-    count = 5 if intent == "debugging" else 3
-    
-    logger.info("Stack Overflow 검색 시작: %d개", count)
-    
-    try:
-        results = search_stackoverflow(question_to_use, count)
-        logger.info("Stack Overflow에서 %d개 결과 수집", len(results))
-        
-        # 🔧 FIX: intermediate_steps 제거
-        return {
-            "search_results": results,
-            # intermediate_steps 제거! (병렬 충돌 방지)
-        }
-    except Exception as e:
-        logger.error("Stack Overflow 검색 실패: %s", e)
-        return {}
-
-
-@trace_node("search_github")
-def search_github_node(state: Union[AgentState, WorkerState]) -> dict:
-    """GitHub Issues/Discussions에서 검색을 수행합니다."""
-    # 🔧 [FIX] 변수 접근 수정
-    current_q = state.processing_question if isinstance(state, WorkerState) else state.user_question
-    question_to_use = state.refined_question if hasattr(state, 'refined_question') and state.refined_question else current_q
-    
-    intent = state.detected_intent or "learning"
-    count = 5 if intent == "code_review" else 3 if intent == "learning" else 2
-    
-    logger.info("GitHub 검색 시작: %d개", count)
-    
-    try:
-        results = search_github(question_to_use, count)
-        logger.info("GitHub에서 %d개 결과 수집", len(results))
-        
-        # 🔧 FIX: intermediate_steps 제거
-        return {
-            "search_results": results,
-            # intermediate_steps 제거! (병렬 충돌 방지)
-        }
-    except Exception as e:
-        logger.error("GitHub 검색 실패: %s", e)
-        return {}
-
-
-@trace_node("search_official_docs")
-def search_official_docs_node(state: Union[AgentState, WorkerState]) -> dict:
-    """공식 문서/Tavily에서 검색을 수행합니다."""
-    # 🔧 [FIX] 변수 접근 수정
-    current_q = state.processing_question if isinstance(state, WorkerState) else state.user_question
-    question_to_use = state.refined_question if hasattr(state, 'refined_question') and state.refined_question else current_q
-    
-    intent = state.detected_intent or "learning"
-    count = 5 if intent == "learning" else 2
-    
-    logger.info("공식 문서 검색 시작: %d개", count)
-    
-    try:
-        results = search_official_docs(question_to_use, count)
-        logger.info("공식 문서에서 %d개 결과 수집", len(results))
-        
-        # 🔧 FIX: intermediate_steps 제거
-        return {
-            "search_results": results,
-            # intermediate_steps 제거! (병렬 충돌 방지)
-        }
-    except Exception as e:
-        logger.error("공식 문서 검색 실패: %s", e)
-        return {}
-
-
-@trace_node("collect_results")
-def collect_results_node(state: Union[AgentState, WorkerState]) -> dict:
-    """병렬 검색 결과를 수집하고 카운트합니다."""
-    total_results = len(state.search_results)
-    
-    logger.info("검색 결과 수집 완료: %d개", total_results)
-    
-    # 🔧 FIX: 로그만 찍고, intermediate_steps는 업데이트하지 않음
-    # (병렬 노드에서 intermediate_steps 업데이트 시 충돌 발생)
-    
-    return {}  # 빈 딕셔너리 반환 (상태 변경 없음)
-
-
-@trace_node("evaluate_results")
-def evaluate_results_node(state: Union[AgentState, WorkerState]) -> dict:
-    """검색 결과의 개수와 품질을 모두 평가합니다."""
-    search_results = state.search_results
-    refinement_count = state.refinement_count
-    
-    result_count = len(search_results)
-    
-    logger.info("검색 결과 평가: %d개 (개선 횟수: %d)", result_count, refinement_count)
-    
-    # 안전장치: 이미 1회 개선했으면 더 이상 개선하지 않음
-    if refinement_count >= 1:
-        steps_delta = [
-            f"⚠️ 최대 개선 횟수 도달 ({refinement_count}회), 현재 결과로 진행"
-        ]
-        return {
-            "needs_refinement": False,
-            "intermediate_steps": steps_delta
-        }
-    
-    # 1차 평가: 개수
-    if result_count < 2:
-        steps_delta = [
-            f"⚠️ 검색 결과 부족 ({result_count}개 < 2개), 쿼리 개선 필요"
-        ]
-        return {
-            "needs_refinement": True,
-            "intermediate_steps": steps_delta
-        }
-    
-    # 2차 평가: 품질
-    scored_results = [r for r in search_results if r.relevance_score is not None]
-    
-    if scored_results:
-        avg_score = sum(r.relevance_score for r in scored_results) / len(scored_results)
-        
-        if avg_score < 0.5:
-            steps_delta = [
-                f"⚠️ 검색 결과 품질 부족 (평균 점수: {avg_score:.2f} < 0.5), 쿼리 개선 필요"
-            ]
-            return {
-                "needs_refinement": True,
-                "intermediate_steps": steps_delta
-            }
-        
-        steps_delta = [
-            f"✅ 검색 결과 충분 ({result_count}개, 평균 점수: {avg_score:.2f}), 필터링 단계로 진행"
-        ]
-    else:
-        steps_delta = [
-            f"✅ 검색 결과 충분 ({result_count}개), 필터링 단계로 진행"
-        ]
-    
-    return {
-        "needs_refinement": False,
-        "intermediate_steps": steps_delta
-    }
-
-
-@trace_node("refine_search")
-def refine_search_node(state: Union[AgentState, WorkerState]) -> dict:
-    """
-    검색 쿼리를 개선합니다.
-    
-    🔧 CRITICAL: 
-    - user_question을 직접 업데이트하지 않고, refined_question에 저장
-    - 부모 AgentState와 충돌 방지를 위해 WorkerState 필드만 반환
-    - ❌ 절대 반환하면 안 되는 것들: user_question, messages, final_answer
-    """
-    # 🔧 [FIX] 변수 접근 수정
-    user_question = state.processing_question if isinstance(state, WorkerState) else state.user_question
-    original_question = state.original_question or user_question
-    result_count = len(state.search_results)
-    
-    logger.info("검색 쿼리 개선 중: %s (%d개 결과)", user_question[:50], result_count)
-    
-    refinement_prompt = f"""검색 결과가 부족합니다. 검색 쿼리를 개선하세요.
-
-원본 질문: {user_question}
-현재 결과 수: {result_count}개 (목표: 2개 이상)
-
-개선 전략 (하나 선택):
-1. MORE_SPECIFIC: 기술적 세부사항 추가
-2. MORE_GENERAL: 더 넓은 용어 사용
-3. TRANSLATE: 언어 변환
-
-다음 JSON 형식으로만 답변하세요:
-{{
-    "new_query": "개선된 검색 쿼리",
-    "strategy": "MORE_SPECIFIC|MORE_GENERAL|TRANSLATE",
-    "reasoning": "이 전략을 선택한 이유 1-2문장"
-}}
-
-JSON 외에 다른 텍스트는 포함하지 마세요."""
-
-    try:
-        import json
-        
-        messages_to_llm = [HumanMessage(content=refinement_prompt)]
-        response = llm.invoke(messages_to_llm)
-        
-        response_text = response.content.strip()
-        if "```json" in response_text:
-            response_text = response_text.split("```json")[1].split("```")[0].strip()
-        elif "```" in response_text:
-            response_text = response_text.split("```")[1].split("```")[0].strip()
-        
-        refinement_data = json.loads(response_text)
-        
-        new_query = refinement_data.get("new_query", user_question)
-        strategy = refinement_data.get("strategy", "MORE_GENERAL")
-        reasoning = refinement_data.get("reasoning", "")
-        
-        steps_delta = [
-            f"🔄 쿼리 개선: {strategy}",
-            f"   이전: {user_question[:50]}...",
-            f"   이후: {new_query[:50]}...",
-            f"   이유: {reasoning}"
-        ]
-        
-        logger.info("쿼리 개선 완료: %s → %s", user_question[:30], new_query[:30])
-        
-        # 🔧 CRITICAL: WorkerState 필드만 반환 (부모 AgentState와 충돌 방지)
-        return {
-            "refined_question": new_query,      # ✅ WorkerState 필드
-            "original_question": original_question,  # ✅ WorkerState 필드
-            "refinement_count": state.refinement_count + 1,  # ✅ WorkerState 필드
-            "search_results": [],  # ✅ WorkerState 필드 (reducer 있음)
-            "intermediate_steps": steps_delta  # ✅ WorkerState 필드
-            
-            # ❌ 절대 반환하면 안 되는 것들:
-            # "user_question": ...,   # 부모 AgentState와 충돌!
-            # "messages": ...,        # 부모 AgentState와 충돌!
-            # "final_answer": ...,    # 너무 이른 시점!
-        }
-        
-    except Exception as e:
-        logger.error("쿼리 개선 실패: %s", e, exc_info=True)
-        
-        fallback_query = user_question + " tutorial example"
-        
-        steps_delta = [
-            f"⚠️ 쿼리 개선 실패, 기본 전략 사용",
-            f"   이후: {fallback_query}"
-        ]
-        
-        # 🔧 CRITICAL: WorkerState 필드만 반환
-        return {
-            "refined_question": fallback_query,  # ✅ WorkerState 필드
-            "original_question": original_question,  # ✅ WorkerState 필드
-            "refinement_count": state.refinement_count + 1,  # ✅ WorkerState 필드
-            "search_results": [],  # ✅ WorkerState 필드 (reducer 있음)
-            "intermediate_steps": steps_delta  # ✅ WorkerState 필드
-        }
-
-
-@trace_node("filter_and_score")
-def filter_and_score_node(state: Union[AgentState, WorkerState]) -> dict:
-    """검색 결과를 필터링하고 관련도 점수를 매깁니다."""
-    search_results = state.search_results
-    logger.info("검색 결과 필터링 중: %d개", len(search_results))
-    
-    # 기본 필터링
-    filtered = [
-        r for r in search_results
-        if r.content and len(r.content) >= 50 and r.url
-    ]
-    
-    logger.info("기본 필터링 후: %d개 결과", len(filtered))
-    
-    # 상위 5개 결과만 LLM으로 점수 매기기
-    # 🔧 [FIX] scoring_prompt 내부에서 질문 참조 시 수정
-    current_q = state.processing_question if isinstance(state, WorkerState) else state.user_question
-    
-    for result in filtered[:5]:
-        if result.relevance_score is None:
-            try:
-                scoring_prompt = f"""질문: {current_q}
-
-검색 결과: {result.content[:500]}
-
-이 검색 결과가 질문에 얼마나 관련이 있는지 0.0에서 1.0 사이의 점수로 평가하세요.
-점수만 숫자로 답하세요. (예: 0.8)"""
-
-                response = llm.invoke([HumanMessage(content=scoring_prompt)])
-                score_str = response.content.strip()
-                result.relevance_score = float(score_str)
-                
-            except Exception as e:
-                logger.warning("점수 매기기 실패: %s", e)
-                result.relevance_score = 0.5
-    
-    # 관련도 순으로 정렬
-    filtered.sort(key=lambda r: r.relevance_score or 0, reverse=True)
-    
-    # 상위 5개만 유지
-    top_results = filtered[:5]
-    
-    subtask_results = dict(state.subtask_results)
-    subtask_results["filtered_results"] = [r.model_dump() for r in top_results]
-    
-    steps_delta = [f"✂️ 필터링 완료: {len(top_results)}개 결과 선택"]
-    
-    logger.info("필터링 완료: %d개 결과", len(top_results))
-    
-    return {
-        "subtask_results": subtask_results,
-        "intermediate_steps": steps_delta
-    }
-
-
-@trace_node("summarize_results")
-def summarize_results_node(state: Union[AgentState, WorkerState]) -> dict:
-    """필터링된 각 검색 결과를 초보 개발자가 이해하기 쉽게 요약합니다."""
-    subtask_results = state.subtask_results
-    filtered_results = subtask_results.get("filtered_results", [])
-    logger.info("검색 결과 요약 중: %d개", len(filtered_results))
-    
-    summaries = []
-    
-    for result_dict in filtered_results:
-        try:
-            summary_prompt = f"""다음 검색 결과를 초보 개발자가 이해하기 쉽게 2-3문장으로 요약하세요:
-
-출처: {result_dict['source']}
-내용: {result_dict['content'][:1000]}
-
-핵심 내용만 간단명료하게 요약하세요."""
-
-            response = llm.invoke([HumanMessage(content=summary_prompt)])
-            
-            summaries.append({
-                "source": result_dict['source'],
-                "url": result_dict['url'],
-                "summary": response.content.strip(),
-                "relevance": result_dict.get('relevance_score', 0.5)
-            })
-            
-        except Exception as e:
-            logger.error("요약 실패: %s", e)
-    
-    updated_subtask_results = dict(subtask_results)
-    updated_subtask_results["summaries"] = summaries
-    
-    steps_delta = [f"📝 요약 완료: {len(summaries)}개 결과"]
-    
-    logger.info("요약 완료: %d개", len(summaries))
-    
-    return {
-        "subtask_results": updated_subtask_results,
-        "intermediate_steps": steps_delta
-    }
-
-
-@trace_node("generate_answer")
-async def generate_answer_node(state: Union[AgentState, WorkerState]) -> dict:
-    """
-    요약된 정보를 바탕으로 최종 답변을 생성합니다.
-    
-    수정 사항:
-    1. 다중 질문 모드에서도 캐시 저장 로직이 실행되도록 순서 변경
-    2. 단일 질문 모드에서 AIMessage 반환 (히스토리 저장)
-    """
-    subtask_results = state.subtask_results
-    summaries = subtask_results.get("summaries", [])
-    intent = state.detected_intent or "learning"
-    
-    # 변수 접근
-    current_q = state.processing_question if isinstance(state, WorkerState) else state.user_question
-    
-    logger.info("최종 답변 생성 중: %s (질문: %s)", intent, current_q[:30])
-    
-    # 1. 의도별 프롬프트 템플릿
-    templates = {
-        "debugging": """다음 정보를 바탕으로 디버깅 질문에 답변하세요:
-
-질문: {question}
-
-수집된 정보:
-{summaries}
-
-답변 구조:
-1. 문제 정의
-2. 발생 원인
-3. 해결 방법 (코드 예제 포함)
-4. 주의사항
-5. 참고 자료
-
-초보 개발자도 이해할 수 있게 Markdown 형식으로 작성하세요.""",
-        
-        "learning": """다음 정보를 바탕으로 학습 질문에 답변하세요:
-
-질문: {question}
-
-수집된 정보:
-{summaries}
-
-답변 구조:
-1. 개념 설명 (간단명료)
-2. 동작 원리
-3. 예제 코드 (주석포함)
-4. 실무 활용 팁
-5. 추가 학습 자료
-
-초보 개발자도 이해할 수 있게 Markdown 형식으로 작성하세요.""",
-        
-        "code_review": """다음 정보를 바탕으로 코드 리뷰 질문에 답변하세요:
-
-질문: {question}
-
-수집된 정보:
-{summaries}
-
-답변 구조:
-1. 현재 접근 방식 분석
-2. 개선 포인트
-3. 리팩토링 예제
-4. 베스트 프랙티스
-5. 참고 패턴
-
-초보 개발자도 이해할 수 있게 Markdown 형식으로 작성하세요."""
-    }
-    
-    template = templates.get(intent, templates["learning"])
-    
-    # 2. 요약 텍스트 포맷팅
-    summaries_text = "\n\n".join([
-        f"출처: {s['source']} ({s['url']})\n요약: {s['summary']}"
-        for s in summaries
-    ])
-    
-    # 3. 이전 대화 맥락 추가 (Context Pollution 방지: 최근 1개만 참고용으로)
-    context_prefix = ""
-    messages_history = state.messages
-    if messages_history and len(messages_history) > 1:
-        # 검색 기반 답변이므로 이전 대화는 아주 최소한만 참조 (직전 1개)
-        prev_msg = messages_history[-2] if len(messages_history) >= 2 else None
-        if prev_msg:
-             context_prefix = f"이전 대화 맥락(참고): {prev_msg.content[:200]}...\n---\n"
-    
-    final_prompt = (context_prefix + template).format(
-        question=(state.original_question or current_q),
-        summaries=summaries_text
-    )
-    
-    updates = {}
-    steps_delta: List[str] = []
-    
-    try:
-        # 4. LLM 호출
-        response = llm.invoke([HumanMessage(content=final_prompt)])
-        final_answer = response.content.strip()
-        
-        # 5. 캐시 저장 로직 (DRY - 중복 방지 함수)
-        should_cache = state.should_cache if state.should_cache is not None else True
-        canonical_question = state.canonical_question
-        qtype = state.question_type or "independent"
-        question_to_cache = canonical_question or current_q
-
-        async def _try_cache_save():
-            """조건 충족 시 Qdrant에 캐시 저장"""
-            if should_cache and qtype in ["new_topic", "independent"]:
-                try:
-                    await qdrant_manager.save_to_cache(
-                        question=question_to_cache,
-                        answer=final_answer
-                    )
-                    logger.info("✅ 캐시 저장 완료: %s", question_to_cache[:30])
-                    return True
-                except Exception as cache_err:
-                    logger.error("캐시 저장 실패: %s", cache_err)
-                    return False
-            return False
-
-        # 6. 결과 반환 및 분기 처리
-        is_multi = isinstance(state, WorkerState) and state.worker_is_multi
-
-        if is_multi:
-            # [핵심] 다중 질문 모드: Return하기 '전에' 캐시 저장 시도
-            await _try_cache_save()
-            
-            logger.info("다중 질문 모드: 답변을 multi_answers에 추가")
-            return {
-                "multi_answers": [{
-                    "index": state.worker_idx,
-                    "question": state.worker_sub_text or current_q,
-                    "answer": final_answer
-                }]
-            }
-        
-        else:
-            # 단일 질문 모드
-            updates["final_answer"] = final_answer
-            # [핵심] 대화 히스토리에 AI 답변 추가
-            updates["messages"] = [AIMessage(content=final_answer)]
-            
-            # 캐시 저장 시도
-            saved = await _try_cache_save()
-            
-            if saved:
-                steps_delta.append(f"✅ 최종 답변 생성 완료 (길이: {len(final_answer)}자)")
-                steps_delta.append(f"💾 캐시 저장 완료 (질문: {question_to_cache[:50]}...)")
-            else:
-                steps_delta.append(f"✅ 최종 답변 생성 완료 (길이: {len(final_answer)}자)")
-                steps_delta.append("⚠️ 캐시 저장 생략 (독립적이지 않거나 일회성 질문)")
-                logger.info("최종 답변 생성 완료 (캐시 저장 생략)")
-            
-            updates["intermediate_steps"] = steps_delta
-            return updates
-        
-    except Exception as e:
-        logger.error("답변 생성 실패: %s", e, exc_info=True)
-        
-        is_multi = isinstance(state, WorkerState) and state.worker_is_multi
-        if is_multi:
-            return {
-                "multi_answers": [{
-                    "index": state.worker_idx,
-                    "question": state.worker_sub_text or current_q,
-                    "answer": "답변 생성에 실패했습니다. 다시 시도해 주세요."
-                }]
-            }
-        else:
-            updates["final_answer"] = "답변 생성에 실패했습니다. 다시 시도해 주세요."
-            steps_delta.append(f"❌ 답변 생성 실패: {str(e)}")
-            updates["intermediate_steps"] = steps_delta
-            return updates

hf-space2/CodeWeaver/src/agent/state.py

@@ -1,141 +0,0 @@
-from typing import Any, Dict, List, Optional, Literal, Tuple, Annotated
-from operator import add
-
-from pydantic import BaseModel, Field
-from langchain_core.messages import BaseMessage
-from langgraph.graph import add_messages
-
-
-_STEPS_RESET_TOKEN = "__RESET_STEPS__"
-_MULTI_ANS_RESET_TOKEN = "__RESET_MULTI_ANS__"
-
-
-def merge_intermediate_steps(old: List[str], new: List[str]) -> List[str]:
-    """intermediate_steps reducer."""
-    if not new:
-        return old
-    if new[0] == _STEPS_RESET_TOKEN:
-        return new[1:]
-    return old + new
-
-
-def merge_multi_answers(old: List[Dict[str, Any]], new: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
-    """multi_answers reducer."""
-    if not new:
-        return old
-    head = new[0]
-    if isinstance(head, dict) and head.get("__token__") == _MULTI_ANS_RESET_TOKEN:
-        return new[1:]
-    return old + new
-
-
-def merge_search_results(old: List["SearchResult"], new: List["SearchResult"]) -> List["SearchResult"]:
-    """
-    search_results reducer.
-    병렬 검색 노드들이 동시에 search_results를 업데이트할 수 있도록 병합 로직 제공.
-    """
-    return old + new
-
-
-class SearchResult(BaseModel):
-    """검색 도메인에서 공통으로 사용하는 단일 검색 결과 모델."""
-    source: str = Field(..., description="검색 출처")
-    content: str = Field(..., description="검색 결과의 핵심 내용")
-    url: Optional[str] = Field(default=None, description="원본 출처 URL")
-    relevance_score: Optional[float] = Field(default=None, description="관련도 점수")
-
-
-class AgentState(BaseModel):
-    """부모 그래프 전용 상태."""
-    
-    # Core fields
-    user_question: str = Field(default="", description="사용자의 원본 질문")
-    messages: Annotated[List[BaseMessage], add_messages] = Field(
-        default_factory=list,
-        description="대화 메시지 히스토리"
-    )
-    
-    # Final output
-    final_answer: Optional[str] = Field(default=None, description="최종 생성된 답변")
-    
-    # Debugging/tracing
-    intermediate_steps: Annotated[List[str], merge_intermediate_steps] = Field(
-        default_factory=list,
-        description="실행 단계별 로그"
-    )
-    
-    # Planning
-    plan: Optional[Dict[str, Any]] = Field(
-        default=None,
-        description="질문 분해 계획"
-    )
-    
-    # Multi-question handling
-    is_multi_question: bool = Field(default=False)
-    sub_question_index: int = Field(default=0)
-    sub_question_text: Optional[str] = Field(default=None)
-    original_multi_question: Optional[str] = Field(default=None)
-    multi_answers: Annotated[List[Dict[str, Any]], merge_multi_answers] = Field(
-        default_factory=list,
-        description="다중 질문의 각 답변 리스트"
-    )
-    
-    class Config:
-        arbitrary_types_allowed = True
-
-
-class WorkerState(BaseModel):
-    """
-    서브그래프 전용 상태.
-    부모 AgentState와 키 이름이 겹치지 않도록 주의해야 합니다.
-    """
-    
-    # === 입력 (부모로부터 받음) ===
-    processing_question: str = Field(default="", description="현재 처리 중인 질문")
-    messages: List[BaseMessage] = Field(default_factory=list, description="대화 히스토리")
-    
-    # 🔧 [FIX] 부모 상태와 충돌 방지를 위해 이름 변경 (worker_ 접두사)
-    worker_is_multi: bool = Field(default=False)
-    worker_idx: int = Field(default=0)
-    worker_sub_text: Optional[str] = Field(default=None)
-    
-    # === 서브그래프 내부 전용 필드 ===
-    # (이 필드들은 서브그래프 내부에서만 사용, 부모에게 전달 안 됨)
-    question_type: Optional[Literal["clarification", "new_topic", "independent"]] = None
-    should_cache: Optional[bool] = None
-    canonical_question: Optional[str] = None
-    analysis_reasoning: Optional[str] = None
-    cached_result: Optional[str] = None
-    detected_intent: Optional[Literal["debugging", "learning", "code_review"]] = None
-    
-    # 검색 결과 (병렬 업데이트 가능하도록 reducer 적용)
-    search_results: Annotated[List[SearchResult], merge_search_results] = Field(
-        default_factory=list,
-        description="병렬 검색 결과 (reducer로 자동 병합)"
-    )
-    
-    subtask_results: Dict[str, Any] = Field(default_factory=dict)
-    
-    # 쿼리 개선 (이 필드들은 refine_search_node만 업데이트)
-    needs_refinement: bool = False
-    refinement_count: int = 0
-    original_question: Optional[str] = None
-    refined_question: Optional[str] = None  # 🔧 개선된 쿼리를 별도 필드로 관리
-    
-    # 🔧 서브그래프 내부 로그 (부모에게 전달 안 됨!)
-    intermediate_steps: List[str] = Field(
-        default_factory=list,
-        description="서브그래프 내부 로그 (부모에 전달하지 않음)"
-    )
-    
-    # === 출력 (부모에게 전달될 필드) ===
-    # 이 필드들은 부모 AgentState에도 존재하며, Reducer��� 있거나 충돌이 허용되는 필드여야 함
-    final_answer: Optional[str] = None
-    
-    multi_answers: Annotated[List[Dict[str, Any]], merge_multi_answers] = Field(
-        default_factory=list,
-        description="다중 질문 답변용"
-    )
-    
-    class Config:
-        arbitrary_types_allowed = True

hf-space2/CodeWeaver/src/tools/__init__.py

@@ -1,12 +0,0 @@
-from .search_tools import (
-    search_github,
-    search_official_docs,
-    search_stackoverflow,
-)
-
-__all__ = [
-    "search_stackoverflow",
-    "search_github",
-    "search_official_docs",
-]
-

hf-space2/CodeWeaver/src/tools/search_tools.py

@@ -1,217 +0,0 @@
-import logging
-import os
-import time
-from typing import List
-
-import requests
-from tavily import TavilyClient  # type: ignore[import]
-
-from src.agent.state import SearchResult
-
-
-logger = logging.getLogger(__name__)
-
-
-def search_stackoverflow(query: str, limit: int = 3) -> List[SearchResult]:
-    """Stack Overflow에서 관련 질문을 검색한다.
-    
-    Args:
-        query: 검색 쿼리
-        limit: 반환할 최대 결과 수
-        
-    Returns:
-        SearchResult 리스트 (실패 시 빈 리스트)
-    """
-    if not query.strip():
-        logger.warning("Stack Overflow 검색: 빈 쿼리")
-        return []
-    
-    try:
-        url = "https://api.stackexchange.com/2.3/search/advanced"
-        params = {
-            "q": query,
-            "order": "desc",
-            "sort": "votes",
-            "site": "stackoverflow",
-            "pagesize": limit,
-            "filter": "withbody",
-        }
-        
-        response = requests.get(url, params=params, timeout=10)
-        response.raise_for_status()
-        
-        data = response.json()
-        items = data.get("items", [])
-        
-        results = []
-        max_score = max((item.get("score", 0) for item in items), default=1)
-        
-        for item in items:
-            title = item.get("title", "")
-            body = item.get("body", "")[:500]  # 본문 일부만 포함
-            content = f"{title}\n\n{body}"
-            
-            score = item.get("score", 0)
-            # 정규화: 0-1 범위로 변환
-            relevance = min(score / max(max_score, 1), 1.0) if max_score > 0 else 0.5
-            
-            results.append(
-                SearchResult(
-                    source="Stack Overflow",
-                    content=content,
-                    url=item.get("link"),
-                    relevance_score=relevance,
-                )
-            )
-        
-        logger.info("Stack Overflow 검색 성공: %d개 결과", len(results))
-        
-        # Rate limit 준수
-        time.sleep(1)
-        
-        return results
-        
-    except Exception as e:
-        logger.error("Stack Overflow 검색 실패: %s", e, exc_info=True)
-        return []
-
-
-def search_github(query: str, limit: int = 3) -> List[SearchResult]:
-    """GitHub에서 관련 코드를 검색한다.
-    
-    Args:
-        query: 검색 쿼리
-        limit: 반환할 최대 결과 수
-        
-    Returns:
-        SearchResult 리스트 (실패 시 빈 리스트)
-    """
-    if not query.strip():
-        logger.warning("GitHub 검색: 빈 쿼리")
-        return []
-    
-    try:
-        url = "https://api.github.com/search/code"
-        
-        # Python 코드로 제한 (언어 감지 로직은 추후 확장 가능)
-        search_query = f"{query} language:python"
-        
-        params = {
-            "q": search_query,
-            "sort": "indexed",
-            "per_page": limit,
-        }
-        
-        headers = {
-            "Accept": "application/vnd.github.v3+json",
-        }
-        
-        # GitHub 토큰이 있으면 Authorization 헤더 추가
-        github_token = os.getenv("GITHUB_TOKEN", "").strip()
-        if github_token:
-            headers["Authorization"] = f"token {github_token}"
-            logger.debug("GitHub 토큰 사용 (인증된 요청)")
-        else:
-            logger.warning(
-                "GITHUB_TOKEN이 설정되지 않음 - rate limit 제한적 (60 req/hr). "
-                "토큰 설정 시 5,000 req/hr로 증가"
-            )
-        
-        response = requests.get(url, params=params, headers=headers, timeout=10)
-        response.raise_for_status()
-        
-        data = response.json()
-        items = data.get("items", [])
-        
-        results = []
-        for item in items:
-            repo_name = item.get("repository", {}).get("full_name", "unknown")
-            path = item.get("path", "")
-            content = f"Repository: {repo_name}\nFile: {path}"
-            
-            results.append(
-                SearchResult(
-                    source="GitHub",
-                    content=content,
-                    url=item.get("html_url"),
-                    relevance_score=0.8,  # GitHub 결과는 일반적으로 높은 관련도
-                )
-            )
-        
-        logger.info("GitHub 검색 성공: %d개 결과", len(results))
-        
-        # Rate limit 준수
-        time.sleep(1)
-        
-        return results
-        
-    except requests.exceptions.HTTPError as e:
-        if e.response.status_code == 403:
-            logger.warning("GitHub API rate limit 초과")
-        elif e.response.status_code == 401:
-            logger.warning("GitHub API 인증 실패 (토큰이 없거나 잘못됨). 토큰 없이 계속 진행합니다.")
-        else:
-            logger.error("GitHub 검색 HTTP 에러: %s", e, exc_info=True)
-        return []
-    except Exception as e:
-        logger.error("GitHub 검색 실패: %s", e, exc_info=True)
-        return []
-
-
-def search_official_docs(query: str, limit: int = 3) -> List[SearchResult]:
-    """Tavily API를 사용해 공식 문서를 검색한다.
-    
-    Args:
-        query: 검색 쿼리
-        limit: 반환할 최대 결과 수
-        
-    Returns:
-        SearchResult 리스트 (실패 시 빈 리스트)
-    """
-    if not query.strip():
-        logger.warning("Official Docs 검색: 빈 쿼리")
-        return []
-    
-    api_key = os.getenv("TAVILY_API_KEY", "").strip()
-    if not api_key:
-        logger.error("TAVILY_API_KEY 환경 변수가 설정되어 있지 않습니다.")
-        return []
-    
-    try:
-        client = TavilyClient(api_key=api_key)
-        
-        response = client.search(
-            query=query,
-            search_depth="basic",
-            max_results=limit,
-            include_domains=[
-                "docs.python.org",
-                "docs.oracle.com",
-                "spring.io/guides",
-                "developer.mozilla.org",
-                "reactjs.org/docs",
-            ],
-        )
-        
-        results = []
-        for item in response.get("results", []):
-            content = item.get("content", "")
-            url = item.get("url", "")
-            score = item.get("score", 0.5)  # Tavily가 제공하는 관련도 점수
-            
-            results.append(
-                SearchResult(
-                    source="Official Docs",
-                    content=content,
-                    url=url,
-                    relevance_score=score,
-                )
-            )
-        
-        logger.info("Tavily 검색 성공: %d개 결과", len(results))
-        return results
-        
-    except Exception as e:
-        logger.error("Tavily 검색 실패: %s", e, exc_info=True)
-        return []
-

hf-space2/CodeWeaver/src/utils/__init__.py

@@ -1,7 +0,0 @@
-"""유틸리티 모듈."""
-
-from .tracing import ensure_tracing_enabled, trace_node
-
-__all__ = ["ensure_tracing_enabled", "trace_node"]
-
-