🎓 AI 수학 과외 선생님

학생의 사고력을 키워주는 단계별 힌트 기반 AI 수학 튜터

📌 프로젝트 소개

이 프로젝트는 학생이 스스로 문제를 해결하도록 도와주는 AI 수학 과외 선생님입니다.
수학 문제 이미지를 업로드하면, AI가 바로 풀이를 알려주는 대신:

• 단계별 힌트(1~3단계)를 통해 사고 과정을 유도하고
• 선생님 스타일(페르소나)을 선택해서 톤을 바꿀 수 있으며
• 문제 풀이 기록을 기반으로 학습 현황과 약점 단원을 시각화해 줍니다.

---

핵심 철학

• ❌ 정답을 직접 알려주지 않음
• ✅ 단계별 힌트로 사고력 향상
• ✅ 다양한 선생님 페르소나 제공
• ✅ 학습 진도 및 통계 추적

🚀 주요 기능

1. 단계별 힌트 시스템

• 1단계 힌트: 문제를 어떻게 접근해야 할지 방향 제시
• 2단계 힌트: 핵심 개념, 중요한 포인트 짚어주기
• 3단계 힌트: 정답 직전까지 구체적인 풀이 안내 (정답 자체는 최대한 미노출)

2. 선생님 페르소나

• 👨‍🏫 친근한 선생님: 칭찬과 격려 위주, 마음 편하게 설명
• 👩‍🏫 엄격한 선생님: 논리적인 질문과 정확한 개념 점검
• 🤖 중립적 선생님: 감정 없이 차분하게 풀이만 정리

3. 학습 분석 & 리포트

• 힌트 사용 분포 (1·2·3단계 비율)
• 주간 문제 해결 개수 그래프
• 학년/단원별 레이더 차트(강점·약점 단원 시각화)
• 가장 최근에 맞힌 문제에 대해,
  • 풀이 흐름 요약 +
  • 잘한 점 / 보완할 점 피드백 자동 생성

📁 프로젝트 구조

EDUTECH/
│
├── app.py                 # Streamlit 메인 앱 엔트리 포인트
├── README.md
├── requirements.txt       # Python 의존성 목록
├── .env                   # 환경 변수 (OPENAI_API_KEY 등)
├── __init__.py
│
├── assets/                # 정적 리소스
│   └── logo.png           # 사이드바 로고 이미지
│
├── components/            # UI 컴포넌트 모듈
│   ├── analytics.py       # 학습 분석(그래프, 레이더 차트, 풀이 리뷰)
│   ├── chat_interface.py  # 채팅 UI 및 메시지 렌더링
│   ├── hint_buttons.py    # 1·2·3단계 힌트 버튼 + 힌트 레벨 표시
│   ├── sidebar.py         # 왼쪽 사이드바 (학생정보, 통계, 설정)
│   └── teacher_selection.py # 선생님 스타일 선택 카드 컴포넌트
│
├── config/
│   └── settings.py        # 학년/난이도/단원 설정, 앱 기본 설정
│
├── utils/                 # 공통 유틸리티/서비스 레이어
│   ├── __init__.py
│   ├── ai_handler.py      # OpenAI API 호출, 이미지 인코딩, 응답 생성
│   ├── prompt_manager.py  # 베이스 프롬프트 & 페르소나 프롬프트 관리
│   └── session_manager.py # Streamlit 세션 상태 및 저장/로드 관리
│
├── prompts/               # 프롬프트 템플릿
│   └── base_tutor.yaml    # 기본 수학 과외 선생님 시스템 프롬프트
│
├── data/                  # 데이터/세션/로그 저장용 디렉토리
│   └── logs/              # (선택) 세션 저장 파일, 로그 파일 등
│
└── logs/                  # (필요 시) 추가 로그 디렉토리

🛠 설치 방법

1. 환경 설정

# 가상환경 생성(선택사항)
conda create -n edutech python=3.11.13 
conda activate edutech

# 패키지 설치
pip install -r requirements.txt

2. API 키 설정

.env.example 파일을 복사하여 .env 파일을 만들고, OpenAI API 키를 입력하세요:

OPENAI_API_KEY=해당 API키

3. 실행

streamlit run app.py

📊 사용 방법

1. 문제 업로드: 수학 문제 이미지를 업로드하거나 텍스트로 입력
2. 선생님 선택: 사이드바에서 원하는 선생님 페르소나 선택
3. 힌트 단계 선택: 필요한 수준의 힌트 선택
4. 대화형 학습: AI 선생님과 대화하며 문제 해결