LectureForge 🎓

AI-Powered Lecture Material Generator using Multi-Agent Pipeline System

🚀 v0.6.3 | --config 디렉토리 거부 버그 수정 · README/docs --config·--eval 동작 설명 전면 보완

PDF, 웹페이지, 인터넷 검색에서 정보를 수집하여 고품질 강의자료를 자동 생성하는 AI 시스템입니다.

핵심 통계: 12개 에이전트 | 9개 도구 | 9개 CLI 명령 | 1,891+ 테스트 (~81% 커버리지) | ~$0.035/60분 강의 | Python 3.11 권장

데이터 위치: ~/Documents/LectureForge/ (일반 폴더, Finder/탐색기에서 바로 접근)

📋 목차

• 주요 기능
• 빠른 시작
• 사용법
• 명령어 가이드
• FAQ
• 변경 이력
• 기여하기

✨ 주요 기능

컨텐츠 생성

• 📚 멀티소스 수집: PDF, URL, 웹 검색을 통한 포괄적 정보 수집
• 📍 Location-based 이미지 매칭: RAG 컨텍스트 기반 자동 이미지 배치 (+750% 활용률)
• 🖼️ 대화형 이미지 편집: 생성된 강의의 이미지 삭제/교체 (Vector DB 기반 대안 검색)
• 🎨 구조화된 HTML 출력: Mermaid 다이어그램, 검색 인덱스, 코드 하이라이팅
• 🎬 프레젠테이션 슬라이드: Reveal.js 기반 자동 변환 (--to-slides) — 섹션별 LLM 재작성 (≤35자, 말줄임표 없음), 발표자 노트 기본 포함 (--without-notes로 제외)
• 🌐 웹 기반 강의 편집기 (v0.5.0+): edit 명령어 — 3-패널 SPA (섹션 CRUD, EasyMDE 마크다운, 이미지 갤러리·대안 검색), 로컬 Flask 서버(포트 5757), 브라우저 자동 오픈

품질 보증

• ✅ 6차원 품질 평가: 완성도, 흐름, 시간, 난이도, 시각자료, 정확성
• 🔄 자동 개선: 품질 기준 미달 시 최대 3회 자동 수정
• 🔧 KB 기반 재평가·보충 (--re-evaluate): 기존 강의를 지식창고와 대조·품질 재평가하고 미반영 청크를 보충 추가 (*_enhanced.html)
• 🧠 RMC 자기검토 (v0.3.8+): 에이전트 내부 2단계 자기반성 (Layer 1 검토 + Layer 2 검토의 검토)
  • CurriculumDesigner: 섹션 순서 논리성, 학습목표 커버리지, 선수 내용 순서 자동 검증 및 수정
  • ContentWriter: 개념 비약, 설명 모호성, 흐름 단절 등 의미론적 품질 검토 후 수정
  • QAAgent: 각 주장을 소스 컨텍스트와 대조 → 할루시네이션 항목 제거 또는 경고 표시
• 🧪 테스트 커버리지: 1,891+ 테스트 함수 (~81% 커버리지)

지식 관리

• 🗄️ RAG 기반 지식창고: ChromaDB 벡터 DB로 대화형 Q&A 지원
• 🌐 다국어 지원: 한영 혼합 PDF 지원, 자동 언어 감지, Cross-lingual 검색 (v0.3.2+)
• 🎯 고급 RAG 품질 (v0.3.5+):
  • 400단어 구조화 답변 (5개 Markdown 섹션 강제)
  • 15+15 듀얼 쿼리 검색 (다국어, top-12 결과)
  • Rich Markdown 패널 렌더링 (터미널에서 아름다운 출력)
  • 동적 신뢰도 점수 (ChromaDB L2 거리 올바른 변환)
• ⚡ 쿼리 캐싱: 동일 질문 60% 빠른 응답
• 💬 소스 인용: 자동 참조 및 페이지 번호 제공

안정성 & 성능

