Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 24 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
<a href="https://github.com/needsbuilder/ttobak/actions/workflows/ci.yml"><img src="https://github.com/needsbuilder/ttobak/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
<img src="https://img.shields.io/badge/code-Apache--2.0-blue" alt="License: Apache-2.0">
<img src="https://img.shields.io/badge/python-3.11%2B-3776AB" alt="Python 3.11+">
<img src="https://img.shields.io/badge/tests-417_passed-2ea44f" alt="tests 417 passed">
<img src="https://img.shields.io/badge/tests-427_passed-2ea44f" alt="tests 427 passed">
<img src="https://img.shields.io/badge/corpus-CC_BY_4.0-lightgrey" alt="Corpus CC BY 4.0">
</p>

Expand Down Expand Up @@ -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 없이 끝까지 동작합니다.** 필요한 모델은 직접
Expand All @@ -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개

```
Expand All @@ -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) — 반드시 읽어 주세요
Expand Down
51 changes: 51 additions & 0 deletions tests/test_public_api.py
Original file line number Diff line number Diff line change
@@ -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__
22 changes: 22 additions & 0 deletions ttobak/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -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__",
]
Loading