docstudio 0.2.0__tar.gz

docstudio-0.2.0/.gitignore

@@ -0,0 +1,35 @@
+# Build artifacts
+dist/
+build/
+*.egg-info/
+*.egg
+.eggs/
+
+# Byte-compiled / cache
+__pycache__/
+*.py[cod]
+*.so
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Tooling / IDE
+.idea/
+.vscode/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Local secrets — never commit tokens
+.pypirc
+*.token
+.env

docstudio-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 biaoli
+
+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.

docstudio-0.2.0/PKG-INFO

@@ -0,0 +1,223 @@
+Metadata-Version: 2.4
+Name: docstudio
+Version: 0.2.0
+Summary: Bidirectional, Markdown-centric document conversion: reverse (X->Markdown) like markitdown, plus high-fidelity forward export (Markdown->PDF/Word/LaTeX/EPUB/Excel) and optional VLM image recognition.
+Project-URL: Homepage, https://github.com/Sudo-Biao/docstudio
+Project-URL: Repository, https://github.com/Sudo-Biao/docstudio
+Project-URL: Issues, https://github.com/Sudo-Biao/docstudio/issues
+Author-email: biaoli <biaoli@swufe.edu.cn>
+License: MIT
+License-File: LICENSE
+Keywords: conversion,document,docx,epub,latex,markdown,markitdown,ocr,pdf,vlm
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Office/Business
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.9
+Requires-Dist: markdown>=3.5
+Requires-Dist: markdownify>=0.11
+Provides-Extra: all
+Requires-Dist: ebooklib; extra == 'all'
+Requires-Dist: mammoth; extra == 'all'
+Requires-Dist: markitdown[all]; extra == 'all'
+Requires-Dist: openpyxl; extra == 'all'
+Requires-Dist: pdfminer-six; extra == 'all'
+Requires-Dist: pillow; extra == 'all'
+Requires-Dist: pymupdf; extra == 'all'
+Requires-Dist: pypdf; extra == 'all'
+Requires-Dist: pytesseract; extra == 'all'
+Requires-Dist: python-docx; extra == 'all'
+Requires-Dist: python-pptx; extra == 'all'
+Requires-Dist: requests; extra == 'all'
+Provides-Extra: llm
+Requires-Dist: requests; extra == 'llm'
+Provides-Extra: markitdown
+Requires-Dist: markitdown[all]; extra == 'markitdown'
+Provides-Extra: ocr
+Requires-Dist: pillow; extra == 'ocr'
+Requires-Dist: pymupdf; extra == 'ocr'
+Requires-Dist: pytesseract; extra == 'ocr'
+Provides-Extra: office
+Requires-Dist: ebooklib; extra == 'office'
+Requires-Dist: mammoth; extra == 'office'
+Requires-Dist: openpyxl; extra == 'office'
+Requires-Dist: python-docx; extra == 'office'
+Requires-Dist: python-pptx; extra == 'office'
+Provides-Extra: pdf
+Requires-Dist: pdfminer-six; extra == 'pdf'
+Requires-Dist: pypdf; extra == 'pdf'
+Provides-Extra: pdf-chrome
+Requires-Dist: playwright; extra == 'pdf-chrome'
+Provides-Extra: pdf-weasy
+Requires-Dist: weasyprint; extra == 'pdf-weasy'
+Description-Content-Type: text/markdown
+
+# DocumentStudio (Python)
+
+A **bidirectional, Markdown-centric** document converter — a Python library and
+CLI in the spirit of Microsoft's [`markitdown`](https://github.com/microsoft/markitdown),
+but going **both ways**:
+
+| Direction | Formats | Notes |
+|-----------|---------|-------|
+| **Reverse** `X → Markdown` | PDF, Word, PPT, Excel, EPUB, HTML, CSV/TSV, JSON, ZIP, images | like markitdown; can *delegate to* markitdown when installed |
+| **Forward** `Markdown → X` | HTML, **PDF**, **Word (.docx)**, **LaTeX**, EPUB, Excel (.xlsx), text | high-fidelity export — the part markitdown does **not** do |
+| **AI / VLM** | image & scanned-PDF recognition, "smart cleanup" | any OpenAI-compatible endpoint; vision model optional |
+| **AI assistant** | polish, translate, summarise, expand, continue, grammar, formalise, titles, outline, fix-LaTeX, free-form | one-shot ops on a document |
+| **Toolbox** | table of contents, merge PDFs, extract images | headless, no browser |
+| **Templates** | academic, techdoc, minutes, readme, weekly, blog | ready-to-edit Markdown |
+
+The design mirrors markitdown's: a small core, a converter **registry** that's open
+for extension, and **optional dependency extras** so a minimal install still works.
+
+## Install
+
+```bash
+pip install docstudio                 # core: csv/tsv/json/html  +  md→html/latex/text
+pip install "docstudio[office]"       # docx, pptx, xlsx, epub
+pip install "docstudio[pdf]"          # PDF text extraction (pdfminer.six)
+pip install "docstudio[ocr]"          # scanned-PDF / image OCR (PyMuPDF, pytesseract)
+pip install "docstudio[llm]"          # AI cleanup + VLM (requests)
+pip install "docstudio[markitdown]"   # reuse Microsoft markitdown for the reverse path
+pip install "docstudio[all]"
+```
+
+For **Markdown → PDF/DOCX/EPUB** with the best fidelity, install
+[`pandoc`](https://pandoc.org) plus a TeX engine (`xelatex`):
+```bash
+sudo apt install pandoc texlive-xetex texlive-latex-recommended fonts-noto-cjk
+```
+PDF also has two pure-Python backends as fallbacks: `weasyprint`
+(`docstudio[pdf-weasy]`) and headless-Chrome via `playwright`
+(`docstudio[pdf-chrome]`, full KaTeX math).
+
+## Library
+
+```python
+from docstudio import DocumentStudio
+ds = DocumentStudio()                       # use_markitdown=True by default
+
+# anything → Markdown
+md = ds.to_markdown("report.pdf")
+md = ds.to_markdown("slides.pptx")
+
+# Markdown → anything (non-md inputs are auto-converted first)
+ds.convert("paper.md",  to="pdf",   out="paper.pdf")
+ds.convert("paper.md",  to="docx",  out="paper.docx")
+ds.convert("scan.pdf",  to="docx",  out="scan.docx")   # PDF → md → docx
+ds.convert("table.png", to="xlsx",  out="table.xlsx")  # image → md → xlsx
+```
+
+### AI + Vision (VLM)
+
+```python
+from docstudio import DocumentStudio
+from docstudio.llm import LLM
+
+llm = LLM(base_url="https://api.openai.com", api_key="sk-...",
+          model="gpt-4o-mini", vlm_model="gpt-4o")
+
+print(LLM.fetch_models("https://api.openai.com", "sk-..."))   # pick from the list
+
+ds = DocumentStudio(llm=llm)
+md = ds.to_markdown("photographed_table.jpg")   # recognised by the vision model
+md = ds.to_markdown("scanned_book.pdf")         # page-by-page VLM when no text layer
+md = llm.cleanup_markdown(rough_text)           # turn messy OCR into clean Markdown
+```
+
+## AI assistant (operate on a document)
+
+One-shot AI operations on Markdown/text — the *AI Assistant* from the web app.
+Needs an `llm` (any OpenAI-compatible endpoint).
+
+```python
+from docstudio import DocumentStudio
+from docstudio.llm import LLM
+
+# any OpenAI-compatible endpoint — OpenAI, DeepSeek, vLLM, Ollama, a gateway…
+# you choose base_url + model; nothing is hard-coded to a provider
+ds = DocumentStudio(llm=LLM(base_url="https://api.openai.com",
+                            api_key="sk-...", model="gpt-4o-mini"))
+
+ds.assist(md, action="polish")     # 润色
+ds.assist(md, action="to_en")      # 翻译成英文（to_zh 反之）
+ds.assist(md, action="summary")    # 摘要
+ds.assist(md, action="outline")    # 生成大纲
+ds.assist(md, instruction="把所有表格改成要点列表")   # 自由指令
+
+DocumentStudio.assist_actions()
+# polish, to_en, to_zh, summary, expand, condense, continue,
+# grammar, formal, titles, outline, fix_latex
+```
+
+## Toolbox
+
+```python
+ds.generate_toc(md)                              # insert a Markdown table of contents
+ds.merge_pdfs(["a.pdf", "b.pdf"], "all.pdf")     # concatenate PDFs (needs pypdf)
+ds.extract_images("report.pdf", "./imgs")        # pull embedded images out (PDF/DOCX/PPTX/EPUB)
+```
+
+## Templates
+
+Six ready-to-edit Markdown templates: `academic`, `techdoc`, `minutes`,
+`readme`, `weekly`, `blog`.
+
+```python
+ds.templates()                # {slug: (title, description)}
+body = ds.template("academic")
+```
+
+## CLI
+
+```bash
+docstudio report.pdf                      # → report.md   (prints to stdout)
+docstudio report.pdf -o out.md
+cat report.pdf | docstudio                # stdin → stdout
+docstudio paper.md --to pdf -o paper.pdf  # Markdown → anything
+docstudio scan.pdf --to docx              # PDF → md → docx
+docstudio photo.jpg --vlm-model gpt-4o --base-url https://api.openai.com --api-key sk-...
+docstudio --list-formats
+
+docstudio paper.md --toc -o paper.md                     # insert a table of contents
+docstudio notes.md --assist polish --base-url https://api.openai.com --model gpt-4o-mini --api-key sk-... -o clean.md
+docstudio notes.md --instruction "翻译成英文" --base-url https://api.openai.com --model gpt-4o-mini --api-key sk-... -o en.md
+docstudio --merge a.pdf b.pdf -o all.pdf                 # merge PDFs
+docstudio report.pdf --extract-images ./imgs             # pull out images
+docstudio --template academic                            # print a template
+docstudio --list-templates
+```
+
+## Extending
+
+Register your own converter — exactly how the built-ins are defined:
+
+```python
+from docstudio.core import registry
+
+@registry.ingester("rtf")
+def rtf_to_md(source, ds=None, **opts):
+    ...
+    return markdown_text
+
+@registry.exporter("rst")
+def md_to_rst(md, out=None, ds=None, **opts):
+    ...
+    return out
+```
+
+## Relationship to markitdown
+
+`markitdown` is excellent at `X → Markdown` for LLM pipelines. DocumentStudio
+**reuses** it for that direction when present (`use_markitdown=True`), and adds the
+missing half: turning Markdown back into polished, human-facing **PDF / Word /
+LaTeX / EPUB / Excel**, plus a vision-model path for images and scanned PDFs.
+
+MIT licensed.

docstudio-0.2.0/README.md

@@ -0,0 +1,162 @@
+# DocumentStudio (Python)
+
+A **bidirectional, Markdown-centric** document converter — a Python library and
+CLI in the spirit of Microsoft's [`markitdown`](https://github.com/microsoft/markitdown),
+but going **both ways**:
+
+| Direction | Formats | Notes |
+|-----------|---------|-------|
+| **Reverse** `X → Markdown` | PDF, Word, PPT, Excel, EPUB, HTML, CSV/TSV, JSON, ZIP, images | like markitdown; can *delegate to* markitdown when installed |
+| **Forward** `Markdown → X` | HTML, **PDF**, **Word (.docx)**, **LaTeX**, EPUB, Excel (.xlsx), text | high-fidelity export — the part markitdown does **not** do |
+| **AI / VLM** | image & scanned-PDF recognition, "smart cleanup" | any OpenAI-compatible endpoint; vision model optional |
+| **AI assistant** | polish, translate, summarise, expand, continue, grammar, formalise, titles, outline, fix-LaTeX, free-form | one-shot ops on a document |
+| **Toolbox** | table of contents, merge PDFs, extract images | headless, no browser |
+| **Templates** | academic, techdoc, minutes, readme, weekly, blog | ready-to-edit Markdown |
+
+The design mirrors markitdown's: a small core, a converter **registry** that's open
+for extension, and **optional dependency extras** so a minimal install still works.
+
+## Install
+
+```bash
+pip install docstudio                 # core: csv/tsv/json/html  +  md→html/latex/text
+pip install "docstudio[office]"       # docx, pptx, xlsx, epub
+pip install "docstudio[pdf]"          # PDF text extraction (pdfminer.six)
+pip install "docstudio[ocr]"          # scanned-PDF / image OCR (PyMuPDF, pytesseract)
+pip install "docstudio[llm]"          # AI cleanup + VLM (requests)
+pip install "docstudio[markitdown]"   # reuse Microsoft markitdown for the reverse path
+pip install "docstudio[all]"
+```
+
+For **Markdown → PDF/DOCX/EPUB** with the best fidelity, install
+[`pandoc`](https://pandoc.org) plus a TeX engine (`xelatex`):
+```bash
+sudo apt install pandoc texlive-xetex texlive-latex-recommended fonts-noto-cjk
+```
+PDF also has two pure-Python backends as fallbacks: `weasyprint`
+(`docstudio[pdf-weasy]`) and headless-Chrome via `playwright`
+(`docstudio[pdf-chrome]`, full KaTeX math).
+
+## Library
+
+```python
+from docstudio import DocumentStudio
+ds = DocumentStudio()                       # use_markitdown=True by default
+
+# anything → Markdown
+md = ds.to_markdown("report.pdf")
+md = ds.to_markdown("slides.pptx")
+
+# Markdown → anything (non-md inputs are auto-converted first)
+ds.convert("paper.md",  to="pdf",   out="paper.pdf")
+ds.convert("paper.md",  to="docx",  out="paper.docx")
+ds.convert("scan.pdf",  to="docx",  out="scan.docx")   # PDF → md → docx
+ds.convert("table.png", to="xlsx",  out="table.xlsx")  # image → md → xlsx
+```
+
+### AI + Vision (VLM)
+
+```python
+from docstudio import DocumentStudio
+from docstudio.llm import LLM
+
+llm = LLM(base_url="https://api.openai.com", api_key="sk-...",
+          model="gpt-4o-mini", vlm_model="gpt-4o")
+
+print(LLM.fetch_models("https://api.openai.com", "sk-..."))   # pick from the list
+
+ds = DocumentStudio(llm=llm)
+md = ds.to_markdown("photographed_table.jpg")   # recognised by the vision model
+md = ds.to_markdown("scanned_book.pdf")         # page-by-page VLM when no text layer
+md = llm.cleanup_markdown(rough_text)           # turn messy OCR into clean Markdown
+```
+
+## AI assistant (operate on a document)
+
+One-shot AI operations on Markdown/text — the *AI Assistant* from the web app.
+Needs an `llm` (any OpenAI-compatible endpoint).
+
+```python
+from docstudio import DocumentStudio
+from docstudio.llm import LLM
+
+# any OpenAI-compatible endpoint — OpenAI, DeepSeek, vLLM, Ollama, a gateway…
+# you choose base_url + model; nothing is hard-coded to a provider
+ds = DocumentStudio(llm=LLM(base_url="https://api.openai.com",
+                            api_key="sk-...", model="gpt-4o-mini"))
+
+ds.assist(md, action="polish")     # 润色
+ds.assist(md, action="to_en")      # 翻译成英文（to_zh 反之）
+ds.assist(md, action="summary")    # 摘要
+ds.assist(md, action="outline")    # 生成大纲
+ds.assist(md, instruction="把所有表格改成要点列表")   # 自由指令
+
+DocumentStudio.assist_actions()
+# polish, to_en, to_zh, summary, expand, condense, continue,
+# grammar, formal, titles, outline, fix_latex
+```
+
+## Toolbox
+
+```python
+ds.generate_toc(md)                              # insert a Markdown table of contents
+ds.merge_pdfs(["a.pdf", "b.pdf"], "all.pdf")     # concatenate PDFs (needs pypdf)
+ds.extract_images("report.pdf", "./imgs")        # pull embedded images out (PDF/DOCX/PPTX/EPUB)
+```
+
+## Templates
+
+Six ready-to-edit Markdown templates: `academic`, `techdoc`, `minutes`,
+`readme`, `weekly`, `blog`.
+
+```python
+ds.templates()                # {slug: (title, description)}
+body = ds.template("academic")
+```
+
+## CLI
+
+```bash
+docstudio report.pdf                      # → report.md   (prints to stdout)
+docstudio report.pdf -o out.md
+cat report.pdf | docstudio                # stdin → stdout
+docstudio paper.md --to pdf -o paper.pdf  # Markdown → anything
+docstudio scan.pdf --to docx              # PDF → md → docx
+docstudio photo.jpg --vlm-model gpt-4o --base-url https://api.openai.com --api-key sk-...
+docstudio --list-formats
+
+docstudio paper.md --toc -o paper.md                     # insert a table of contents
+docstudio notes.md --assist polish --base-url https://api.openai.com --model gpt-4o-mini --api-key sk-... -o clean.md
+docstudio notes.md --instruction "翻译成英文" --base-url https://api.openai.com --model gpt-4o-mini --api-key sk-... -o en.md
+docstudio --merge a.pdf b.pdf -o all.pdf                 # merge PDFs
+docstudio report.pdf --extract-images ./imgs             # pull out images
+docstudio --template academic                            # print a template
+docstudio --list-templates
+```
+
+## Extending
+
+Register your own converter — exactly how the built-ins are defined:
+
+```python
+from docstudio.core import registry
+
+@registry.ingester("rtf")
+def rtf_to_md(source, ds=None, **opts):
+    ...
+    return markdown_text
+
+@registry.exporter("rst")
+def md_to_rst(md, out=None, ds=None, **opts):
+    ...
+    return out
+```
+
+## Relationship to markitdown
+
+`markitdown` is excellent at `X → Markdown` for LLM pipelines. DocumentStudio
+**reuses** it for that direction when present (`use_markitdown=True`), and adds the
+missing half: turning Markdown back into polished, human-facing **PDF / Word /
+LaTeX / EPUB / Excel**, plus a vision-model path for images and scanned PDFs.
+
+MIT licensed.

docstudio-0.2.0/docstudio/__init__.py

@@ -0,0 +1,35 @@
+"""DocumentStudio — bidirectional document conversion library.
+
+Reverse  (X -> Markdown):  PDF, Word, PPT, Excel, EPUB, HTML, CSV/TSV, JSON,
+                           ZIP, images (OCR / VLM).  Optionally backed by
+                           Microsoft `markitdown` when installed.
+Forward  (Markdown -> X):  HTML, PDF, Word(.docx), LaTeX, EPUB, Excel(.xlsx),
+                           plain text.  High-fidelity export is the part
+                           markitdown does NOT do.
+AI assistant            :  polish, translate, summarise, expand, continue,
+                           grammar, formalise, titles, outline, fix-LaTeX,
+                           free-form instructions.
+Toolbox                 :  table of contents, merge PDFs, extract images.
+Templates               :  academic, techdoc, minutes, readme, weekly, blog.
+
+Quick start
+-----------
+    from docstudio import DocumentStudio
+    ds = DocumentStudio()
+
+    md = ds.to_markdown("report.pdf")                    # anything -> Markdown
+    ds.convert("paper.md", to="pdf", out="paper.pdf")    # Markdown -> anything
+
+    ds.generate_toc(md)                                  # toolbox
+    ds.merge_pdfs(["a.pdf", "b.pdf"], "all.pdf")
+    body = ds.template("academic")                       # template library
+
+    from docstudio.llm import LLM                         # AI assistant
+    ds = DocumentStudio(llm=LLM(base_url="...", api_key="...", model="..."))
+    ds.assist(md, action="polish")
+    ds.assist(md, instruction="把所有表格改成要点列表")
+"""
+from .core import DocumentStudio, ConversionError, registry
+
+__all__ = ["DocumentStudio", "ConversionError", "registry"]
+__version__ = "0.2.0"

docstudio-0.2.0/docstudio/assistant.py

@@ -0,0 +1,73 @@
+"""AI document assistant — LLM-powered operations on Markdown / plain text.
+
+Mirrors the *AI Assistant* of the Document Studio web app: a fixed set of
+one-shot actions (polish, translate, summarise, expand, ...) plus a free-form
+``instruction``. Every action is a single chat completion against whatever
+OpenAI-compatible endpoint the :class:`~docstudio.llm.LLM` is configured for.
+"""
+from __future__ import annotations
+
+import re
+from typing import Optional
+
+# action key -> system prompt (kept in sync with the web app's AI_ACTS)
+ACTIONS = {
+    "polish":    "你是中文技术写作助手。润色下面的 Markdown：提升流畅度、准确性与可读性，"
+                 "规范标点与格式，严格保留原意与全部信息，不新增不删减。只输出 Markdown，不要解释。",
+    "to_en":     "Translate the following Markdown into fluent, natural English. Preserve all "
+                 "Markdown structure (headings, lists, tables, math $...$, code). Output only the "
+                 "translated Markdown.",
+    "to_zh":     "把下面的 Markdown 翻译成自然流畅的简体中文，保留所有 Markdown 结构"
+                 "（标题、列表、表格、公式 $...$、代码）。只输出翻译后的 Markdown。",
+    "summary":   "为下面的内容写一段简洁、准确的摘要（约150-250字）。只输出摘要的 Markdown 段落，不要解释。",
+    "expand":    "扩展并丰富下面的内容：补充细节、例子与解释，保持原结构与风格，不偏离主题、不编造事实。"
+                 "只输出 Markdown。",
+    "condense":  "精炼下面的内容：去除冗余，保留要点与关键信息，保持 Markdown 结构。只输出 Markdown。",
+    "continue":  "延续下面文档的主题、风格与结构，自然地继续往下写 1-3 段。只输出新增的 Markdown 内容，"
+                 "不要重复已有内容。",
+    "grammar":   "修正下面文档中的语法、拼写与标点错误，不改变原意与写作风格。只输出修正后的 Markdown。",
+    "formal":    "把下面的内容改写为更正式、专业的书面语，保留全部信息与 Markdown 结构。只输出 Markdown。",
+    "titles":    "为下面的文档给出 5 个高质量的标题建议，用 Markdown 无序列表呈现。只输出列表。",
+    "outline":   "根据下面的内容或主题，生成一个结构化的 Markdown 多级标题大纲。只输出大纲。",
+    "fix_latex": "修正下面 LaTeX / Markdown 数学公式中的语法错误（缺失的 $、未配对的花括号、"
+                 "拼错的命令等），不改变实际内容与结构。只输出修正后的内容。",
+}
+
+_CUSTOM_SYS = ("你是专业文档编辑助手。严格按用户指令处理下面的 Markdown 文档/文本。"
+               "只输出处理后的 Markdown 结果，不要解释、不要整篇代码围栏。")
+
+
+def list_actions():
+    """Return the available action keys."""
+    return list(ACTIONS)
+
+
+def _strip_fence(s: str) -> str:
+    s = re.sub(r"^\s*```(?:markdown|md)?\s*\n?", "", s, flags=re.I)
+    s = re.sub(r"\n?```\s*$", "", s)
+    return s.strip()
+
+
+def assist(llm, text: str, action: Optional[str] = None,
+           instruction: Optional[str] = None) -> str:
+    """Run an AI assistant operation on ``text`` and return the result.
+
+    Provide ``action`` (one of :data:`ACTIONS`) and/or a free-form
+    ``instruction``. With both, the instruction refines the chosen action.
+    """
+    if llm is None:
+        raise RuntimeError("assist() needs an LLM — create DocumentStudio(llm=LLM(...)).")
+    text = text or ""
+    if action:
+        if action not in ACTIONS:
+            raise ValueError("unknown action %r; choose from: %s"
+                             % (action, ", ".join(ACTIONS)))
+        system = ACTIONS[action]
+        user = (("指令：%s\n\n" % instruction) if instruction else "") + \
+               (("文档：\n" + text) if text.strip() else "（文档为空）")
+    else:
+        if not instruction:
+            raise ValueError("provide either action= or instruction=")
+        system = _CUSTOM_SYS
+        user = "指令：%s\n\n文档：\n%s" % (instruction, text)
+    return _strip_fence(llm.chat(system, user))