Hyungi Ahn
6785d53d3d
Phase 4-A 가 wrong/unsure 한 문제씩 풀이 캐시. 4-B 는 세션 전체 wrong/unsure
5~30건을 묶어 200~400자 자연어 요약 1건 생성. 결과 화면 헤더 카드.
큐 인프라는 4-A study_question_jobs 와 분리 — FK 단일 의미 + 운영 SQL 명확성
+ 4-A/4-B 가드/payload/재시도 정책 차이. 신규 study_quiz_session_jobs (큐) +
study_quiz_session_analysis (결과 캐시 PK=session_id, UPSERT) + 전용 consumer.
Backend:
- migrations/233 — study_quiz_session_jobs (FK study_quiz_sessions NOT NULL,
status pending/processing/completed/failed/skipped, max_attempts=2)
- migrations/234 — partial unique idx (session_id) WHERE pending/processing
- migrations/235 — study_quiz_session_analysis (session_id PK, summary_md,
confidence, model_name, generated_at, is_stale)
- models/study_quiz_session_job — ORM + enqueue_session_analysis_job() (멱등)
- models/study_quiz_session_analysis — ORM (PK = session_id)
- services/study/session_summary_guard — GUARD_PATTERN (정규식) +
normalize_confidence() 단일 source, worker + tests 가 import 공유
- services/study/session_summary_rag — gather_session_summary_context()
documents 만 (PR-3 _gather_document_evidence 재사용). evidence 없어도 호출
허용 (4-A 와 다른 정책 — 세션 기록 자체가 evidence)
- services/study/session_analysis_enqueue — auto (finalize/fallback) +
request_session_analysis_regenerate (manual). manual 은 wrong/unsure < 5
즉시 차단, active job 차단, 기존 analysis 있으면 is_stale=true 박기
- prompts/study_session_summary_envelope.txt — envelope JSON
{summary_md, confidence}. 정량 정수만 인용 가능, 비율/추세/범위/날짜 금지
- workers/study_session_analysis_worker — terminal status 분기:
· wrong/unsure < 5 → status=skipped, error_code=insufficient_attempts
· question_text/outcome 부족 → skipped, evidence_missing
· GUARD_PATTERN match → failed, guard_fail
· 800자 hard cap + confidence normalize
· timeout/parse/unknown → 재시도 후보
· UPSERT study_quiz_session_analysis ON CONFLICT DO UPDATE (PK session_id)
- workers/study_session_queue_consumer — 4-A consumer 패턴 복제. BATCH_SIZE=1
+ STALE_MINUTES=10. MLX gate 4-A 와 공유 (Semaphore(1))
- main.py — APScheduler add_job(consume_study_session_queue, ..., 1분 주기)
- session_finalize — 끝에서 enqueue_session_analysis_auto (best-effort)
- api/study_topics:
· QuizSessionAnalysisOut + ai_session_analysis 응답 필드 (analysis row +
최신 job status/error_code)
· GET fallback enqueue (기존 analysis 또는 active job 없으면만, non-blocking)
· POST /quiz-sessions/{sid}/regenerate-summary — manual 트리거
Frontend (quiz-sessions/[sid]/+page.svelte):
- 결과 헤더에 세션 요약 카드 (AI 풀이 indicator 직후, 바로 할 일 직전)
- summary_md 박혔으면 markdown 렌더, 없으면 job_status / error_code 분기:
· pending/processing → "AI 가 세션 분석 중"
· insufficient_attempts → "오답·모르겠음 5건 미만"
· evidence_missing → "자료 부족"
· guard_fail → "환각 검증 차단" + 재생성 링크
- confidence='low' 배지 + is_stale "재생성 중" 배지
- 재생성 버튼 + regenerateSummary() — reason 별 toast 분기
ship gate:
- tests/test_session_summary_guard_pattern.py — 허용 5 + 차단 7 케이스 +
normalize_confidence 표준/비표준 검증. python3 직접 실행 패스.
Plan: ~/.claude/plans/nifty-sparking-spindle.md (Phase 4-B v1)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
hyungi_Document_Server
Self-hosted 개인 지식관리(PKM) 웹 애플리케이션
기술 스택
- 백엔드: FastAPI + SQLAlchemy (async)
- 데이터베이스: PostgreSQL 16 + pgvector + pg_trgm
- 프론트엔드: SvelteKit
- 문서 파싱: kordoc (HWP/HWPX/PDF → Markdown)
- AI: Qwen3.5-35B-A3B (MLX), nomic-embed-text, Claude API (폴백)
- 인프라: Docker Compose, Caddy, Synology NAS
주요 기능
- 문서 자동 분류/태그/요약 (AI 기반)
- 전문검색 + 벡터 유사도 검색
- HWP/PDF/Markdown 문서 뷰어
- 법령 변경 모니터링 (산업안전보건법 등)
- 이메일 자동 수집 (MailPlus IMAP)
- 일일 다이제스트
- CalDAV 태스크 연동 (Synology Calendar)
Quick Start
git clone https://git.hyungi.net/hyungi/hyungi_document_server.git hyungi_Document_Server
cd hyungi_Document_Server
# 인증 정보 설정
cp credentials.env.example credentials.env
nano credentials.env # 실제 값 입력
# 실행
docker compose up -d
http://localhost:8000/docs 에서 API 문서 확인
디렉토리 구조
├── app/ FastAPI 백엔드 (API, 워커, AI 클라이언트)
├── frontend/ SvelteKit 프론트엔드
├── services/kordoc/ 문서 파싱 마이크로서비스 (Node.js)
├── gpu-server/ GPU 서버 배포 (AI Gateway)
├── migrations/ PostgreSQL 스키마
├── docs/ 설계 문서, 배포 가이드
└── tests/ 테스트 코드
인프라 구성
| 서버 | 역할 |
|---|---|
| Mac mini M4 Pro | Docker Compose (FastAPI, PostgreSQL, kordoc, Caddy) + MLX AI |
| Synology NAS | 파일 원본 저장, Synology Office/Drive/Calendar/MailPlus |
| GPU 서버 | AI Gateway, 벡터 임베딩, OCR, 리랭킹 |