ttguy0707/IRIS

IRIS는 Agentic Workflow(에이전트 워크플로우) 기반의 자동화된 심층 조사 및 보고서 생성 시스템입니다. 이 시스템은 전통적인 단방향 RAG(Retrieval-Augmented Generation, 검색 증강 생성)의 선형적 질의응답 모드를 탈피하여, 다중 노드 상태 머신(State Machine)을 구축함으로써 의도 인식, 경로 계획, 동적 검색(하이브리드/로컬), 심층 작성부터 자기 검토 및 부분 미세 조정에 이르는 전 자동 폐쇄 루프(Closed-loop)를 구현했습니다.

🧠

Agentic 워크플로우 엔진 (Powered by LangGraph)

• 전통적인 체인 방식(LCEL) 호출 대신 그래프 기반(Graph-based) 구조를 채택하여 복잡한 조건 분기 및 순환 흐름을 지원합니다.

• Router(라우터), Planner(플래너), Researcher(리서처), Writer(라이터), Reviewer(리뷰어), Refiner(리파이너) 등 이기종 노드들이 내장되어 협업합니다.

🛡️

환각 방지 및 동적 라우팅 (Relevance Grader)

• 전통적인 RAG의 "강제 답변/환각" 페인 포인트를 해결합니다. 로컬 문서 검색 후, 경량급 심판 노드(Grader LLM)가 문서와 질문의 관련성을 실시간으로 평가합니다.

• 사용자가 업로드한 문서가 질문과 관련이 없다고 판단되면, 시스템은 자동으로 차단 메커니즘(순수 문서 모드에서 중단 및 경고) 또는 지능적 강등(하이브리드 모드에서 전체 웹 검색으로 자동 전환)을 트리거합니다.

🔄

세션 레벨 메모리 및 중단점 재개 (Session-Level Persistence)

• AsyncSqliteSaver(SQLite Checkpoint 메커니즘)를 도입하여 단일 세션 레벨의 지속성을 구현합니다.

• 전단의 **의도 인식 노드 (Intent Router)**와 결합하여, 시스템은 "새로운 연구 주제 시작"과 "기존 보고서에 대한 수정 명령 수행"("제1장을 더 쉽게 확장해줘" 등)을 정확히 구분하며, 교차 턴(Cross-turn)의 중단점 재개 및 부분 미세 조정을 실현합니다. 페이지를 새로고침할 때마다 새로운 익명 세션이 시작됩니다.

⚡

전체 비동기 아키텍처 및 스트리밍 (Asynchronous & SSE)

• 백엔드는 FastAPI를 기반으로 전체 비동기(async/await) 아키텍처를 채택하여, LLM 노드 스케줄링과 SQLite의 동시 읽기/쓰기를 블로킹 없이 처리합니다.

• Server-Sent Events (SSE) 기술을 사용하여 Agent의 내부 상태 흐름과 최종 보고서의 타이핑 효과(Typewriter)를 프론트엔드로 저지연 전송합니다.

🎨

현대적인 인터랙션 경험 (Modern UI/UX)

• 프론트엔드는 Vue 3 + Tailwind CSS로 구축되었으며, iOS Siri 스타일의 "호흡하는" 사고 애니메이션을 포함합니다.

• markdown-it 및 KaTeX를 깊이 있게 통합하였으며, 하위 레벨의 정규식 전처리를 통해 서로 다른 대규모 언어 모델(LLM) 간의 LaTeX 구분자 불일치 문제를 해결하여 고난도 수학 공식을 완벽하게 렌더링합니다.

User Input
↓
Intent Router
...

Backend (백엔드)

• API 프레임워크: Python 3.10+, FastAPI
• Agent 아키텍처: LangChain, LangGraph
• 벡터 검색: ChromaDB (로컬 지식 베이스 RAG)
• 지속성 저장소: SQLite (aiosqlite 비동기 드라이버 지원, Checkpointing)
• 핵심 LLM: OpenAI API (GPT-4o, GPT-4o-mini)
• 웹 검색: Tavily Search API

Frontend (프론트엔드)

• 핵심 프레임워크: Vue 3 (Composition API)
• UI 스타일: Tailwind CSS, @tailwindcss/typography
• 콘텐츠 렌더링: markdown-it, markdown-it-katex

git clone https://github.com/ttguy0707/IRIS.git
cd IRIS

cd backend
# 1. 가상 환경 생성 및 활성화 (강력 권장)
python -m venv venv
...

(서비스 실행 후, Swagger API 디버깅 문서는 http://localhost:8000/docs를 통해 접속 가능합니다)

cd ../frontend
# 1. Node.js 의존성 설치
npm install
...

(브라우저를 열고 터미널에 표시된 http://localhost:5173 에 접속하여 사용을 시작하세요)

IRIS/
├── backend/
│ ├── app/
...

IRIS를 구축하는 과정에서 가장 큰 도전 과제는 전통적인 대규모 언어 모델(LLM) 블랙박스 호출의 제어 불가능성을 어떻게 깨뜨릴 것인가였습니다.

**LangGraph 상태 머신 (State Machine)**을 도입함으로써, 시스템은 실행 과정에서 "성찰 (Reflection)" 및 "동적 오류 수정 (Dynamic Error Correction)" 능력을 갖추게 되었습니다. 또한 AsyncSqliteSaver를 도입하여 무상태 (Stateless) API의 고질적인 문제를 완벽히 해결했습니다. 이는 에이전트 (Agent)가 문맥을 이해하고 사용자의 "수정 요청 (Rejection/Revision)" 명령을 수용할 수 있게 할 뿐만 아니라, 복잡한 학술 조사 시나리오에서의 강건성 (Robustness)을 대폭 향상시켰습니다. 본 프로젝트는 에이전틱 시스템 (Agentic System)의 하위 실행 메커니즘, 동시성 제어 (Concurrency Control), 그리고 프론트엔드-백엔드 간의 스트리밍 상호작용 (Streaming Interaction)에 대한 심도 있는 엔지니어링 실무 사례입니다.