• 🔄 자동 재시도: API 실패 시 지수 백오프 (최대 3회)
• 💰 비용 추적: 실시간 토큰 사용량 및 비용 추정
• 🔧 타입 힌트: ~70% 타입 안정성 (340/489 함수)
• 🎯 예외 처리: 구조화된 예외 시스템 (9개 카테고리)
• 📝 프롬프트 관리: 템플릿 기반 프롬프트 시스템
• 🦙 Ollama 지원 (v0.5.5+): LLM_PROVIDER=ollama로 로컬 LLM 사용 — OpenAI API 키 없이 강의 생성 가능
• 🔬 파이프라인 계측 (v0.6.1+, opt-in): create --eval <DIR> — Gate A–G 품질 계측 (목표 정렬·SLA·보안·설명 가능성); pip install "lecture-forge[eval]" 필요

🚀 빠른 시작

1️⃣ 설치

방법 1: pipx로 설치 (가장 간편 ⭐⭐)

# pipx 설치 (아직 없는 경우)
pip install pipx
pipx ensurepath

# lecture-forge 설치 (격리된 환경에서 자동 설치)
pipx install lecture-forge

# playwright 설치 (pipx 환경에 주입 후 브라우저 다운로드)
pipx inject lecture-forge playwright
playwright install chromium

# [선택] agent-evaluator 계측 기능 (create --eval 사용 시)
pipx inject lecture-forge agent-evaluator

# 사용
lecture-forge create

pipx의 장점:

• ✅ 격리된 환경에서 자동 설치
• ✅ 시스템 전역에서 lecture-forge 명령 사용 가능
• ✅ 다른 Python 프로젝트와 의존성 충돌 없음
• ✅ conda/venv 환경 관리 불필요

방법 2: PyPI + conda 환경 (권장 ⭐)

# Python 3.11 환경 생성 (강력 권장)
conda create -n lecture-forge python=3.11
conda activate lecture-forge

# PyPI에서 설치
pip install lecture-forge

# [선택] agent-evaluator 계측 기능 (create --eval 사용 시)
pip install "lecture-forge[eval]"

# 웹 스크래핑용 브라우저 설치
playwright install chromium

방법 3: 개발 설치 (소스 코드 수정 시)

# Git 클론
git clone https://github.com/bullpeng72/Lecture_forge.git
cd Lecture_forge

# Python 3.11 환경 생성
conda create -n lecture-forge python=3.11
conda activate lecture-forge

# 로컬 소스에서 설치
pip install -e .

# [선택] agent-evaluator 계측 기능 포함 설치
pip install -e ".[eval]"

# 웹 스크래핑용 브라우저 설치
playwright install chromium

선택적 설치 옵션 (Optional Extras)

[eval] 설치 내용: agent-evaluator 코어 패키지 (numpy, pandas, openai, anthropic 5개)만 추가됩니다. Phoenix/OTEL 추적이 필요하면 추가로 pip install "agent-evaluator[otel]", 대시보드는 pip install "agent-evaluator[serve]".

Python 버전 호환성:

• ✅ Python 3.11: 강력 권장 - 모든 의존성 완벽 지원
• ✅ Python 3.12: 완벽 지원 - v0.3.3부터 공식 지원
• ✅ Python 3.13: 지원됨 - v0.3.8부터 검증 완료

Python 3.11, 3.12, 3.13 모두 지원합니다.

2️⃣ 환경 설정

방법 1: 대화형 설정 (권장 ⭐)

# 대화형 설정 마법사 실행
lecture-forge init

이 명령어는 다음을 수행합니다:

• ✅ 플랫폼별 최적 위치에 .env 파일 자동 생성
  • Windows: %USERPROFILE%\Documents\LectureForge\.env
  • Mac/Linux: ~/Documents/LectureForge/.env
• ✅ LLM 공급자 선택 (OpenAI / Ollama) 및 API 키 입력 안내 — Ollama 선택 시 OpenAI 불필요
• ✅ 선택적 이미지 검색 API 설정 (Pexels, Unsplash)
• ✅ 파일 권한 자동 설정 (Unix/Mac: 600)

방법 2: 수동 설정

# .env 파일 생성 (프로젝트 개발 시)
cp .env.example .env

.env 파일을 열어 다음 항목을 설정하세요:

필수 API 키 (OpenAI 사용 시):

# OpenAI API (OpenAI 사용 시 필수, Ollama 사용 시 불필요)
OPENAI_API_KEY=sk-proj-...

# 검색 API (필수)
SERPER_API_KEY=...                # 무료: 2,500회/월

Ollama 로컬 LLM 사용 시 (OpenAI API 키 불필요):

