docstudio 0.2.0__py3-none-any.whl

docstudio/ingest.py

@@ -0,0 +1,205 @@
+"""Reverse converters: X -> Markdown.
+
+Pure-python paths (csv/tsv/json/html) have no heavy deps.  Office / PDF / EPUB
+paths import their library lazily and raise a friendly message if missing, so a
+minimal install still works for the common cases (mirrors markitdown's optional
+extras)."""
+from __future__ import annotations
+
+import csv as _csv
+import io
+import json
+import zipfile
+from pathlib import Path
+
+from .core import registry, ConversionError, detect_format
+
+# --------------------------------------------------------------------------- #
+# small helpers shared by several converters
+# --------------------------------------------------------------------------- #
+def _rows_to_md(rows):
+    rows = [r for r in rows if any(str(c).strip() for c in r)]
+    if not rows:
+        return ""
+    cols = max(len(r) for r in rows)
+
+    def cell(x):
+        return str("" if x is None else x).replace("|", r"\|").replace("\n", "<br>").strip()
+
+    def pad(r):
+        r = list(r) + [""] * (cols - len(r))
+        return [cell(c) for c in r]
+
+    head = pad(rows[0])
+    out = "| " + " | ".join(head) + " |\n|" + "|".join(" --- " for _ in head) + "|\n"
+    for r in rows[1:]:
+        out += "| " + " | ".join(pad(r)) + " |\n"
+    return out
+
+
+def _read_text(source):
+    return Path(source).read_text(encoding="utf-8-sig")
+
+
+@registry.ingester("csv")
+def csv_to_md(source, ds=None, **_):
+    return _rows_to_md(list(_csv.reader(io.StringIO(_read_text(source)))))
+
+
+@registry.ingester("tsv")
+def tsv_to_md(source, ds=None, **_):
+    return _rows_to_md(list(_csv.reader(io.StringIO(_read_text(source)), delimiter="\t")))
+
+
+@registry.ingester("json")
+def json_to_md(source, ds=None, **_):
+    raw = _read_text(source)
+    try:
+        data = json.loads(raw)
+    except Exception:
+        return "```json\n" + raw.strip() + "\n```"
+    if (isinstance(data, list) and data
+            and all(isinstance(x, dict) for x in data)):
+        cols = list(dict.fromkeys(k for o in data for k in o))
+        rows = [cols] + [[(json.dumps(o[c], ensure_ascii=False)
+                           if isinstance(o.get(c), (dict, list))
+                           else o.get(c, "")) for c in cols] for o in data]
+        return _rows_to_md(rows)
+    return "```json\n" + json.dumps(data, ensure_ascii=False, indent=2) + "\n```"
+
+
+@registry.ingester("html")
+def html_to_md(source, ds=None, html=None, **_):
+    from markdownify import markdownify as _md
+    text = html if html is not None else _read_text(source)
+    return _md(text, heading_style="ATX", bullets="-").strip()
+
+
+@registry.ingester("docx")
+def docx_to_md(source, ds=None, **_):
+    try:
+        import mammoth
+    except ImportError as e:  # pragma: no cover
+        raise ConversionError("docx support needs `pip install docstudio[office]` (mammoth)") from e
+    with open(source, "rb") as fh:
+        html = mammoth.convert_to_html(fh).value
+    return html_to_md(None, html=html)
+
+
+@registry.ingester("pptx")
+def pptx_to_md(source, ds=None, **_):
+    try:
+        from pptx import Presentation
+    except ImportError as e:  # pragma: no cover
+        raise ConversionError("pptx support needs `pip install docstudio[office]` (python-pptx)") from e
+    prs = Presentation(str(source))
+    out = []
+    for i, slide in enumerate(prs.slides, 1):
+        out.append(f"## Slide {i}\n")
+        for shape in slide.shapes:
+            if shape.has_text_frame:
+                for para in shape.text_frame.paragraphs:
+                    t = "".join(run.text for run in para.runs).strip()
+                    if t:
+                        out.append(f"- {t}")
+        out.append("")
+    return "\n".join(out).strip()
+
+
+@registry.ingester("xlsx")
+def xlsx_to_md(source, ds=None, **_):
+    try:
+        import openpyxl
+    except ImportError as e:  # pragma: no cover
+        raise ConversionError("xlsx support needs `pip install docstudio[office]` (openpyxl)") from e
+    wb = openpyxl.load_workbook(str(source), read_only=True, data_only=True)
+    parts = []
+    for ws in wb.worksheets:
+        rows = [[("" if c is None else c) for c in row]
+                for row in ws.iter_rows(values_only=True)]
+        if rows:
+            parts.append(f"## {ws.title}\n\n" + _rows_to_md(rows))
+    return "\n\n".join(parts).strip()
+
+
+@registry.ingester("epub")
+def epub_to_md(source, ds=None, **_):
+    try:
+        from ebooklib import epub, ITEM_DOCUMENT
+    except ImportError as e:  # pragma: no cover
+        raise ConversionError("epub support needs `pip install docstudio[office]` (ebooklib)") from e
+    book = epub.read_epub(str(source))
+    parts = []
+    for item in book.get_items_of_type(ITEM_DOCUMENT):
+        parts.append(html_to_md(None, html=item.get_content().decode("utf-8", "ignore")))
+    return "\n\n".join(p for p in parts if p.strip()).strip()
+
+
+@registry.ingester("pdf")
+def pdf_to_md(source, ds=None, vlm_if_scanned=True, **_):
+    try:
+        from pdfminer.high_level import extract_text
+    except ImportError as e:  # pragma: no cover
+        raise ConversionError("pdf support needs `pip install docstudio[pdf]` (pdfminer.six)") from e
+    text = (extract_text(str(source)) or "").strip()
+    # crude scanned detection; fall back to the VLM/OCR path when available
+    if len(text) < 40 and vlm_if_scanned and ds is not None and getattr(ds, "llm", None):
+        return _pdf_vlm(source, ds)
+    return _collapse(text)
+
+
+def _pdf_vlm(source, ds):
+    try:
+        import fitz  # PyMuPDF
+    except ImportError as e:  # pragma: no cover
+        raise ConversionError("scanned-PDF VLM path needs `pip install docstudio[ocr]` (PyMuPDF)") from e
+    doc = fitz.open(str(source))
+    out = []
+    for page in doc:
+        pix = page.get_pixmap(dpi=180)
+        out.append(ds.llm.vlm_extract(pix.tobytes("png"), mode="text"))
+    return "\n\n".join(out).strip()
+
+
+@registry.ingester("image")
+def image_to_md(source, ds=None, mode="text", **_):
+    if ds is not None and getattr(ds, "llm", None) and ds.llm.has_vision:
+        return ds.llm.vlm_extract(Path(source).read_bytes(), mode=mode)
+    try:
+        import pytesseract
+        from PIL import Image
+    except ImportError as e:  # pragma: no cover
+        raise ConversionError(
+            "image OCR needs a vision model (configure llm) or "
+            "`pip install docstudio[ocr]` (pytesseract+Pillow)") from e
+    return pytesseract.image_to_string(Image.open(source), lang="chi_sim+eng").strip()
+
+
+@registry.ingester("zip")
+def zip_to_md(source, ds=None, **_):
+    out, n = [], 0
+    with zipfile.ZipFile(source) as zf:
+        for name in sorted(zf.namelist()):
+            if name.endswith("/") or "__MACOSX" in name:
+                continue
+            try:
+                fmt = detect_format(name)
+            except ConversionError:
+                continue
+            tmp = Path("/tmp") / Path(name).name
+            tmp.write_bytes(zf.read(name))
+            try:
+                part = ds.to_markdown(tmp, fmt=fmt) if ds else ""
+            except Exception as e:  # noqa: BLE001
+                part = f"_(failed: {e})_"
+            finally:
+                tmp.unlink(missing_ok=True)
+            if part.strip():
+                n += 1
+                out.append(f"## {name}\n\n{part.strip()}\n\n---")
+    return (f"# Archive ({n} files)\n\n" + "\n\n".join(out)).strip() if n else "(no convertible files)"
+
+
+def _collapse(text):
+    import re
+    return re.sub(r"\n{3,}", "\n\n", text).strip()

