FactWave 🌊

AI 기반 다중 에이전트 실시간 팩트체킹 시스템

FactWave는 CrewAI 오케스트레이션을 활용하여 5개의 전문 AI 에이전트가 협업하는 3단계 검증 시스템입니다. 실시간 WebSocket 통신과 Chrome 확장 프로그램을 통해 웹 브라우징 중 즉시 정보 검증이 가능합니다.

✨ 주요 특징

🤖 5개 전문 에이전트: 학술(25%), 뉴스(30%), 통계(20%), 논리(15%), 소셜(10%) 가중치 기반 협업
⚡ 실시간 스트리밍: WebSocket 기반 분석 과정 실시간 모니터링
🎯 3단계 검증 파이프라인: 독립 분석 → 구조화된 토론 → 최종 종합
🌐 Chrome 사이드 패널: Manifest V3 기반 450x600px 확장 프로그램
📊 10+ 전문 연구 도구: 학술 논문, 뉴스, 통계 데이터, SNS 트렌드 통합 분석
🧠 RAG 시스템: 40+ OWID 데이터셋 사전 인덱싱된 ChromaDB 벡터 검색
🌍 다국어 지원: 한국어 우선, 영어 보조 지원

🏗️ 시스템 아키텍처

3단계 협업 검증 파이프라인

[입력 진술] → [Step 1: 독립 분석] → [Step 2: 구조화된 토론] → [Step 3: 최종 종합] → [검증 결과]

Step 1: 독립적 초기 분석

각 에이전트가 자신의 전문 도구를 활용하여 독립적으로 분석:

에이전트	가중치	전문 도구	캐싱 전략
📚 학술 에이전트	25%	OpenAlex (240M+ 논문), ArXiv, Wikipedia, Tavily	72시간
📰 뉴스 에이전트	30%	Naver News, NewsAPI (80K+ 언론사), Google Fact Check	1시간
📊 통계 에이전트	20%	KOSIS, FRED, World Bank, OWID RAG	72시간
🤔 논리 에이전트	15%	순수 논리 분석 (도구 미사용)	-
👥 소셜 에이전트	10%	Twitter API (twscrape), YouTube	30분

Step 2: 구조화된 토론

모든 에이전트가 Step 1 결과를 공유하고 상호 검토
외부 도구 없이 순수 토론과 분석
다른 관점을 고려한 의견 개선 및 반박

Step 3: 최종 종합

Super Agent가 모든 분석 종합
가중 신뢰도 매트릭스 생성
최종 판정 및 상세 근거 제시

🚀 빠른 시작

1. 프로젝트 클론

git clone <repository-url>
cd FactWave

2. 백엔드 설정

cd backend
pip install -e .  # 또는 uv pip install -e . (더 빠름)

# 환경변수 설정
cp example.env .env
# .env 파일에 필수 API 키 추가

3. 프론트엔드 설정

cd frontend
npm install

4. 실행

백엔드 서버 (터미널 1):

cd backend
python -m app.api.server  # FastAPI WebSocket 서버 (포트 8000)

프론트엔드 개발 서버 (터미널 2):

cd frontend
npm run dev  # Vite 개발 서버 (포트 5173)

5. Chrome 확장 프로그램 설치

Chrome에서 chrome://extensions/ 열기
"개발자 모드" 활성화
"압축 해제된 확장 프로그램 로드" 클릭
frontend/dist 폴더 선택

📁 프로젝트 구조

백엔드 아키텍처