LLM_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=llama3.2
OLLAMA_EMBEDDING_MODEL=nomic-embed-text
SERPER_API_KEY=...                # 웹 검색은 여전히 필요

선택 사항:

# 이미지 검색 API (선택)
PEXELS_API_KEY=...                # 무료 무제한
UNSPLASH_ACCESS_KEY=...           # 무료: 50회/시간

# 검색 및 크롤링 설정 (기본값으로 충분)
SEARCH_NUM_RESULTS=10             # 검색 결과 수 (최대 100)
DEEP_CRAWLER_MAX_PAGES=10         # 크롤링 페이지 수
IMAGE_SEARCH_PER_PAGE=10          # 이미지 검색 결과 수

# 품질 설정
QUALITY_THRESHOLD=80              # 품질 임계값 (70-90)
MAX_ITERATIONS=3                  # 최대 개선 반복 횟수

💡 더 많은 설정 옵션은 .env.example 파일 참조

.env 파일 위치

LectureForge는 다음 순서로 .env 파일을 탐색합니다:

1. 환경 변수: LECTURE_FORGE_ENV_FILE로 지정한 경로
2. 현재 디렉토리: ./.env
3. 사용자 디렉토리 (권장):
   • Windows: %USERPROFILE%\Documents\LectureForge\.env
   • Mac/Linux: ~/Documents/LectureForge/.env

API 키 획득:

• OpenAI: platform.openai.com (사용량 기반 과금)
• Serper: serper.dev (무료 2,500회/월)
• Pexels: pexels.com/api (무료)
• Unsplash: unsplash.com/developers (무료 50회/시간)
• Ollama: ollama.com (무료, 로컬 실행) — OPENAI_API_KEY 불필요

3️⃣ 첫 강의 생성

lecture-forge create

대화형으로 강의 정보를 입력하면 자동으로 강의자료가 생성됩니다! 🎉

💻 사용법

명령어 개요

빠른 실행 예제

# 🚀 초기 설정 (처음 한 번만)
lecture-forge init

# 🎓 강의 생성 (대화형 - 가장 간단)
lecture-forge create

# 🎓 고품질 강의 (이미지 검색 포함)
lecture-forge create --image-search --quality-level strict

# 🔬 파이프라인 계측 포함 강의 생성 (v0.6.1+, pip install "lecture-forge[eval]" 필요)
lecture-forge create --eval eval_results/

# 💬 Q&A 모드 (자동으로 최신 지식베이스 선택)
lecture-forge chat

# 🌐 영문 PDF 번역 (한국어 강의자료 생성)
lecture-forge translate paper.pdf
lecture-forge translate paper.pdf --no-translate   # 원문 구조 확인 (번역 없음)

# 🎨 슬라이드 변환
lecture-forge improve outputs/lecture.html --to-slides

# 🖼️ 이미지 편집
lecture-forge edit-images outputs/lecture.html

# 🧹 지식베이스 정리 (대화형 선택)
lecture-forge cleanup

# 📂 폴더 열기 (강의 결과물 확인)
lecture-forge home outputs

명령어 상세 가이드

🚀 init - 초기 설정

기본 사용:

lecture-forge init

대화형 마법사가 API 키 입력을 안내하고 자동으로 .env 파일을 생성합니다.

옵션:

기본 저장 위치:

• Windows: C:\Users\<username>\Documents\LectureForge\.env
• Mac/Linux: ~/Documents/LectureForge/.env

예제:

# 처음 설정 (권장)
lecture-forge init

# 특정 항목만 수정 (기존 API 키 유지)
lecture-forge init --reconfigure

# 현재 설정 확인
lecture-forge init --show

# 커스텀 디렉토리 사용
lecture-forge init --path /my/config/dir

하는 일 (기본 모드):

1. LLM 공급자 선택 (OpenAI / Ollama)
2. 필수 API 키 입력 (OpenAI, Serper) — Ollama 사용 시 OpenAI 불필요
3. 품질 설정 (기본값으로 건너뛰기 가능)
4. 선택적 이미지 API 설정 (Pexels, Unsplash)
5. .env 파일 자동 생성
6. 기본 설정 값 자동 설정
7. 파일 권한 보안 설정 (Unix/Mac)

📚 create - 강의 생성

