Text-to-SQL 멀티 에이전트 시스템 (Multi-Agent System): LangGraph와 LangChain을 기반으로 구축된 멀티 에이전트 RAG (Retrieval-Augmented Generation) 시스템을 사용하여 자연어 질문을 SQL 쿼리로 변환하는 전문적인 웹 애플리케이션입니다. 🎯 주요 기능

채팅 세션 (Chat Sessions): 여러 개의 독립된 채팅 세션을 생성하고 관리합니다.
CSV 업로드 (CSV Upload): CSV 파일을 업로드하면 자동으로 쿼리 가능한 데이터베이스로 변환됩니다.
Text-to-SQL: 평이한 영어로 질문하면 다음을 제공합니다:

생성된 SQL 쿼리
깔끔한 테이블 형식의 쿼리 결과
비기술적 사용자를 위한 간단한 설명

멀티 에이전트 아키텍처 (Multi-Agent Architecture): 스키마 분석, SQL 생성 및 쿼리 실행을 위한 특화된 에이전트들이 LangGraph를 사용합니다.

🛠️ 기술 스택 (Technology Stack)
백엔드 (Backend)

FastAPI - REST API 프레임워크
LangChain - LLM (Large Language Model) 통합 및 도구 관리
LangGraph - 멀티 에이전트 오케스트레이션 (Orchestration) 및 워크플로우
SQLite - 각 세션별 인메모리 데이터베이스
Ollama - LLM 제공자 (Claude 3.5 Sonnet)

프론트엔드 (Frontend)

HTML/CSS/JavaScript - 깔끔하고 전문적인 인터페이스
Vanilla JS - 단순함을 위해 프레임워크 미사용

📋 사전 요구 사항 (Prerequisites)

Python 3.8 이상
Ollama (여기에서 받으세요)
VSCode (권장) 또는 기타 코드 에디터

🚀 설치 단계 (Installation Steps)
1단계: 프로젝트 구조 생성
VSCode를 열고 다음과 같은 폴더 구조를 생성합니다:
text-to-sql-app/
├── backend/
│ ├── main.py
│ ├── agents.py
│ ├── database.py
│ ├── models.py
│ ├── requirements.txt
│ └── .env
├── frontend/
│ ├── index.html
│ ├── styles.css
│ └── script.js
└── README.md

2단계: 백엔드 설정

VSCode에서 터미널을 엽니다 (Ctrl + ~ 또는 Cmd + ~)
backend 폴더로 이동합니다:

bash cd backend

가상 환경을 생성합니다:

bash # Windows
python -m venv venv
venv\Scripts\activate

macOS/Linux

python3 -m venv venv
source venv/bin/activate

의존성을 설치합니다:

bash pip install -r requirements.txt

.env 파일을 생성하고 사용 중인 Ollama 버전을 추가합니다: OLLAMA_MODEL=llama3.2

Step 3: 백엔드 실행

가상 환경 (virtual environment)이 활성화된 상태에서 backend 폴더로 이동하여 다음을 실행합니다:

python main.py

다음 메시지가 표시되어야 합니다:
INFO: Uvicorn running on http://0.0.0.0:8006

이 터미널을 계속 실행 상태로 유지하세요!

Step 4: 프론트엔드 실행

VSCode에서 새 터미널을 엽니다 (Ctrl + Shift + ~).
frontend 폴더로 이동합니다:

cd frontend

간단한 HTTP 서버를 시작합니다:

옵션 A - Python (권장):

# Python 3
python -m http.server 3006

# Python 2
python -m SimpleHTTPServer 3006

옵션 B - Node.js (설치되어 있는 경우):

npx http-server -p 3006

옵션 C - VS Code 확장 프로그램:

1. "Live Server" 확장 프로그램을 설치합니다.
2. index.html 파일을 마우스 오른쪽 버튼으로 클릭합니다.
3. "Open with Live Server"를 선택합니다.

브라우저를 열고 다음 주소로 접속합니다:

http://localhost:3006

📱 사용 방법

• 세션 생성하기

1. 사이드바에서 "+ New Session"을 클릭합니다.
2. 이름(예: "Customer Analysis")을 입력합니다.
3. "Create"를 클릭합니다.

• CSV 파일 업로드하기

1. "📁 Upload CSV" 버튼을 클릭합니다.
2. CSV 파일을 선택하거나 드래그 앤 드롭합니다.
3. 업로드 확인 메시지가 뜰 때까지 기다립니다.

• 질문하기

1. 일반적인 영어 문장으로 질문을 입력합니다 (예: "How many customers are from London?").
2. Enter를 누르거나 Send를 클릭합니다.
3. 생성된 SQL 쿼리 (SQL query), 결과, 그리고 설명을 확인합니다.

• 시도해 볼 만한 질문 예시

• 데이터셋에 총 몇 개의 행(rows)이 있나요?

• 총 구매액 기준 상위 5명의 고객은 누구인가요?

• 지난달의 모든 주문 내역을 보여주세요

• 제품의 평균 가격은 얼마인가요?

• 고객이 가장 많은 도시는 어디인가요?

• 제품 카테고리별 총 매출을 계산하세요