backend/
├── app/
│   ├── agents/                    # AI 에이전트 시스템
│   │   ├── base.py               # FactWaveAgent 기본 클래스
│   │   ├── academic_agent.py     # 학술 연구 전문가
│   │   ├── news_agent.py         # 뉴스 검증 전문가
│   │   ├── statistics_agent.py   # 통계 데이터 전문가
│   │   ├── logic_agent.py        # 논리 검증 전문가
│   │   ├── social_agent.py       # 소셜 미디어 전문가
│   │   └── super_agent.py        # 최종 종합 코디네이터
│   │
│   ├── services/tools/            # 도메인별 연구 도구
│   │   ├── base_tool.py          # EnhancedBaseTool (캐싱, 재시도)
│   │   ├── academic/             # 학술 도구
│   │   │   ├── arxiv_tool.py
│   │   │   ├── openalex_tool.py
│   │   │   └── wikipedia_tool.py
│   │   ├── news/                 # 뉴스 도구
│   │   │   ├── naver_news_tool.py
│   │   │   ├── newsapi_tool.py
│   │   │   └── factcheck_google_tool.py
│   │   ├── statistics/           # 통계 도구
│   │   │   ├── kosis_search_tool.py
│   │   │   ├── fred_search_tool.py
│   │   │   ├── worldbank_search_tool.py
│   │   │   └── owid_enhanced_rag.py
│   │   ├── community/            # 커뮤니티 도구
│   │   │   ├── twitter_tool.py
│   │   │   └── youtube_tool.py
│   │   └── verification/         # 검증 도구
│   │       ├── ai_image_detector.py
│   │       └── youtube_video_analyzer.py
│   │
│   ├── core/
│   │   ├── crew.py               # FactWaveCrew 메인 오케스트레이터
│   │   └── streaming_crew.py     # WebSocket 스트리밍 지원
│   │
│   ├── api/
│   │   └── server.py             # FastAPI WebSocket 서버
│   │
│   ├── config/
│   │   └── prompts.yaml          # 중앙화된 프롬프트 관리
│   │
│   └── utils/
│       ├── llm_config.py         # LLM 설정 (GPT-4.1-mini)
│       ├── prompt_loader.py      # 동적 프롬프트 로딩
│       └── websocket_manager.py  # WebSocket 이벤트 관리
│
├── owid_enhanced_vectordb/        # ChromaDB 벡터 데이터베이스
└── owid_datasets/                 # 40+ OWID 데이터셋

프론트엔드 구조

frontend/
├── manifest.json                  # Chrome Extension Manifest V3
├── background.js                  # Service Worker
├── src/
│   ├── App.jsx                   # 메인 앱 컴포넌트
│   ├── components/
│   │   ├── Discussion.jsx        # 토론 탭 (실시간 팩트체킹)
│   │   ├── Results.jsx           # 결과 탭 (검증 결과 표시)
│   │   ├── Library.jsx           # 라이브러리 탭 (저장된 검증)
│   │   ├── LoadingMessage.jsx    # 로딩 애니메이션
│   │   ├── ImageAnalysisResult.jsx
│   │   └── YouTubeThumbnail.jsx
│   └── utils/
│       └── youtube.js             # YouTube 유틸리티

🛠️ 핵심 구현 세부사항

에이전트 시스템

기본 클래스: FactWaveAgent - 모든 에이전트의 부모 클래스
Step별 LLM: GPT-4.1-mini 사용, 단계별 온도/토큰 최적화
도구 로깅: 실시간 도구 사용 모니터링 및 결과 추적
독립 실행: Step 1에서 개별 Crew 인스턴스로 독립성 보장

연구 도구 특징

EnhancedBaseTool: 모든 도구의 기본 클래스
MD5 캐싱: 도구별 TTL 설정 (학술: 72h, 뉴스: 1h, 소셜: 30m)
HTTP 재시도: 지수 백오프로 안정성 확보
속도 제한: API별 rate limiting 자동 관리
우아한 실패: 도구 실패 시 시스템 중단 없이 계속 진행

RAG 시스템 (OWID)

ChromaDB: 영구 벡터 저장소
40+ 데이터셋: 기후, 경제, 건강, 교육 등 사전 인덱싱
하이브리드 검색: 벡터 유사도 + BM25 순위
메타데이터 필터: 카테고리, 날짜, 국가별 필터링

WebSocket 통신 프로토콜

// 클라이언트 → 서버
{"action": "start", "statement": "검증할 문장"}

// 서버 → 클라이언트
{
  "type": "task_started|task_completed|agent_analysis|tool_call|final_result",
  "step": "step1|step2|step3",
  "agent": "academic|news|logic|social|statistics|super",
  "content": {...},
  "timestamp": "ISO 8601"
}