기본 사용:

lecture-forge create

대화형으로 정보를 입력하면 자동으로 강의를 생성합니다.

옵션:

품질 레벨:

• lenient (70점): 빠른 초안
• balanced (80점): 기본값 ✅
• strict (90점): 고품질

예제:

# 기본 생성
lecture-forge create

# 고품질 + 이미지 검색
lecture-forge create --image-search --quality-level strict

# Async 모드 (70% 빠름, 실험적)
lecture-forge create --async-mode

# YAML 설정 사용 (파일을 먼저 생성한 뒤 경로를 지정)
lecture-forge create --config my_config.yaml

# agent-evaluator 계측 활성화 (v0.6.1+, pip install "lecture-forge[eval]" 필요)
lecture-forge create --eval eval_results/
lecture-forge create --config my_config.yaml --eval eval_results/ --quality-level strict

YAML 설정 파일 형식 (my_config.yaml):

topic: "Introduction to Machine Learning"
duration: 90                    # 강의 시간 (분)
audience_level: "intermediate"  # beginner / intermediate / advanced
pdfs:
  - "ml_paper.pdf"
urls:
  - "https://example.com/ml-guide"
keywords:
  - "machine learning basics"
  - "supervised learning"
image_keywords:
  - "machine learning diagram"

ℹ️ --config 옵션은 실제 존재하는 파일 경로를 지정해야 합니다. 대화형 입력(lecture-forge create) 대신 YAML 파일로 반복 재현 가능한 설정을 관리할 때 유용합니다.

💬 chat - Q&A 모드

기본 사용:

lecture-forge chat

자동으로 최신 지식베이스를 선택합니다.

옵션:

대화형 명령어:

• /help: 도움말 표시
• /exit, /quit: 종료
• Ctrl+C: 강제 종료

예제:

# 자동 선택
lecture-forge chat

# 특정 지식베이스 사용
lecture-forge chat -kb ./data/vector_db/lecture_20260209_123456

✏️ edit - 웹 기반 강의 편집기 (v0.5.0+)

기본 사용:

lecture-forge edit outputs/lecture.html

로컬 Flask 서버(기본 포트 5757)를 실행하고 브라우저를 자동으로 엽니다.

옵션:

3-패널 에디터 구성:

• 왼쪽 패널: 섹션 목록 — 섹션 추가·삭제·순서 변경
• 중앙 패널: Markdown 편집기 (EasyMDE) — HTML ↔ Markdown 자동 변환
• 오른쪽 패널: 이미지 갤러리 — 대안 검색 (Vector DB), 교체, 업로드

예제:

# 기본 실행 (포트 5757, 브라우저 자동 오픈)
lecture-forge edit outputs/my_lecture.html

# 커스텀 포트
lecture-forge edit outputs/my_lecture.html --port 8080

# 서버만 시작 (원격 접속 등)
lecture-forge edit outputs/my_lecture.html --no-browser

⚠️ Reveal.js 슬라이드 파일(*_slides.html)은 지원하지 않습니다.

🖼️ edit-images - 이미지 편집

기본 사용:

lecture-forge edit-images outputs/lecture.html

옵션:

대화형 명령어:

예제:

# 기본 (원본_edited.html로 저장)
lecture-forge edit-images outputs/my_lecture.html

# 출력 파일 지정
lecture-forge edit-images outputs/my_lecture.html -o outputs/final.html

🌐 translate - 영문 PDF → 한국어 강의자료 (v0.4.1+)

기본 사용:

lecture-forge translate paper.pdf

영어 PDF에서 챕터 구조를 추출하고, 한국어로 번역하여 HTML 강의자료를 생성합니다.

옵션:

구조 추출 우선순위:

1. PDF TOC — 가장 정확, 학술 PDF 80%+ 적용
2. 폰트 크기 분석 — 본문보다 큰 폰트 자동 감지
3. 페이지 그룹 (폴백) — 균등 페이지 범위 분할

번역 특징:

• 기술 용어: 한국어(English) 형식 유지 (예: 신경망(Neural Network))
• 코드 블록: __CODE_BLOCK_N__ 플레이스홀더로 원문 보존
• AI/ML 표준 용어 사전 25개 적용 (일관된 번역)
• PDF 아티팩트 자동 제거 (페이지 번호, 워터마크 등)

