CodeWeaver/README.md

---
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`를 참고하세요.