pptx-md 0.1.0__py3-none-any.whl

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",
+]

pptx_md/api.py

@@ -0,0 +1,130 @@
+"""Public API orchestrator — convert() + ConvertOptions (FR-16, ADR-601/602).
+
+This module is the single entry point for the pptx-md conversion pipeline.
+It assembles the M2–M5 pipeline stages into one function and exposes the
+ConvertOptions value object that aggregates all per-stage parameters.
+
+Design constraints:
+    - ADR-601: Orchestrator lives here; __init__.py re-exports only.
+    - ADR-602: ConvertOptions is a frozen dataclass (immutable, thread-safe).
+    - ADR-604: validate=True is logging-only; return type is always str.
+    - NFR-08: This module MUST NOT import VLM SDKs directly.
+              describer is injected by the caller via ConvertOptions.
+    - NFR-06: Log metadata only — never raw text or PII fragments.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+# Internal pipeline imports — these are all stdlib+internal modules,
+# no VLM SDK is imported here (NFR-08, ADR-601).
+from pptx_md.assembler import assemble_document
+from pptx_md.description_pipeline import enrich_descriptions
+from pptx_md.image_pipeline import enrich_images
+from pptx_md.parser import parse_presentation
+from pptx_md.validator import validate_markdown
+
+if TYPE_CHECKING:
+    from pptx_md.describer import ImageDescriber
+    from pptx_md.masking import MaskingOptions
+
+_logger = logging.getLogger("pptx_md.api")
+
+__all__ = ["ConvertOptions", "convert"]
+
+
+# ---------------------------------------------------------------------------
+# ConvertOptions — frozen dataclass (ADR-602)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class ConvertOptions:
+    """Aggregated options for convert() (FR-16, ADR-602).
+
+    Collects the per-stage parameters of the M2–M5 pipeline into one
+    immutable value object so callers configure the whole conversion in a
+    single place.
+
+    Attributes:
+        describer: VLM image-description provider (ImageDescriber Protocol).
+                   None (default) = skip VLM enrichment (NFR-08).
+        masking:   PII masking options (MaskingOptions).
+                   None (default) = no masking (FR-15 opt-in).
+        validate:  When True, validate_markdown() is called after assembly
+                   and results are emitted as log warnings.  Return type
+                   is always str regardless of this flag (ADR-604).
+    """
+
+    describer: ImageDescriber | None = None
+    masking: MaskingOptions | None = None
+    validate: bool = False
+
+
+# ---------------------------------------------------------------------------
+# convert() — 5-stage pipeline orchestrator (ADR-601)
+# ---------------------------------------------------------------------------
+
+
+def convert(
+    source: str | os.PathLike[str],
+    *,
+    options: ConvertOptions | None = None,
+) -> str:
+    """Convert a PPTX file into a single Markdown document (FR-16).
+
+    Orchestrates the M2–M5 pipeline:
+        parse -> enrich_images -> enrich_descriptions -> assemble (-> validate?).
+
+    Args:
+        source:  Path to a .pptx file (str or pathlib.Path).
+        options: Optional ConvertOptions; None means defaults
+                 (no VLM, no masking, no validation logging).
+
+    Returns:
+        The assembled Markdown document as a str.
+
+    Raises:
+        ParseError: If the file is missing or not a valid PPTX (file-level
+                    fail-fast — M2 ADR-205).  Per-shape/per-image failures
+                    are isolated and never raise (M3/M4/M5 graceful policy).
+    """
+    opts = options if options is not None else ConvertOptions()
+
+    source_path = Path(source)
+    _logger.debug("convert: start source=%s", source_path.name)
+
+    # --- Stage 1: parse (ParseError propagates on file-level failure) ---
+    pres = parse_presentation(source_path)
+    _logger.debug("convert: parsed slides=%d", len(pres.slides))
+
+    # --- Stage 2: enrich images (classification, always runs) ---
+    enrich_images(pres)
+
+    # --- Stage 3: enrich descriptions (opt-in via describer, NFR-08) ---
+    enrich_descriptions(pres, opts.describer)
+
+    # --- Stage 4: assemble Markdown (masking opt-in) ---
+    md = assemble_document(pres, masking=opts.masking)
+
+    # --- Stage 5: validate (opt-in, logging-only — ADR-604) ---
+    if opts.validate:
+        result = validate_markdown(md)
+        if not result.valid:
+            _logger.warning(
+                "validate_markdown: invalid document (warnings=%d)",
+                len(result.warnings),
+            )
+        elif result.warnings:
+            _logger.info(
+                "validate_markdown: %d warning(s)",
+                len(result.warnings),
+            )
+
+    _logger.debug("convert: done md_len=%d", len(md))
+    return md

pptx_md/assembler.py

@@ -0,0 +1,267 @@
+"""Markdown assembler — converts a SlideIR / PresentationIR into Markdown (FR-11/12).
+
+Public interface:
+    assemble_slide(slide: SlideIR, *, masking: MaskingOptions | None = None) -> str
+    assemble_document(
+        presentation: PresentationIR, *, masking: MaskingOptions | None = None
+    ) -> str
+
+Design constraints (ADR-218):
+    - Deterministic: same IR -> same Markdown (no randomness, no set/dict iteration).
+    - IR is read-only: assembler never mutates input objects.
+    - Partial-failure isolation: one shape failure does not abort the slide/document.
+    - No VLM/python-pptx/Pillow imports (NFR-08).
+    - Uses mermaid.is_complex_table() for FR-13 Mermaid fallback.
+    - masking=None means no masking (opt-in, FR-15).
+"""
+
+from __future__ import annotations
+
+import logging
+
+from pptx_md.ir import (
+    GroupShapeIR,
+    ImageShapeIR,
+    OtherShapeIR,
+    PresentationIR,
+    ShapeIR,
+    SlideIR,
+    TableShapeIR,
+    TextShapeIR,
+)
+from pptx_md.masking import MaskingOptions, mask_text
+from pptx_md.mermaid import is_complex_table, table_to_mermaid
+
+__all__ = ["assemble_slide", "assemble_document"]
+
+_logger = logging.getLogger("pptx_md.assembler")
+
+# ---------------------------------------------------------------------------
+# Module-level named constants (ADR-218 — determinism, §3.2 heading rule)
+# ---------------------------------------------------------------------------
+_SLIDE_HEADING_PREFIX: str = "##"
+_INDENT_UNIT: str = "  "  # two spaces per indent level
+_BULLET_MARKER: str = "- "
+_SLIDE_SEPARATOR: str = "\n\n---\n\n"
+
+
+# ---------------------------------------------------------------------------
+# Public functions
+# ---------------------------------------------------------------------------
+
+
+def assemble_slide(
+    slide: SlideIR,
+    *,
+    masking: MaskingOptions | None = None,
+) -> str:
+    """Render one SlideIR into a deterministic Markdown block (FR-11).
+
+    Read-only: does not mutate the IR.  Same IR -> same Markdown (ADR-218).
+    masking=None means no masking (opt-in, FR-15).
+
+    Args:
+        slide: A SlideIR instance (read-only).
+        masking: Optional MaskingOptions instance (FR-15).
+
+    Returns:
+        A Markdown string representing this slide.  Empty/blank slides return
+        an empty string or heading-only string without raising (FR-11 AC7).
+    """
+    return _render_slide(slide, masking)
+
+
+def assemble_document(
+    presentation: PresentationIR,
+    *,
+    masking: MaskingOptions | None = None,
+) -> str:
+    """Map-Reduce assembly of the whole presentation into one document (FR-12).
+
+    Map: assemble_slide per slide (sequential, ADR-220).
+    Reduce: join with a slide separator, in IR list order.
+    Deterministic and order-preserving (ADR-220).
+
+    Args:
+        presentation: A PresentationIR instance (read-only).
+        masking: Optional MaskingOptions instance (FR-15).
+
+    Returns:
+        A single Markdown document string.
+    """
+    # AC2: sort slides by index (ascending) regardless of IR list order (ADR-220)
+    sorted_slides = sorted(presentation.slides, key=lambda s: s.index)
+
+    slide_blocks: list[str] = []
+    for slide in sorted_slides:
+        try:
+            block = _render_slide(slide, masking)
+        except Exception as exc:  # noqa: BLE001 — slide-level isolation
+            _logger.warning(
+                "assemble_document: slide index=%d failed, skipping. "
+                "shape_count=%d error_type=%s",
+                slide.index,
+                len(slide.shapes),
+                type(exc).__name__,
+            )
+            block = f"{_SLIDE_HEADING_PREFIX} Slide {slide.index + 1}"
+        slide_blocks.append(block)
+
+    return _SLIDE_SEPARATOR.join(slide_blocks)
+
+
+# ---------------------------------------------------------------------------
+# Private render functions
+# ---------------------------------------------------------------------------
+
+
+def _render_slide(slide: SlideIR, masking: MaskingOptions | None) -> str:
+    """Render a single SlideIR to Markdown."""
+    parts: list[str] = []
+
+    # Heading (AC1: first line is heading)
+    if slide.title:
+        parts.append(f"{_SLIDE_HEADING_PREFIX} {slide.title}")
+    else:
+        # Blank title: emit heading with slide index+1 (1-based display)
+        parts.append(f"{_SLIDE_HEADING_PREFIX} Slide {slide.index + 1}")
+
+    # Shapes in IR order (AC1: shapes serialised in IR appearance order)
+    for shape in slide.shapes:
+        rendered = _render_shape(shape, masking)
+        if rendered:
+            parts.append(rendered)
+
+    return "\n\n".join(parts)
+
+
+def _render_shape(shape: ShapeIR, masking: MaskingOptions | None) -> str:
+    """Dispatch to the appropriate renderer; isolate per-shape failures (ADR-220)."""
+    try:
+        if isinstance(shape, TextShapeIR):
+            return _render_text(shape, masking)
+        if isinstance(shape, TableShapeIR):
+            return _render_table(shape)
+        if isinstance(shape, ImageShapeIR):
+            return _render_image(shape, masking)
+        if isinstance(shape, GroupShapeIR):
+            return _render_group(shape, masking)
+        if isinstance(shape, OtherShapeIR):
+            return _render_other(shape, masking)
+        # Unknown subclass — best-effort skip
+        _logger.warning(
+            "_render_shape: unknown shape kind=%s shape_id=%d — skipping",
+            getattr(shape, "kind", "?"),
+            shape.shape_id,
+        )
+        return ""
+    except Exception as exc:  # noqa: BLE001 — shape-level isolation
+        _logger.warning(
+            "_render_shape: shape_id=%d kind=%s render failed error_type=%s — skipping",
+            shape.shape_id,
+            getattr(shape, "kind", "?"),
+            type(exc).__name__,
+        )
+        return ""
+
+
+def _render_text(shape: TextShapeIR, masking: MaskingOptions | None) -> str:
+    """Render a TextShapeIR to Markdown paragraphs / indented bullets (AC1, AC2)."""
+    lines: list[str] = []
+    for para in shape.paragraphs:
+        text = para.text
+        # Apply masking if provided (FR-15)
+        if masking is not None:
+            text = mask_text(text, masking)
+
+        if para.level > 0:
+            # Indented bullet item (AC2: level=1 deeper than level=0)
+            indent = _INDENT_UNIT * para.level
+            lines.append(f"{indent}{_BULLET_MARKER}{text}")
+        else:
+            # Top-level paragraph
+            lines.append(text)
+
+    return "\n".join(lines)
+
+
+def _render_table(shape: TableShapeIR) -> str:
+    """Render a TableShapeIR as GFM table or Mermaid fallback (AC3, FR-13)."""
+    if is_complex_table(shape):
+        # FR-13 Mermaid fallback
+        return table_to_mermaid(shape)
+
+    # GFM pipe table (AC3: header separator included)
+    rows = shape.rows
+    if not rows:
+        return ""
+
+    header = rows[0]
+    table_lines: list[str] = []
+
+    # Header row
+    table_lines.append("| " + " | ".join(header) + " |")
+    # Separator row (one --- per column)
+    table_lines.append("| " + " | ".join("---" for _ in header) + " |")
+    # Data rows
+    for row in rows[1:]:
+        # Pad/truncate row to match header column count
+        padded = list(row) + [""] * (len(header) - len(row))
+        padded = padded[: len(header)]
+        table_lines.append("| " + " | ".join(padded) + " |")
+
+    return "\n".join(table_lines)
+
+
+def _render_image(shape: ImageShapeIR, masking: MaskingOptions | None) -> str:
+    """Render an ImageShapeIR according to M3/M4 slot priority (AC4, AC5, §3.4).
+
+    Priority (first match):
+    1. description (M4) present -> body paragraph (+ classification label)
+    2. description absent, alt_text present -> ![alt_text](...)
+    3. both absent, classification (M3) present -> _[image: {classification}]_
+    4. all absent -> _[image]_
+    """
+    description = shape.description
+    alt_text = shape.alt_text
+    classification = shape.classification
+
+    if description is not None:
+        # AC4: description present -> description text block (no placeholder)
+        text = description
+        if masking is not None:
+            text = mask_text(text, masking)
+        if classification is not None:
+            return f"{text}\n\n_[{classification} image]_"
+        return text
+
+    # AC5: description=None -> alt_text image syntax
+    if alt_text:
+        masked_alt = mask_text(alt_text, masking) if masking is not None else alt_text
+        return f"![{masked_alt}](...)"
+
+    if classification is not None:
+        return f"_[image: {classification}]_"
+
+    return "_[image]_"
+
+
+def _render_group(shape: GroupShapeIR, masking: MaskingOptions | None) -> str:
+    """Render a GroupShapeIR by recursively rendering children in order (AC6)."""
+    child_parts: list[str] = []
+    for child in shape.children:
+        rendered = _render_shape(child, masking)
+        if rendered:
+            child_parts.append(rendered)
+    return "\n\n".join(child_parts)
+
+
+def _render_other(shape: OtherShapeIR, masking: MaskingOptions | None) -> str:
+    """Render an OtherShapeIR: non-empty fallback_text -> paragraph, else skip (AC8)."""
+    if not shape.fallback_text:
+        # AC8: empty fallback_text -> silently omit
+        return ""
+    text = shape.fallback_text
+    if masking is not None:
+        text = mask_text(text, masking)
+    return text