From 2c3de055759a35e34cf7b5e5f63d75290200b643 Mon Sep 17 00:00:00 2001 From: YONGBEOM GWON Date: Tue, 25 Aug 2026 14:06:11 +0900 Subject: [PATCH] =?UTF-8?q?feat(api):=20=EA=B3=B5=EA=B0=9C=20=ED=95=A8?= =?UTF-8?q?=EC=88=98=EB=A5=BC=20=ED=8C=A8=ED=82=A4=EC=A7=80=20=EC=B5=9C?= =?UTF-8?q?=EC=83=81=EC=9C=84=EB=A1=9C=20=EC=9E=ACexport=20=ED=95=9C?= =?UTF-8?q?=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README·결과보고서는 parse·simplify·score·verify·match·render_html 을 "공개 함수 6개" 로 소개하는데, ttobak/__init__.py 에는 __version__ 밖에 없어서 `from ttobak import simplify` 가 ImportError 였다. 서브모듈 경로를 아는 사람만 코어를 가져다 쓸 수 있었고, README 어디에도 import 예제가 없었다. parse 만 제외한다. `ttobak.parse` 는 서브패키지 이름이기도 해서 최상위 이름을 함수로 덮으면 `import ttobak.parse.pdf_parser` 가 깨진다(실제로 재export 를 넣자 pdfminer 폴백 테스트가 죽었다). 하나의 이름이 모듈이면서 함수일 수는 없으므로 parse 는 모듈 경로를 정본으로 둔다. 서브패키지 리네임은 파괴적 변경이라 별도 결정 사항이다. README 에 실제로 실행되는 예제를 넣었다 — get_provider("fake") 는 기본 응답이 없으면 IndexError 라, 예제도 그대로 돌려보고 default 를 넘기도록 고쳤다. 테스트 수 표기도 417 → 427 로 동기화했다(배지 alt 텍스트 포함, 세 곳 모두). --- README.md | 27 ++++++++++++++++++--- tests/test_public_api.py | 51 ++++++++++++++++++++++++++++++++++++++++ ttobak/__init__.py | 22 +++++++++++++++++ 3 files changed, 97 insertions(+), 3 deletions(-) create mode 100644 tests/test_public_api.py diff --git a/README.md b/README.md index d822ae1..4801785 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ CI License: Apache-2.0 Python 3.11+ - tests 417 passed + tests 427 passed Corpus CC BY 4.0