예제:

# 기본 번역 (→ paper_ko.html)
lecture-forge translate paper.pdf

# 출력 파일명 지정
lecture-forge translate paper.pdf -o my_lecture_ko

# 원문 구조 확인 (번역 없음, 빠름)
lecture-forge translate paper.pdf --no-translate

# 고품질 + 슬라이드 변환
lecture-forge translate paper.pdf --quality-level strict --with-slides

# 초급 대상 번역
lecture-forge translate paper.pdf --audience-level beginner

# Mermaid 다이어그램 생성 포함 (기본 OFF)
lecture-forge translate paper.pdf --with-diagrams

🎨 improve - 강의 향상

기본 사용:

lecture-forge improve outputs/lecture.html --to-slides

옵션:

예제:

# 슬라이드 변환 (기본)
lecture-forge improve outputs/lecture.html --to-slides

# 발표자 노트 없이 슬라이드 변환
lecture-forge improve outputs/lecture.html --to-slides --without-notes

# KB 기반 품질 재평가 + 보충 (→ *_enhanced.html)
lecture-forge improve outputs/lecture.html --re-evaluate

# 엄격한 기준으로 재평가
lecture-forge improve outputs/lecture.html --re-evaluate --quality-level strict

# 기존 파일 (메타데이터 없음) — KB 경로 수동 지정
lecture-forge improve outputs/lecture.html --re-evaluate --kb ~/Documents/LectureForge/data/vector_db/MyTopic_...

# 재평가 + 슬라이드 변환 동시 적용
lecture-forge improve outputs/lecture.html --re-evaluate --to-slides

🧹 cleanup - 지식베이스 관리

기본 사용:

lecture-forge cleanup

대화형으로 삭제할 지식베이스를 선택합니다.

옵션:

예제:

# 대화형 선택 (안전)
lecture-forge cleanup

# 전체 삭제 (복구 불가능!)
lecture-forge cleanup --all

📤 출력 결과

강의 생성 완료 후 다음 파일들이 생성됩니다:

outputs/
├── [주제]_[날짜시간].html           # 📄 HTML 강의자료
└── [주제]_[날짜시간]_slides.html   # 🎬 슬라이드 (--to-slides 사용 시)

data/
└── vector_db/
    └── [주제]_[날짜시간]/           # 🗄️ 지식베이스 (Q&A용)
        ├── chroma.sqlite3
        └── ...

포함 내용:

• ✅ HTML 강의자료: 이미지, Mermaid 다이어그램, 코드 하이라이팅, 검색 인덱스
• ✅ 지식베이스: ChromaDB 벡터 DB (대화형 Q&A 지원)
• ✅ 통계 정보: 품질 점수, 토큰 사용량, 예상 비용
• ✅ 슬라이드: Reveal.js 프레젠테이션 (선택 사항)

🔧 고급 설정 (.env 파일)

더 많은 제어가 필요한 경우 .env 파일에서 다음 설정을 조정할 수 있습니다:

# 검색 및 크롤링
SEARCH_NUM_RESULTS=20              # 기본: 10, 최대: 100
DEEP_CRAWLER_MAX_PAGES=30          # 기본: 10
DEEP_CRAWLER_MAX_DEPTH=3           # 기본: 2

# 이미지
IMAGE_SEARCH_PER_PAGE=15           # 기본: 10
MAX_IMAGES_PER_SEARCH=20           # 기본: 10

# 품질
QUALITY_THRESHOLD=90               # 기본: 80 (70-90)
MAX_ITERATIONS=5                   # 기본: 3

# 성능
CHUNK_SIZE=800                     # 기본: 1000 (작을수록 정밀)
WEB_SCRAPER_TIMEOUT=60             # 기본: 30초

💡 전체 설정 목록: .env.example 파일 참조 (15+ 환경변수)

🏗️ 시스템 아키텍처

Multi-Agent 파이프라인 (12개 전문 에이전트)