🏗️ 아키텍처 개요 (Architecture Overview)
┌─────────────────────────────────────────────────────────────┐
│ Frontend (Browser) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │
│ │ │ Sidebar │ │ Chat Area │ │ Upload Modal │ │
│ │ │ (Sessions) │ │ (Q&A + SQL) │ │ (CSV Upload) │ │
│ │ └──────────────┘ └──────────────┘ └──────────────────┘ │
│ └─────────────────────────────────────────────────────────────┘
↓ HTTP/REST
┌─────────────────────────────────────────────────────────────┐
│ FastAPI Backend │
│ │ │ ┌─────────────────────────────────────────────────────┐ │
│ │ │ │ LangGraph Multi-Agent Workflow │ │
│ │ │ │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────┐ │
│ │ │ │ │ │ │ Agent 1: │→ │ Agent 2: │→ │ Agent 3: │ │
│ │ │ │ │ │ │ Schema │ │ SQL │ │ Explain │ │
│ │ │ │ │ │ │ Analyzer │ │ Generator │ │ Query │ │
│ │ │ │ │ │ │ │ │ │ └──────────────┘ └──────────────┘ └──────────┘ │
│ │ └─────────────────────────────────────────────────────┘ │
│ │ ↓ │
│ │ ┌─────────────────────────────────────────────────────┐ │
│ │ │ Session Manager + SQLite In-Memory Databases │ │
│ │ └─────────────────────────────────────────────────────┘ │
│ └─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ Ollama version OLLAMA_MODEL=llama3.2 │
└─────────────────────────────────────────────────────────────┘

🤖 멀티 에이전트 시스템 설명 (Multi-Agent System Explained)
이 시스템은 세 개의 특화된 에이전트를 순차적으로 사용합니다:

Schema Analyzer Agent (스키마 분석 에이전트)

• 데이터베이스 구조를 분석합니다
• 관련 테이블과 컬럼을 식별합니다
• 데이터 타입(data types)과 제약 조건(constraints)을 이해합니다

SQL Generator Agent (SQL 생성 에이전트)

• 질문을 바탕으로 SQL 쿼리를 생성합니다
• 적절한 SQLite 구문을 사용합니다
• 쿼리가 실행 가능한지 확인합니다

Query Explainer Agent (쿼리 설명 에이전트)

SQL 쿼리를 쉬운 용어로 설명합니다
비기술적 사용자도 이해할 수 있게 만듭니다
결과에 대한 문맥(Context)을 제공합니다

🔧 API 엔드포인트 (API Endpoints)

Method	Endpoint	Description
POST	/sessions	새로운 세션 생성
GET	/sessions	모든 세션 조회
GET	/sessions/{id}	특정 세션 조회
DELETE	/sessions/{id}	세션 삭제
POST	/sessions/{id}/upload	CSV 파일 업로드
POST	/sessions/{id}/question	질문하기
GET	/sessions/{id}/messages	채팅 기록 조회

📊 테스트를 위한 샘플 CSV 파일

customers.csv라는 파일을 생성하세요:

customer_id,name,city,country,total_purchases
1,John Smith,London,UK,1500
2,Jane Doe,Paris,France,2300
3,Bob Johnson,London,UK,890
4,Alice Brown,Berlin,Germany,3200
5,Charlie Davis,Paris,France,1100

이 파일을 저장한 후 시스템 테스트를 위해 업로드하세요!

🐛 문제 해결 (Troubleshooting)

백엔드(Backend)가 시작되지 않을 때

• 가상 환경(Virtual environment)이 활성화되어 있는지 확인하세요
• 모든 종속성(Dependencies)이 설치되었는지 확인하세요: pip list
• .env 파일에 올바른 Ollama 버전이 설정되어 있는지 확인하세요

프론트엔드(Frontend)가 백엔드에 연결할 수 없을 때

• 백엔드가 8006 포트에서 실행 중인지 확인하세요
• 브라우저 콘솔에서 CORS 에러가 있는지 확인하세요
• 127.0.0.1 대신 http://localhost:3006을 시도해 보세요

SQL 쿼리가 실패할 때

• CSV가 성공적으로 업로드되었는지 확인하세요
• 컬럼(Column) 이름에 특수 문자가 포함되어 있지 않은지 확인하세요
• 먼저 더 단순한 질문부터 시도해 보세요

에이전트(Agent) 에러

• OpenRouter API 키가 유효한지 확인하세요
• API 크레딧이 있는지 확인하세요
• 상세한 에러 메시지를 확인하기 위해 터미널을 살펴보세요

💡 더 나은 결과를 위한 팁

명확하고 구체적인 질문을 하세요

• 좋은 예: "런던 출신 고객은 몇 명인가요?"
• 나쁜 예: "런던 고객"

가능하면 정확한 컬럼 이름을 사용하세요

• 업로드 후 테이블을 확인하여 컬럼 이름을 파악하세요

단순하게 시작하여 점진적으로 복잡하게 진행하세요

• 처음에는: "모든 고객을 보여줘"
• 그다음에는: "구매액이 1000 이상인 고객을 보여줘"

한 번에 하나씩 질문하세요

• 복잡한 쿼리는 단계별로 나누어 질문하세요