LearnAI는 Model Control Protocol(MCP)을 활용하여 사용자의 관심 주제에 맞춤형 학습 커리큘럼을 제공하고, 일별 학습 계획을 관리하며, AI 멘토 역할을 수행하는 개인화 학습 지원 시스템입니다.
- 사용자별 맞춤형 학습 커리큘럼 생성
- 일별 학습 계획 및 진도 관리
- 실시간 AI 멘토링 및 학습 상담
- 학습 기록 추적 및 분석
-
MCP Agent 시스템
- MCP 서버와 LangGraph 에이전트 통합
- 모듈화된 에이전트 관리 (
agent.py) - 동적 서버 전환 기능
-
웹 기반 채팅 인터페이스
- FastAPI 기반 백엔드 API
- HTML/CSS/JavaScript 프론트엔드
- 실시간 채팅 기능
-
기본 인프라
- 로컬 및 네트워크 접근 지원
- 템플릿 기반 UI 구조
- 모듈화된 코드 아키텍처
- FastAPI: 웹 프레임워크 및 API 서버
- Python 3.11: 메인 개발 언어
- MCP (Model Control Protocol): AI 에이전트 통신
- LangGraph: AI 워크플로우 관리
- LangChain: AI 애플리케이션 프레임워크
- HTML5/CSS3: 기본 웹 구조 및 스타일링
- Vanilla JavaScript: 클라이언트 사이드 로직
- Jinja2: 서버사이드 템플릿 엔진
- Ollama: 로컬 LLM 실행 환경
- midm-2.0-base-q8: 메인 언어 모델
- ChatOpenAI: OpenAI API 호환 인터페이스
사용자가 처음 LearnAI에 접속하면 AI 에이전트와의 대화를 통해 다음 정보를 수집합니다:
- 학습 목표: 무엇을 배우고 싶은지, 왜 배우려고 하는지
- 학습 제약조건: 시간, 예산, 환경적 제약
- 최종 목표: 구체적이고 측정 가능한 학습 목표 설정
1단계에서 수집된 정보를 바탕으로 개인화된 학습 로드맵을 생성합니다.
학습 진행 상황을 모니터링하고 필요에 따라 계획을 조정합니다.
learnai/
├── main.py # FastAPI 메인 애플리케이션
├── agent.py # MCP 에이전트 모듈
├── utils.py # 개발/디버깅 유틸리티
├── templates/
│ └── index.html # 메인 채팅 UI
├── servers/ # MCP 서버들
│ ├── user_assessment.py # 사용자 진단 서버 (현재: 날씨 데모)
│ ├── generate_curriculum.py # 커리큘럼 생성 서버 (개발 예정)
│ └── evaluate_user.py # 사용자 평가 서버 (개발 예정)
└── agent.ipynb # 프로토타이핑 노트북
pip install fastapi uvicorn jinja2 python-multipart aiofiles
pip install langchain langchain-openai langgraph mcp langchain-mcp-adaptersollama serve
ollama pull midm-2.0-base-q8 # 모델 다운로드 (필요시)python main.py- 로컬: http://127.0.0.1:8000
- 네트워크: http://[표시된_IP]:8000
GET /: 메인 채팅 UIPOST /chat: 채팅 메시지 처리GET /docs: API 문서 (Swagger UI)
- PostgreSQL/SQLite 데이터베이스 연동
- 사용자 인증 및 회원가입 시스템
- 세션 관리 및 대화 기록 저장
- 사용자 프로필 관리
- 사용자 진단 MCP 서버 (
user_assessment.py) - 사용자 학습 수준 평가 MCP 서버 (
evaluate_user.py) - 맞춤형 커리큘럼 생성 MCP 서버 (
generate_curriculum.py) - 일별 학습 계획 생성 및 관리
- 학습 진도 추적 시스템
- 반응형 웹 디자인
- 대시보드 및 학습 현황 시각화
- 모바일 친화적 인터페이스
- 다크모드 지원
- 실시간 알림 시스템
- 학습 분석 및 리포트
- 소셜 학습 기능 (스터디 그룹)
- 외부 학습 자료 연동
- Docker 컨테이너화
- 클라우드 배포 (AWS/GCP/Heroku)
- CI/CD 파이프라인 구축
- 모니터링 및 로깅 시스템
- 성능 최적화 및 스케일링
- MCP 서버별 독립적인 기능 구현
- 에이전트와 웹 서버의 명확한 분리
- 재사용 가능한 유틸리티 함수
- 새로운 MCP 서버 추가 용이
- 서버 타입별 동적 전환 지원
- 플러그인 방식의 기능 확장
- 핫 리로드 지원 (개발 모드)
- API 문서 자동 생성
- 프로토타이핑을 위한 Jupyter 노트북 지원
- Fork the repository
- Create a feature branch
- Make your changes
- Submit a pull request
MIT License
프로젝트 관련 문의사항이나 버그 리포트는 이슈 트래커를 이용해 주세요.
LearnAI System Architecture
┌─────────────────────────────────────────────────────────────┐
│ Web Interface (index.html) │
│ 사용자가 채팅 UI를 통해 메시지 입력 │
└─────────────────────────┬───────────────────────────────────┘
│ POST /chat
┌─────────────────────────▼───────────────────────────────────┐
│ FastAPI Server (main.py) │
│ • 웹 서버 역할 │
│ • 채팅 API 엔드포인트 제공 │
│ • 템플릿 렌더링 │
└─────────────────────────┬───────────────────────────────────┘
│ MultiMCPAgent.chat()
┌─────────────────────────▼───────────────────────────────────┐
│ Multi-Agent System (agent.py) │
│ • 여러 MCP 서버를 동시 관리 │
│ • 학습 의도 감지 및 라우팅 │
│ • 세션 상태 관리 │
│ • Assessment vs General 대화 분기 │
└─────────────────┬─────────────────┬─────────────────────────┘
│ │
Assessment Mode General Mode
│ │
┌────────────────▼────────────────┐ │
│ User Assessment MCP Server │ │
│ (user_assessment.py) │ │
│ │ │
│ • Stateful 세션 관리 │ │
│ • LangGraph Multi-Agent │ │
│ • 파일 기반 영구 저장 │ │
│ │ │
│ ┌─────────────────────────────┐ │ │
│ │ LangGraph Workflow │ │ │
│ │ ┌─────────────────────────┐│ │ │
│ │ │ Extraction Agent ││ │ │
│ │ │ • 정보 추출 (엄격) ││ │ │
│ │ │ • UserInfoSchema 활용 ││ │ │
│ │ └─────────────────────────┘│ │ │
│ │ │ │ │ │
│ │ ┌─────────▼─────────────────┐│ │ │
│ │ │ Response Agent ││ │ │
│ │ │ • 완료도 체크 ││ │ │
│ │ │ • 질문 생성 or 완료 ││ │ │
│ │ │ • UI 정리 처리 ││ │ │
│ │ └─────────────────────────┘│ │ │
│ └─────────────────────────────┘ │ │
└─────────────────────────────────┘ │
│
┌──────────────────────────▼──────────────────────────┐
│ General Conversation │
│ • LangChain ReAct Agent │
│ • 일반 멘토링 대화 │
│ • 다른 MCP 도구들 활용 │
└─────────────────────────────────────────────────────┘
Session Management Flow
┌──────────────────────────────────────────────────────────────┐
│ Session Storage │
│ sessions/ 폴더 │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ abc123.json │ │ def456.json │ │ xyz789.json │ ... │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
│ 각 파일 구조: │
│ { │
│ "messages": [...], # 대화 기록 │
│ "topic": "파이썬", # 추출된 학습 주제 │
│ "constraints": "초보자, 주 2시간", # 제약 조건 │
│ "goal": "웹 개발", # 구체적 목표 │
│ "session_id": "abc123", │
│ "completed": false, # 평가 완료 여부 │
│ "current_agent": "response" │
│ } │
└──────────────────────────────────────────────────────────────┘
User Assessment Workflow
┌─────────────────────────────────────────────────────────────────┐
│ 사용자 입력: "나 파이썬 배우고 싶어" │
└─────────────────────┬───────────────────────────────────────────┘
│
┌─────────────────────▼───────────────────────────────────────────┐
│ Step 1: 학습 의도 감지 (_should_use_assessment_tool) │
│ • 키워드 매칭: "배우고 싶어", "공부하고 싶어", "학습" 등 │
│ • assessment_in_progress 상태 체크 │
│ → Assessment Flow 진입 │
└─────────────────────┬───────────────────────────────────────────┘
│
┌─────────────────────▼───────────────────────────────────────────┐
│ Step 2: 세션 관리 │
│ • 기존 세션 복원 또는 새 세션 생성 │
│ • sessions/세션ID.json 파일에서 로드 │
│ • 대화 기록에 사용자 메시지 추가 │
└─────────────────────┬───────────────────────────────────────────┘
│
┌─────────────────────▼───────────────────────────────────────────┐
│ Step 3: LangGraph Workflow 실행 │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Extraction Agent │ │
│ │ • 엄격한 정보 추출 (명시적 언급만) │ │
│ │ • "파이썬 배우고 싶어" → topic: "파이썬" │ │
│ │ • constraints: "", goal: "" (빈 값 유지) │ │
│ │ • UserInfoSchema로 구조화 │ │
│ └─────────────────┬───────────────────────────────────────────┘ │
│ │ │
│ ┌─────────────────▼───────────────────────────────────────────┐ │
│ │ Response Agent │ │
│ │ • 완료도 체크: topic ✓, constraints ✗, goal ✗ │ │
│ │ • 미완료 → 다음 질문 생성 │ │
│ │ • "파이썬 학습 조건을 알려주세요!" 생성 │ │
│ │ • 마크다운 제거, 세션 정보 숨김 │ │
│ └─────────────────────────────────────────────────────────────┘ │
└─────────────────────┬───────────────────────────────────────────┘
│
┌─────────────────────▼───────────────────────────────────────────┐
│ Step 4: 응답 처리 │
│ • 세션 데이터를 sessions/세션ID.json에 저장 │
│ • UI용 응답 정리 (_clean_response_for_ui) │
│ • 사용자에게 다음 질문 반환 │
└─────────────────────────────────────────────────────────────────┘
Information Extraction Rules
┌─────────────────────────────────────────────────────────────────┐
│ 입력: "나 파이썬 공부하고 싶어" │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Extraction Prompt (매우 엄격한 기준) │ │
│ │ • 사용자가 직접 말한 단어만 추출 │ │
│ │ • 절대 추론, 유추, 해석 금지 │ │
│ │ • 없으면 빈 문자열로 유지 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌─────────────────────────▼───────────────────────────────────┐ │
│ │ UserInfoSchema 구조화 출력 │ │
│ │ topic: "파이썬" ← 명시적으로 언급됨 │ │
│ │ constraints: "" ← 언급되지 않음 │ │
│ │ goal: "" ← 언급되지 않음 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ 잘못된 추출 예시 (하지 않음): │
│ topic: "파이썬 학습" ❌ │
│ constraints: "시간 정보 필요" ❌ │
│ goal: "프로그래밍" ❌ │
└─────────────────────────────────────────────────────────────────┘
Question Generation Logic
┌─────────────────────────────────────────────────────────────────┐
│ Current Profile State: │
│ topic: "파이썬", constraints: "", goal: "" │
└─────────────────────────┬───────────────────────────────────────┘
│
┌─────────────▼─────────────┐
│ _generate_next_question │
└─────────────┬─────────────┘
│
┌────────────────▼────────────────┐
│ Missing Information Check │
└─┬─────────────┬─────────────────┘
│ │
topic 없음 constraints 없음
│ │
┌──────▼──────┐ ┌────▼─────────────────────┐
│ "어떤 분야를│ │ "파이썬 학습 조건을 │
│ 학습하고 │ │ 알려주세요!" │
│ 싶으신가요?"│ │ • 현재 수준 │
│ │ │ • 시간 투자 │
└─────────────┘ └──────────────────────────┘
│
┌─────────▼─────────────────┐
│ goal 없음 │
│ "파이썬 학습 목표를 │
│ 알려주세요!" │
│ • 취업/이직 │
│ • 업무 활용 │
│ • 개인 프로젝트 │
│ • 취미/자기계발 │
└───────────────────────────┘
UI Response Cleaning Process
┌─────────────────────────────────────────────────────────────────┐
│ Raw Response: │
│ 🚀 **파이썬 학습 목표를 알려주세요!** │
│ │
│ **어떤 목적으로 파이썬을(를) 배우시나요?** │
│ - 취업이나 이직을 위해서 │
│ - 현재 업무에 활용하려고 │
│ │
│ _Session: abc123 | Status: In Progress_ │
└─────────────────────────┬───────────────────────────────────────┘
│ _clean_response_for_ui()
┌─────────────────────────▼───────────────────────────────────────┐
│ Cleaned Response: │
│ 🚀 파이썬 학습 목표를 알려주세요! │
│ │
│ 어떤 목적으로 파이썬을(를) 배우시나요? │
│ • 취업이나 이직을 위해서 │
│ • 현재 업무에 활용하려고 │
│ │
│ 구체적인 목표를 알면 더 맞춤형 로드맵을 제시할 수 있어요! │
└─────────────────────────────────────────────────────────────────┘
│
├─ ** 마크다운 굵은글씨 제거
├─ - 리스트를 • 불릿으로 변경
├─ 세션 정보 완전 제거
└─ 여러 줄바꿈 정리
Completion Status Check
┌─────────────────────────────────────────────────────────────────┐
│ _should_continue() 함수 │
│ │
│ topic_complete = bool(state.get("topic")) ← True │
│ constraints_complete = bool(state.get("constraints")) ← False │
│ goal_complete = bool(state.get("goal")) ← False │
│ │
│ if all three are True: │
│ return "complete" → 완료 메시지 생성 │
│ else: │
│ return "continue" → 다음 질문 생성 │
└─────────────────────────────────────────────────────────────────┘
실제 대화 흐름
┌─────────────────────────────────────────────────────────────────┐
│ User: "나 파이썬 공부하고 싶어" │
│ → Assessment: topic="파이썬", constraints="", goal="" │
│ → AI: "파이썬 학습 조건을 알려주세요! 현재 수준과 시간..." │
│ │
│ User: "완전 초보자고 주 2시간 가능해" │
│ → Assessment: topic="파이썬", constraints="완전 초보자, 주 2시간", goal="" │
│ → AI: "파이썬 학습 목표를 알려주세요! 취업, 업무활용..." │
│ │
│ User: "취업 준비하려고" │
│ → Assessment: topic="파이썬", constraints="완전 초보자, 주 2시간", goal="취업" │
│ → AI: "🎯 학습 프로필 분석 완료! [완료 메시지]" │
│ │
│ → assessment_in_progress = False 전환 │
│ → 이후 일반 멘토링 모드로 전환 │
└─────────────────────────────────────────────────────────────────┘
이 구조를 통해 Stateful Multi-Agent Assessment System이 사용자의 학습 프로필을 단계적으로 수집하고, 완료 후에는 일반 멘토링 모드로 자연스럽게 전환됩니다.