flowchart TD
    CLI["🖥️ CLI Interface<br/>입력 수집, 진행 상황, Q&A 인터랙션"]
    Orchestrator["⚙️ Pipeline Orchestrator<br/>에이전트 조율 및 태스크 관리"]
    Phase12["📚 Phase 1-2<br/>Collection & Analysis"]
    KB["🗄️ Knowledge Base<br/>Vector DB + RAG Caching"]
    Phase34["✍️ Phase 3-4<br/>Generation & Quality QA"]
    Output["📤 Output<br/>HTML + Slides"]

    CLI --> Orchestrator
    Orchestrator --> Phase12
    Orchestrator --> KB
    Phase12 -->|저장| KB
    KB -->|RAG Query| Phase34
    Phase34 -->|RAG Query| KB
    Phase34 --> Output

    style CLI fill:#e1f5ff
    style Orchestrator fill:#fff4e1
    style Phase12 fill:#e8f5e9
    style KB fill:#f3e5f5
    style Phase34 fill:#fff9c4
    style Output fill:#ffebee

12개 전문 에이전트

9개 도구 (Tools)

품질 평가 시스템 (6차원)

%%{init: {'theme':'base', 'themeVariables': { 'pie1':'#e8f5e9', 'pie2':'#bbdefb', 'pie3':'#fff9c4', 'pie4':'#f8bbd0', 'pie5':'#ffccbc', 'pie6':'#d1c4e9'}}}%%
pie title 품질 평가 가중치 분포
    "내용 완성도 (학습 목표)" : 25
    "논리적 흐름 (연결성)" : 20
    "난이도 적합성 (레벨)" : 20
    "시각자료 품질 (이미지)" : 15
    "시간 적합성 (분량)" : 10
    "기술적 정확성 (검증)" : 10

합격 기준: 80점 이상 (자동 반복 개선, 최대 3회)

❓ FAQ

설치 및 설정

# 버전 확인
python --version

# Python 3.11 환경 생성 (권장)
conda create -n lecture-forge python=3.11
conda activate lecture-forge
pip install lecture-forge

# 검색 결과 증가
SEARCH_NUM_RESULTS=20

# 크롤링 범위 확대
DEEP_CRAWLER_MAX_PAGES=30

# 타임아웃 증가
WEB_SCRAPER_TIMEOUT=60

사용법

기술적 질문

# 전체 테스트
pytest tests/ -v

# 커버리지 확인
pytest tests/ --cov=lecture_forge --cov-report=html

# 특정 테스트
pytest tests/unit/agents/test_content_writer.py -v

# 특정 에이전트만
pytest tests/unit/agents/ -v

# 개발 환경
.env.development

# 프로덕션 환경
.env.production

# 사용
cp .env.production .env
lecture-forge create

📝 변경 이력

v0.6.3 (2026-04-27) — 🐛 --config 버그 수정 + CLI 문서 전면 보완

• 🐛 --config 디렉토리 거부 수정: click.Path(dir_okay=False) 추가 — 디렉토리 경로 전달 시 "Is a directory" 에러 대신 Click이 즉시 명확한 에러 출력
• 📝 create 명령어 문서 전면 보완: YAML 형식 블록 추가; --config 파일 필수(자동 생성 없음) 안내; --eval이 --config 없이 독립 사용 가능·인수 필수·디렉토리 미존재 허용 명시
• 📝 docs/ 현행화: cli.md — --config·--eval 옵션 설명 YAML 형식 포함 전면 갱신; getting-started.md — --eval Quick Commands 추가·Config File Mode에 주의사항 및 조합 예제 추가

v0.6.2 (2026-04-27) — 📦 의존성 정비 + docs/ 오류 수정 + 저장소 정리

• 🐛 pipx resolution-too-deep 수정 (agent-evaluator 0.9.0): arize-phoenix, opentelemetry-*, fastapi, uvicorn, pdfplumber를 하드 deps에서 optional extras([otel]/[serve]/[pdf])로 분리 — pipx install "lecture-forge[eval]" 정상 동작
• 📝 docs/ 오류 수정: cli.md --eval 옵션 누락 추가 + generate_lecture() 시그니처 갱신; agents.md ContentEnhancer 섹션 신설; system-overview.md PyPDF2→PyMuPDF 오표기 수정·도구 목록 실제 코드 기준 정정
• 🧹 저장소 정리: 레거시 setup.py·MANIFEST.in·mypy.ini·DEPLOYMENT_GUIDE.md·config.yaml 제거; mypy.ini per-module 설정 pyproject.toml [[tool.mypy.overrides]]로 통합
• 📝 의존성 배포 전략 문서화: CLAUDE.md extras 계층 표 + 핵심 원칙 (무거운 패키지는 optional extras + lazy import)

