CodeWeaver/README.md

metadata

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/ 디렉터리 기준 예시입니다.

cd CodeWeaver

# uv 사용(권장)
uv sync

# 또는 pip 사용
pip install -r requirements.txt

sentence-transformers가 최초 실행 시 BAAI/bge-m3 모델을 다운로드할 수 있습니다(네트워크 필요).

2) 환경 변수 설정(.env)

CodeWeaver/.env 파일을 만들고 아래를 설정하세요(필수/선택 구분).

# 필수: 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)

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