docstudio/latex.py

@@ -0,0 +1,124 @@
+"""Markdown -> LaTeX (self-contained, no pandoc required).
+
+A faithful port of the browser tool's tested `mdToLaTeX`: math (`$...$`,
+`$$...$$`) and code are protected before escaping; Chinese documents use the
+``ctexart`` class (compile with xelatex), otherwise ``article``."""
+from __future__ import annotations
+
+import re
+
+_SPECIAL = {"&": r"\&", "%": r"\%", "#": r"\#", "_": r"\_",
+            "{": r"\{", "}": r"\}", "$": r"\$",
+            "~": r"\textasciitilde{}", "^": r"\textasciicircum{}"}
+
+
+def _escape(text: str) -> str:
+    text = text.replace("\\", "\x00")
+    for ch, rep in _SPECIAL.items():
+        text = text.replace(ch, rep)
+    return text.replace("\x00", r"\textbackslash{}")
+
+
+def _inline(text: str) -> str:
+    # protect inline code first
+    codes = []
+    def _c(m):
+        codes.append(m.group(1)); return f"\x01{len(codes)-1}\x01"
+    text = re.sub(r"`([^`]+)`", _c, text)
+
+    text = _escape(text)
+    text = re.sub(r"\*\*(.+?)\*\*", r"\\textbf{\1}", text)
+    text = re.sub(r"(?<!\*)\*(?!\*)(.+?)\*(?!\*)", r"\\textit{\1}", text)
+    text = re.sub(r"\[(.+?)\]\((.+?)\)", r"\\href{\2}{\1}", text)
+
+    for i, c in enumerate(codes):
+        text = text.replace(f"\x01{i}\x01", r"\texttt{" + _escape(c) + "}")
+    return text
+
+
+def md_to_latex(md: str, title: str = "", chinese: bool | None = None) -> str:
+    if chinese is None:
+        chinese = bool(re.search(r"[\u4e00-\u9fff]", md))
+
+    # protect math + fenced code with placeholders
+    store = []
+    def _stash(m):
+        store.append(m.group(0)); return f"\x02{len(store)-1}\x02"
+    md = re.sub(r"\$\$[\s\S]+?\$\$|\$(?:\\.|[^$\n])+?\$|```[\s\S]*?```",
+                _stash, md)
+
+    body, lines, i = [], md.split("\n"), 0
+    while i < len(lines):
+        line = lines[i]
+        m = re.match(r"^(#{1,6})\s+(.+)", line)
+        if m:
+            depth = len(m.group(1))
+            cmd = ["section", "section", "subsection", "subsubsection",
+                   "paragraph", "subparagraph", "subparagraph"][depth]
+            body.append(f"\\{cmd}{{{_inline(m.group(2))}}}")
+            i += 1; continue
+        # table
+        if re.match(r"^\s*\|.*\|\s*$", line) and i + 1 < len(lines) \
+                and re.match(r"^\s*\|?[\s:|-]+\|?\s*$", lines[i + 1]) and "-" in lines[i + 1]:
+            block = []
+            while i < len(lines) and "|" in lines[i]:
+                block.append(lines[i]); i += 1
+            body.append(_table(block)); continue
+        # unordered / ordered list
+        if re.match(r"^\s*[-*]\s+", line) or re.match(r"^\s*\d+\.\s+", line):
+            ordered = bool(re.match(r"^\s*\d+\.", line))
+            env = "enumerate" if ordered else "itemize"
+            items = []
+            while i < len(lines) and (re.match(r"^\s*[-*]\s+", lines[i])
+                                      or re.match(r"^\s*\d+\.\s+", lines[i])):
+                items.append(re.sub(r"^\s*(?:[-*]|\d+\.)\s+", "", lines[i]))
+                i += 1
+            body.append(f"\\begin{{{env}}}")
+            body += [f"  \\item {_inline(it)}" for it in items]
+            body.append(f"\\end{{{env}}}")
+            continue
+        # blockquote
+        if line.startswith(">"):
+            quote = []
+            while i < len(lines) and lines[i].startswith(">"):
+                quote.append(lines[i][1:].strip()); i += 1
+            body.append("\\begin{quote}\n" + _inline(" ".join(quote)) + "\n\\end{quote}")
+            continue
+        if line.strip() == "":
+            body.append(""); i += 1; continue
+        body.append(_inline(line)); i += 1
+
+    text = "\n".join(body)
+    # restore math / code
+    def _restore(m):
+        s = store[int(m.group(1))]
+        if s.startswith("```"):
+            inner = s.strip("`")
+            inner = re.sub(r"^[a-zA-Z0-9]*\n", "", inner)
+            return "\\begin{verbatim}\n" + inner + "\n\\end{verbatim}"
+        return s
+    text = re.sub(r"\x02(\d+)\x02", _restore, text)
+
+    cls = "ctexart" if chinese else "article"
+    pkgs = ["\\usepackage{amsmath,amssymb}", "\\usepackage{hyperref}",
+            "\\usepackage{graphicx}", "\\usepackage{booktabs}"]
+    head = (f"\\documentclass[12pt]{{{cls}}}\n" + "\n".join(pkgs) +
+            (f"\n\\title{{{_inline(title)}}}\n\\date{{}}" if title else ""))
+    doc = "\\begin{document}\n" + ("\\maketitle\n" if title else "") + text + "\n\\end{document}\n"
+    return head + "\n" + doc
+
+
+def _table(block):
+    rows = [r for k, r in enumerate(block) if k != 1]
+    cells = [[c.replace(r"\|", "|").strip()
+              for c in re.sub(r"^\s*\||\|\s*$", "", r).split("|")] for r in rows]
+    ncol = max(len(r) for r in cells)
+    spec = "l" * ncol
+    out = ["\\begin{tabular}{" + spec + "}", "\\toprule"]
+    for k, r in enumerate(cells):
+        r = r + [""] * (ncol - len(r))
+        out.append(" & ".join(_inline(c) for c in r) + " \\\\")
+        if k == 0:
+            out.append("\\midrule")
+    out += ["\\bottomrule", "\\end{tabular}"]
+    return "\n".join(out)