v0.6.1 (2026-04-24) — 🔬 agent-evaluator 계측 통합 + openai SDK v2 지원

• 🔬 agent-evaluator 계측 통합 (opt-in): generate_lecture(eval_output_dir=...) — ContentWriterAdapter 등 어댑터 래퍼로 파이프라인 계측; 미설치 시 경고 후 스킵
• 📦 eval/ 모듈 추가: monitor.py (build_lecture_monitor()), adapters.py
• 🔧 openai SDK 버전 범위 확장: <2.0.0 → <3.0.0 — openai v2.x SDK 지원

v0.6.0 (2026-04-21) — 🖼 이미지 배치 정밀화 + HTML 품질 개선 + gpt-5-nano 기본 모델

• 💰 gpt-5-nano 기본 모델: DEFAULT_MODEL · VISION_MODEL 모두 gpt-5-nano — 멀티모달 지원, gpt-4o-mini 대비 2.5× 비용 절감 ($0.05/1M 입력)
• 🖼️ 이미지 위치 정밀화: create — _find_best_paragraph() 폴백을 중간 문단으로 개선; translate — page_y0 기반 page_fraction [0,1] 도입 (ImageReference.page_fraction)
• 🎯 create 이미지 품질: section_position [0,1] 기반 ±30% 필터링, 섹션 간 이미지 누수 차단, max_section_images 캡 강제
• 🔄 create 학습목표 재정렬: 섹션 확정 후 _align_objectives_to_sections() — 실제 섹션 제목 반영한 구체적 목표 재생성
• 🔒 translate 번역 품질 강화: 「CODEBLK:N」 플레이스홀더 + fuzzy restore, #### 번역 추가, 한자 자동 제거 (_strip_non_korean_cjk()), 중복 헤딩 제거, 페이지 범위 검증 경고
• 🐛 HTML 품질 수정: heading 이중 다운그레이드 버그 수정 (h3→h4 먼저, h2→h3 순서), alt 텍스트 125자 제한 (전체 설명은 figcaption 유지)
• 🧹 ContentExpander 헤딩 dedup: _deduplicate_headings() — expansion 결과에서 원본과 중복된 헤딩 블록 자동 제거
• 🧪 테스트: 1,891+, ~81% 커버리지

v0.5.x (2026-02-26 ~ 2026-04-17) — 🌐 웹 편집기 · Ollama 지원 · Vision AI · 테스트 강화

• 🌐 웹 기반 강의 편집기 (v0.5.0): edit 명령어 — 3-패널 SPA 에디터 (포트 5757), 섹션 CRUD, EasyMDE, 이미지 갤러리·대안 검색. CLI 명령어 8개 → 9개
• 🔧 안정성 (v0.5.2): BaseAgent max_tokens 전역화, RMC 루프 상한 (MAX_RMC_ROUNDS), 다이어그램 병렬 생성 (ThreadPoolExecutor), HTML 섹션 ID 중복 방지
• 🔒 패키징 안정화 (v0.5.3): server.py 절대경로 index.html 직접 읽기 — PyPI wheel 누락 대응
• 🧪 테스트 대폭 강화 (v0.5.4): 1,436개 → 1,837개 (+401개, ~48% → ~81%), utils/json_utils.py JSON fence 유틸 통합
• 🦙 Ollama LLM 지원 (v0.5.5): LLM_PROVIDER=ollama, create_llm() 팩토리 — OpenAI API 없이 강의 생성; thinking=False 전체 적용으로 Ollama 빈 응답 버그 수정; init LLM-first 설정, --reconfigure/--show 3모드
• 🐛 Ollama 호환 버그수정 (v0.5.6): PDFImageDescriber 401 수정, TokenTracker 모델명 오표시 수정, 로컬 LLM — API 비용 없음 표시
• 🧹 코드 품질 (v0.5.7): 미사용 import 20개 파일 정리 (기능 변경 없음)
• 🔍 RAG 커버리지 (v0.5.8): 토픽 추출 균형 배분, probe query 10개 → 14개 (PDF 후반부 샘플링 강화)
• 🔭 Vision AI 이미지 설명 (v0.5.9): PDFImageDescriber Vision LLM — base64 multimodal, 텍스트 추론 자동 폴백; 이미지 단일 저장 (outputs/{stem}_images/), 번들링 단계 제거