프롬프트 관리 (prompts.yaml)

중앙화된 관리: 모든 에이전트 프롬프트 YAML 파일 관리
핫 리로딩: 시스템 재시작 없이 프롬프트 수정 가능
Step별 템플릿: 단계별 맞춤형 프롬프트
판정 옵션: 13가지 세분화된 판정 카테고리

🛠️ 기술 스택

백엔드

Python 3.12+ / UV 패키지 관리자
FastAPI - WebSocket API 서버
CrewAI - 멀티 에이전트 오케스트레이션 프레임워크
OpenAI GPT-4.1-mini - 메인 LLM (모든 Step에서 사용)
ChromaDB - 벡터 데이터베이스 (OWID RAG 시스템)
Pydantic - 구조화된 응답 스키마 검증
Rich - 터미널 UI 및 로깅 시각화

프론트엔드

React 19.1.0 - 최신 UI 프레임워크
Vite - 차세대 번들러
Tailwind CSS - 유틸리티 기반 스타일링
Chrome Extension Manifest V3 - 최신 확장 프로그램 표준
Service Worker - 백그라운드 처리

연구 도구 API

OpenAlex - 240M+ 학술 논문 (API키 불필요)
ArXiv - 수학/물리/CS 프리프린트 논문
Naver News API - 한국 뉴스 검색
NewsAPI - 80,000+ 글로벌 언론사
Google Fact Check API - ClaimReview 팩트체크 데이터베이스
Wikipedia API - 다국어 백과사전
KOSIS API - 한국 통계청
FRED API - 미국 연방준비제도 경제 데이터
World Bank API - 세계은행 개발 지표
Twitter API (twscrape) - 소셜 미디어 트렌드

🧪 테스트 및 개발

테스트 실행

# WebSocket 클라이언트 테스트
cd backend
python test_websocket_client.py

# 개별 도구 테스트
python tests/test_tavily.py
python tests/test_tool_usage.py
python tests/test_youtube_tool.py

# 유닛 테스트 전체 실행
python -m pytest tests/

# CLI 인터페이스 테스트
python main.py

개발 워크플로우

# 백엔드 개발
cd backend
python -m app.api.server  # 포트 8000에서 서버 시작

# 프론트엔드 개발  
cd frontend
npm run dev  # 포트 5173에서 개발 서버 시작
npm run build  # 프로덕션 빌드
npm run build:watch  # 빌드 감시 모드

# 코드 품질 관리
cd backend
ruff check .    # 린팅 검사
ruff format .   # 코드 포매팅
cd frontend
npm run lint    # ESLint 검사

성능 최적화 팁

캐시 관리: .cache/ 디렉토리 정기 정리
벡터 DB 재구성: python build_owid_index.py (데이터셋 업데이트 시)
도구별 TTL: 학술(72h), 뉴스(1h), 소셜(30m)로 최적화
동시 실행: Step 1에서 5개 에이전트 병렬 처리

🌍 사용 시나리오

1. 뉴스 기사 검증

입력: "2024년 한국 GDP 성장률이 3.2%를 기록했다"

📰 뉴스 에이전트: 최신 경제 뉴스 검색
📊 통계 에이전트: KOSIS, FRED 경제 지표 확인
🤔 논리 에이전트: 수치의 합리성 분석

2. 과학적 주장 검증

입력: "비타민 C가 감기를 예방한다는 연구 결과가 발표되었다"

📚 학술 에이전트: ArXiv, OpenAlex 논문 검색
📰 뉴스 에이전트: 의학 뉴스 및 팩트체크 결과
🤔 논리 에이전트: 과학적 방법론 평가

3. 소셜 트렌드 검증

입력: "최근 젊은층 사이에서 환경 보호 관심이 급증했다"

👥 소셜 에이전트: Twitter 트렌드 분석
📊 통계 에이전트: 환경 관련 통계 데이터
📰 뉴스 에이전트: 환경 관련 보도 현황

📊 13가지 판정 카테고리

✅ 사실 계열