docstudio/llm.py

@@ -0,0 +1,106 @@
+"""OpenAI-compatible LLM + Vision (VLM) client.
+
+Mirrors the browser tool: one base URL / key for a text model, and an optional
+(possibly different) endpoint for a vision model used to recognise images and
+scanned PDFs.  Only depends on ``requests``."""
+from __future__ import annotations
+
+import base64
+from typing import List, Optional, Union
+
+
+class LLM:
+    def __init__(self, base_url="", api_key="",
+                 model="", *, vlm_model="", vlm_base_url="", vlm_api_key="",
+                 temperature=0.2):
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.model = model
+        self.vlm_model = vlm_model
+        self.vlm_base_url = (vlm_base_url or base_url).rstrip("/")
+        self.vlm_api_key = vlm_api_key or api_key
+        self.temperature = temperature
+
+    # -- discovery -------------------------------------------------------- #
+    @staticmethod
+    def fetch_models(base_url: str, api_key: str) -> List[str]:
+        import requests
+        base = base_url.rstrip("/")
+        ep = base + ("/models" if base.endswith("/v1") else "/v1/models")
+        r = requests.get(ep, headers={"Authorization": f"Bearer {api_key}"}, timeout=30)
+        r.raise_for_status()
+        data = r.json().get("data", r.json())
+        ids = [(m if isinstance(m, str) else m.get("id") or m.get("name"))
+               for m in (data or [])]
+        return sorted({i for i in ids if i})
+
+    # -- text ------------------------------------------------------------- #
+    def chat(self, system: str, user: str) -> str:
+        import requests
+        if not self.base_url:
+            raise ValueError("LLM.base_url is not set — pass your OpenAI-compatible "
+                             "endpoint, e.g. base_url='https://api.openai.com'")
+        if not self.model:
+            raise ValueError("LLM.model is not set — pass the model id for your provider, "
+                             "e.g. model='gpt-4o-mini'")
+        ep = self._ep(self.base_url)
+        r = requests.post(ep, headers=self._h(self.api_key), timeout=120, json={
+            "model": self.model, "temperature": self.temperature,
+            "messages": [{"role": "system", "content": system},
+                         {"role": "user", "content": user}]})
+        r.raise_for_status()
+        return r.json()["choices"][0]["message"]["content"]
+
+    def cleanup_markdown(self, raw: str) -> str:
+        """AI 'smart cleanup' — turn rough extracted text into clean Markdown."""
+        return self.chat(
+            "You convert rough text into clean, well-structured GitHub-Flavored "
+            "Markdown. Preserve headings, lists, tables and math ($...$). "
+            "Output only Markdown.", raw)
+
+    # -- vision ----------------------------------------------------------- #
+    @property
+    def has_vision(self) -> bool:
+        return bool(self.vlm_model and (self.vlm_api_key or self.api_key))
+
+    def vlm_extract(self, image: Union[bytes, str], mode: str = "text") -> str:
+        import requests
+        if not self.vlm_base_url:
+            raise ValueError("no vision endpoint — set vlm_base_url (or base_url) and vlm_model")
+        if not self.vlm_model:
+            raise ValueError("LLM.vlm_model is not set — pass the vision model id for your provider")
+        data_url = self._data_url(image)
+        prompt = (
+            "Recognise the table(s) in the image and output ONLY standard "
+            "Markdown table(s) with a header and |---| separator row, no prose."
+            if mode == "table" else
+            "Transcribe all text in the image as Markdown, preserving headings, "
+            "lists, tables and math ($...$). Output only the content.")
+        ep = self._ep(self.vlm_base_url)
+        r = requests.post(ep, headers=self._h(self.vlm_api_key), timeout=180, json={
+            "model": self.vlm_model, "temperature": 0.1, "max_tokens": 4096,
+            "messages": [{"role": "user", "content": [
+                {"type": "text", "text": prompt},
+                {"type": "image_url", "image_url": {"url": data_url}}]}]})
+        r.raise_for_status()
+        out = r.json()["choices"][0]["message"]["content"]
+        if isinstance(out, list):
+            out = "".join(p.get("text", "") for p in out)
+        import re
+        return re.sub(r"^```(?:markdown|md)?\s*\n?|\n?```\s*$", "", out).strip()
+
+    # -- helpers ---------------------------------------------------------- #
+    @staticmethod
+    def _ep(base):
+        return base + ("/chat/completions" if base.endswith("/v1") else "/v1/chat/completions")
+
+    @staticmethod
+    def _h(key):
+        return {"Content-Type": "application/json", "Authorization": f"Bearer {key}"}
+
+    @staticmethod
+    def _data_url(image):
+        if isinstance(image, str) and image.startswith("data:"):
+            return image
+        raw = image if isinstance(image, (bytes, bytearray)) else open(image, "rb").read()
+        return "data:image/png;base64," + base64.b64encode(raw).decode()

