또박(Ttobak) 은 어려운 한국어 공공·행정 문서(공문·고지서·안내문)를 쉬운 글(Easy-Read) 로 바꾸는 오픈소스 엔진입니다. 쉬움을 K-ER 점수로 측정하고, 숫자·날짜·금액·기한·자격·기관명이 바뀌지 않았는지 Fidelity 게이트로 검증하며, 왜곡이 의심되면 고치지 않고 사람 검수로 회부합니다.
English — Ttobak is an open-source engine that turns hard Korean public documents into Easy-Read Korean: it measures easiness with a rule-based K-ER rubric, guards facts (amounts, dates, deadlines, eligibility, agency names) through a fidelity gate, and routes suspected distortions to human review instead of silently auto-fixing them.
📺 2분 37초 시연 영상 보기 — 실제 실행 화면만으로 구성한 데모입니다.
실제 실행 화면입니다(합성·편집 없음, 로컬 qwen2.5:7b).
원문의 “만 19세 이상”이 쉬운 글에서 “19세에서”로 바뀌자, 또박은 자격 경계가
흐려진 것으로 보고 검수 필요로 회부했습니다 — 그럴듯하게 고쳐놓고 넘어가지 않습니다.
| 📏 측정하는 쉬움 | 열두 가지 규칙(문장 길이·어려운 낱말·피동·부정 밀도 …)으로 K-ER 점수를 매기고, 점수보다 규칙별 위반 체크리스트를 핵심 산출물로 냅니다. |
| 🧷 사실이 먼저 | Fidelity 게이트가 금액·날짜·연락처·자격·기관명·개수를 슬롯별로 원문과 대조합니다. 값이 사라지면 자동 재교정, 미만→이하 같은 의미 반전이나 강서구청→송파구청 같은 기관 바꿔치기는 자동 교정 없이 사람 검수로 돌려보냅니다. |
| 📄 포맷 네이티브 | 관공서 원본 포맷(PDF·HWPX)을 변환 없이 직접 파싱합니다. |
| 🔓 전부 공개 | 코드(Apache-2.0)·코퍼스(CC BY 4.0)·평가 하네스까지 공개. 기본 구성이 로컬 오픈웨이트 모델(큐원 2.5 7B, Apache-2.0)이라 인터넷도 상용 API도 없이 돌아갑니다. |
python3 -m venv venv && source venv/bin/activate # 가상환경 생성 (최신 macOS/우분투의 PEP 668 필수)
python -m pip install -e ".[dev,ollama]" # 설치 (Python 3.11+)
ollama serve & ollama pull qwen2.5:7b # 로컬 모델 (Apache-2.0, 약 4.7GB)
ttobak web # 웹 데모 — 기본이 로컬 모델입니다
python -m pytest -q # 테스트 (417개)또박은 인터넷 없이, 상용 API 없이 끝까지 동작합니다. 필요한 모델은 직접 내려받아 직접 구동하는 오픈웨이트 모델 하나뿐입니다.
모델을 받기 전에 화면만 먼저 보고 싶으면 ttobak web --provider fake(고정 응답
스텁 — 실제 변환 아님, 화면에 그렇게 표시됩니다). 원격 API를 쓰고 싶으면
--provider anthropic도 있지만, 어느 것도 파이프라인의 필수 구성요소가 아닙니다
— 자세한 건 docs/providers.md.
parse() 텍스트·PDF·HWPX → IR Document
simplify() GENERATE → MEASURE → REVISE 루프 (Fidelity 위반 시에만 재교정)
score() K-ER 규칙 루브릭: 12규칙 평균 0–100 + 위반 체크리스트
verify() 슬롯 추출 → HIGH 슬롯 정확일치 검증 → 드리프트/부정 가드 → 판정
match() 픽토그램 렉시콘 룩업 (경로 참조만 — 글리프 비내장)
render_html() 원문/쉬운본 나란히 HTML + 면책 + 배지
웹 데모와 평가 하네스는 전부 이 코어의 얇은 래퍼입니다.
- 공개 합성 코퍼스 11쌍: K-ER 평균 71.2 → 80.7 (Δ +9.5), 규칙 위반 평균 −2.09건,
전 페어 Fidelity PASS — 재현:
python -m tooling.annotate_corpus - 테스트 417개 통과 · 라이선스/보안 감사 clean (
ttobak audit) - CI 5중 게이트: 정적분석(ruff) + pytest + 의존성 라이선스 허용목록 + 자산 분리 검사 + 감사
- K-ER 점수는 한국 Easy-Read 지침에 정렬된 규칙 기반 루브릭이며 경험적으로 검증된 지표가 아닙니다 (공개·검증된 한국어 Easy-Read 라벨 코퍼스 부재). 0–100 점수는 보조 지표이고, 규칙별 위반 체크리스트(pass/fail)가 핵심 산출물입니다.
- Fidelity 게이트의 현재 커버리지를 정직하게 밝힙니다: 금액·날짜·연락처·자격 경계·부정 표현은 정규화 기반 정확 검증, 기관명·개수는 패턴 기반 best-effort 검증입니다(행정기관 접미사 사전·단위명사 — 사전 밖 기관명이나 희귀 표기는 놓칠 수 있음). 반대 방향의 한계도 있습니다: 단위 동의어(6개월→여섯 달, 65세→65살)는 아직 등가로 인정하지 못해 왜곡이 아닌데도 재교정으로 회부될 수 있습니다(안전 방향 오류). 담당자 성명·기간·조건·양태 슬롯과 NER 교차검증은 로드맵입니다.
- 모든 출력은 원문과 면책 고지를 함께 렌더링합니다: "자동 변환 결과이며 법적 효력은 원문이 우선합니다."
- 또박은 "한국어 Easy-Read AI 최초"를 주장하지 않습니다(온글·KCI·KIPS 선행). 엣지는 열림 + 측정 + 자가 교정 + 포맷 네이티브입니다.
- 코퍼스는 현재 전부 합성 문서이며 사람 최종 검수가 남아 있습니다. 실문서(KOGL-1) 보강과 100~300쌍 확장은 로드맵입니다.
쉬운 정보는 코드만으로 좋아지지 않습니다. 어떤 문서가 왜 어려운지 아는 사람의 손이 필요합니다.
개발자가 아니어도 할 수 있는 것
- 코퍼스 페어 추가 — 지금 11쌍이고 전부 제가 지어낸 예시입니다. 실제 공공문서 기반 페어가 필요합니다
- 픽토그램 낱말 추가 — 글을 읽기 어려운 사람은 그림을 먼저 봅니다. 지금 33개뿐입니다
코드로 시작하기 좋은 것
good first issue라벨을 보세요. 범위와 주의점을 이슈 안에 적어 뒀습니다
개발 규율(TDD)·커밋 형식·라이선스 경계는 CONTRIBUTING.md에
있습니다. 한국어·영어 모두 환영합니다.
| 대상 | 라이선스 | 위치 |
|---|---|---|
| 코드 | Apache-2.0 | LICENSE |
| 코퍼스(데이터) | CC BY 4.0 | corpus/ |
| 픽토그램 | CC BY-SA (Mulberry·OpenMoji, 세트별) | assets/ |
세 라이선스는 섞이지 않으며, CI가 분리를 강제합니다:
python scripts/check_licenses.py # GPL/AGPL/NC 의존성 발견 시 실패
python -m tooling.check_licenses --root . # = ttobak audit (자산 분리·시크릿 포함)자세한 출처는 THIRD_PARTY_LICENSES.md와
NOTICE를 보세요.
MVP 스코프 (2026 오픈소스 개발자대회 출품)
- 입력: 텍스트 + PDF + HWPX(best-effort) → IR. (이미지 OCR = 스트레치)
- 파이프라인: GENERATE → MEASURE → REVISE (provider-agnostic LLM).
- K-ER: 규칙 루브릭 → 0–100 + 위반 목록.
- Fidelity 게이트: 숫자/날짜/금액/기한/자격/엔티티 추출·검증·롤백 (고-recall, fail-safe = '검수 필요').
- 렌더러: 원문/쉬운본 나란히 HTML + 면책 + K-ER·Fidelity 배지 + 소형 픽토그램 룩업.
- 표면: 파이썬 패키지 + 웹 데모. (MCP 서버 = 스트레치)
Stretch (not MVP): 이미지 OCR, MCP 서버, K-ER 모델 레이어(KcBERT/RSRS), semantic-NLI fidelity, semantic 픽토그램 매칭, TTS, 배치.