@@ -51,7 +51,7 @@ python3 -m venv venv && source venv/bin/activate # 가상환경 생성 (최신 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개) +python -m pytest -q # 테스트 (427개) ``` **또박은 인터넷 없이, 상용 API 없이 끝까지 동작합니다.** 필요한 모델은 직접 @@ -62,6 +62,27 @@ python -m pytest -q # 테스트 (417개) `--provider anthropic`도 있지만, 어느 것도 파이프라인의 필수 구성요소가 아닙니다 — 자세한 건 [`docs/providers.md`](docs/providers.md). +### 라이브러리로 가져다 쓰기 + +```python +from ttobak import simplify, render_html # 공개 함수는 패키지 최상위에 있습니다 +from ttobak.parse import parse # parse 만 모듈 경로입니다 (아래 주 참고) +from ttobak.levels import Level +from ttobak.providers import get_provider + +doc = parse("납부기한이 경과할 경우 연체금이 가산됩니다.", "text/plain") +provider = get_provider("fake", default="기한이 지나면 돈을 더 내야 해요.") # 모델 없이 확인용 스텁 +result = simplify(doc, Level.EASY, provider) + +print(result.verdict.value) # pass / revise / human_review — 파이프라인 최종 판정 +print(result.ker.score) # 규칙 기반 보조 점수 (검증된 지표 아님) +open("out.html", "w").write(render_html(result)) +``` + +> `parse` 만 `ttobak.parse` 에서 가져옵니다. `ttobak.parse` 가 서브패키지 이름이기도 해서 +> 최상위 이름을 함수로 덮으면 `import ttobak.parse.pdf_parser` 가 깨지기 때문입니다 — +> 하나의 이름이 모듈이면서 함수일 수는 없습니다. + ## 아키텍처 — 공개 함수 6개 ``` @@ -79,7 +100,7 @@ render_html() 원문/쉬운본 나란히 HTML + 면책 + 배지 - 공개 합성 코퍼스 11쌍: K-ER 평균 **71.2 → 80.7 (Δ +9.5)**, 규칙 위반 평균 −2.09건, **전 페어 Fidelity PASS** — 재현: `python -m tooling.annotate_corpus --corpus` -- 테스트 **417개** 통과 · 라이선스/보안 감사 clean (`ttobak audit`) +- 테스트 **427개** 통과 · 라이선스/보안 감사 clean (`ttobak audit`) - CI 5중 게이트: 정적분석(ruff) + pytest + 의존성 라이선스 허용목록 + 자산 분리 검사 + 감사 ## 정직성 (Honesty) — 반드시 읽어 주세요 diff --git a/tests/test_public_api.py b/tests/test_public_api.py new file mode 100644 index 0000000..63e31da --- /dev/null +++ b/tests/test_public_api.py @@ -0,0 +1,51 @@ +"""공개 API 표면 — README·결과보고서가 소개하는 함수들을 실제로 쓸 수 있어야 한다. + +문서는 parse·simplify·score·verify·match·render_html 을 공개 API 로 소개하는데, +그동안 패키지 최상위에는 아무것도 없어서(`from ttobak import simplify` 는 ImportError) +서브모듈 경로를 아는 사람만 쓸 수 있었다. + +`parse` 만 예외다: `ttobak.parse` 는 서브패키지 이름이기도 해서, 최상위 이름을 함수로 +덮으면 `import ttobak.parse.pdf_parser` 가 깨진다(하나의 이름이 모듈이면서 함수일 수는 +없다). 그래서 parse 는 모듈 경로를 정본으로 유지한다. 서브패키지 리네임은 파괴적 변경 +이라 별도 결정 사항이다. +""" +import importlib + +import ttobak + +ROOT_EXPORTS = ["simplify", "score", "verify", "match", "render_html"] + + +def test_root_exports_are_importable(): + missing = [name for name in ROOT_EXPORTS if not hasattr(ttobak, name)] + assert not missing, f"패키지 최상위에서 빠진 공개 함수: {missing}" + + +def test_root_exports_are_the_canonical_implementations(): + """재export 가 사본이 아니라 정본을 가리켜야 한다 (monkeypatch 계약 보존).""" + from ttobak.fidelity import verify + from ttobak.metric import score + from ttobak.pictogram import match + from ttobak.pipeline import simplify + from ttobak.render import render_html + + assert ttobak.simplify is simplify + assert ttobak.score is score + assert ttobak.verify is verify + assert ttobak.match is match + assert ttobak.render_html is render_html + + +def test_all_declares_the_root_surface(): + for name in ROOT_EXPORTS: + assert name in ttobak.__all__, f"__all__ 에 {name} 없음" + + +def test_parse_stays_a_traversable_subpackage(): + """parse 는 이름 충돌 때문에 최상위로 올리지 않는다. 모듈 경로가 정본이다.""" + from ttobak.parse import parse + + assert callable(parse) + # 최상위 이름을 함수로 덮었다면 이 줄이 ImportError 로 죽는다. + assert importlib.import_module("ttobak.parse.pdf_parser") is not None + assert "parse" not in ttobak.__all__ diff --git a/ttobak/__init__.py b/ttobak/__init__.py index f5d46a3..93620f7 100644 --- a/ttobak/__init__.py +++ b/ttobak/__init__.py @@ -6,3 +6,25 @@ """ __version__ = "0.2.0" + +# 공개 API 재export — 다른 프로젝트가 코어를 가져다 쓸 때 서브모듈 경로를 몰라도 되게 한다. +# 정본은 각 서브모듈이며 여기서는 이름만 다시 노출한다. pipeline 이 테스트 monkeypatch 를 +# 위해 score/verify 를 모듈 레벨로 들고 있는 구조는 건드리지 않는다. +# +# parse 는 일부러 빠져 있다: `ttobak.parse` 는 서브패키지 이름이기도 해서 최상위 이름을 +# 함수로 덮으면 `import ttobak.parse.pdf_parser` 가 깨진다. 하나의 이름이 모듈이면서 +# 함수일 수는 없다. parse 는 `from ttobak.parse import parse` 가 정본이다. +from ttobak.fidelity import verify +from ttobak.metric import score +from ttobak.pictogram import match +from ttobak.pipeline import simplify +from ttobak.render import render_html + +__all__ = [ + "simplify", + "score", + "verify", + "match", + "render_html", + "__version__", +]