docstudio/templates.py

@@ -0,0 +1,61 @@
+"""Built-in Markdown templates — the template library from the web app.
+
+Each template mirrors the Document Studio web app. Use :func:`names` to list
+them and :func:`get` to fetch the Markdown body.
+"""
+from __future__ import annotations
+
+# slug -> {"title": zh title, "desc": zh description, "md": markdown body}
+TEMPLATES = {
+    "academic": {
+        "title": "学术论文",
+        "desc": "标题、摘要、引言、方法、实验、结论、参考文献结构",
+        "md": "# 论文标题\n\n## 摘要\n\n本文提出……\n\n**关键词**：关键词1；关键词2\n\n## 1. 引言\n\n研究背景与动机。公式示例 $f(x)=\\sum_{i=1}^{n} w_i x_i$。\n\n## 2. 方法\n\n### 2.1 模型\n\n$$\\mathcal{L}=\\mathcal{L}_{cls}+\\lambda\\mathcal{L}_{reg}$$\n\n## 3. 实验\n\n| 方法 | 准确率 |\n|------|--------|\n| Baseline | 78.3% |\n| Ours | **85.1%** |\n\n## 4. 结论\n\n## 参考文献\n\n[1] Author. Title. Venue, Year.",
+    },
+    "techdoc": {
+        "title": "技术文档",
+        "desc": "概述、安装、用法、API、示例的标准技术文档",
+        "md": "# 项目名称\n\n> 一句话简介。\n\n## 概述\n\n## 安装\n\n```bash\nnpm install package-name\n```\n\n## 快速开始\n\n```js\nimport { run } from 'package-name';\nrun();\n```\n\n## API\n\n### `run(options)`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| options | object | 配置项 |\n\n## 许可证\n\nMIT",
+    },
+    "minutes": {
+        "title": "会议纪要",
+        "desc": "时间、参会人、议题、决议、待办事项",
+        "md": "# 会议纪要\n\n- **时间**：2026-06-20 14:00\n- **参会人**：\n- **主持**：\n\n## 议题\n\n1. \n2. \n\n## 讨论与决议\n\n## 待办事项\n\n- [ ] 事项一 — 负责人 — 截止日期\n- [ ] 事项二",
+    },
+    "readme": {
+        "title": "README",
+        "desc": "开源项目 README 模板，含徽章、特性、贡献",
+        "md": "# 项目名\n\n简短描述。\n\n## ✨ 特性\n\n- 特性一\n- 特性二\n\n## 📦 安装\n\n```bash\n# ...\n```\n\n## 🚀 使用\n\n## 🤝 贡献\n\n欢迎 PR。\n\n## 📄 License\n\nMIT © 2026",
+    },
+    "weekly": {
+        "title": "周报",
+        "desc": "本周完成、下周计划、问题与风险",
+        "md": "# 本周工作周报\n\n## ✅ 本周完成\n\n1. \n2. \n\n## 📋 下周计划\n\n1. \n\n## ⚠️ 问题与风险\n\n## 💡 备注",
+    },
+    "blog": {
+        "title": "博客文章",
+        "desc": "带封面、引言、小标题的文章结构",
+        "md": "# 文章标题\n\n*发布于 2026-06-20*\n\n> 引言：用一段话抓住读者。\n\n## 背景\n\n## 正文小标题\n\n正文内容……\n\n## 结语\n\n感谢阅读。",
+    },
+}
+
+
+def names():
+    """Return the list of template slugs (academic, techdoc, minutes, ...)."""
+    return list(TEMPLATES)
+
+
+def info():
+    """Return ``{slug: (title, description)}`` for all templates."""
+    return {k: (v["title"], v["desc"]) for k, v in TEMPLATES.items()}
+
+
+def get(name: str) -> str:
+    """Return the Markdown body of template ``name`` (by slug or zh title)."""
+    if name in TEMPLATES:
+        return TEMPLATES[name]["md"]
+    for v in TEMPLATES.values():
+        if v["title"] == name:
+            return v["md"]
+    raise KeyError("unknown template %r; choose from: %s"
+                   % (name, ", ".join(TEMPLATES)))

