ilangs/AI_Math_Tutor_HF

단원 선택 → AI 개념 설명 → 이해도 평가 → 문제 풀기 → AI 채점

학생 질문 입력 → 수학 질문 분류 → ChromaDB RAG 검색 → OpenAI 맞춤 답변

단원 선택 → 10문제 자동 출제 → 일괄 제출 → AI 병렬 채점 → 결과 저장

┌─────────────────────────────────────────────────────────────────┐
│                    Frontend (HTML / JS)                        │
│   login.html · app.html · section1~5.js                         │
│   - 로그인/회원가입 UI                                           │
│   - 섹션별 기능 화면 (학습/채팅/시험/대시보드/토큰로그)              │
└──────────────────────────┬──────────────────────────────────────┘
                           │  HTTP fetch (JWT Bearer Token)
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│               FastAPI Server (server.py)                       │
│                                                                │
│   /auth/*  → routers/auth.py   (로그인·회원가입·JWT 발급)        │
│   /api/*   → routers/tutor.py  (AI 튜터 기능 전체)               │
└──────────────────────────┬──────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│             Service Layer (app/services/tutor_service.py)      │
│                      비즈니스 로직 처리                         │
└──────────────────────────┬──────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│          LangChain Integration (app/tutor/integration.py)      │
│                                                                │
│   explain_chain · reexplain_chain · concept_chain               │
│   answer_chain · rag_chain · classify_chain                    │
│   generate_speech_with_cache (TTS + MD5 캐싱)                   │
└────────┬───────────────────────────────┬────────────────────────┘
         │                               │
         ▼                               ▼
┌─────────────────┐         ┌────────────────────────────────────┐
│  OpenAI OpenAI  │         │         Two-Track 데이터 조회      │
│  (LLM + TTS)    │         │                                   │
│                 │         │  Track 1: CSV / SQLite 직접 조회    │
│  text-embedding │         │  - 오늘의 학습 (정확한 단원 필터링)  │
│  -3-small       │         │  - 단원 시험 (무작위 10문제 추출)    │
│  (RAG Embed)    │         │                                    │
└─────────────────┘         │  Track 2: ChromaDB RAG 검색         │
                            │  - AI 자유학습 채팅                 │
                            │  - 시맨틱(의미) 유사도 검색         │
                            └────────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Data Layer                                  │
│   database/user_db.sqlite   - 사용자·학습·시험·채팅·토큰 로그      │
│   database/vector_store/    - ChromaDB 벡터 인덱스              │
│   data/processed/*.csv      - 수학 문제 데이터셋                │
└─────────────────────────────────────────────────────────────────┘

원본 ZIP (JSON 파일들)
         │
         ▼
[1단계] collect_data_tutor.py
  - ZIP 내부 JSON 순회 → OCR 텍스트 추출
  - 문제(question) : 정답(answer) 1:1 매칭
  - 출력: 초기 통합 CSV (풀이및정답 컬럼)
         │
         ▼
[2단계] csv_refiner.py
  - OpenAI로 데이터 정제
  - '풀이및정답' → '정답' + '친절한 풀이' 컬럼 분리
  - 초등학생 눈높이 언어로 변환
  - 출력: 최종 학습용 CSV (math_tutor_dataset.csv)
         │
         ▼
[3단계] rag_helper.py
  - 임베딩 모델 설정 (text-embedding-3-small)
  - ChromaDB 연결 및 배치(Batch) 저장 도구 정의
  - RAG 검색 함수 정의
         │
         ▼
[4단계] build_vector_db.py  ← 실행 진입점
  - python build_vector_db.py 명령으로 실행
  - CSV 읽기 → rag_helper 호출 → ChromaDB 벡터 저장
  - 출력: database/vector_store/ (ChromaDB 인덱스)
         │
         ▼
ChromaDB 벡터 DB 완성
(AI 자유학습 채팅에서 RAG 검색에 사용)

AI_Math_Tutor_4team/
│
├── server.py                     # FastAPI 앱 진입점, 미들웨어·라우터 등록
├── requirements.txt              # Python 패키지 의존성 목록
├── .env                          # 환경변수 (API 키, JWT 시크릿 등)
│
├── app/                          # 백엔드 애플리케이션 코어
│   ├── routers/
│   │   ├── auth.py               # 로그인·회원가입·JWT 발급 API (/auth/*)
│   │   └── tutor.py              # AI 튜터 기능 전체 API (/api/*)
│   ├── services/
│   │   └── tutor_service.py      # 비즈니스 로직 (LLM 호출 조율)
│   ├── tutor/
│   │   └── integration.py        # LangChain 체인 정의, TTS 캐싱
│   └── utils/
│       └── db_manager.py         # SQLite CRUD, bcrypt 비밀번호 관리
│
├── frontend/                     # 프론트엔드 정적 파일
│   ├── login.html                # 로그인·회원가입 화면
│   ├── app.html                  # 메인 앱 화면 (로그인 후)
│   ├── js/
│   │   ├── app.js                # 공통 JS (인증, API fetch 유틸)
│   │   ├── section1.js           # 오늘의 학습 화면 (학습 흐름 UI)
│   │   ├── section2.js           # AI 자유학습 채팅
│   │   ├── section3.js           # 시험 화면 + 시험 결과 모달 UI
│   │   ├── section4.js           # 성적 로그 대시보드 (그래프 + 시험 기록 UI)
│   │   └── section5.js           # 토큰 사용 로그
│   ├── css/                      # 스타일시트
│   └── assets/                   # 이미지·아이콘 등 미디어 파일
│
├── RAG_sys/                      # RAG 데이터 파이프라인
│   ├── collect_data_tutor.py     # [1단계] 원본 데이터 수집·병합
│   ├── csv_refiner.py            # [2단계] AI 기반 데이터 정제
│   ├── rag_helper.py             # [3단계] ChromaDB 저장 모듈 정의
│   └── build_vector_db.py        # [4단계] 벡터 DB 구축 실행 스크립트
│
├── data/
│   └── processed/
│       ├── math_dataset.csv        # ZIP 내부 JSON 순회 OCR 텍스트 추출
│       └── math_tutor_dataset.csv  # 정제된 최종 수학 문제 데이터셋
│
└── database/
    ├── user_db.sqlite              # SQLite DB (사용자·학습·시험·채팅·토큰)
    └── vector_store/
        └── chroma.sqlite3          # ChromaDB 벡터 인덱스

git clone https://github.com/ilangs/AI_Math_Tutor_4team

# 가상환경 생성
py -3.10 -m venv .venv

# Windows
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate

pip install -r requirements.txt

uvicorn server:app --reload --port 8000

http://127.0.0.1:8000/

# ── OpenAI API ───────────────────────────────────────────
OPENAI_API_KEY="sk-..."           # OpenAI API 키 (필수)

# ── JWT 인증 ─────────────────────────────────────────────
# 아래 명령으로 생성:
#   python -c "import secrets; print(secrets.token_hex(32))"
JWT_SECRET_KEY="여기에_발급된_시크릿_키_입력"

# routers/tutor.py 에서 LLM 호출마다 적용
from langchain_community.callbacks import get_openai_callback

with get_openai_callback() as cb:
    result = await some_llm_function(...)   # LLM 호출

# with 블록 종료 후 cb에 토큰 정보가 자동 집계됨
save_token_usage(
    username=current_user["username"],
    action="개념설명",                       # 기능명 분류
    prompt=cb.prompt_tokens,               # 입력 토큰 수
    completion=cb.completion_tokens,       # 출력 토큰 수
    total=cb.total_tokens,                 # 합계 토큰 수
    cost=cb.total_cost,                    # 달러 비용
)