RepoSage: 개발자를 위한 오프라인 에이전트 기반 GraphRAG 시스템

RepoSage는 개발자와 엔지니어링 팀을 위해 설계된 100% 오프라인, 에이전트 기반 GraphRAG 시스템입니다. 사용자는 로컬 디렉토리 경로 또는 GitHub 저장소 URL을 제공하여 코드베이스에 대해 자연어 질의를 할 수 있습니다. 이 시스템은 컨텍스트를 자율적으로 검색하고, 기능적 의존성을 탐색하며, 정확한 파일 경로와 라인 번호가 포함된 정밀한 답변을 생성합니다.

전통적인 Retrieval-Augmented Generation (RAG) 시스템은 임의의 문자 제한 분할과 구조적 의존성 이해 불가로 인해 복잡한 코드베이스에서 실패합니다. RepoSage는 다음 요소들을 결합하여 이러한 한계를 극복합니다:

추상 구문 트리(AST) 청킹: 코드를 임의의 텍스트 청크가 아닌 원자적인 구조 단위(함수, 클래스)로 논리적으로 파싱합니다.
지식 그래프 (GraphRAG): 함수 호출 의존성이 수집 시점에 매핑됩니다. 검색 중에는 엔진이 호출자와 피호출자의 컨텍스트를 동적으로 주입하여 누락된 의존성 환각(hallucinations)을 사실상 제거합니다.
자율 에이전트 워크플로우: LangGraph로 구동되는 질의 엔진은 자율적으로 작동하며, 시맨틱 검색을 실행하고 추가 컨텍스트가 필요할 경우 특정 파일을 선제적으로 읽습니다.
실시간 SSE 스트리밍: Server-Sent Events (SSE)를 사용하여 답변을 토큰 단위로 현대적이고 애니메이션이 적용된 React 프론트엔드로 직접 스트리밍합니다.

RepoSage는 전적으로 로컬에서 작동하며, 추론 모델(예: qwen3:4b 또는 qwen2.5-coder:7b)을 실행하는 Ollama를 활용하여 독점 코드베이스에 대한 절대적인 개인 정보를 보장합니다.

최첨단 애니메이션 프론트엔드: React, Vite, Tailwind CSS, Framer Motion 및 스프링 물리 차트, 기술적 모의 터미널, 접이식 대시보드 사이드바를 사용하여 재구축되었습니다.
더블 모드 질의 엔진:

• 표준 RAG 모드 (SSE 스트리밍): /query/stream에 연결합니다.

거의 즉각적이고 스트리밍되는 토큰 응답을, 인라인 소스 태그와 함께 제공합니다.

Agent Mode (에이전트 모드): LangGraph를 활용하여 반복적인 도구 실행(semantic_search 및 read_file)을 통해 복잡한 코드베이스 질의를 능동적으로 조사합니다.

병렬 하이브리드 검색 (Parallelized Hybrid Search): Python의 ThreadPoolExecutor를 사용하여 밀집 벡터 검색(ChromaDB)과 어휘 키워드 매칭(BM25)을 병렬로 실행하여 I/O 지연 시간을 1초 미만으로 줄입니다.

빠른 인제스천 순회 (Fast Ingestion Traversal Walk): 파일 글롭핑(file globbing) 대신 os.walk를 사용하여 제외 디렉토리(.git, node_modules, .venv 등)를 건너뛰고 제자리에서 처리함으로써 리포지토리 색인화 속도를 극적으로 높였습니다.

문맥적 검색 (Contextual Retrieval, Anthropic 패턴): 파일 수준의 요약을 자동 생성하여 개별 청크에 앞에 붙여 넣어, 마이크로 레벨 검색 내에서도 매크로 레벨의 문맥을 보존합니다.

캐시 가속화 요약 (Cache-Accelerated Summaries): 높은 수준의 리포지토리 요약(summary_cache.json)을 캐싱하여 이후 대시보드 로드 시 LLM 분석 실행을 건너뜁니다.

정밀 인용 배지 (Precision Citation Badges): 채팅 창에 파일명:줄번호 형식의 상호작용 가능한 배지로 검증 가능한 출처 위치를 표시합니다.

질의 확장 토글 (Query Expansion Toggle): ENABLE_QUERY_EXPANSION=false로 설정하여 추론 모델의 질의 확장을 건너뛰고, 로컬 환경에서 질의 실행 속도를 높입니다.

graph TD
A[소스 코드 <br/> GitHub 또는 로컬] --> B[언어 인식 파서]
B -->|Python AST| C[청크 빌더]
...

