# 유주의 시험공부 도우미 🎓
> AI-powered personal tutor for Korean middle school exams  
> Built with **Upstage Document Parse · Solar Pro 3 · Streamlit**  
> No RAG. No vector DB. Just long-context.

---

## 왜 만들었나

중학교 1학년 딸의 기말고사를 앞두고, 8개 교과목 교과서를 AI로 학습할 수 있는  
개인 과외 앱이 만들었습니다. 학원 대신, 딸이 혼자 쓸 수 있는 도구로 만들었습니다.

---

## Why long-context, not RAG

The exam scope is a unit's worth of pages, which fits comfortably in Solar Pro 3's
128K context window. Loading it directly means **no retrieval miss** — the answer is
always in the context, so there is no chunking, embedding, vector DB, or reranker
to build and tune.

Note on "parsing": skipping RAG does **not** mean skipping document parsing.
Because the textbooks are scanned images, we still run them through Upstage
Document Parse once — to turn dense scans into clean text + figure alt-text.
That is a one-time *input-quality* step, not a retrieval pipeline.

> **no RAG · yes document parsing**

---

## 기술 스택

| 역할 | 기술 |
|------|------|
| 교과서 PDF 파싱 (스캔본) | Upstage Document Parse API |
| 튜터링 LLM (기본값) | Upstage Solar Pro 3 (`solar-pro`) |
| 멀티모달 옵션 | Claude Haiku 4.5 · GPT-5.4 mini |
| UI | Streamlit |
| 컨텍스트 전략 | Long-context (단원 전체를 컨텍스트에 적재) |
| 패키지 관리 | uv |

---

## 주요 기능 — 5가지 학습 모드

| 모드 | 설명 |
|------|------|
| 🗺️ 전체 그림 | 단원 핵심 주제 및 흐름 요약 |
| 🔑 핵심 개념 | 시험 필수 개념 중요도 순 정리 |
| 👩‍🏫 단계별 학습 | 개념별 1:1 인터랙티브 설명 (멀티턴 대화) |
| 📝 퀴즈 | 자동 문제 생성 + 채점 + 해설 |
| 🎯 모의고사 | 기초 → 응용 → 심화 난이도 순서 시험 |

---

## 모델 비교 결과 — Solar Pro 3 vs Claude Haiku 4.5 vs GPT-5.4 mini

동일 프롬프트, 동일 교과서 범위로 직접 비교했습니다.

| 항목 | Solar Pro 3 | Claude Haiku 4.5 | GPT-5.4 mini |
|------|:-----------:|:----------------:|:------------:|
| 입력 ($/1M tokens) | **$0.15** | $1.00 | $0.75 |
| 출력 ($/1M tokens) | **$0.60** | $5.00 | $4.50 |
| 한국어 최적화 | ⭐ 최강 | 양호 | 양호 |
| 교과서 디테일 재현 | ⭐ 자발적 포함 | 뭉뚱그림 | 뭉뚱그림 |
| 한국 시험 스타일 이해 | ⭐ 자연스러움 | 보통 | 보통 |
| 이미지 인식 | ❌ 텍스트 전용 | ✅ | ✅ |
| 컨텍스트 창 | 128K | 200K | 1.1M |

**결론:** 한국어 교육 콘텐츠에서 Solar Pro 3는 비용 대비 최강이었습니다.  
단원 전체를 long-context로 넘기는 구조에서 Haiku 대비 7~8배 저렴한 가격은 실질적인 차이입니다.

> Solar Pro 3는 텍스트 전용 모델입니다. 그림이 포함된 과목(과학·기술가정)은  
> Claude Haiku 4.5 또는 GPT-5.4 mini를 선택하면 이미지 블록으로 전달됩니다.

---

## Document Parse 사용 소감

### 잘 된 점 ✅
- 병합 셀 포함 표 구조를 HTML로 정확하게 변환
- figure 내 글자를 alt 텍스트로 OCR → 이미지 없이도 LLM에 그림 내용 전달 가능
- 한글 본문, 과학 용어, 레이아웃 분류(paragraph / heading / table / figure) 신뢰도 높음
- pypdf 대비 스캔본 인식률 및 토큰 비용 모두 개선

### 아쉬운 점 & 개선 제안 🔧
- `base64_encoding` 파라미터의 Python(httpx/requests) 작동 예시가 공식 문서에 없어 디버깅 시간 소요  
  → 현재 코드는 alt 텍스트로 우회 처리
- 동기 API 20페이지 한도 → 교과서(평균 30~150페이지)에서 체감되는 제약  
  → 단원별 PDF 분할로 우회
- Document Parse → Solar LLM 연동 end-to-end 예시 코드가 있으면 온보딩이 훨씬 빠를 것

---

## 아키텍처

```
교과서 PDF (스캔본)
        │
        ▼
Upstage Document Parse  ── 1회성 전처리 (parse_upstage.py)
(OCR · 표 · 레이아웃 분류)
        │
        ▼  JSON 저장 (textbooks/<과목>/parsed/<단원>.json)
        │
        ▼
단원 전체 텍스트를 컨텍스트에 적재  ── 앱 실행 시 (load_parsed.py)
        │
        ├── 텍스트 블록  →  Solar Pro 3 / Claude / GPT
        └── 이미지 블록  →  Claude / GPT (멀티모달)
                │
                ▼
        Solar Pro 3 128K 컨텍스트 윈도우
        (튜터링 응답 생성 · prompt cache 적용)
                │
                ▼
        Streamlit UI (5가지 학습 모드)
```

**국어(텍스트 PDF)는 별도 경로:** Document Parse 없이 PDF를 직접 `document` 블록으로 전달.

---

## Setup (uv)

```powershell
# 1. uv 설치 (한 번만) — Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

```bash
# 2. 저장소 클론
git clone https://github.com/YOUR_ID/yuju-study-helper
cd yuju-study-helper
```

```bash
# 3. .env 생성
ANTHROPIC_API_KEY=sk-ant-...   # Claude 모델용 (선택)
UPSTAGE_API_KEY=up-...         # Solar Pro 3 + Document Parse
OPENAI_API_KEY=sk-...          # GPT 모델용 (선택)
```

의존성은 `uv run` 첫 실행 때 `pyproject.toml` 기준으로 자동 설치됩니다.  
`pip install` / 가상환경 활성화 불필요.

---

## 교과서 폴더 구조

```
textbooks/             ← .gitignore로 제외 (저작권)
  과학/
    1단원_물질의구성.pdf
    2단원_소화와순환.pdf
    parsed/            ← parse_upstage.py 실행 후 자동 생성
      1단원_물질의구성.json
      2단원_소화와순환.json
  국어/
    1단원_시의이해.pdf   ← 텍스트 PDF, 파싱 불필요
```

---

## 실행 순서

```bash
# 스캔본 과목만 — 최초 1회 파싱 (Upstage API 크레딧 소모)
uv run parse_upstage.py

# 튜터 앱 실행
uv run streamlit run app.py
```

---

## 파일 구조

```
yuju-study-helper/
├── app.py             # Streamlit 메인 앱 · 사이드바 과목/단원 선택
├── tutor.py           # LLM 라우팅 (Claude · GPT · Solar) · 5가지 모드 프롬프트
├── load_parsed.py     # 단원 JSON → Claude content 블록 변환
├── parse_upstage.py   # Upstage Document Parse 일괄 처리 스크립트
├── pyproject.toml     # uv 의존성
├── .env               # API 키 (gitignore)
└── README.md
```

---

## 만든 사람

**안홍덕 (Hongduk Ahn)**  
[LinkedIn](https://linkedin.com/in/hongduk-ahn-9a1761149)