pptx-md 0.1.0__tar.gz

pptx_md-0.1.0/.gitignore

@@ -0,0 +1,34 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.pyo
+*.pyd
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Testing / coverage
+.coverage
+.coverage.*
+htmlcov/
+.pytest_cache/
+
+# Hatch
+.hatch/
+
+# Type checking
+.mypy_cache/
+
+# IDE
+.vscode/
+.idea/

pptx_md-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ms9648
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pptx_md-0.1.0/PKG-INFO

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: pptx-md
+Version: 0.1.0
+Summary: Convert PPTX files into LLM-friendly Markdown (VLM-first image understanding).
+Project-URL: Homepage, https://github.com/ms9648/pptx-md
+Project-URL: Repository, https://github.com/ms9648/pptx-md
+Author: ms9648
+License: MIT
+License-File: LICENSE
+Keywords: llm,markdown,powerpoint,pptx,vlm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.11
+Requires-Dist: pillow
+Requires-Dist: python-pptx
+Provides-Extra: dev
+Requires-Dist: black; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: vlm
+Requires-Dist: anthropic>=0.40; extra == 'vlm'
+Requires-Dist: openai>=1.0; extra == 'vlm'
+Description-Content-Type: text/markdown
+
+# pptx-md
+
+[![CI](https://github.com/ms9648/pptx-md/actions/workflows/ci.yml/badge.svg)](https://github.com/ms9648/pptx-md/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/pptx-md.svg)](https://pypi.org/project/pptx-md/)
+[![Python](https://img.shields.io/pypi/pyversions/pptx-md.svg)](https://pypi.org/project/pptx-md/)
+
+PPTX 파일을 LLM-friendly Markdown으로 변환하는 Python 라이브러리.
+
+VLM(Vision Language Model) 기반 이미지 이해와 개인정보 마스킹을 지원합니다.
+
+---
+
+## 설치
+
+### Core (텍스트 변환만)
+
+```bash
+pip install pptx-md
+```
+
+### VLM 지원 포함 (이미지 설명 생성)
+
+```bash
+pip install pptx-md[vlm]
+```
+
+VLM extras는 `anthropic` 및 `openai` SDK를 함께 설치합니다.
+
+---
+
+## Quick Start
+
+### 기본 변환 (core-only)
+
+```python
+from pptx_md import convert
+
+md = convert("deck.pptx")
+print(md)
+```
+
+`convert()`는 파싱 → 이미지 분류 → Markdown 어셈블 파이프라인을 실행하고
+Markdown 문자열을 반환합니다.
+
+### 옵션과 함께
+
+```python
+from pptx_md import convert, ConvertOptions
+
+opts = ConvertOptions(validate=True)
+md = convert("deck.pptx", options=opts)
+```
+
+---
+
+## VLM 이미지 설명
+
+VLM을 사용하면 이미지 슬라이드에 자연어 설명을 자동으로 생성합니다.
+API 키는 **반드시 환경변수**로 전달합니다 (NFR-05).
+
+```python
+import os
+from pptx_md import convert, ConvertOptions, get_describer
+
+describer = get_describer("anthropic", api_key=os.environ["ANTHROPIC_API_KEY"])
+opts = ConvertOptions(describer=describer)
+md = convert("deck.pptx", options=opts)
+```
+
+OpenAI를 사용하려면:
+
+```python
+import os
+from pptx_md import convert, ConvertOptions, get_describer
+
+describer = get_describer("openai", api_key=os.environ["OPENAI_API_KEY"])
+opts = ConvertOptions(describer=describer)
+md = convert("deck.pptx", options=opts)
+```
+
+---
+
+## 개인정보 마스킹 (opt-in)
+
+이메일·전화번호 등 PII를 `[REDACTED]`로 치환합니다. 기본값은 **비활성**입니다.
+
+### 기본 패턴 활성화
+
+```python
+from pptx_md import convert, ConvertOptions, MaskingOptions
+
+opts = ConvertOptions(masking=MaskingOptions(enabled=True))
+md = convert("deck.pptx", options=opts)
+```
+
+### 커스텀 패턴 추가
+
+```python
+import re
+from pptx_md import convert, ConvertOptions, MaskingOptions
+
+custom_masking = MaskingOptions(
+    enabled=True,
+    patterns=[
+        re.compile(r"\d{6}-\d{7}"),   # 주민등록번호
+        re.compile(r"사번\s*:\s*\d+"), # 사번
+    ],
+)
+opts = ConvertOptions(masking=custom_masking)
+md = convert("deck.pptx", options=opts)
+```
+
+---
+
+## Markdown 검증
+
+```python
+from pptx_md import convert, validate_markdown
+
+md = convert("deck.pptx")
+result = validate_markdown(md)
+
+if not result.valid:
+    print("검증 실패:", result.warnings)
+elif result.warnings:
+    print("경고:", result.warnings)
+```
+
+`convert(validate=True)`를 사용하면 변환과 동시에 검증 결과를 로그로 출력합니다
+(반환값은 항상 `str`).
+
+---
+
+## 커스텀 VLM 제공자 (플러그인)
+
+`ImageDescriber` 프로토콜을 구현하면 어떤 VLM 제공자도 플러그인으로 사용할 수
+있습니다.
+
+```python
+from pptx_md import convert, ConvertOptions, ImageDescriber
+
+
+class MyDescriber:
+    def describe(
+        self,
+        image_bytes: bytes,
+        image_ext: str,
+        shape_hint: str | None,
+    ) -> str:
+        return "이미지에 대한 설명"
+
+
+opts = ConvertOptions(describer=MyDescriber())
+md = convert("deck.pptx", options=opts)
+```
+
+---
+
+## 예외 처리
+
+```python
+from pptx_md import convert, ParseError, DescribeError
+
+try:
+    md = convert("deck.pptx")
+except ParseError as e:
+    print(f"PPTX 파일을 읽을 수 없습니다: {e}")
+```
+
+---
+
+## 전체 API 레퍼런스
+
+[docs/api.md](docs/api.md) 에 공개 심볼 전체 레퍼런스가 있습니다.
+
+상세 사용 가이드는 [docs/usage.md](docs/usage.md)를 참고하세요.
+
+---
+
+## 요구사항
+
+- Python 3.11+
+- Core: `python-pptx`, `Pillow`
+- VLM 지원: `pip install pptx-md[vlm]` (`anthropic` 또는 `openai` SDK)
+
+---
+
+## 라이선스
+
+[MIT](LICENSE)

pptx_md-0.1.0/README.md

@@ -0,0 +1,190 @@
+# pptx-md
+
+[![CI](https://github.com/ms9648/pptx-md/actions/workflows/ci.yml/badge.svg)](https://github.com/ms9648/pptx-md/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/pptx-md.svg)](https://pypi.org/project/pptx-md/)
+[![Python](https://img.shields.io/pypi/pyversions/pptx-md.svg)](https://pypi.org/project/pptx-md/)
+
+PPTX 파일을 LLM-friendly Markdown으로 변환하는 Python 라이브러리.
+
+VLM(Vision Language Model) 기반 이미지 이해와 개인정보 마스킹을 지원합니다.
+
+---
+
+## 설치
+
+### Core (텍스트 변환만)
+
+```bash
+pip install pptx-md
+```
+
+### VLM 지원 포함 (이미지 설명 생성)
+
+```bash
+pip install pptx-md[vlm]
+```
+
+VLM extras는 `anthropic` 및 `openai` SDK를 함께 설치합니다.
+
+---
+
+## Quick Start
+
+### 기본 변환 (core-only)
+
+```python
+from pptx_md import convert
+
+md = convert("deck.pptx")
+print(md)
+```
+
+`convert()`는 파싱 → 이미지 분류 → Markdown 어셈블 파이프라인을 실행하고
+Markdown 문자열을 반환합니다.
+
+### 옵션과 함께
+
+```python
+from pptx_md import convert, ConvertOptions
+
+opts = ConvertOptions(validate=True)
+md = convert("deck.pptx", options=opts)
+```
+
+---
+
+## VLM 이미지 설명
+
+VLM을 사용하면 이미지 슬라이드에 자연어 설명을 자동으로 생성합니다.
+API 키는 **반드시 환경변수**로 전달합니다 (NFR-05).
+
+```python
+import os
+from pptx_md import convert, ConvertOptions, get_describer
+
+describer = get_describer("anthropic", api_key=os.environ["ANTHROPIC_API_KEY"])
+opts = ConvertOptions(describer=describer)
+md = convert("deck.pptx", options=opts)
+```
+
+OpenAI를 사용하려면:
+
+```python
+import os
+from pptx_md import convert, ConvertOptions, get_describer
+
+describer = get_describer("openai", api_key=os.environ["OPENAI_API_KEY"])
+opts = ConvertOptions(describer=describer)
+md = convert("deck.pptx", options=opts)
+```
+
+---
+
+## 개인정보 마스킹 (opt-in)
+
+이메일·전화번호 등 PII를 `[REDACTED]`로 치환합니다. 기본값은 **비활성**입니다.
+
+### 기본 패턴 활성화
+
+```python
+from pptx_md import convert, ConvertOptions, MaskingOptions
+
+opts = ConvertOptions(masking=MaskingOptions(enabled=True))
+md = convert("deck.pptx", options=opts)
+```
+
+### 커스텀 패턴 추가
+
+```python
+import re
+from pptx_md import convert, ConvertOptions, MaskingOptions
+
+custom_masking = MaskingOptions(
+    enabled=True,
+    patterns=[
+        re.compile(r"\d{6}-\d{7}"),   # 주민등록번호
+        re.compile(r"사번\s*:\s*\d+"), # 사번
+    ],
+)
+opts = ConvertOptions(masking=custom_masking)
+md = convert("deck.pptx", options=opts)
+```
+
+---
+
+## Markdown 검증
+
+```python
+from pptx_md import convert, validate_markdown
+
+md = convert("deck.pptx")
+result = validate_markdown(md)
+
+if not result.valid:
+    print("검증 실패:", result.warnings)
+elif result.warnings:
+    print("경고:", result.warnings)
+```
+
+`convert(validate=True)`를 사용하면 변환과 동시에 검증 결과를 로그로 출력합니다
+(반환값은 항상 `str`).
+
+---
+
+## 커스텀 VLM 제공자 (플러그인)
+
+`ImageDescriber` 프로토콜을 구현하면 어떤 VLM 제공자도 플러그인으로 사용할 수
+있습니다.
+
+```python
+from pptx_md import convert, ConvertOptions, ImageDescriber
+
+
+class MyDescriber:
+    def describe(
+        self,
+        image_bytes: bytes,
+        image_ext: str,
+        shape_hint: str | None,
+    ) -> str:
+        return "이미지에 대한 설명"
+
+
+opts = ConvertOptions(describer=MyDescriber())
+md = convert("deck.pptx", options=opts)
+```
+
+---
+
+## 예외 처리
+
+```python
+from pptx_md import convert, ParseError, DescribeError
+
+try:
+    md = convert("deck.pptx")
+except ParseError as e:
+    print(f"PPTX 파일을 읽을 수 없습니다: {e}")
+```
+
+---
+
+## 전체 API 레퍼런스
+
+[docs/api.md](docs/api.md) 에 공개 심볼 전체 레퍼런스가 있습니다.
+
+상세 사용 가이드는 [docs/usage.md](docs/usage.md)를 참고하세요.
+
+---
+
+## 요구사항
+
+- Python 3.11+
+- Core: `python-pptx`, `Pillow`
+- VLM 지원: `pip install pptx-md[vlm]` (`anthropic` 또는 `openai` SDK)
+
+---
+
+## 라이선스
+
+[MIT](LICENSE)

pptx_md-0.1.0/pyproject.toml

@@ -0,0 +1,77 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pptx-md"
+version = "0.1.0"
+description = "Convert PPTX files into LLM-friendly Markdown (VLM-first image understanding)."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+authors = [{ name = "ms9648" }]
+keywords = ["pptx", "markdown", "powerpoint", "llm", "vlm"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Topic :: Text Processing :: Markup :: Markdown",
+]
+dependencies = [
+    "python-pptx",
+    "Pillow",
+]
+
+[project.optional-dependencies]
+# VLM SDK 는 반드시 여기에만 (스킬 §4, ADR-002). core 에 포함 금지.
+vlm = [
+    "anthropic>=0.40",
+    "openai>=1.0",
+]
+dev = [
+    "pytest",
+    "pytest-cov",
+    "ruff",
+    "black",
+    "mypy",
+]
+
+[project.urls]
+Homepage = "https://github.com/ms9648/pptx-md"
+Repository = "https://github.com/ms9648/pptx-md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pptx_md"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/pptx_md",
+    "tests",
+    "README.md",
+    "LICENSE",
+    "pyproject.toml",
+]
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.black]
+line-length = 88
+target-version = ["py311"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+ignore_missing_imports = true
+files = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+# M6: 커버리지 게이트 활성화 (FR-17, ADR-005 / 원 예고: ADR-004)
+addopts = "--cov=src/pptx_md --cov-report=term-missing --cov-fail-under=75"

pptx_md-0.1.0/src/pptx_md/__init__.py

@@ -0,0 +1,48 @@
+"""pptx-md — Convert PPTX files into LLM-friendly Markdown.
+
+Public API (FR-16, ADR-603):
+
+    from pptx_md import convert, ConvertOptions
+
+    md = convert("deck.pptx")
+
+    # With options:
+    from pptx_md import ConvertOptions, MaskingOptions, get_describer
+    opts = ConvertOptions(
+        describer=get_describer("anthropic", api_key="..."),
+        masking=MaskingOptions(enabled=True),
+        validate=True,
+    )
+    md = convert("deck.pptx", options=opts)
+
+Internal submodules (parse_presentation, enrich_images, etc.) are NOT part
+of the public API and may change without notice.  Access via
+``from pptx_md.parser import parse_presentation`` is possible but outside
+SemVer guarantees (ADR-603).
+"""
+
+from __future__ import annotations
+
+from pptx_md.api import ConvertOptions, convert
+from pptx_md.describer import ImageDescriber
+from pptx_md.errors import DescribeError, InstallationError, ParseError, PptxMdError
+from pptx_md.masking import MASK_TOKEN, MaskingOptions
+from pptx_md.providers import get_describer
+from pptx_md.validator import ValidationResult, validate_markdown
+
+__version__: str = "0.1.0"
+
+__all__ = [
+    "convert",
+    "ConvertOptions",
+    "MaskingOptions",
+    "MASK_TOKEN",
+    "validate_markdown",
+    "ValidationResult",
+    "ImageDescriber",
+    "get_describer",
+    "PptxMdError",
+    "ParseError",
+    "DescribeError",
+    "InstallationError",
+]