출처 해결 (Source Resolution): 공개 GitHub URL(GitPython을 통해 클론) 또는 로컬 폴더를 받습니다.
가지치기된 인제스천 순회 (Pruned Ingestion traversal): os.walk가 제외 디렉토리(node_modules, .git, .venv)를 무시하고 파일을 순회하면서 스캔하기 전에 처리하여, 디스크 작업을 최적화합니다.
언어 인식 파싱 (Language-Aware Parsing): 파일은 구조적 단위를 추출하기 위해 파싱됩니다. Python은 ast를 사용하고 JavaScript/TypeScript는 정규 표현식 패턴을 사용합니다.
그래프 구성 (Graph Construction): 함수 선언 및 호출(ast.Call)의 NetworkX 방향 그래프를 구성합니다.

)).Context 주입 및 벡터 영속성 (Vector Persistence): 파일 요약을 계산하여 개별 청크에 추가하고, 이 청크들은 임베딩되어 호출 그래프와 함께 ChromaDB에 저장됩니다.

graph TD
Q[사용자 질의] --> M{모드 선택}
M -->|표준 RAG(Standard RAG)| S[SSE Stream /query/stream]
...

스트리밍 SSE (표준 RAG): /query/stream으로 질의를 직접 전송하며, 이는 컨텍스트를 검색하고, 그래프 순회(graph traversal)를 실행하며, 토큰을 클라이언트로 즉시 스트리밍합니다.에이전트 추론 (Agent Mode): LangGraph 워크플로우가 Ollama를 제어하여 의미론적 검색(semantic searches)을 수행하고 read_file 도구를 반복적으로 호출하여 코드 파일을 조사합니다.병렬 검색 (Parallel Retrieval): BM25와 ChromaDB 조회가 별도의 스레드에서 병렬로 실행되며, Reciprocal Rank Fusion (RRF)을 통해 병합되어 총 검색 시간을 1초 미만으로 유지합니다.출처 인용 (Source citations): 인라인 출처가 실시간으로 UI에 전달되고 렌더링됩니다.

Python 3.11 이상 Node.js 18 이상 (프론트엔드용) Ollama 로컬 실행 Git

필요한 모델은 Ollama를 통해 가져옵니다. 기본적으로 RepoSage는 추론에 qwen3:4b 또는 qwen2.5-coder:7b를 사용하고, 임베딩에는 nomic-embed-text를 사용합니다.

olllama pull qwen3:4b
olllama pull nomic-embed-text

환경 템플릿을 복사합니다:

cp .env.example .env

변수를 검토하고 조정합니다:

# 필수: Ollama 기본 URL
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=qwen3:4b
...

가상 환경을 구성하고 포트 8000에서 FastAPI를 시작합니다.

:

cd backend
python -m venv .venv
# 환경 활성화:
...

새 터미널 창에서 종속성을 설치하고 포트 5173에서 Vite 개발 서버를 시작합니다.

:

cd frontend
npm install
npm run dev

브라우저에서 **http://localhost:5173**으로 이동합니다.

Docker Compose는 프론트엔드와 백엔드를 격리된 컨테이너에서 실행합니다.

환경 변수 설정: .env 파일에

파일의 백엔드 컨테이너를 호스트 머신의 Ollama 인스턴스로 지정합니다:
Windows/macOS:
OLLAMA_BASE_URL=http://host.docker.internal:11434<br>CHROMA_PERSIST_DIR=/app/chroma_db<br><br>Linux:
브리지 IP(일반적으로 http://172.17.0.1:11434)를 지정합니다.

Ollama가 외부 네트워크 요청을 받을 수 있도록 호스트 환경 변수 OLLAMA_HOST=0.0.0.0을 설정하고 Ollama를 재시작해야 합니다. -
컨테이너 시작:
docker compose up -d --build<br><br>서비스 접속:
프론트엔드 앱:
http://localhost:5173<br><br>백엔드 API 문서:
http://localhost:8001/docs<br><br>(참고: 백엔드 컨테이너는 호스트 시스템의 포트 8001에 매핑됩니다.)
백엔드 상태 확인:
http://localhost:8001/health<br><br>```
reposage/
├── backend/
│ ├── main.py # FastAPI 애플리케이션 진입점
...

<br>백엔드 pytest 스위트를 실행합니다:
`python -m pytest backend/tests/ -v`<br><br>이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 LICENSE 파일을 참조하십시오.