Metadata-Version: 2.4
Name: docextr
Version: 0.1.1
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Rust
License-File: LICENSE
License-File: THIRD_PARTY_LICENSES.txt
Summary: Rust 기반 텍스트·표·이미지·출처 추출 라이브러리
License-Expression: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# DocExtr

문서에서 추출 목적별 결과를 만드는 Rust 기반 Python 라이브러리입니다. 파싱은 wheel에 들어 있는
Rust 엔진이 같은 프로세스에서 하며, 외부 프로세스나 원격 API를 쓰지 않습니다.

- 형식: HWP·HWPX, DOC·DOCX, PPTX, XLSX·XLS·XLSB·ODS, PDF(텍스트 레이어), HTML, Markdown·텍스트·소스 코드, 이미지
- 목적 4종: `text`(원문 충실 평문·순수 Markdown), `agent`(에이전트용 Markdown·경량 구조·이미지),
  `embedding`(추정 토큰 청크), `search`(평평한 검색 문서)
- Python 3.9~3.14

```python
import docextr

result = docextr.extract_file("document.hwpx")             # 기본: 네 목적 전부
print(result["manifest"]["status"])                         # success / partial / failed
print(result["text"]["text"])
for chunk in result["embedding"]["chunks"]:
    print(chunk["id"], chunk["est_tokens"], chunk["embed_text"][:40])

result = docextr.extract_file("proposal.hwp", targets=["agent", "search"])
docextr.export_file("document.hwpx", "new-output-directory")  # 목적별 파일로 쓰기

engine = docextr.Engine(cache_entries=10_000, cache_bytes=256 * 1024 * 1024)  # 반복 호출
for path in paths:
    result = engine.extract_file(path, targets=["text"])
```

결과 dict는 `manifest`(항상)와 요청한 목적 키를 가집니다. 목적 하나가 실패하면 그 목적만 `failed`이고
manifest `status`는 `partial`입니다. 문서가 아닌 입력과 문서 추출 실패는 예외입니다
(`RuntimeError('unsupported_format')`·`RuntimeError('empty_or_binary')`·`ValueError('size_limit_exceeded')` 등).
타입 정보는 패키지에 포함된 `docextr/__init__.pyi`에 있습니다.

OCR 선택 옵션은 `ocr_empty_units`(기본 False), `ocr_unit_indices`(1부터 시작, None은 전부),
`ocr_include_notes`(기본 True; False는 본문 자산만), `ocr_pdf_render`(기본 False)입니다.
PDF 렌더 OCR은 선택한 쪽을 주석 없이 Rust로 렌더하며 이미지 조각을 개별 인식하지 않습니다.
CPU 입력의 긴 변은 1,280px로 보정합니다. `ocr.elapsed_ms`와 제공 가능한 `input_tokens`·`output_tokens`를 반환합니다.
입력 토큰은 이미지 토큰을 포함하며 과금용 텍스트 토큰 수가 아닙니다. 시간은 캐시가 저장한 원래 인식 시간입니다.
OCR의 `success`는 정확도·완전성 보증이 아닙니다. 진단과 실패 전 인식 글자도 함께 확인할 수 있습니다.
노트 OCR은 본문에서 분리하고 `body_unit_indices`·`note_unit_indices`로 자산 참조 단위를 제공합니다.

`result["agent"]["agent"]["units"]`는 단위마다 정규화한 `body_markdown`·`body_text`를 제공합니다.
합성 쪽·슬라이드 표식과 발표자 노트는 본문에서 제외하고, 본문 속 같은 표식은 그대로 보존합니다.
발표자 노트는 `agent["notes"]`의 `unit_index`로 연결합니다. 파싱한 쪽·슬라이드가 있는 빈 PDF·PPTX도
성공하며 단위 구조·PPTX 디자인을 반환합니다. 이때 embedding·search 목록은 비어 있습니다.

## OCR

이미지 자산의 글자 인식(PaddleOCR-VL 1.6 Q8, CPU)은 기본으로 꺼져 있고
`options={"ocr": True, "ocr_models": "<모델 디렉터리>"}`로 켭니다. 약 1.10 GB 모델은 wheel에 들어 있지 않으며
추출 중에 내려받지 않습니다. 모델을 따로 설치해야 하고, 모델이 없으면 경고 후 OCR 없이 계속합니다.

## 라이선스

MIT. 포함된 제3자 구성요소의 고지는 wheel 메타데이터의 `THIRD_PARTY_LICENSES.txt`에 있습니다.