v0.4.x (2026-02-22 ~ 2026-02-25) - 🔍 보강·번역·아키텍처 정리

• 🔍 검색 커버리지 (v0.4.0): 섹션 전체 인덱싱, --re-evaluate HTML 통계 자동 업데이트, --to-slides 기본 LLM 재작성 (≤35자)
• 🌐 translate 명령어 (v0.4.1): PDF 아티팩트 제거, TOC 감지, AI/ML 용어사전 25개, --with-diagrams opt-in
• 🏗️ 아키텍처 정리 (v0.4.3): agents/ → cli/ import 위반 제거, config 안전 파싱, 테스트 36개 추가

v0.3.x (2026-02-12 ~ 2026-02-20) - 기반 기능 구축

• 🧠 RMC 자기검토 (v0.3.8): CurriculumDesigner·ContentWriter·QAAgent 2단계 자기반성, 할루시네이션 항목 제거, Python 3.13 검증
• 🖼️ UI & 슬라이드 (v0.3.7): Lightbox 클릭 확대, 한국어 서브스트링 검색, Mermaid 전체 너비, API 수정
• 🔧 코드 품질 (v0.3.6): make_api_retry() 팩토리, BaseImageSearchTool, RAG 파라미터 환경변수화, Chat 로그
• 🎯 RAG 품질 (v0.3.5): 400단어 구조화 답변, 15+15 듀얼쿼리(top-12), ChromaDB 신뢰도 수정, Rich 렌더링
• ⚡ Async I/O (v0.3.4): --async-mode, httpx 병렬 수집 70% 향상
• ⌨️ 입력 시스템 (v0.3.3): prompt-toolkit, 한국어 완벽 지원, 히스토리·자동완성
• 🌐 다국어 (v0.3.2): langdetect, Cross-lingual 듀얼쿼리, 지능형 재랭킹
• 📂 디렉토리 (v0.3.1): ~/Documents/LectureForge/, home 커맨드, 자동 마이그레이션
• 🎨 프레젠테이션 (v0.3.0): Mermaid 다이어그램, 예외처리 시스템(9개), 슬라이드 최적화

v0.2.x (2026-02-09 ~ 2026-02-12) - 품질·안정성

• ⚡ RAG 쿼리 캐싱(60%), 자동 API 재시도(지수 백오프), Config 리팩토링(15+ 환경변수)
• 🐛 이미지 크기 버그 수정(원본 보존), Visual score·슬라이드 버그 수정, Full HD WebP 지원
• 🧪 77+ 단위 테스트, 타입 힌트 40% → 75%

v0.1.0 (2026-02-08) - 🎉 Initial Release

• 10개 전문 에이전트, 멀티소스 수집 (PDF·URL·검색)
• Location-based 이미지 매칭 (+750%), ChromaDB 지식창고
• 6차원 품질 평가, HTML 출력, Reveal.js 슬라이드 변환

🤝 기여하기

기여를 환영합니다! 다음 절차를 따라주세요:

1. 이슈 생성: 변경사항을 먼저 논의
2. 포크 & 브랜치: feature 브랜치 생성
3. 테스트 작성: 새 기능에 대한 테스트 추가
4. PR 제출: 변경사항 설명과 함께 제출

자세한 내용은 CONTRIBUTING.md를 참조하세요.

📄 라이선스

MIT License - 자세한 내용은 LICENSE 참조

📞 지원 및 문의

• 이슈 트래커: GitHub Issues
• 프로젝트 가이드: CLAUDE.md
• 기술 분석: INPUT_LIMITS_ANALYSIS.md
• 테스트 가이드: tests/README.md

🙏 감사의 말

이 프로젝트는 다음 오픈소스 프로젝트들을 활용합니다:

• LangChain - Multi-Agent 프레임워크
• ChromaDB - 벡터 데이터베이스
• OpenAI - GPT-4o 모델
• Serper - 검색 API
• Pexels & Unsplash - 이미지 API

Made with ❤️ by Sungwoo Kim
⭐ 이 프로젝트가 도움이 되었다면 GitHub Star를 눌러주세요!