docstudio/tools.py

@@ -0,0 +1,107 @@
+"""Headless document utilities — the toolbox from the Document Studio web app.
+
+These are pure / lightweight helpers that don't need a browser:
+
+* :func:`generate_toc`   — build & insert a Markdown table of contents
+* :func:`merge_pdfs`     — concatenate several PDFs into one (pypdf)
+* :func:`extract_images` — pull embedded images out of PDF / DOCX / PPTX / EPUB
+"""
+from __future__ import annotations
+
+import re
+import zipfile
+from pathlib import Path
+from typing import List
+
+_IMG_EXT = {"png", "jpg", "jpeg", "gif", "bmp", "svg", "webp", "emf", "wmf", "tiff"}
+
+
+def generate_toc(md: str, title: str = "目录") -> str:
+    """Return ``md`` with a Markdown table of contents inserted.
+
+    The TOC is built from ``##`` and ``###`` headings (``###`` indented),
+    placed right after the first ``#`` title, or prepended if there is none.
+    Faithful port of the web app's *Table of contents* tool.
+    """
+    heads = re.findall(r"^(#{2,3})\s+(.+)$", md, flags=re.M)
+    if not heads:
+        return md
+    toc = "## %s\n\n" % title
+    for hashes, text in heads:
+        indent = "  " if len(hashes) == 3 else ""
+        toc += "%s- %s\n" % (indent, text.strip())
+    m = re.search(r"^#\s+.+$", md, flags=re.M)
+    if m:
+        return md.replace(m.group(0), m.group(0) + "\n\n" + toc, 1)
+    return toc + "\n" + md
+
+
+def merge_pdfs(paths: List[str], out: str) -> str:
+    """Merge ``paths`` (PDF files) into a single PDF written to ``out``.
+
+    Requires ``pypdf`` (``pip install "docstudio[pdf]"``).
+    """
+    if not paths:
+        raise ValueError("merge_pdfs: no input PDFs given")
+    try:
+        from pypdf import PdfReader, PdfWriter
+    except ImportError as e:  # pragma: no cover
+        raise RuntimeError('merge_pdfs needs pypdf: pip install "docstudio[pdf]"') from e
+    writer = PdfWriter()
+    for p in paths:
+        reader = PdfReader(str(p))
+        for page in reader.pages:
+            writer.add_page(page)
+    out = str(out)
+    with open(out, "wb") as fh:
+        writer.write(fh)
+    return out
+
+
+def extract_images(source: str, out_dir: str) -> List[str]:
+    """Extract embedded images from ``source`` into ``out_dir``.
+
+    Supports PDF (via PyMuPDF) and OOXML / EPUB containers (DOCX, PPTX, XLSX,
+    EPUB) by reading their ``media`` parts. Returns the written file paths.
+    """
+    src = Path(source)
+    out = Path(out_dir)
+    out.mkdir(parents=True, exist_ok=True)
+    ext = src.suffix.lower().lstrip(".")
+    written: List[str] = []
+
+    if ext == "pdf":
+        try:
+            import fitz  # PyMuPDF
+        except ImportError as e:  # pragma: no cover
+            raise RuntimeError('PDF image extraction needs PyMuPDF: '
+                               'pip install "docstudio[ocr]"') from e
+        doc = fitz.open(str(src))
+        seen = set()
+        for pno in range(len(doc)):
+            for img in doc.get_page_images(pno):
+                xref = img[0]
+                if xref in seen:
+                    continue
+                seen.add(xref)
+                pix = fitz.Pixmap(doc, xref)
+                if pix.n - pix.alpha >= 4:  # CMYK / other -> RGB
+                    pix = fitz.Pixmap(fitz.csRGB, pix)
+                fn = out / ("img_%03d.png" % xref)
+                pix.save(str(fn))
+                written.append(str(fn))
+        doc.close()
+
+    elif ext in ("docx", "pptx", "xlsx", "epub"):
+        with zipfile.ZipFile(str(src)) as z:
+            for name in z.namelist():
+                low = name.lower()
+                tail = low.rsplit(".", 1)[-1]
+                if ("media" in low or "image" in low) and tail in _IMG_EXT:
+                    target = out / Path(name).name
+                    target.write_bytes(z.read(name))
+                    written.append(str(target))
+    else:
+        raise ValueError("unsupported source for image extraction: .%s" % ext)
+
+    return written