참: 확실하게 사실 (95-100% 신뢰도)
대체로_참: 대부분 사실 (75-95% 신뢰도)
부분적_참: 일부만 사실 (50-75% 신뢰도)

❓ 판단 어려움 계열

불확실: 증거 부족으로 판단 어려움
정보부족: 검증할 충분한 정보 없음
논란중: 전문가들 사이에 의견 분분

❌ 거짓 계열

부분적_거짓: 일부가 거짓 (25-50% 거짓)
대체로_거짓: 대부분 거짓 (5-25% 사실)
거짓: 확실하게 거짓 (0-5% 사실)

⚠️ 기타 계열

과장됨: 사실이지만 과장된 표현
오해소지: 오해의 여지가 있는 표현
맥락오류: 맥락에서 벗어난 주장
시대착오: 과거에는 맞았지만 현재는 부정확

🔑 API 키 설정

필수 API 키

# .env 파일에 추가
OPENAI_API_KEY=your_openai_api_key  # GPT-4.1-mini 사용
NAVER_CLIENT_ID=your_naver_client_id
NAVER_CLIENT_SECRET=your_naver_client_secret

선택적 API 키 (고도화 기능)

# 국제 뉴스 확장
NEWSAPI_KEY=your_newsapi_key

# Google 팩트체크 데이터베이스
GOOGLE_API_KEY=your_google_api_key

# 경제 통계 데이터  
FRED_API_KEY=your_fred_key

# 한국 통계청
KOSIS_API_KEY=your_kosis_key

# 소셜 미디어 분석 (고급 기능)
# Twitter 계정 설정은 TWITTER_ACCOUNTS_GUIDE.md 참조

📚 추가 문서

CLAUDE.md - Claude Code 개발 가이드
SETUP_GUIDE.md - 상세 설치 가이드
backend/docs/ - 백엔드 API 문서
backend/TWITTER_ACCOUNTS_GUIDE.md - Twitter 계정 설정

🤝 기여하기

Fork the repository
Create feature branch (git checkout -b feature/AmazingFeature)
Commit changes (git commit -m 'Add some AmazingFeature')
Push to branch (git push origin feature/AmazingFeature)
Open Pull Request

📝 라이선스

MIT License - LICENSE 파일 참조

🙏 감사의 말

CrewAI - 멀티 에이전트 오케스트레이션
OpenAlex - 오픈 학술 논문 데이터베이스
Our World in Data - 글로벌 통계 데이터
모든 오픈소스 기여자들

FactWave - AI 협업으로 진실을 밝히다 🌊

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
backend		backend
frontend		frontend
mobile		mobile
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
README.md		README.md
SETUP_GUIDE.md		SETUP_GUIDE.md
example.env		example.env

firepool7030/FactWave

Folders and files

Latest commit

History

Repository files navigation

FactWave 🌊

✨ 주요 특징

🏗️ 시스템 아키텍처

3단계 협업 검증 파이프라인

Step 1: 독립적 초기 분석

Step 2: 구조화된 토론

Step 3: 최종 종합

🚀 빠른 시작

1. 프로젝트 클론

2. 백엔드 설정

3. 프론트엔드 설정

4. 실행

5. Chrome 확장 프로그램 설치

📁 프로젝트 구조

백엔드 아키텍처

프론트엔드 구조

🛠️ 핵심 구현 세부사항

에이전트 시스템

연구 도구 특징

RAG 시스템 (OWID)

WebSocket 통신 프로토콜

프롬프트 관리 (prompts.yaml)

🛠️ 기술 스택

백엔드

프론트엔드

연구 도구 API

🧪 테스트 및 개발

테스트 실행

개발 워크플로우

성능 최적화 팁

🌍 사용 시나리오

1. 뉴스 기사 검증

2. 과학적 주장 검증

3. 소셜 트렌드 검증

📊 13가지 판정 카테고리

✅ 사실 계열

❓ 판단 어려움 계열

❌ 거짓 계열

⚠️ 기타 계열

🔑 API 키 설정

필수 API 키

선택적 API 키 (고도화 기능)

📚 추가 문서

🤝 기여하기

📝 라이선스

🙏 감사의 말

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages