Add CodeWeaver Gradio app

ARCHITECTURE.md

@@ -0,0 +1,230 @@
+# CodeWeaver 아키텍처 (실제 코드 기준)
+
+이 문서는 현재 저장소의 CodeWeaver가 **어떤 순서로 동작하는지**, 그리고 그 원리가 무엇인지(상태/라우팅/병렬화/캐시)를 **코드와 1:1로 정합**되게 설명합니다.
+
+## 전체 구성 요소
+
+- **UI**: Gradio 채팅 UI (`CodeWeaver/ui/app.py`)
+  - 사용자 입력을 `AgentState`로 포장한 뒤 `agent.ainvoke(..., config={"configurable": {"thread_id": ...}})`로 실행합니다.
+- **오케스트레이션(그래프)**: LangGraph `StateGraph` (`CodeWeaver/src/agent/graph.py`)
+  - `START → create_plan`로 진입 후, 질문 유형/개수에 따라 분기합니다.
+  - 체크포인팅: `MemorySaver` 사용(스레드/세션 단위 상태 유지).
+- **노드 구현**: (`CodeWeaver/src/agent/nodes.py`)
+  - 질문 분석, 캐시 조회, 의도 분류, 3소스 병렬 검색, 결과 평가/리파인, 필터링/요약, 답변 생성, 다중 질문 결합 등을 담당합니다.
+- **상태 모델(Reducer 포함)**: (`CodeWeaver/src/agent/state.py`)
+  - `search_results`는 `Annotated[List[SearchResult], add]`로 **병렬 검색 결과가 자동 병합**됩니다.
+  - `intermediate_steps`, `multi_answers`는 **리셋 토큰을 지원하는 커스텀 reducer**로, 체크포인팅/스레드 유지 시 이전 턴의 누적을 방지합니다.
+- **캐시(Vector DB)**: Qdrant Cloud (`CodeWeaver/src/vector_db/qdrant_client.py`)
+  - 임베딩은 로컬 `BAAI/bge-m3`(`sentence-transformers`)로 생성, Qdrant에 저장/검색합니다.
+- **검색 소스**: (`CodeWeaver/src/tools/search_tools.py`)
+  - Stack Overflow(공식 StackExchange API), GitHub Code Search API, Tavily(공식문서 도메인 제한) 사용.
+
+## 사용자 제공 그래프와의 정합성
+
+사용자께서 제공한 Mermaid 그래프는 이 프로젝트의 의도와 **대부분 일치**합니다.
+
+### 일치하는 부분(핵심 파이프라인)
+
+- `create_plan`에서 **single_topic / multiple_questions(2개) / too_many(3+)** 분기
+- 단일 질문(혹은 단일 주제)에서:
+  - `analyze_question → check_cache → (hit면 return_cached_answer) / (miss면 classify_intent)`
+  - `classify_intent` 이후 3소스 검색을 Send API로 병렬 실행(fan-out)하고 `collect_results`에서 fan-in
+  - `evaluate_results → (필요 시 refine_search 1회) → filter_and_score → summarize_results → generate_answer`
+- `evaluate_results`가 부족하면 `refine_search → classify_intent`로 **최대 1회 루프**
+
+### 실제 코드에서 추가/변형된 부분(중요)
+
+1) **clarification(보충 요청) 전용 경로가 존재**
+
+- `analyze_question` 결과가 `clarification`이면
+  - **캐시/검색을 수행하지 않고**
+  - `generate_with_history`로 바로 답변하고 종료합니다.
+
+2) **multiple_questions fan-out은 `analyze_question`로 직접 들어가지 않음**
+
+사용자 그래프는 “dynamic에서 Send로 analyze_question을 2번 호출” 형태에 가깝지만, 실제 구현은 다릅니다.
+
+- 실제 구현은 `fanout_multi_questions`가 `Send("run_single_question_worker", child_state)`를 생성합니다.
+- 이유: outer graph에서 질문 2개를 동시에 동일 파이프라인(analyze/cache/intent/…)으로 돌리면
+  - `question_type`, `cached_result` 같은 **scalar 채널(state 필드)**이 병렬 업데이트 충돌을 일으킬 수 있습니다.
+- 따라서 **worker 내부에서 별도의 ‘단일 질문 그래프’를 실행**하고,
+  - outer graph에는 reducer 채널인 `multi_answers`만 업데이트하여 충돌을 제거합니다.
+
+## 실제 실행 흐름(코드 기준)
+
+### 1) UI → Agent 실행(엔트리)
+
+`CodeWeaver/ui/app.py`에서:
+
+- 입력 문자열 `message`를 `AgentState(user_question=..., messages=[HumanMessage(...)], ...)`로 만들고
+- `thread_id`를 `config={"configurable":{"thread_id": thread_id}}`로 전달하여 `agent.ainvoke()` 실행
+  - `MemorySaver`가 `thread_id` 단위로 상태를 보존합니다.
+
+### 2) 메인 그래프(Top-level) 흐름
+
+`CodeWeaver/src/agent/graph.py` 기준 메인 흐름은 아래와 같습니다.
+
+```mermaid
+graph TD
+    startNode[START] --> createPlan[create_plan]
+
+    createPlan -->|single_topic| analyzeQuestion[analyze_question]
+    createPlan -->|multiple_questions_2| initiateDynamic[initiate_dynamic_search]
+    createPlan -->|too_many_3plus| tooMany[handle_too_many_questions]
+
+    tooMany --> endNode[END]
+
+    analyzeQuestion -->|clarification| withHistory[generate_with_history]
+    withHistory --> endNode
+
+    analyzeQuestion -->|new_topic_or_independent| checkCache[check_cache]
+    checkCache -->|hit| returnCached[return_cached_answer]
+    returnCached --> endNode
+
+    checkCache -->|miss| classifyIntent[classify_intent]
+
+    classifyIntent --> searchSO[search_stackoverflow]
+    classifyIntent --> searchGH[search_github]
+    classifyIntent --> searchDocs[search_official_docs]
+
+    searchSO --> collect[collect_results]
+    searchGH --> collect
+    searchDocs --> collect
+
+    collect --> evalNode[evaluate_results]
+    evalNode -->|needs_refinement_and_lt1| refine[refine_search]
+    refine --> classifyIntent
+
+    evalNode -->|sufficient_or_ge1| searchSubgraph[search_subgraph]
+    searchSubgraph --> generateAnswer[generate_answer]
+    generateAnswer --> routeAfterGen[route_after_generate]
+    routeAfterGen -->|single| endNode
+    routeAfterGen -->|multi| combine[combine_answers]
+    combine --> endNode
+
+    initiateDynamic --> fanout[fanout_multi_questions]
+    fanout --> worker[run_single_question_worker]
+    worker --> combine
+```
+
+### 3) `create_plan`: 질문 개수/형태 판별 + “3개 이상” 하드 가드
+
+`create_plan_node`는 입력을 아래 3가지로 분류합니다.
+
+- **single_topic**: 하나의 주제를 다양한 관점으로 묻는 형태
+- **multiple_questions**: 독립 질문 2개
+- **too_many**: 독립 질문 3개 이상
+
+추가로, LLM 분류와 무관하게 다음 조건이면 **결정론적으로 too_many**로 강제합니다.
+
+- 물음표가 3개 이상
+- 또는 “질문 후보”가 3개 이상(줄바꿈/번호/구분자 등으로 추정)
+
+또한 체크포인팅 상태 누적을 막기 위해, 매 실행 시작 시 `multi_answers`를 리셋 토큰으로 초기화합니다.
+
+### 4) `analyze_question`: 질문 타입(clarification/new_topic/independent) + 캐시 적격성 판단
+
+`analyze_question_node`가 LLM으로 아래 값을 생성합니다.
+
+- `question_type`: `clarification | new_topic | independent`
+- `should_cache`: 캐시 저장 여부
+- `canonical_question`: 캐시용 정규화 질문(should_cache=true일 때)
+
+라우팅은 `graph.py`의 `route_after_analysis`에서:
+
+- `clarification` → `generate_with_history` (검색/캐시 생략)
+- 나머지 → `check_cache`
+
+### 5) 캐시(`check_cache` / `return_cached_answer`)
+
+`check_cache_node`는 Qdrant에서 유사 질문을 검색합니다.
+
+- 임베딩: 로컬 `BAAI/bge-m3` (1024차원)
+- 임계값: cosine score **0.85 이상**이면 hit로 간주
+
+hit면 `return_cached_answer_node`가 저장된 답변을 즉시 반환합니다.
+
+### 6) 의도 분류(`classify_intent`)
+
+`classify_intent_node`가 질문을 `debugging | learning | code_review`로 분류합니다.
+
+이 값은 검색 개수 등 일부 정책에 반영됩니다(예: StackOverflow는 debugging이면 더 많이 가져옴).
+
+### 7) 병렬 검색(fan-out) → 수집(fan-in)
+
+`classify_intent` 이후 conditional edge 함수가 `Send(...)` 3개를 반환하여 병렬로 실행됩니다.
+
+- `search_stackoverflow_node`
+- `search_github_node`
+- `search_official_docs_node`
+
+각 노드는 `{"search_results": [..]}`를 반환하고, `AgentState.search_results`의 reducer(`add`)가 이를 자동 병합합니다.
+
+`collect_results_node`는 병합된 총 결과 개수만 집계합니다.
+
+### 8) 결과 평가(`evaluate_results`)와 쿼리 리파인(`refine_search`)
+
+`evaluate_results_node`는 다음 기준으로 “개선 필요”를 판단합니다.
+
+- 결과 개수 < 2 → 개선 필요
+- (relevance_score가 있다면) 평균 점수 < 0.5 → 개선 필요
+
+`refine_search_node`는 LLM이 `MORE_SPECIFIC | MORE_GENERAL | TRANSLATE` 전략을 선택해 쿼리를 개선합니다.
+
+- 무한 루프 방지: `refinement_count < 1`일 때만 1회 허용
+- 재검색을 위해 `search_results`를 빈 리스트로 초기화하고 `classify_intent`로 되돌아갑니다.
+
+### 9) `search_subgraph`: 필터링 + 요약
+
+메인 그래프에는 `search_subgraph`가 “하나의 노드”처럼 붙어 있습니다.
+
+- `filter_and_score`: 최소 길이/URL 조건으로 필터 후, 상위 일부에 대해 관련도 점수 부여
+- `summarize_results`: 각 결과를 2~3문장으로 요약
+
+### 10) `generate_answer`: 답변 생성 + (조건부) 캐시 저장
+
+`generate_answer_node`는 의도에 따라 템플릿을 바꿔 최종 답변을 생성합니다.
+
+캐시 저장 정책:
+
+- `question_type`가 `new_topic` 또는 `independent`이고 `should_cache`가 true이면 저장
+- `clarification`은 저장하지 않음(라우팅상 보통 여기로 오지 않지만 방어적으로 체크)
+
+### 11) 다중 질문(multiple_questions) 처리 원리
+
+다중 질문의 핵심은 “outer graph는 충돌 없이 orchestration만, 실제 파이프라인은 worker 내부에서 실행”입니다.
+
+#### 흐름
+
+- `create_plan(case=multiple_questions)` → `initiate_dynamic_search` (준비)
+- `fanout_multi_questions`(conditional edge)이 질문 2개를 각각 `run_single_question_worker`로 Send
+- `run_single_question_worker_node` 내부에서 **단일 질문용 그래프를 별도 compile/실행**
+- worker 결과는 `multi_answers`에 append(reducer로 병합)
+- 모든 worker가 끝나면 `combine_answers_node`가 Markdown으로 결합
+
+#### 왜 worker가 필요한가?
+
+outer graph에서 동일한 state를 복제해 `analyze_question`부터 동시에 돌리면,
+scalar 채널(`question_type`, `cached_result` 등)이 서로 덮어쓰일 수 있습니다.
+
+그래서 실제 구현은:
+
+- worker 내부에서 단일 질문 그래프를 돌리고
+- outer state에는 **reducer 채널인 `multi_answers`만** 업데이트
+
+이 방식으로 병렬 실행 안정성을 확보합니다.
+
+## 환경 변수(실행에 필요한 실제 값)
+
+필수:
+
+- `GOOGLE_API_KEY`: Gemini 호출(`langchain-google-genai`)
+- `QDRANT_URL`, `QDRANT_API_KEY`: Qdrant Cloud 캐시
+- `TAVILY_API_KEY`: 공식 문서 검색(Tavily)
+
+선택:
+
+- `GITHUB_TOKEN`: GitHub API rate limit 완화(없으면 60 req/hr 수준)
+- `LANGCHAIN_TRACING_V2`, `LANGCHAIN_API_KEY`: LangSmith 트레이싱(선택)
+
+

CodeWeaver/.env.example

@@ -0,0 +1,9 @@
+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=

CodeWeaver/.gitignore

@@ -0,0 +1,23 @@
+# 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

CodeWeaver/.python-version

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

CodeWeaver/README.md

@@ -0,0 +1,118 @@
+---
+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`를 참고하세요.

CodeWeaver/main.py

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

CodeWeaver/pyproject.toml

@@ -0,0 +1,27 @@
+[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 옵션으로 실행)",
+]

CodeWeaver/requirements.txt

@@ -0,0 +1,24 @@
+# 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
+

CodeWeaver/src/agent/__init__.py

@@ -0,0 +1,51 @@
+"""
+CodeWeaver 에이전트 모듈.
+
+LangGraph 기반 개발자 질문 답변 에이전트를 제공합니다.
+
+주요 컴포넌트:
+- State: 에이전트 상태 관리
+- Nodes: 개별 처리 노드
+- Graph: LangGraph 워크플로우
+"""
+
+from .state import AgentState, SearchResult
+from .graph import agent, build_agent_graph, create_agent
+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,
+)
+
+__all__ = [
+    # State
+    "AgentState",
+    "SearchResult",
+    
+    # Graph
+    "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

@@ -0,0 +1,422 @@
+"""
+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
+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,
+    initiate_dynamic_search_node,
+    combine_answers_node,
+    fanout_multi_questions,
+    run_single_question_worker_node,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def build_search_subgraph() -> StateGraph:
+    """
+    검색 결과 처리 서브그래프를 구성합니다.
+    
+    흐름: filter_and_score → summarize_results
+    
+    이 서브그래프는 메인 그래프에서 하나의 노드처럼 동작하며,
+    검색 결과의 필터링과 요약을 담당합니다.
+    
+    Returns:
+        컴파일된 서브그래프
+    """
+    # 서브그래프 생성 (AgentState 사용)
+    subgraph = StateGraph(AgentState)
+    
+    # 노드 추가
+    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(state: AgentState) -> Literal["generate_with_history", "check_cache"]:
+    """
+    질문 분석 결과에 따라 다음 노드를 결정합니다.
+    
+    Phase 2: New Routing Structure
+    
+    Args:
+        state: 현재 에이전트 상태
+    
+    Returns:
+        - "generate_with_history": 후속 질문 → 대화 히스토리 기반 답변
+        - "check_cache": 독립 질문 → 캐시 확인
+    """
+    # NOTE: 과거 체크포인트/구버전 상태값 호환을 위해 구값도 매핑 처리
+    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"
+
+    # new_topic / independent 는 모두 캐시 확인(히트면 검색 생략, 미스면 검색)
+    return "check_cache"
+
+
+def route_after_plan(state: AgentState) -> Literal["analyze_question", "initiate_dynamic_search", "handle_too_many_questions"]:
+    """
+    create_plan 결과에 따라 다음 노드를 결정합니다.
+    
+    Phase 4: Dynamic Parallel Search
+    
+    Args:
+        state: 현재 에이전트 상태
+    
+    Returns:
+        - "analyze_question": 단일 주제 → 기존 그래프 실행
+        - "initiate_dynamic_search": 다중 질문 (2개) → Send API로 그래프 2회 실행
+        - "handle_too_many_questions": 질문 3개 이상 → 에러 메시지
+    """
+    plan = state.plan or {}
+    case = plan.get("case", "single_topic")
+    
+    if case == "too_many":
+        return "handle_too_many_questions"
+    elif case == "multiple_questions":
+        return "initiate_dynamic_search"
+    else:
+        return "analyze_question"
+
+
+def route_after_cache(state: AgentState) -> Literal["return_cached_answer", "classify_intent"]:
+    """
+    캐시 히트 여부에 따라 다음 노드를 결정합니다.
+    
+    Phase 3 → Phase 4: create_plan 제거됨 (이미 START에서 실행)
+    
+    Args:
+        state: 현재 에이전트 상태
+    
+    Returns:
+        - "return_cached_answer": 캐시 히트 시 즉시 답변 반환
+        - "classify_intent": 캐시 미스 시 의도 분류
+    """
+    if state.cached_result:
+        return "return_cached_answer"
+    else:
+        return "classify_intent"
+
+
+def route_after_generate(state: AgentState) -> Literal["combine_answers", END]:
+    """
+    generate_answer 후 다음 노드를 결정합니다.
+    
+    Phase 4: Dynamic Parallel Search
+    
+    Args:
+        state: 현재 에이전트 상태
+    
+    Returns:
+        - "combine_answers": 다중 질문 → 답변 통합
+        - END: 단일 질문 → 종료
+    """
+    if state.is_multi_question:
+        return "combine_answers"
+    return END
+
+
+def route_after_evaluation(state: AgentState) -> Literal["refine_search", "search_subgraph"]:
+    """
+    검색 결과 평가 후 다음 노드를 결정합니다.
+    
+    Phase 3: Open Deep Research 패턴 - 쿼리 개선 루프
+    
+    Args:
+        state: 현재 에이전트 상태
+    
+    Returns:
+        - "refine_search": 결과 부족 & 개선 횟수 0회 → 쿼리 개선
+        - "search_subgraph": 결과 충분 or 개선 횟수 1회 → 필터링 진행
+    """
+    needs_refinement = state.needs_refinement
+    refinement_count = state.refinement_count
+    
+    # 안전장치: 최대 1회만 개선
+    if needs_refinement and refinement_count < 1:
+        return "refine_search"
+    else:
+        return "search_subgraph"
+
+
+def initiate_parallel_search(state: AgentState):
+    """
+    Send API를 사용하여 3개의 검색 노드를 병렬로 실행합니다.
+    
+    LangGraph Send API (Map-Reduce 패턴):
+    - 각 검색 노드에 동일한 state를 전송
+    - 모든 노드가 병렬로 실행됨
+    - 결과는 자동으로 머지됨
+    
+    Args:
+        state: 현재 에이전트 상태
+    
+    Returns:
+        Send 객체 리스트 (fan-out)
+    """
+    
+    # Send API를 사용한 fan-out
+    # 3개의 검색 노드가 동시에 실행됨
+    return [
+        Send("search_stackoverflow", state),
+        Send("search_github", state),
+        Send("search_official_docs", state),
+    ]
+
+
+def build_agent_graph() -> StateGraph:
+    """
+    CodeWeaver 에이전트의 메인 그래프를 구성합니다.
+    
+    Phase 4: Dynamic Parallel Search for Multiple Questions
+    
+    전체 흐름:
+    1. START → create_plan (질문 유형 및 개수 판단)
+    2. 질문 유형에 따른 분기:
+       - single_topic: analyze_question → 기존 그래프
+       - multiple_questions: initiate_dynamic_search → Send API (각 질문마다 기존 그래프 독립 실행)
+       - too_many: handle_too_many_questions → END
+    3. analyze_question → 질문 분석
+       - clarification: generate_with_history → END
+       - new_topic/independent: check_cache
+    4. 캐시 확인:
+       - 히트: return_cached_answer → END
+       - 미스: classify_intent
+    5. Send API (병렬 검색 fan-out):
+       - classify_intent → 3개 검색 노드 병렬 실행
+    6. collect_results (fan-in) → evaluate_results
+    7. 검색 결과 평가:
+       - 부족 & refinement_count < 1: refine_search → classify_intent (루프)
+       - 충분 or refinement_count >= 1: search_subgraph
+    8. search_subgraph (filter → summarize)
+    9. search_subgraph → generate_answer
+    10. generate_answer 후 분기:
+        - is_multi_question: combine_answers → END
+        - 단일 질문: END
+    
+    핵심 개선사항 (Phase 4):
+    - ✅ create_plan을 START로 이동 (질문 개수 먼저 감지)
+    - ✅ Send API로 기존 그래프 재사용 (코드 중복 없음)
+    - ✅ 질문 3개 이상 시 친절한 에러 메시지
+    - ✅ Reducer 패턴으로 자동 fan-in
+    
+    Returns:
+        구성된 StateGraph (컴파일 전)
+    """
+    # 메인 그래프 생성
+    graph = StateGraph(AgentState)
+    
+    # Phase 4: 계획 수립 (START 직후)
+    graph.add_node("create_plan", create_plan_node)
+    graph.add_node("handle_too_many_questions", handle_too_many_questions_node)
+    graph.add_node("initiate_dynamic_search", initiate_dynamic_search_node)
+    
+    # Phase 2: 질문 분석 & 대화 히스토리 처리
+    graph.add_node("analyze_question", analyze_question_node)
+    graph.add_node("generate_with_history", generate_with_history_node)
+    
+    # 캐시 관련
+    graph.add_node("check_cache", check_cache_node)
+    graph.add_node("return_cached_answer", return_cached_answer_node)
+    
+    # 의도 분류
+    graph.add_node("classify_intent", classify_intent_node)
+    
+    # Send API를 위한 병렬 검색 노드
+    graph.add_node("search_stackoverflow", search_stackoverflow_node)
+    graph.add_node("search_github", search_github_node)
+    graph.add_node("search_official_docs", search_official_docs_node)
+    
+    # Phase 3: 결과 수집 및 평가
+    graph.add_node("collect_results", collect_results_node)
+    graph.add_node("evaluate_results", evaluate_results_node)
+    graph.add_node("refine_search", refine_search_node)
+    
+    # 최종 답변 생성
+    graph.add_node("generate_answer", generate_answer_node)
+    
+    # Phase 4: 다중 질문 답변 통합
+    graph.add_node("combine_answers", combine_answers_node)
+    graph.add_node("run_single_question_worker", run_single_question_worker_node)
+    
+    # 서브그래프 (필터링 & 요약)
+    search_subgraph = build_search_subgraph()
+    graph.add_node("search_subgraph", search_subgraph)
+    
+    # ===== 엣지 구성 =====
+    
+    # 1. START → create_plan (Phase 4: 진입점 변경)
+    graph.add_edge(START, "create_plan")
+    
+    # 2. create_plan → 분기 (Phase 4: 질문 유형별 분기)
+    graph.add_conditional_edges(
+        "create_plan",
+        route_after_plan,
+        {
+            "analyze_question": "analyze_question",
+            "initiate_dynamic_search": "initiate_dynamic_search",
+            "handle_too_many_questions": "handle_too_many_questions",
+        }
+    )
+    
+    # 3. handle_too_many_questions → END
+    graph.add_edge("handle_too_many_questions", END)
+    
+    # 4. initiate_dynamic_search는 Send 리턴 (각 Send가 analyze_question으로)
+    # 실제 fan-out은 conditional edge 함수에서 수행해야 함
+    graph.add_conditional_edges(
+        "initiate_dynamic_search",
+        fanout_multi_questions,
+    )
+    # multi-question worker들이 끝나면 reducer(multi_answers)에 모인 결과를 합칩니다.
+    # Fan-in: 두 worker가 모두 이 edge로 들어오면 combine_answers는 1회 실행됩니다.
+    graph.add_edge("run_single_question_worker", "combine_answers")
+    
+    # 5. 질문 분석 결과에 따른 분기
+    graph.add_conditional_edges(
+        "analyze_question",
+        route_after_analysis,
+        {
+            "generate_with_history": "generate_with_history",
+            "check_cache": "check_cache",
+        }
+    )
+    
+    # 6. 대화 히스토리 기반 답변 → END
+    graph.add_edge("generate_with_history", END)
+    
+    # 7. 캐시 확인 결과에 따른 분기 (Phase 4: create_plan 제거됨)
+    graph.add_conditional_edges(
+        "check_cache",
+        route_after_cache,
+        {
+            "return_cached_answer": "return_cached_answer",
+            "classify_intent": "classify_intent",
+        }
+    )
+    
+    # 8. 캐시 히트 시 즉시 종료
+    graph.add_edge("return_cached_answer", END)
+    
+    # 9. Send API를 사용한 병렬 검색 (fan-out)
+    graph.add_conditional_edges(
+        "classify_intent",
+        initiate_parallel_search,
+    )
+    
+    # 10. 모든 검색 노드 → collect_results (fan-in)
+    graph.add_edge("search_stackoverflow", "collect_results")
+    graph.add_edge("search_github", "collect_results")
+    graph.add_edge("search_official_docs", "collect_results")
+    
+    # 11. collect_results → evaluate_results
+    graph.add_edge("collect_results", "evaluate_results")
+    
+    # 12. 검색 결과 평가에 따른 분기 (Phase 3: refine_search 추가)
+    graph.add_conditional_edges(
+        "evaluate_results",
+        route_after_evaluation,
+        {
+            "refine_search": "refine_search",
+            "search_subgraph": "search_subgraph",
+        }
+    )
+    
+    # 13. 쿼리 개선 → 의도 분류 (루프)
+    graph.add_edge("refine_search", "classify_intent")
+    
+    # 14. 서브그래프 → 최종 답변 생성
+    graph.add_edge("search_subgraph", "generate_answer")
+    
+    # 15. 최종 답변 후 분기 (Phase 4: 다중 질문 처리)
+    graph.add_conditional_edges(
+        "generate_answer",
+        route_after_generate,
+        {
+            "combine_answers": "combine_answers",
+            END: END
+        }
+    )
+    
+    # 16. combine_answers → 종료
+    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)
+

CodeWeaver/src/agent/nodes.py

@@ -0,0 +1,1387 @@
+"""
+CodeWeaver LangGraph 노드 구현.
+
+각 노드는 AgentState를 받아 처리하고 업데이트된 상태를 반환합니다.
+모든 노드는 LangSmith를 통해 자동으로 추적됩니다.
+"""
+
+import asyncio
+import logging
+import os
+from typing import List, Literal, Optional
+
+from langchain_core.messages import HumanMessage, SystemMessage
+from langchain_google_genai import ChatGoogleGenerativeAI
+from langgraph.graph import StateGraph, START, END
+from langgraph.types import Send
+
+from src.agent.state import AgentState, SearchResult
+from src.agent.state import _MULTI_ANS_RESET_TOKEN  # reset token for multi_answers reducer
+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()
+
+
+@trace_node("analyze_question")
+async def analyze_question_node(state: AgentState) -> dict:
+    """
+    질문을 분석하여 유형을 분류하고 캐시 적격성을 판단합니다.
+    
+    Phase 2: Question Analysis & Cache Eligibility Decision
+    
+    분류:
+    - followup: 이전 대화에 의존하는 후속 질문
+    - cache_candidate: 독립적이고 재사용 가능한 질문
+    - new_search: 독립적이지만 캐시하지 않을 질문 (시간 민감 등)
+    """
+    user_question = state.user_question
+    messages = state.messages
+    
+    
+    # 대화 맥락 구성
+    has_history = messages and len(messages) > 1
+    context_info = ""
+    
+    if has_history:
+        context_info = "\n이전 대화 맥락:\n"
+        for msg in messages[-4:-1]:  # 현재 질문 제외 최근 3개
+            if hasattr(msg, 'type') and hasattr(msg, 'content'):
+                role = "사용자" if msg.type == "human" else "AI"
+                context_info += f"{role}: {msg.content[:100]}\n"
+    
+    analysis_prompt = f"""질문을 분석하여 유형을 분류하고, 캐시 적격성을 판단하세요.
+
+{context_info}
+현재 질문: {user_question}
+
+분류 기준:
+
+1. **clarification** (보충/형식 변경 요청)
+   - 이전 답변/대화 내용을 바탕으로 "설명 방식"을 바꾸거나 보충을 요청
+   - 예: "좀 더 쉽게 설명해줘", "예제 코드로 보여줘", "한 줄로 요약해줘", "다시 설명해줘"
+   - 원칙: 검색/캐시가 아니라 대화 히스토리 기반 답변
+   - should_cache = false, canonical_question = null
+   
+2. **new_topic** (대화 중 새 개념 질문)
+   - 대화가 이어지는 중이지만, 질문 자체가 독립적으로 성립하는 '새 개념/정의/비교/사용법' 질문
+   - 예: (React 이야기 중) "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)
+        
+        # JSON 파싱
+        import 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()
+        
+        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"
+
+        # 1차 정책 보정: clarification은 캐시 금지
+        if question_type == "clarification":
+            should_cache = False
+            canonical_question = None
+        else:
+            # new_topic/independent는 기본적으로 캐시 가능
+            if canonical_question is None or (isinstance(canonical_question, str) and not canonical_question.strip()):
+                canonical_question = user_question
+        
+        # 실행(run) 시작마다 step 로그를 리셋하고, 이번 실행의 step만 누적되게 함
+        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: AgentState) -> dict:
+    """
+    벡터 DB 캐시에서 유사한 질문을 검색합니다.
+    
+    threshold 0.85 이상인 경우 캐시 히트로 판단합니다.
+    """
+    question_for_lookup = state.canonical_question or state.user_question
+    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("create_plan")
+def create_plan_node(state: AgentState) -> dict:
+    """
+    질문을 분석하여 유형과 개수를 판단합니다.
+    
+    Phase 4: Dynamic Parallel Search
+    - single_topic: 하나의 주제 (기존 그래프 실행)
+    - multiple_questions: 독립 질문 2개 (Send API로 그래프 2회 실행)
+    - too_many: 독립 질문 3개 이상 (에러 메시지)
+    
+    LangGraph 공식 가이드라인: 노드는 한 가지 일만 수행 (계획 수립)
+    """
+    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개 제한 강제 (단, 3개 이상은 위 하드 가드에서 too_many로 처리됨)
+        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))
+        
+        # NOTE: 이 그래프는 체크포인팅/스레드 유지가 가능하므로,
+        # multi_answers는 매 실행(run) 시작 시 리셋해야 이전 턴 누적이 발생하지 않습니다.
+        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("classify_intent")
+def classify_intent_node(state: AgentState) -> dict:
+    """
+    LLM을 사용하여 사용자 질문의 의도를 분류합니다.
+    
+    분류 카테고리:
+    - debugging: 에러 해결, 버그 수정
+    - learning: 개념 학습, 원리 이해
+    - code_review: 코드 개선, 리팩토링
+    """
+    logger.info("의도 분류 중: %s", state.user_question[:50])
+    
+    classification_prompt = f"""질문을 다음 세 가지 의도 중 하나로 분류하세요:
+
+1. debugging: 에러 해결, 버그 수정, 문제 해결
+   예: "ImportError가 발생해요", "이 코드가 작동하지 않아요"
+
+2. learning: 개념 학습, 원리 이해, 튜토리얼
+   예: "async/await가 뭔가요?", "JPA 동작 원리는?"
+
+3. code_review: 코드 개선, 리팩토링, 베스트 프랙티스
+   예: "이 코드를 개선할 방법은?", "더 나은 설계는?"
+
+질문: {state.user_question}
+
+반드시 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
+    return updates
+
+
+@trace_node("search_stackoverflow")
+def search_stackoverflow_node(state: AgentState) -> dict:
+    """
+    Stack Overflow에서 검색을 수행합니다.
+    
+    Send API를 통한 병렬 검색의 일부로 실행됩니다.
+    search_results와 intermediate_steps는 Annotated[List, add]로
+    정의되어 있어 자동으로 머지됩니다.
+    """
+    intent = state.detected_intent or "learning"
+    count = 5 if intent == "debugging" else 3
+    
+    logger.info("Stack Overflow 검색 시작: %d개", count)
+    
+    try:
+        results = search_stackoverflow(state.user_question, count)
+        logger.info("Stack Overflow에서 %d개 결과 수집", len(results))
+        
+        # reducer가 자동으로 머지하므로 새 결과만 반환
+        return {
+            "search_results": results,
+            "intermediate_steps": [f"🔍 Stack Overflow: {len(results)}개 결과"]
+        }
+    except Exception as e:
+        logger.error("Stack Overflow 검색 실패: %s", e)
+        return {
+            "intermediate_steps": [f"⚠️ Stack Overflow 검색 실패: {str(e)}"]
+        }
+
+
+@trace_node("search_github")
+def search_github_node(state: AgentState) -> dict:
+    """
+    GitHub Issues/Discussions에서 검색을 수행합니다.
+    
+    Send API를 통한 병렬 검색의 일부로 실행됩니다.
+    """
+    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(state.user_question, count)
+        logger.info("GitHub에서 %d개 결과 수집", len(results))
+        
+        # reducer가 자동으로 머지
+        return {
+            "search_results": results,
+            "intermediate_steps": [f"🔍 GitHub: {len(results)}개 결과"]
+        }
+    except Exception as e:
+        logger.error("GitHub 검색 실패: %s", e)
+        return {
+            "intermediate_steps": [f"⚠️ GitHub 검색 실패: {str(e)}"]
+        }
+
+
+@trace_node("search_official_docs")
+def search_official_docs_node(state: AgentState) -> dict:
+    """
+    공식 문서/Tavily에서 검색을 수행합니다.
+    
+    Send API를 통한 병렬 검색의 일부로 실행됩니다.
+    """
+    intent = state.detected_intent or "learning"
+    count = 5 if intent == "learning" else 2
+    
+    logger.info("공식 문서 검색 시작: %d개", count)
+    
+    try:
+        results = search_official_docs(state.user_question, count)
+        logger.info("공식 문서에서 %d개 결과 수집", len(results))
+        
+        # reducer가 자동으로 머지
+        return {
+            "search_results": results,
+            "intermediate_steps": [f"🔍 공식 문서: {len(results)}개 결과"]
+        }
+    except Exception as e:
+        logger.error("공식 문서 검색 실패: %s", e)
+        return {
+            "intermediate_steps": [f"⚠️ 공식 문서 검색 실패: {str(e)}"]
+        }
+
+
+@trace_node("collect_results")
+def collect_results_node(state: AgentState) -> dict:
+    """
+    병렬 검색 결과를 수집하고 카운트합니다.
+    
+    Fan-in 포인트: 3개의 병렬 검색 노드가 모두 완료된 후 실행됩니다.
+    LangGraph 공식 가이드라인: Send API의 fan-in 지점에서 결과 집계
+    """
+    total_results = len(state.search_results)
+    
+    logger.info("검색 결과 수집 완료: %d개", total_results)
+    
+    steps_delta = [
+        f"📊 검색 결과 수집: 총 {total_results}개"
+    ]
+    
+    return {
+        "intermediate_steps": steps_delta
+    }
+
+
+@trace_node("evaluate_results")
+def evaluate_results_node(state: AgentState) -> dict:
+    """
+    검색 결과의 개수와 품질을 모두 평가합니다.
+    
+    평가 기준:
+    1. 개수: 최소 2개 이상
+    2. 품질: 평균 relevance_score >= 0.6
+    """
+    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차 평가: 품질 (relevance_score가 있는 경우만)
+    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)
+        
+        # 평균 점수가 0.5 미만이면 품질 부족
+        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:
+        # relevance_score가 아직 없으면 개수만으로 판단
+        steps_delta = [
+            f"✅ 검색 결과 충분 ({result_count}개), 필터링 단계로 진행"
+        ]
+    
+    return {
+        "needs_refinement": False,
+        "intermediate_steps": steps_delta
+    }
+
+
+@trace_node("refine_search")
+def refine_search_node(state: AgentState) -> dict:
+    """
+    검색 쿼리를 개선합니다.
+    
+    Open Deep Research 패턴:
+    - LLM이 전략을 선택 (구체화/일반화/번역)
+    - 원본 질문 보존 (최종 답변 생성 시 사용)
+    
+    LangGraph 공식 가이드라인:
+    - 상태에 원시 데이터 저장 (전략 정보 포함)
+    - 프롬프트는 노드 내에서 동적 생성
+    """
+    user_question = 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: 기술적 세부사항 추가
+   예: "React hooks" → "React useEffect cleanup function dependencies"
+   
+2. MORE_GENERAL: 더 넓은 용어 사용
+   예: "Spring Cloud Sleuth 2.x trace" → "distributed tracing Spring Boot"
+   
+3. TRANSLATE: 언어 변환
+   예: "JWT 인증 구현" → "JWT authentication implementation"
+   예: "WebSocket connection" → "WebSocket 연결 방법"
+
+다음 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)
+        
+        # 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()
+        
+        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])
+        
+        return {
+            "user_question": new_query,
+            "original_question": original_question,
+            "refinement_count": state.refinement_count + 1,
+            "search_results": [],  # CRITICAL: 이전 검색 결과 제거 후 재검색
+            "intermediate_steps": steps_delta
+        }
+        
+    except Exception as e:
+        logger.error("쿼리 개선 실패: %s", e, exc_info=True)
+        
+        # 기본 전략: 영문 키워드 추출 (간단한 fallback)
+        fallback_query = user_question + " tutorial example"
+        
+        steps_delta = [
+            f"⚠️ 쿼리 개선 실패, 기본 전략 사용",
+            f"   이후: {fallback_query}"
+        ]
+        
+        return {
+            "user_question": fallback_query,
+            "original_question": original_question,
+            "refinement_count": state.refinement_count + 1,
+            "search_results": [],  # CRITICAL: 실패 시에도 이전 검색 결과 제거
+            "intermediate_steps": steps_delta
+        }
+
+
+@trace_node("filter_and_score")
+def filter_and_score_node(state: AgentState) -> dict:
+    """
+    검색 결과를 필터링하고 관련도 점수를 매깁니다.
+    
+    - 최소 길이 50자 이상, URL 존재하는 결과만 유지
+    - 상위 5개 결과에 대해 LLM으로 관련도 평가
+    - 관련도 순으로 정렬하여 상위 10개 선택
+    """
+    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으로 점수 매기기 (비용 절감)
+    for result in filtered[:5]:
+        if result.relevance_score is None:
+            try:
+                scoring_prompt = f"""질문: {state.user_question}
+
+검색 결과: {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: AgentState) -> dict:
+    """
+    필터링된 각 검색 결과를 초보 개발자가 이해하기 쉽게 요약합니다.
+    
+    각 결과를 2-3문장으로 핵심 내용만 추출합니다.
+    """
+    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: AgentState) -> dict:
+    """
+    요약된 정보를 바탕으로 최종 답변을 생성합니다.
+    
+    의도별로 다른 답변 구조를 사용하며, 생성된 답변은 캐시에 저장됩니다.
+    """
+    subtask_results = state.subtask_results
+    summaries = subtask_results.get("summaries", [])
+    intent = state.detected_intent or "learning"
+    
+    logger.info("최종 답변 생성 중: %s", intent)
+    
+    # 의도별 프롬프트 템플릿
+    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"])
+    
+    # 요약 텍스트 포맷팅
+    summaries_text = "\n\n".join([
+        f"출처: {s['source']} ({s['url']})\n요약: {s['summary']}"
+        for s in summaries
+    ])
+    
+    # 이전 대화 맥락 추가 (messages 사용)
+    context_prefix = ""
+    messages_history = state.messages
+    if messages_history and len(messages_history) > 1:
+        context_prefix = "이전 대��� 맥락:\n"
+        # 최근 6개 메시지 (3턴) 사용
+        for msg in messages_history[-6:]:
+            if hasattr(msg, 'type'):
+                if msg.type == "human":
+                    context_prefix += f"사용자: {msg.content}\n"
+                elif msg.type == "ai":
+                    context_prefix += f"AI: {msg.content[:200]}...\n\n"
+        context_prefix += "---\n현재 질문:\n"
+    
+    final_prompt = (context_prefix + template).format(
+        question=(state.original_question or state.user_question),
+        summaries=summaries_text
+    )
+    
+    updates = {}
+    steps_delta: List[str] = []
+    
+    try:
+        response = llm.invoke([HumanMessage(content=final_prompt)])
+        final_answer = response.content.strip()
+        
+        updates["final_answer"] = final_answer
+        
+        # Phase 3: 조건부 캐시 저장
+        # - clarification: 캐시 금지 (그래프 상 generate_with_history로 빠지지만, 방어적으로 한 번 더 체크)
+        # - new_topic/independent: 캐시 가능(should_cache가 True일 때)
+        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"
+        
+        if should_cache and qtype in ["new_topic", "independent"]:
+            # 캐시할 질문: canonical_question 우선, 없으면 원본 질문
+            question_to_cache = canonical_question or state.user_question
+            
+            await qdrant_manager.save_to_cache(
+                question=question_to_cache,
+                answer=final_answer
+            )
+            
+            steps_delta.append(f"✅ 최종 답변 생성 완료 (길이: {len(final_answer)}자)")
+            steps_delta.append(f"💾 캐시 저장 완료 (질문: {question_to_cache[:50]}...)")
+            logger.info("최종 답변 생성 및 캐시 저장 완료: %s", question_to_cache[:50])
+        else:
+            steps_delta.append(f"✅ 최종 답변 생성 완료 (길이: {len(final_answer)}자)")
+            steps_delta.append("⚠️ 캐시 저장 생략 (독립적이지 않거나 일회성 질문)")
+            logger.info("최종 답변 생성 완료 (캐시 저장 생략)")
+        
+    except Exception as e:
+        logger.error("답변 생성 실패: %s", e, exc_info=True)
+        updates["final_answer"] = "답변 생성에 실패했습니다. 다시 시도해 주세요."
+        steps_delta.append(f"❌ 답변 생성 실패: {str(e)}")
+    
+    updates["intermediate_steps"] = steps_delta
+    
+    # Phase 4: Multi-question handling
+    # NOTE: AgentState는 Pydantic(BaseModel)이므로 dict-style state.get(...) 사용 금지
+    if state.is_multi_question:
+        answer_text = updates.get("final_answer")
+        if answer_text:
+            # Append to multi_answers (reducer will auto-merge)
+            updates["multi_answers"] = [{
+                "index": state.sub_question_index,
+                "question": state.sub_question_text or state.user_question,
+                "answer": answer_text
+            }]
+            logger.info("다중 질문 답변 추가: Q%d", state.sub_question_index)
+    
+    return updates
+
+
+@trace_node("return_cached_answer")
+def return_cached_answer_node(state: AgentState) -> dict:
+    """
+    캐시 히트 시 저장된 답변을 반환합니다.
+    
+    검색 및 생성 과정을 건너뛰고 즉시 답변을 제공합니다.
+    """
+    logger.info("캐시된 답변 반환")
+    
+    steps_delta = ["💾 캐시된 답변 반환 (검색 생략)"]
+    
+    return {
+        "final_answer": state.cached_result,
+        "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("initiate_dynamic_search")
+def initiate_dynamic_search_node(state: AgentState) -> dict:
+    """
+    다중 질문 처리의 진입 노드.
+    
+    IMPORTANT:
+    - LangGraph에서 `List[Send]`는 **노드 반환값**이 아니라,
+      `add_conditional_edges(...)`에 전달하는 **edge 함수 반환값**으로만 사용해야 합니다.
+    - 따라서 이 노드는 dict 업데이트만 반환하고,
+      실제 fan-out은 별도 edge 함수(`fanout_multi_questions`)가 담당합니다.
+    """
+    plan = state.plan or {}
+    sub_questions = plan.get("sub_questions", [])
+    logger.info("동적 복제 준비: %d개 질문", len(sub_questions))
+    return {
+        "intermediate_steps": [f"🔀 다중 질문 fan-out 준비: {len(sub_questions)}개"]
+    }
+
+
+def fanout_multi_questions(state: AgentState):
+    """
+    다중 질문을 Send API로 fan-out 합니다.
+    
+    반환값(List[Send])은 conditional edge 함수에서만 허용됩니다.
+    """
+    from langgraph.types import Send
+
+    plan = state.plan or {}
+    sub_questions = plan.get("sub_questions", [])
+    original_question = state.user_question
+    messages = state.messages
+
+    logger.info("동적 복제: %d개 질문을 각각 전체 그래프로 실행", len(sub_questions))
+
+    sends = []
+    for i, sq in enumerate(sub_questions):
+        # IMPORTANT: 이 프로젝트는 AgentState(BaseModel)를 노드 입력으로 사용하므로,
+        # Send arg도 dict가 아니라 AgentState 인스턴스로 보내야 합니다.
+        child = state.model_copy(deep=True)
+
+        # 질문 교체 + 다중 질문 메타데이터
+        child.user_question = sq
+        child.is_multi_question = True
+        child.sub_question_index = i
+        child.sub_question_text = sq
+        child.original_multi_question = original_question
+
+        # 공통 유지 필드
+        child.messages = messages
+        child.plan = plan
+
+        # 기존 그래프가 다시 채울 필드들은 초기화
+        child.question_type = None
+        child.should_cache = None
+        child.canonical_question = None
+        child.analysis_reasoning = None
+        child.cached_result = None
+        child.detected_intent = None
+        child.search_results = []
+        child.subtask_results = {}
+        child.refinement_count = 0
+        child.needs_refinement = False
+        child.original_question = None
+        child.final_answer = None
+        child.multi_answers = []
+        child.intermediate_steps = [f"🔄 질문 {i+1}/{len(sub_questions)}: {sq[:50]}"]
+
+        # 다중 질문은 outer graph에서 기존 파이프라인 전체를 병렬로 돌리면
+        # scalar state 채널(question_type 등)에서 concurrent update 충돌이 납니다.
+        # 따라서 worker 노드 안에서 '단일 질문 그래프'를 별도로 실행한 뒤,
+        # outer state에는 multi_answers(reducer)만 업데이트합니다.
+        sends.append(Send("run_single_question_worker", child))
+
+    return sends
+
+
+@trace_node("combine_answers")
+def combine_answers_node(state: AgentState) -> dict:
+    """
+    Fan-in: 모든 Send가 완료되면 multi_answers를 조합합니다.
+    
+    Reducer (Annotated[List[dict], add])가 자동으로 
+    모든 parallel Send의 결과를 multi_answers에 모아둡니다.
+    
+    이 노드는 단순히 모아진 결과를 읽어서 Markdown으로 조합합니다.
+    """
+    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)}개 답변 조합 완료"]
+    }
+
+
+def _build_search_subgraph_local() -> StateGraph:
+    """nodes.py 내부에서 단일 질문 그래프용 검색 서브그래프를 구성."""
+    subgraph = StateGraph(AgentState)
+    subgraph.add_node("filter_and_score", filter_and_score_node)
+    subgraph.add_node("summarize_results", summarize_results_node)
+    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 _get_single_question_agent():
+    """
+    다중 질문 worker에서 사용할 '단일 질문 파이프라인' 그래프를 lazy-compile 해서 캐싱합니다.
+    (outer state 충돌을 피하기 위해, worker 내부에서 별도 그래프를 실행)
+    """
+    global _SINGLE_QUESTION_AGENT  # type: ignore[name-defined]
+    try:
+        return _SINGLE_QUESTION_AGENT  # type: ignore[name-defined]
+    except Exception:
+        pass
+
+    # ---- routing helpers (graph.py 의 단일 질문 흐름과 동일) ----
+    def _route_after_analysis(s: AgentState) -> Literal["generate_with_history", "check_cache"]:
+        raw_qtype = s.question_type or "independent"
+        legacy_map = {"followup": "clarification", "cache_candidate": "independent", "new_search": "independent"}
+        question_type = legacy_map.get(raw_qtype, raw_qtype)
+        return "generate_with_history" if question_type == "clarification" else "check_cache"
+
+    def _route_after_cache(s: AgentState) -> Literal["return_cached_answer", "classify_intent"]:
+        return "return_cached_answer" if s.cached_result else "classify_intent"
+
+    def _route_after_evaluation(s: AgentState) -> Literal["refine_search", "search_subgraph"]:
+        if s.needs_refinement and s.refinement_count < 1:
+            return "refine_search"
+        return "search_subgraph"
+
+    def _initiate_parallel_search(s: AgentState):
+        return [
+            Send("search_stackoverflow", s),
+            Send("search_github", s),
+            Send("search_official_docs", s),
+        ]
+
+    # ---- build ----
+    g = StateGraph(AgentState)
+    g.add_node("analyze_question", analyze_question_node)
+    g.add_node("generate_with_history", generate_with_history_node)
+    g.add_node("check_cache", check_cache_node)
+    g.add_node("return_cached_answer", return_cached_answer_node)
+    g.add_node("classify_intent", classify_intent_node)
+    g.add_node("search_stackoverflow", search_stackoverflow_node)
+    g.add_node("search_github", search_github_node)
+    g.add_node("search_official_docs", search_official_docs_node)
+    g.add_node("collect_results", collect_results_node)
+    g.add_node("evaluate_results", evaluate_results_node)
+    g.add_node("refine_search", refine_search_node)
+    g.add_node("generate_answer", generate_answer_node)
+
+    search_subgraph = _build_search_subgraph_local()
+    g.add_node("search_subgraph", search_subgraph)
+
+    g.add_edge(START, "analyze_question")
+    g.add_conditional_edges(
+        "analyze_question",
+        _route_after_analysis,
+        {"generate_with_history": "generate_with_history", "check_cache": "check_cache"},
+    )
+    g.add_edge("generate_with_history", END)
+    g.add_conditional_edges(
+        "check_cache",
+        _route_after_cache,
+        {"return_cached_answer": "return_cached_answer", "classify_intent": "classify_intent"},
+    )
+    g.add_edge("return_cached_answer", END)
+    g.add_conditional_edges("classify_intent", _initiate_parallel_search)
+    g.add_edge("search_stackoverflow", "collect_results")
+    g.add_edge("search_github", "collect_results")
+    g.add_edge("search_official_docs", "collect_results")
+    g.add_edge("collect_results", "evaluate_results")
+    g.add_conditional_edges(
+        "evaluate_results",
+        _route_after_evaluation,
+        {"refine_search": "refine_search", "search_subgraph": "search_subgraph"},
+    )
+    g.add_edge("refine_search", "classify_intent")
+    g.add_edge("search_subgraph", "generate_answer")
+    g.add_edge("generate_answer", END)
+
+    _SINGLE_QUESTION_AGENT = g.compile()
+    return _SINGLE_QUESTION_AGENT
+
+
+@trace_node("run_single_question_worker")
+async def run_single_question_worker_node(state: AgentState) -> dict:
+    """
+    다중 질문의 각 서브 질문을 '단일 질문 그래프'로 실행한 뒤,
+    outer graph에는 reducer 채널(multi_answers)만 업데이트합니다.
+    """
+    agent = _get_single_question_agent()
+
+    # inner 실행은 multi-question 플래그를 꺼서(=multi_answers append 방지)
+    inner = state.model_copy(deep=True)
+    inner.is_multi_question = False
+    inner.multi_answers = []
+
+    result = await agent.ainvoke(
+        {
+            "user_question": inner.user_question,
+            "messages": inner.messages,
+        }
+    )
+
+    answer_text = result.get("final_answer") or ""
+    return {
+        "multi_answers": [
+            {
+                "index": state.sub_question_index,
+                "question": state.sub_question_text or state.user_question,
+                "answer": answer_text,
+            }
+        ],
+        "intermediate_steps": [f"✅ 서브 질문 {state.sub_question_index + 1} 처리 완료"],
+    }
+
+
+@trace_node("generate_with_history")
+async def generate_with_history_node(state: AgentState) -> dict:
+    """
+    대화 히스토리만 사용하여 후속 질문에 답변합니다.
+    
+    Phase 2: Follow-up Handler
+    - 캐시 검색 안 함
+    - 웹 검색 안 함
+    - 캐시에 저장 안 함
+    - messages 히스토리만 활용
+    """
+    user_question = state.user_question
+    messages_history = state.messages
+    
+    logger.info("대화 히스토리 기반 답변 생성: %s", user_question[:50])
+    
+    # 대화 맥락 구성
+    context_prompt = "이전 대화를 참고하여 후속 질문에 답변하세요.\n\n"
+    
+    if messages_history:
+        context_prompt += "대화 내역:\n"
+        for msg in messages_history[:-1]:  # 현재 질문 제외
+            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:
+        response = llm.invoke([HumanMessage(content=context_prompt)])
+        final_answer = response.content.strip()
+        
+        updates["final_answer"] = 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)
+        updates["final_answer"] = "답변 생성에 실패했습니다. 다시 시도해 주세요."
+        steps_delta.append(f"❌ 답변 생성 실패: {str(e)}")
+    
+    updates["intermediate_steps"] = steps_delta
+    return updates
+

CodeWeaver/src/agent/state.py

@@ -0,0 +1,183 @@
+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.
+
+    - 기본 동작: old + new (병렬 노드에서 동시에 step을 추가 가능)
+    - 리셋 동작: new의 첫 원소가 _STEPS_RESET_TOKEN 이면 old를 버리고 new[1:]로 교체
+      (체크포인팅으로 누적된 step을 '이번 실행(run)' 기준으로 초기화하기 위함)
+    """
+    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.
+
+    - 기본 동작: old + new (병렬 worker에서 답변을 동시에 append 가능)
+    - 리셋 동작: new의 첫 원소가 {"__token__": _MULTI_ANS_RESET_TOKEN} 이면
+      old를 버리고 new[1:]로 교체
+      (체크포인팅/스레드 유지로 인해 이전 턴의 multi_answers가 누적되는 문제 방지)
+    """
+    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
+
+
+class SearchResult(BaseModel):
+    """검색 도메인에서 공통으로 사용하는 단일 검색 결과 모델."""
+
+    source: str = Field(
+        ...,
+        description="검색 출처 (예: Stack Overflow, 공식 문서, GitHub Issues 등)",
+    )
+    content: str = Field(
+        ...,
+        description="검색 결과의 핵심 내용 또는 발췌 텍스트",
+    )
+    url: Optional[str] = Field(
+        default=None,
+        description="검색 결과의 원본 출처 URL (존재하는 경우에만 설정)",
+    )
+    relevance_score: Optional[float] = Field(
+        default=None,
+        description="검색 쿼리와의 관련도 점수 (0.0–1.0 범위, 클수록 더 관련 있음)",
+    )
+
+
+class AgentState(BaseModel):
+    """CodeWeaver LangGraph 에이전트의 전체 상태를 나타내는 Pydantic 모델.
+    
+    LangGraph 공식 가이드라인:
+    - Pydantic BaseModel 사용 (타입 안전성)
+    - messages 필드에 add_messages reducer 적용
+    - 모든 필드에 기본값 제공
+    """
+
+    # Core fields
+    user_question: str = Field(default="", description="사용자의 원본 질문")
+    messages: Annotated[List[BaseMessage], add_messages] = Field(
+        default_factory=list,
+        description="대화 메시지 히스토리 (add_messages reducer 사용)"
+    )
+    
+    # Legacy conversation history (유지하되 messages 우선)
+    conversation_history: Optional[List[Tuple[str, str]]] = Field(
+        default=None,
+        description="레거시 대화 내역 (messages 우선 사용)"
+    )
+    
+    # Intent classification
+    detected_intent: Optional[Literal["debugging", "learning", "code_review"]] = Field(
+        default=None,
+        description="분류된 질문 의도"
+    )
+    
+    # Cache-related
+    cached_result: Optional[str] = Field(
+        default=None,
+        description="벡터 DB 캐시에서 조회된 답변"
+    )
+    
+    # Search results (Send API를 위한 reducer 사용)
+    search_results: Annotated[List[SearchResult], add] = Field(
+        default_factory=list,
+        description="병렬 검색으로 수집된 결과 리스트 (Send API로 병렬 업데이트)"
+    )
+    
+    # Intermediate processing
+    subtask_results: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="서브태스크 실행 결과 저장소"
+    )
+    
+    # Final output
+    final_answer: Optional[str] = Field(
+        default=None,
+        description="최종 생성된 답변"
+    )
+    
+    # Debugging/tracing (병렬 노드 + 실행 단위 리셋 지원 reducer 사용)
+    intermediate_steps: Annotated[List[str], merge_intermediate_steps] = Field(
+        default_factory=list,
+        description="실행 단계별 로그 (병렬 노드에서 동시 업데이트 가능)"
+    )
+    
+    # Question analysis & cache eligibility
+    question_type: Optional[Literal["clarification", "new_topic", "independent"]] = Field(
+        default=None,
+        description="질문 유형 분류 결과"
+    )
+    analysis_reasoning: Optional[str] = Field(
+        default=None,
+        description="질문 분석 이유"
+    )
+    should_cache: Optional[bool] = Field(
+        default=None,
+        description="캐시 저장 여부"
+    )
+    canonical_question: Optional[str] = Field(
+        default=None,
+        description="정규화된 질문 (캐시용)"
+    )
+    
+    # Planning & Refinement (Phase 3: Open Deep Research pattern)
+    plan: Optional[Dict[str, Any]] = Field(
+        default=None,
+        description="질문 분해 계획: {'sub_questions': [...], 'reasoning': '...'}"
+    )
+    needs_refinement: bool = Field(
+        default=False,
+        description="검색 결과가 부족하여 쿼리 개선 필요 여부"
+    )
+    refinement_count: int = Field(
+        default=0,
+        description="검색 쿼리 개선 시도 횟수 (최대 1회)"
+    )
+    original_question: Optional[str] = Field(
+        default=None,
+        description="쿼리 개선 전 원본 질문 (최종 답변 생성 시 참조)"
+    )
+    
+    # Phase 4: Dynamic Parallel Search for Multiple Questions
+    is_multi_question: bool = Field(
+        default=False,
+        description="현재 다중 질문 처리 중인지 여부"
+    )
+    sub_question_index: int = Field(
+        default=0,
+        description="서브 질문 인덱스 (0부터 시작)"
+    )
+    sub_question_text: Optional[str] = Field(
+        default=None,
+        description="현재 처리 중인 서브 질문 텍스트"
+    )
+    original_multi_question: Optional[str] = Field(
+        default=None,
+        description="다중 질문의 원본 질문 (통합 답변 생성 시 참조)"
+    )
+    multi_answers: Annotated[List[Dict[str, Any]], merge_multi_answers] = Field(
+        default_factory=list,
+        description="다중 질문의 각 답변 리스트 (reducer로 자동 병합)"
+    )
+    
+    class Config:
+        arbitrary_types_allowed = True

CodeWeaver/src/tools/__init__.py

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

CodeWeaver/src/tools/search_tools.py

@@ -0,0 +1,215 @@
+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")
+        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 초과")
+        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")
+    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 []
+

CodeWeaver/src/utils/__init__.py

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

CodeWeaver/src/utils/tracing.py

@@ -0,0 +1,91 @@
+"""
+LangSmith 추적(tracing) 유틸리티 모듈.
+
+LangGraph 노드 실행을 LangSmith에서 추적하고 모니터링하기 위한 도구를 제공합니다.
+공식 문서: https://docs.langchain.com/langsmith/trace-with-langgraph
+"""
+
+import os
+import logging
+import asyncio
+from functools import wraps
+from typing import Any, Callable
+from inspect import iscoroutinefunction
+
+from langsmith import traceable
+
+logger = logging.getLogger(__name__)
+
+
+def ensure_tracing_enabled() -> bool:
+    """
+    LangSmith 추적이 올바르게 설정되었는지 확인합니다.
+    
+    Returns:
+        bool: 추적이 활성화되어 있으면 True, 그렇지 않으면 False
+    """
+    required_vars = ["LANGCHAIN_TRACING_V2", "LANGCHAIN_API_KEY"]
+    
+    missing_vars = [var for var in required_vars if not os.getenv(var)]
+    
+    if missing_vars:
+        logger.warning(
+            "LangSmith 추적이 비활성화되었습니다. 누락된 환경변수: %s",
+            ", ".join(missing_vars)
+        )
+        return False
+    
+    return True
+
+
+def trace_node(node_name: str) -> Callable:
+    """
+    LangGraph 노드 실행을 추적하는 데코레이터.
+    
+    이 데코레이터는 각 노드의 입력/출력, 실행 시간, 에러를 
+    LangSmith 대시보드에 자동으로 기록합니다.
+    동기 및 비동기 함수 모두 지원합니다.
+    
+    Args:
+        node_name: LangSmith에 표시될 노드 이름
+    
+    Returns:
+        Callable: 데코레이트된 함수
+    
+    Example:
+        @trace_node("check_cache")
+        async def check_cache_node(state: AgentState) -> AgentState:
+            # 노드 로직
+            return state
+    """
+    def decorator(func: Callable) -> Callable:
+        # async 함수인지 확인
+        if iscoroutinefunction(func):
+            @wraps(func)
+            @traceable(name=node_name, run_type="chain")
+            async def async_wrapper(*args, **kwargs) -> Any:
+                try:
+                    result = await func(*args, **kwargs)
+                    return result
+                except Exception as e:
+                    logger.error("🔴 노드 실패: %s - %s", node_name, str(e))
+                    raise
+            return async_wrapper
+        else:
+            @wraps(func)
+            @traceable(name=node_name, run_type="chain")
+            def sync_wrapper(*args, **kwargs) -> Any:
+                try:
+                    result = func(*args, **kwargs)
+                    return result
+                except Exception as e:
+                    logger.error("🔴 노드 실패: %s - %s", node_name, str(e))
+                    raise
+            return sync_wrapper
+    return decorator
+
+
+# 모듈 import 시 자동으로 추적 설정 확인
+ensure_tracing_enabled()
+
+

CodeWeaver/src/vector_db/__init__.py

@@ -0,0 +1,6 @@
+from .qdrant_client import QdrantManager
+from .local_embeddings import LocalEmbeddingManager
+
+__all__ = ["QdrantManager", "LocalEmbeddingManager"]
+
+

CodeWeaver/src/vector_db/local_embeddings.py

@@ -0,0 +1,34 @@
+"""
+로컬 임베딩 관리 모듈.
+
+BAAI/bge-m3 모델을 사용해 로컬에서 임베딩을 생성한다.
+"""
+
+import logging
+from typing import List
+
+from sentence_transformers import SentenceTransformer
+
+logger = logging.getLogger(__name__)
+
+
+class LocalEmbeddingManager:
+    """BAAI/bge-m3 로컬 임베딩 생성기."""
+
+    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)
+
+    def get_embedding(self, text: str) -> List[float]:
+        """단일 텍스트를 임베딩."""
+        embedding = self.model.encode(text, convert_to_numpy=True)
+        return embedding.tolist()
+
+    def get_embeddings_batch(self, texts: List[str]) -> List[List[float]]:
+        """배치 텍스트 임베딩."""
+        embeddings = self.model.encode(texts, convert_to_numpy=True)
+        return embeddings.tolist()
+
+

CodeWeaver/src/vector_db/qdrant_client.py

@@ -0,0 +1,225 @@
+import hashlib
+import logging
+import os
+from typing import Dict, List, Optional
+
+from dotenv import load_dotenv  # type: ignore[import]
+from qdrant_client import QdrantClient, models
+
+from src.vector_db.local_embeddings import LocalEmbeddingManager
+
+# .env 파일에서 환경 변수 로드 (로컬 개발 편의성)
+load_dotenv()
+
+logger = logging.getLogger(__name__)
+
+
+class QdrantManager:
+    """Qdrant Cloud 기반 벡터 캐시 관리 클래스.
+
+    - 임베딩 생성: 로컬 BAAI/bge-m3
+    - 벡터 저장/검색: Qdrant Cloud
+    """
+
+    def __init__(self, collection_name: str = "CodeWeaver") -> None:
+        """Qdrant Cloud 클라이언트를 초기화하고 컬렉션을 준비한다."""
+        qdrant_url = os.getenv("QDRANT_URL")
+        qdrant_api_key = os.getenv("QDRANT_API_KEY")
+
+        if not qdrant_url or not qdrant_api_key:
+            raise ValueError(
+                "QDRANT_URL 및 QDRANT_API_KEY 환경 변수가 모두 설정되어 있어야 합니다."
+            )
+
+        # Qdrant Cloud 공식 가이드와 유사한 초기화 형태 사용
+        # https://qdrant.tech/documentation/tutorials-and-examples/cloud-inference-hybrid-search/
+        self.client = QdrantClient(
+            url=qdrant_url,
+            api_key=qdrant_api_key,
+            timeout=30,
+        )
+
+        self.collection_name = collection_name
+        self.embedding_manager = LocalEmbeddingManager()
+
+        logger.info("QdrantManager 초기화: collection=%s, url=%s", collection_name, qdrant_url)
+
+        # 컬렉션이 없다면 생성
+        self._init_collection()
+
+    def _init_collection(self) -> None:
+        """컬렉션이 없으면 생성한다."""
+        try:
+            exists = self.client.collection_exists(self.collection_name)
+        except Exception as e:  # pragma: no cover - 방어적 코드
+            logger.error("Qdrant 컬렉션 존재 여부 확인 실패: %s", e, exc_info=True)
+            raise
+
+        if exists:
+            logger.info("Qdrant 컬렉션 이미 존재: %s", self.collection_name)
+            return
+
+        try:
+            self.client.create_collection(
+                collection_name=self.collection_name,
+                vectors_config=models.VectorParams(
+                    size=1024,  # bge-m3 임베딩 차원
+                    distance=models.Distance.COSINE,
+                ),
+            )
+            logger.info("Qdrant 컬렉션 생성 완료: %s", self.collection_name)
+        except Exception as e:
+            logger.error("Qdrant 컬렉션 생성 실패: %s", e, exc_info=True)
+            raise
+
+    async def get_embedding(self, text: str) -> List[float]:
+        """로컬 임베딩 모델을 사용해 텍스트 임베딩을 생성한다."""
+        try:
+            embedding = self.embedding_manager.get_embedding(text)
+            logger.debug("임베딩 생성 완료 (길이=%d)", len(embedding))
+            return embedding
+        except Exception as e:
+            logger.error("임베딩 생성 실패: %s", e, exc_info=True)
+            raise
+
+    async def search_cache(
+        self,
+        question: str,
+        threshold: float = 0.85,
+    ) -> Optional[str]:
+        """질문에 대한 캐시된 답변을 Qdrant에서 검색한다.
+
+        threshold보다 높은 score를 가진 결과가 있을 때만 answer를 반환한다.
+        """
+        try:
+            embedding = await self.get_embedding(question)
+        except Exception:
+            # 이미 get_embedding 내부에서 로그를 남기므로 여기서는 조용히 실패 처리
+            return None
+
+        try:
+            # Qdrant 공식 문서: query_points를 사용한 벡터 검색
+            # 단일 벡터 컬렉션의 경우 query 파라미터에 벡터 리스트를 직접 전달
+            # https://qdrant.tech/documentation/tutorials-and-examples/cloud-inference-hybrid-search/
+            results = self.client.query_points(
+                collection_name=self.collection_name,
+                query=embedding,  # 단일 벡터 컬렉션: 벡터를 직접 전달
+                limit=1,
+                with_payload=True,
+            )
+        except Exception as e:
+            logger.error("Qdrant 캐시 검색 실패: %s", e, exc_info=True)
+            return None
+
+        if not results.points:
+            logger.info("캐시 미스: 결과 없음 (question=%s)", question)
+            return None
+
+        top = results.points[0]
+        score = getattr(top, "score", None)
+        payload = getattr(top, "payload", {}) or {}
+
+        if score is None:
+            logger.warning("검색 결과에 score가 없습니다. payload=%s", payload)
+            return None
+
+        if score < threshold:
+            logger.info(
+                "캐시 미스: score(%.4f) < threshold(%.4f) (question=%s)",
+                score,
+                threshold,
+                question,
+            )
+            return None
+
+        answer = payload.get("answer")
+        if answer is None:
+            logger.info("캐시 히트이지만 payload에 answer가 없습니다. payload=%s", payload)
+            return None
+
+        logger.info(
+            "캐시 히트: score=%.4f, question=%s, answer_length=%d",
+            score,
+            question,
+            len(str(answer)),
+        )
+        return str(answer)
+
+    async def save_to_cache(self, question: str, answer: str) -> None:
+        """질문-답변 쌍을 Qdrant 캐시에 저장한다.
+        
+        동일한 질문에 대해서는 deterministic ID를 사용하여,
+        upsert 시 기존 엔트리를 덮어쓰게 함으로써 중복을 방지한다.
+        """
+        try:
+            embedding = await 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]}"
+
+        # 기존 엔트리 존재 시(덮어쓰기) 로그를 남긴다. 실패해도 upsert는 계속 시도.
+        try:
+            existing = self.client.retrieve(
+                collection_name=self.collection_name,
+                ids=[point_id],
+                with_payload=False,
+                with_vectors=False,
+            )
+            if existing:
+                logger.info("기존 캐시 엔트리를 덮어씁니다: point_id=%s", point_id)
+        except Exception:
+            pass
+
+        point = models.PointStruct(
+            id=point_id,
+            vector=embedding,
+            payload={
+                "question": question,
+                "answer": answer,
+            },
+        )
+
+        try:
+            self.client.upsert(
+                collection_name=self.collection_name,
+                points=[point],
+            )
+            logger.info(
+                "Qdrant 캐시에 저장 완료 (hash ID로 중복 방지): point_id=%s, question_length=%d, answer_length=%d",
+                point_id,
+                len(question),
+                len(answer),
+            )
+        except Exception as e:
+            logger.error("Qdrant 캐시 저장 실패: %s", e, exc_info=True)
+
+    async def get_cache_stats(self) -> Dict[str, int]:
+        """현재 컬렉션의 캐시 통계를 반환한다."""
+        try:
+            info = self.client.get_collection(self.collection_name)
+            # qdrant_client의 CollectionInfo는 points_count 속성을 제공
+            points_count = getattr(info, "points_count", 0) or 0
+            logger.debug(
+                "Qdrant 캐시 통계 조회: collection=%s, total_entries=%d",
+                self.collection_name,
+                points_count,
+            )
+            return {"total_entries": int(points_count)}
+        except Exception as e:
+            logger.error("Qdrant 캐시 통계 조회 실패: %s", e, exc_info=True)
+            # 호출 측에서 에러 메시지를 참고할 수 있도록 포함
+            return {
+                "total_entries": 0,
+                "error": str(e),  # type: ignore[dict-item]
+            }
+
+

CodeWeaver/ui/app.py

@@ -0,0 +1,272 @@
+import asyncio
+import logging
+import os
+import sys
+import uuid
+from pathlib import Path
+
+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.state import AgentState
+
+# 로깅 설정 (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)
+
+logger = logging.getLogger(__name__)
+
+
+async def chat(
+    message: str,
+    history: list,
+    thread_id: str,
+) -> str:
+    """
+    사용자 메시지를 처리하고 에이전트 응답을 반환합니다.
+    
+    Args:
+        message: 사용자 입력 메시지
+        history: 대화 내역 (Gradio 자동 관리)
+        thread_id: 세션별 고유 ID (MemorySaver가 대화 맥락 추적에 사용)
+        
+    Returns:
+        에이전트의 최종 답변
+    """
+    if not message or not message.strip():
+        return "질문을 입력해주세요."
+    
+    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}}
+        
+        # 에이전트 실행
+        result = await agent.ainvoke(initial_state, config=config)
+        
+        # 최종 답변 추출
+        final_answer = result.get("final_answer", "답변을 생성하지 못했습니다.")
+        
+        return final_answer
+        
+    except Exception as e:
+        logger.error("에러 발생: %s", e, exc_info=True)
+        return f"⚠️ 오류가 발생했습니다: {str(e)}\n다시 시도해주세요."
+
+
+def create_demo() -> gr.Blocks:
+    """Gradio 인터페이스를 생성합니다."""
+    
+
+    
+    # CSS 스타일 (깔끔한 디자인)
+    # - Gradio 기본 CSS가 .contain/.gradio-container 폭을 덮어쓰는 경우가 있어
+    #   둘 다 !important로 고정하여 "처음부터 넓은 폭"을 확실히 유지합니다.
+    css = """
+    .gradio-container {
+        max-width: 1280px !important;
+        width: min(1280px, 100%) !important;
+        margin: 0 auto !important;
+    }
+    .contain {
+        max-width: 1280px !important;
+        width: min(1280px, 100%) !important;
+        margin: 0 auto !important;
+        padding-top: 1.5rem;
+    }
+    .message { font-size: 1.1rem; line-height: 1.6; }
+    """
+    
+    with gr.Blocks(
+        title="CodeWeaver - AI 개발 도우미",
+        theme=gr.themes.Soft(),
+        css=css
+    ) as demo:
+        
+        gr.Markdown("""
+        # 🤖 CodeWeaver
+        ### AI 기반 개발 질문 답변 시스템
+        
+        초보 개발자를 위한 친절한 AI 도우미입니다.
+        
+        **주요 기능:**
+        - ✅ 에러 해결 (디버깅)
+        - ✅ 개념 학습
+        - ✅ 코드 리뷰 및 개선 제안
+        - ✅ **다중 질문 처리** (최대 2개까지 동시 처리)
+        - ✅ **대화 맥락 이해** (이전 대화를 참고한 후속 질문 답변)
+        - ✅ **스마트 캐싱** (유사 질문 즉시 답변)
+        - ✅ **자동 검색 개선** (결과 부족 시 쿼리 자동 최적화)
+        
+        💬 개발 관련 질문을 자유롭게 해보세요!
+        - 단일 질문: "Spring Boot JPA N+1 문제 해결 방법은?"
+        - 다중 질문: "JWT가 뭐야? CORS는?" (최대 2개)
+        - 후속 질문: "좀 더 쉽게 설명해줘" (이전 답변 참고)
+        """)
+        
+        # 세션별 고유 ID (브라우저 세션마다 독립적으로 생성)
+        session_id = gr.State(value=lambda: str(uuid.uuid4()))
+        
+        # 채팅 인터페이스
+        chatbot_interface = gr.ChatInterface(
+            fn=chat,
+            examples=None,  # examples는 아래 Accordion에서 수동 처리
+            chatbot=gr.Chatbot(height=500),
+            textbox=gr.Textbox(
+                placeholder="질문을 입력하세요...",
+                container=False,
+                scale=7
+            ),
+            retry_btn=None,
+            undo_btn=None,
+            clear_btn="🗑️ 대화 초기화",
+            additional_inputs=[session_id],  # thread_id 전달
+        )
+        
+        # Clear 버튼 클릭 시 새 세션 ID 생성 (새 대화 시작)
+        def reset_session():
+            new_id = str(uuid.uuid4())
+            return new_id
+        
+        # Clear 버튼에 세션 리셋 핸들러 추가
+        if chatbot_interface.clear_btn:
+            chatbot_interface.clear_btn.click(
+                reset_session,
+                None,
+                session_id,
+                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는?",  # 다중 질문 예시
+        ]
+        
+        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)
+            """)
+        
+
+        
+        # 사용 가이드
+        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. 응답 시간
+            - **첫 질문**: 10~15초 소요 (검색 + 답변 생성)
+            - **유사 질문**: 즉시 답변 (캐시 활용, 임계값 0.85 이상)
+            - **다중 질문**: 각 질문별 병렬 처리로 효율적
+            
+            ### 6. 더 나은 답변을 위한 팁
+            - 에러 메시지를 포함해주세요
+            - 사용 중인 언어/프레임워크를 명시하세요
+            - 시도했던 해결 방법을 함께 알려주세요
+            - 검색 결과가 부족하면 자동으로 쿼리를 개선합니다 (최대 1회)
+            """)
+    
+    return demo
+
+
+# 앱 생성
+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 버그 우회용
+    )

DYNAMIC_PARALLEL_SEARCH.md

@@ -0,0 +1,553 @@
+# Dynamic Parallel Search for Multiple Independent Questions
+
+## 개요
+
+CodeWeaver Phase 4는 **다중 독립 질문**을 Send API로 동적 병렬 처리하여, 각 질문마다 독립적인 검색 파이프라인을 실행합니다.
+
+### 핵심 철학
+
+> "기존 그래프를 100% 재사용하되, 질문 개수만큼 복제해서 병렬 실행한다"
+
+- **기존 코드 재사용률**: ~95%
+- **새로운 노드**: 5개 추가
+- **새로운 edge 함수**: 1개 추가 (fanout_multi_questions)
+- **수정된 노드**: 2개 수정 (create_plan, generate_answer)
+
+## 주요 기능
+
+### 1. 자동 질문 유형 감지
+
+**create_plan_node**가 질문을 분석하여 3가지 케이스로 분류:
+
+#### Case 1: single_topic
+- **정의**: 하나의 주제를 다각도로 묻는 경우
+- **예시**: "Spring Security JWT 인증 구현 방법"
+- **서브질문**: ["개념", "구현", "예제"] (답변 섹션 구조용)
+- **실행**: 기존 그래프 1회 (검색은 원본 질문으로)
+
+#### Case 2: multiple_questions
+- **정의**: 서로 무관한 독립 질문 (최대 2개)
+- **예시**: "JWT가 뭐야? CORS는?"
+- **서브질문**: ["JWT가 뭐야?", "CORS는?"] (각각 별도 검색)
+- **실행**: Send API로 기존 그래프 2회 병렬 실행
+
+#### Case 3: too_many
+- **정의**: 질문 3개 이상
+- **예시**: "JWT? CORS? Docker?"
+- **실행**: 친절한 에러 메시지 표시, 대화 계속 가능
+- **하드 가드**: LLM 분류와 무관하게 물음표 개수(3개 이상) 또는 질문 후보 개수(3개 이상)로 결정론적 차단
+
+### 2. 질문 개수 제한
+
+비용 및 품질 관리를 위해 **최대 2개 질문**으로 제한:
+
+```
+입력: "JWT? CORS? Docker? Redis?"
+처리: too_many 케이스 → 에러 메시지
+안내: "하나의 주제로 통합" 또는 "2개만 선택" 권장
+```
+
+### 3. Send API 동적 복제
+
+**중요**: LangGraph에서 `List[Send]`는 노드 반환값이 아니라 **conditional edge 함수 반환값**으로만 사용됩니다.
+
+```python
+# initiate_dynamic_search_node: state 준비만 (dict 반환)
+def initiate_dynamic_search_node(state: AgentState) -> dict:
+    return {"intermediate_steps": [...]}  # Send 반환 안 함!
+
+# fanout_multi_questions: conditional edge 함수 (List[Send] 반환)
+def fanout_multi_questions(state: AgentState) -> List[Send]:
+    sends = []
+    for i, question in enumerate(["JWT가 뭐야?", "CORS는?"]):
+        child_state = state.model_copy(deep=True)
+        child_state.user_question = question
+        child_state.is_multi_question = True
+        # ... 메타데이터 설정 ...
+        sends.append(Send("run_single_question_worker", child_state))
+    return sends
+
+# run_single_question_worker: 내부 서브그래프 실행
+# 각 Send는 독립적으로 내부 그래프를 실행:
+# analyze → cache → classify → search(×3) → collect → eval → subgraph → generate
+# → multi_answers에 결과 추가
+```
+
+### 4. Reducer 자동 Fan-in (Reset 기능 포함)
+
+```python
+# State 정의 (커스텀 reducer 사용)
+multi_answers: Annotated[List[Dict[str, Any]], merge_multi_answers] = []
+
+# merge_multi_answers reducer:
+# - 기본 동작: old + new (병렬 worker에서 답변을 동시에 append)
+# - 리셋 동작: new의 첫 원소가 {"__token__": "__RESET_MULTI_ANS__"}이면
+#   old를 버리고 new[1:]로 교체 (이전 턴 누적 방지)
+
+# run_single_question_worker 1이 리턴:
+{"multi_answers": [{"index": 0, "question": "JWT가 뭐야?", "answer": "..."}]}
+
+# run_single_question_worker 2가 리턴:
+{"multi_answers": [{"index": 1, "question": "CORS는?", "answer": "..."}]}
+
+# LangGraph Reducer가 자동 병합:
+state.multi_answers = [
+    {"index": 0, ...},
+    {"index": 1, ...}
+]
+
+# combine_answers_node가 이를 통합 Markdown으로 변환
+```
+
+## 그래프 흐름
+
+```mermaid
+graph TD
+    START[START] --> plan[create_plan]
+    
+    plan -->|single_topic| analyze[analyze_question]
+    plan -->|multiple_questions 2개| dynamic[initiate_dynamic_search]
+    plan -->|too_many 3+| tooMany[handle_too_many_questions]
+    
+    tooMany --> END
+    
+    analyze --> cache[check_cache]
+    cache -->|hit| returnCache[return_cached_answer]
+    cache -->|miss| classify[classify_intent]
+    
+    returnCache --> END
+    
+    classify --> searchSO[search_stackoverflow]
+    classify --> searchGH[search_github]
+    classify --> searchDocs[search_official_docs]
+    
+    searchSO --> collect[collect_results]
+    searchGH --> collect
+    searchDocs --> collect
+    
+    collect --> eval[evaluate_results]
+    
+    eval -->|needs_refinement| refine[refine_search]
+    eval -->|sufficient| filterNode[filter_and_score]
+    
+    refine --> classify
+    
+    filterNode --> summarize[summarize_results]
+    summarize --> generate[generate_answer]
+    
+    generate -->|is_multi_question| combine[combine_answers]
+    generate -->|single_topic| END
+    
+    combine --> END
+    
+    dynamic --> fanout[fanout_multi_questions<br/>conditional edge]
+    fanout -.Send Q1.-> worker1[run_single_question_worker<br/>내부 서브그래프]
+    fanout -.Send Q2.-> worker2[run_single_question_worker<br/>내부 서브그래프]
+    worker1 --> combine
+    worker2 --> combine
+```
+
+### 흐름 설명
+
+#### Single Topic (기존 동작 유지)
+```
+START → create_plan (case: single_topic)
+      → analyze → cache → classify → search(×3) → collect → eval → subgraph → generate → END
+```
+
+#### Multiple Questions (신규)
+```
+START → create_plan (case: multiple_questions)
+      → initiate_dynamic_search (state 준비)
+      → fanout_multi_questions (conditional edge)
+          ├─ Send("run_single_question_worker", Q1) → [내부 서브그래프 전체 파이프라인] → multi_answers[0]
+          └─ Send("run_single_question_worker", Q2) → [내부 서브그래프 전체 파이프라인] → multi_answers[1]
+      → combine_answers (자동 fan-in) → END
+```
+
+#### Too Many (신규)
+```
+START → create_plan (case: too_many)
+      → handle_too_many_questions → END
+(사용자는 즉시 다시 질문 가능)
+```
+
+## 구현 상세
+
+### State 확장
+
+```python
+# src/agent/state.py
+
+class AgentState(BaseModel):
+    # ... 기존 필드 ...
+    
+    # Phase 4: Dynamic Parallel Search
+    is_multi_question: bool = False
+    sub_question_index: int = 0
+    sub_question_text: Optional[str] = None
+    original_multi_question: Optional[str] = None
+    multi_answers: Annotated[List[Dict[str, Any]], merge_multi_answers] = []
+```
+
+### 새로운 노드 (5개)
+
+#### 1. create_plan_node (수정)
+- **위치**: `src/agent/nodes.py` 라인 206
+- **역할**: 질문 유형 및 개수 판단
+- **변경**: 
+  - `case` 필드 추가 (single_topic/multiple_questions/too_many)
+  - **하드 가드 추가**: `_hard_guard_too_many` 함수로 3개 이상 질문 결정론적 차단
+    - 물음표 개수(3개 이상) 또는 질문 후보 개수(3개 이상) 감지
+    - LLM 분류와 무관하게 `too_many`로 강제
+
+#### 2. handle_too_many_questions_node (신규)
+- **위치**: `src/agent/nodes.py` 라인 1068
+- **역할**: 3개 이상 질문 시 안내 메시지
+- **특징**: 대화 종료하지 않음 (즉시 재질문 가능)
+
+#### 3. initiate_dynamic_search_node (신규)
+- **위치**: `src/agent/nodes.py` 라인 1092
+- **역할**: 다중 질문 처리 진입점, state 준비
+- **핵심**: dict만 반환 (Send는 반환하지 않음)
+
+#### 4. fanout_multi_questions (신규 - Edge 함수)
+- **위치**: `src/agent/nodes.py` 라인 1110
+- **역할**: conditional edge 함수로 `List[Send]` 반환
+- **핵심**: 각 서브 질문을 `run_single_question_worker`로 Send
+
+#### 5. run_single_question_worker_node (신규)
+- **위치**: `src/agent/nodes.py` 라인 1306
+- **역할**: 내부 서브그래프를 실행하여 state 충돌 방지
+- **핵심**: 
+  - 독립된 단일 질문 그래프를 내부에서 실행
+  - outer graph의 scalar state 채널 충돌 방지
+  - 결과를 `multi_answers` reducer에만 추가
+
+#### 6. combine_answers_node (신규)
+- **위치**: `src/agent/nodes.py` 라인 1168
+- **역할**: multi_answers를 통합 Markdown 포맷으로 변환
+- **특징**: 자동 fan-in (모든 Send 완료 대기)
+
+### 수정된 노드 (1개)
+
+#### generate_answer_node (5줄 추가)
+- **위치**: `src/agent/nodes.py` 라인 726
+- **추가 내용**:
+```python
+# 기존 로직 마지막에 추가
+if state.is_multi_question:
+    updates["multi_answers"] = [{
+        "index": state.sub_question_index,
+        "question": state.sub_question_text,
+        "answer": final_answer
+    }]
+```
+
+### 그래프 재구성
+
+```python
+# src/agent/graph.py
+
+# 1. START 진입점 변경
+graph.add_edge(START, "create_plan")  # 기존: analyze_question
+
+# 2. create_plan 후 분기 추가
+graph.add_conditional_edges(
+    "create_plan",
+    route_after_plan,
+    {
+        "analyze_question": "analyze_question",
+        "initiate_dynamic_search": "initiate_dynamic_search",
+        "handle_too_many_questions": "handle_too_many_questions"
+    }
+)
+
+# 3. initiate_dynamic_search 후 fan-out
+graph.add_conditional_edges(
+    "initiate_dynamic_search",
+    fanout_multi_questions,  # List[Send] 반환
+)
+
+# 4. run_single_question_worker 후 fan-in
+graph.add_edge("run_single_question_worker", "combine_answers")
+
+# 5. generate_answer 후 분기 추가
+graph.add_conditional_edges(
+    "generate_answer",
+    route_after_generate,
+    {
+        "combine_answers": "combine_answers",
+        END: END
+    }
+)
+```
+
+## 사용 예시
+
+### 예시 1: 단일 주제 (기존 동작)
+
+```python
+from CodeWeaver.src.agent.graph import create_agent
+from langchain_core.messages import HumanMessage
+
+agent = create_agent()
+
+result = await agent.ainvoke({
+    "user_question": "React hooks 완벽 가이드",
+    "messages": [HumanMessage(content="React hooks 완벽 가이드")]
+})
+
+# 결과
+# plan.case: "single_topic"
+# plan.sub_questions: ["hooks란", "주요 hooks", "실무 패턴"]
+# 흐름: 기존 그래프 1회 실행
+# 출력: 일반 답변 형식
+```
+
+### 예시 2: 다중 독립 질문 (신규)
+
+```python
+result = await agent.ainvoke({
+    "user_question": "JWT가 뭐야? CORS 에러는 어떻게 해결해?",
+    "messages": [HumanMessage(content="JWT가 뭐야? CORS 에러는 어떻게 해결해?")]
+})
+
+# 결과
+# plan.case: "multiple_questions"
+# plan.sub_questions: ["JWT가 뭐야?", "CORS 에러는 어떻게 해결해?"]
+# 흐름: Send API로 그래프 2회 병렬 실행
+# 출력:
+```
+
+**출력 예시**:
+```markdown
+# 다중 질문 답변
+
+원본 질문: JWT가 뭐야? CORS 에러는 어떻게 해결해?
+
+---
+
+## 1. JWT가 뭐야?
+
+JWT(JSON Web Token)는 인증 정보를 안전하게 전송하기 위한...
+
+[상세 답변...]
+
+---
+
+## 2. CORS 에러는 어떻게 해결해?
+
+CORS(Cross-Origin Resource Sharing) 에러는...
+
+[상세 답변...]
+```
+
+### 예시 3: 질문 3개 이상
+
+```python
+result = await agent.ainvoke({
+    "user_question": "JWT? CORS? Docker?",
+    "messages": [HumanMessage(content="JWT? CORS? Docker?")]
+})
+
+# 결과
+# plan.case: "too_many"
+# 출력:
+```
+
+**출력 예시**:
+```
+죄송합니다. 한 번에 최대 2개의 질문까지만 처리할 수 있습니다.
+
+다음 중 하나를 선택해서 다시 질문해 주세요:
+
+1. **하나의 주제로 통합해서 질문**
+   예: "JWT 인증과 CORS 설정을 함께 구현하는 방법"
+
+2. **가장 중요한 2개 질문만 선택**
+   예: "JWT가 뭐야? 내 코드에 어떻게 적용해?"
+
+3. **질문을 나눠서 순차적으로 질문**
+   예: 먼저 "JWT가 뭐야?" 질문 → 답변 확인 → 다음 질문
+
+어떻게 도와드릴까요?
+```
+
+## 테스트
+
+테스트 파일은 프로젝트 루트에 있습니다. (삭제됨 - 필요시 재생성)
+
+### 테스트 시나리오
+
+1. ✅ **단일 주제**: "Spring Security JWT 인증 구현 방법"
+   - 기존 그래프 1회 실행
+   - multi_answers 비어있음
+   - 일반 답변 형식
+
+2. ✅ **다중 질문 2개**: "JWT가 뭐야? CORS는?"
+   - Send API로 그래프 2회 병렬 실행
+   - multi_answers에 2개 항목
+   - 섹션 구분된 통합 답변
+
+3. ✅ **질문 3개 이상**: "JWT? CORS? Docker?"
+   - handle_too_many_questions로 분기
+   - 친절한 에러 메시지
+   - 대화 계속 가능
+
+4. ✅ **엣지 케이스**: "JWT? CORS? Docker? Redis?"
+   - **하드 가드로 무조건 too_many 차단** (물음표 4개 감지)
+   - LLM 분류와 무관하게 차단 보장
+
+## 성능 고려사항
+
+### 병렬 실행
+- **단일 주제**: 3개 검색 노드 병렬 (기존)
+- **다중 질문 (2개)**: 2×3=6개 검색 노드 병렬
+- LangGraph Send API가 자동 병렬화 관리
+
+### 비용 관리
+- 질문 개수 제한: 최대 2개
+- 검색 결과 개수: 소스당 3-5개
+- 다중 질문 시 의도 분류 생략 (기본값 "learning" 사용)
+
+### 캐싱
+- **단일 주제**: 전체 답변 캐시 ✅
+- **다중 질문**: 각 서브 질문 답변 개별 캐시 ✅
+  - Q1 답변 → Q1 질문으로 캐시
+  - Q2 답변 → Q2 질문으로 캐시
+- 다음번 동일 질문 시 개별 캐시 히트 가능
+
+## 기술적 핵심
+
+### 1. Send API 패턴 (Conditional Edge 함수 사용)
+
+```python
+# ❌ 잘못된 방법: 노드에서 Send 반환
+def initiate_dynamic_search_node(state):
+    return [Send(...), Send(...)]  # 에러 발생!
+
+# ✅ 올바른 방법: conditional edge 함수에서 Send 반환
+def fanout_multi_questions(state: AgentState) -> List[Send]:
+    sends = []
+    for i, question in enumerate(sub_questions):
+        child_state = state.model_copy(deep=True)
+        child_state.user_question = question
+        sends.append(Send("run_single_question_worker", child_state))
+    return sends
+
+# 그래프 설정
+graph.add_conditional_edges(
+    "initiate_dynamic_search",
+    fanout_multi_questions,  # List[Send] 반환
+)
+
+# LangGraph가 자동으로:
+# 1. 두 Send를 병렬 실행
+# 2. 각 Send의 모든 노드 실행 대기
+# 3. 다음 공통 노드로 이동 (combine_answers)
+```
+
+### 2. Reducer 자동 병합 (Reset 기능 포함)
+
+```python
+# State 정의 (커스텀 reducer)
+multi_answers: Annotated[List[Dict[str, Any]], merge_multi_answers] = []
+
+# merge_multi_answers reducer:
+def merge_multi_answers(old: List[Dict], new: List[Dict]) -> List[Dict]:
+    if not new:
+        return old
+    # Reset 토큰 체크
+    if new[0].get("__token__") == "__RESET_MULTI_ANS__":
+        return new[1:]  # 이전 턴 누적 방지
+    return old + new  # 기본 병합
+
+# create_plan_node에서 매 실행 시작 시 리셋:
+updates["multi_answers"] = [{"__token__": "__RESET_MULTI_ANS__"}]
+
+# 병렬 실행 시:
+# [Q1_answer] + [Q2_answer] = [Q1_answer, Q2_answer]
+```
+
+### 3. Fan-in 보장
+
+```python
+# 모든 검색 노드가 collect_results로 연결
+graph.add_edge("search_stackoverflow", "collect_results")
+graph.add_edge("search_github", "collect_results")
+graph.add_edge("search_official_docs", "collect_results")
+
+# LangGraph가 자동으로:
+# 1. 3개 검색 모두 완료 대기
+# 2. collect_results 1회만 실행
+```
+
+## 코드 변경 요약
+
+### 파일별 변경사항
+
+| 파일 | 추가 | 수정 | 삭제 |
+|------|------|------|------|
+| `state.py` | 5 필드, 1 reducer 함수 | - | - |
+| `nodes.py` | 5 노드 + 1 edge 함수 (~300줄) | 2 노드 (create_plan 하드 가드 추가, generate_answer 5줄) | - |
+| `graph.py` | 3 routing 함수, 엣지 재구성 | build_agent_graph | - |
+
+**총 변경량**: ~350줄 추가, ~100줄 수정
+
+### 재사용률
+
+- **기존 노드 재사용**: 12/16 (75%)
+- **기존 로직 재사용**: ~95% (검색, 평가, 필터링, 요약 등)
+- **새로운 개념**: Send API + Reducer만
+
+## LangGraph 공식 가이드라인 준수
+
+### ✅ Graph API
+- StateGraph 사용
+- Pydantic BaseModel state
+- START/END 명시
+
+### ✅ Workflows + Agents
+- Send API로 동적 병렬화
+- Conditional edges로 라우팅
+- Fan-out/Fan-in 패턴
+
+### ✅ Thinking in LangGraph
+- 노드는 순수 함수 (한 가지 일만)
+- State는 불변 업데이트
+- Reducer로 병합 자동화
+
+## 한계 및 향후 개선
+
+### 현재 한계
+
+1. **질문 개수 제한**: 최대 2개
+   - 비용 vs 품질 트레이드오프
+   - 향후 3-4개로 확장 가능
+
+2. **캐싱 전략**: 통합 답변은 캐시 안 됨
+   - 각 서브 질문은 개별 캐시됨
+   - 동일한 다중 질문 재입력 시 개별 캐시 히트
+
+3. **Refinement 루프**: 다중 질문에서도 각각 독립적으로 작동
+   - 한 질문 refine 시 다른 질문에 영향 없음
+
+### 향후 개선 방향
+
+1. **더 많은 질문 지원**: 3-4개까지 확장
+2. **혼합 질문 감지**: "JWT가 뭐야? 그걸 Spring에 적용하려면?" (순차 의존)
+3. **스트리밍 답변**: 각 서브 질문 완료 즉시 스트리밍
+4. **우선순위**: 중요도에 따라 질문 순서 조정
+
+## 참고 자료
+
+- [LangGraph Graph API](https://docs.langchain.com/oss/python/langgraph/graph-api)
+- [LangGraph Workflows + Agents](https://docs.langchain.com/oss/python/langgraph/workflows-agents)
+- [LangGraph Thinking Guide](https://docs.langchain.com/oss/python/langgraph/thinking-in-langgraph)
+- CodeWeaver Phase 3: Open Deep Research
+
+## 문의
+
+구현 관련 질문이나 버그 리포트는 이슈로 등록해주세요.
+

README.md

@@ -1,12 +1,39 @@
 ---
-title: Codeweaver Ai
-emoji: 🔥
+title: codeweaver-ai
+emoji: 🤖
 colorFrom: blue
-colorTo: gray
+colorTo: purple
 sdk: gradio
-sdk_version: 6.1.0
+sdk_version: "4.44.1"
 app_file: app.py
 pinned: false
+license: mit
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# CodeWeaver AI (Gradio Space)
+
+CodeWeaver를 Hugging Face Spaces에서 실행하기 위한 Gradio 데모입니다.
+
+## 실행 방식
+
+- Space 엔트리: `app.py` (repo root)
+- 실제 Gradio UI: `CodeWeaver/ui/app.py`
+
+## 필수 Secrets (Settings → Variables and secrets)
+
+- `GOOGLE_API_KEY`
+- `TAVILY_API_KEY`
+- `QDRANT_URL`
+- `QDRANT_API_KEY`
+
+선택:
+
+- `GITHUB_TOKEN`
+- `LANGCHAIN_TRACING_V2`, `LANGCHAIN_API_KEY`, `LANGCHAIN_PROJECT`
+
+## 문서
+
+- `ARCHITECTURE.md`
+- `DYNAMIC_PARALLEL_SEARCH.md`
+
+

app.py

@@ -0,0 +1,40 @@
+"""
+Hugging Face Spaces entrypoint.
+
+This file is intentionally minimal:
+- It imports the existing Gradio Blocks app from `CodeWeaver/ui/app.py`
+- It launches it with HF-friendly defaults.
+
+Local dev remains unchanged:
+  - You can still run `python CodeWeaver/ui/app.py` as before.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+
+def _bootstrap_import_path() -> None:
+    # Make `CodeWeaver/` importable as a top-level path so we can `import ui.app`.
+    repo_root = Path(__file__).resolve().parent
+    codeweaver_root = repo_root / "CodeWeaver"
+    sys.path.insert(0, str(codeweaver_root))
+
+
+def main() -> None:
+    _bootstrap_import_path()
+
+    # Import AFTER sys.path tweak
+    from ui.app import app as demo  # type: ignore
+
+    # HF Spaces commonly provides PORT; fall back to 7860 for local.
+    port = int(os.getenv("PORT", "7860"))
+    demo.launch(server_name="0.0.0.0", server_port=port, show_api=False)
+
+
+if __name__ == "__main__":
+    main()
+
+

requirements.txt

@@ -0,0 +1,6 @@
+# Hugging Face Spaces installs dependencies from the repository root.
+# Reuse the project's existing dependency list.
+
+-r CodeWeaver/requirements.txt
+
+