tabella-docs 2.0.3__tar.gz → 2.0.5__tar.gz

{tabella_docs-2.0.3 → tabella_docs-2.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tabella-docs
-Version: 2.0.3
+Version: 2.0.5
 Summary: Portable document lifecycle suite — create (.docx/.xlsx/.pptx/.pdf/.odt/.ods/.odp), convert (pandoc), and read (anydoc + LiteParse OCR) documents. Agent Plugins v1 compatible.
 Author-email: D Yiapanis <d@yiapanis.co>
 License-Expression: MIT
@@ -142,9 +142,10 @@ sections, sheets, slides, tables, images, and page breaks.
 ### Convert
 
 Format conversion via pandoc + LaTeX (page size, margins, headers/footers
-configurable). **Pandoc 3.1 supports 44 input and 54 output formats** —
-`doc_convert` passes your `from`/`to` through, so all of them work. The
-everyday set:
+configurable). **Pandoc 3.1.11 reports 44 input and 65 output formats** —
+`doc_convert` passes your `from`/`to` through, so all of them work. (The counts
+move between pandoc minors; run `pandoc --list-input-formats` to check yours.)
+The everyday set:
 
 | Format | In | Out | Notes |
 |---|---|---|---|
@@ -152,13 +153,13 @@ everyday set:
 | HTML | ✅ | ✅ | html4/html5, chunkedhtml |
 | DOCX (Word) | ✅ | ✅ | |
 | ODT | ✅ | ✅ | + `opendocument` |
-| PDF | ✅ | ✅ | in: text-based PDFs (pandoc's pdf reader); out: needs `pdflatex`/`xelatex` (texlive) — engine auto-selected |
+| PDF | ✅ | ✅ | in: pandoc cannot read PDF, so the text layer is extracted first (OCR when the page is a scan) and the result is converted; out: needs `pdflatex`/`xelatex` (texlive) — engine auto-selected |
 | LaTeX (`.tex`) | ✅ | ✅ | incl. beamer slides out |
 | RST | ✅ | ✅ | |
 | EPUB | ✅ | ✅ | out: epub2/epub3 |
 | CSV / TSV | ✅ | ✅ | out via markdown/AST route |
 | RTF | ✅ | ✅ | |
-| Plain text (`.txt`) | ✅ | ✅ | |
+| Plain text (`.txt`) | ✅ | ✅ | read as markdown — pandoc has no `plain` *reader*, so headings and lists in a `.txt` survive |
 | Org-mode, MediaWiki, Jira wiki, Textile, DocBook, FB2, OPML, IPynb, JATS | ✅ | ✅ | writers for most |
 | Typst / man / ms / texinfo / AsciiDoc | ✅ | ✅ | typst in+out |
 | Presentations | — | ✅ | beamer, revealjs, slidy, s5, dzslides (from any reader, Markdown especially) |
@@ -242,7 +243,7 @@ brew install cairo pango gdk-pixbuf
 
 ### Windows
 
-tabella runs natively on Windows 10/11 (64-bit, Python 3.10+); all five MCP
+tabella runs natively on Windows 10/11 (64-bit, Python 3.11+); all five MCP
 tools are exercised on `windows-latest` in CI. Native dependencies, installed
 per feature:
 
@@ -291,7 +292,7 @@ required. The bootstrap runs once; subsequent startups use the existing venv.
 ### Create a PDF from HTML/CSS
 
 ```python
-from agent_docs.create import create_document
+from tabella.create import create_document
 
 result = create_document(
     format="pdf",
@@ -304,7 +305,7 @@ result = create_document(
 ### Read a DOCX file
 
 ```python
-from agent_docs.read import read
+from tabella.read import read
 
 text = read("/path/to/document.docx")
 # Returns GitHub-Flavored Markdown
@@ -313,7 +314,7 @@ text = read("/path/to/document.docx")
 ### Convert Markdown to PDF
 
 ```python
-from agent_docs.convert import doc_convert
+from tabella.convert import doc_convert
 
 result = doc_convert(
     input_path="/path/to/input.md",

{tabella_docs-2.0.3 → tabella_docs-2.0.5}/README.md

@@ -93,9 +93,10 @@ sections, sheets, slides, tables, images, and page breaks.
 ### Convert
 
 Format conversion via pandoc + LaTeX (page size, margins, headers/footers
-configurable). **Pandoc 3.1 supports 44 input and 54 output formats** —
-`doc_convert` passes your `from`/`to` through, so all of them work. The
-everyday set:
+configurable). **Pandoc 3.1.11 reports 44 input and 65 output formats** —
+`doc_convert` passes your `from`/`to` through, so all of them work. (The counts
+move between pandoc minors; run `pandoc --list-input-formats` to check yours.)
+The everyday set:
 
 | Format | In | Out | Notes |
 |---|---|---|---|
@@ -103,13 +104,13 @@ everyday set:
 | HTML | ✅ | ✅ | html4/html5, chunkedhtml |
 | DOCX (Word) | ✅ | ✅ | |
 | ODT | ✅ | ✅ | + `opendocument` |
-| PDF | ✅ | ✅ | in: text-based PDFs (pandoc's pdf reader); out: needs `pdflatex`/`xelatex` (texlive) — engine auto-selected |
+| PDF | ✅ | ✅ | in: pandoc cannot read PDF, so the text layer is extracted first (OCR when the page is a scan) and the result is converted; out: needs `pdflatex`/`xelatex` (texlive) — engine auto-selected |
 | LaTeX (`.tex`) | ✅ | ✅ | incl. beamer slides out |
 | RST | ✅ | ✅ | |
 | EPUB | ✅ | ✅ | out: epub2/epub3 |
 | CSV / TSV | ✅ | ✅ | out via markdown/AST route |
 | RTF | ✅ | ✅ | |
-| Plain text (`.txt`) | ✅ | ✅ | |
+| Plain text (`.txt`) | ✅ | ✅ | read as markdown — pandoc has no `plain` *reader*, so headings and lists in a `.txt` survive |
 | Org-mode, MediaWiki, Jira wiki, Textile, DocBook, FB2, OPML, IPynb, JATS | ✅ | ✅ | writers for most |
 | Typst / man / ms / texinfo / AsciiDoc | ✅ | ✅ | typst in+out |
 | Presentations | — | ✅ | beamer, revealjs, slidy, s5, dzslides (from any reader, Markdown especially) |
@@ -193,7 +194,7 @@ brew install cairo pango gdk-pixbuf
 
 ### Windows
 
-tabella runs natively on Windows 10/11 (64-bit, Python 3.10+); all five MCP
+tabella runs natively on Windows 10/11 (64-bit, Python 3.11+); all five MCP
 tools are exercised on `windows-latest` in CI. Native dependencies, installed
 per feature:
 
@@ -242,7 +243,7 @@ required. The bootstrap runs once; subsequent startups use the existing venv.
 ### Create a PDF from HTML/CSS
 
 ```python
-from agent_docs.create import create_document
+from tabella.create import create_document
 
 result = create_document(
     format="pdf",
@@ -255,7 +256,7 @@ result = create_document(
 ### Read a DOCX file
 
 ```python
-from agent_docs.read import read
+from tabella.read import read
 
 text = read("/path/to/document.docx")
 # Returns GitHub-Flavored Markdown
@@ -264,7 +265,7 @@ text = read("/path/to/document.docx")
 ### Convert Markdown to PDF
 
 ```python
-from agent_docs.convert import doc_convert
+from tabella.convert import doc_convert
 
 result = doc_convert(
     input_path="/path/to/input.md",

{tabella_docs-2.0.3 → tabella_docs-2.0.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tabella-docs"
-version = "2.0.3"
+version = "2.0.5"
 description = "Portable document lifecycle suite — create (.docx/.xlsx/.pptx/.pdf/.odt/.ods/.odp), convert (pandoc), and read (anydoc + LiteParse OCR) documents. Agent Plugins v1 compatible."
 readme = "README.md"
 license = "MIT"

{tabella_docs-2.0.3 → tabella_docs-2.0.5}/tabella/__init__.py

@@ -13,7 +13,36 @@ from pathlib import Path
 
 from .bootstrap import resolve_venv_python
 
-__version__ = "2.0.3"
+
+def _read_version() -> str:
+    """The package version, from installed metadata or pyproject.toml.
+
+    One source: pyproject.toml. Installed distributions read it back from
+    their metadata (so a wheel cannot disagree with itself); a checkout or a
+    plugin directory parses the file beside the package. plugin.json carries
+    its own literal because a manifest must, and tests/test_version_sync.py
+    fails when the two disagree.
+    """
+    # Source tree first: when this file sits next to a pyproject.toml we are
+    # being imported from a checkout, and that file is the version being
+    # edited — installed metadata would still say the previous release.
+    pyproject = Path(__file__).resolve().parent.parent / "pyproject.toml"
+    try:
+        for line in pyproject.read_text(encoding="utf-8").splitlines():
+            if line.startswith("version = "):
+                return line.split("=", 1)[1].strip().strip('"')
+    except OSError:
+        pass
+    # Installed from a wheel/sdist: the built metadata is authoritative.
+    try:
+        from importlib.metadata import version
+
+        return version("tabella-docs")
+    except Exception:
+        return "0+unknown"
+
+
+__version__ = _read_version()
 
 # ── Configuration ─────────────────────────────────────────────
 

{tabella_docs-2.0.3 → tabella_docs-2.0.5}/tabella/convert.py

@@ -10,6 +10,7 @@ import json
 import logging
 import shutil
 import subprocess
+import tempfile
 from pathlib import Path
 from typing import Optional
 
@@ -27,6 +28,44 @@ def _check_deps(needs_tex: bool = False) -> Optional[str]:
     return None
 
 
+def _extract_pdf(src: Path) -> str:
+    """Extract a PDF's text through the read lane (anydoc, then OCR).
+
+    pandoc has no PDF reader — it converts *to* PDF only. Routing through
+    read() means a text layer is used when present and a scanned page is
+    OCR'd when not, so `doc_convert(x.pdf, "docx")` behaves like the user
+    expects instead of failing inside pandoc.
+    """
+    from .read import read
+
+    return read(str(src))
+
+
+def _validate_extra_args(extra_args: Optional[list]) -> list:
+    """Strict allowlist for pandoc flags.
+
+    pandoc can execute code via --filter/--lua-filter/--pdf-engine, so only
+    formatting flags survive (catalog review #2026-10-16, finding 1). Runs
+    before the dependency check so a hostile flag is rejected as invalid,
+    not masked by "pandoc is not installed".
+    """
+    if not extra_args:
+        return []
+    allowed = {"--toc", "--number-sections"}
+    checked = []
+    for a in extra_args:
+        if a in allowed:
+            checked.append(a)
+        elif re.match(r"^-V\S*=", a):
+            checked.append(a)
+        else:
+            raise ValueError(
+                f"unsupported pandoc argument {a!r}: extra_args allows only "
+                "--toc, --number-sections and -V <key>=<value>"
+            )
+    return checked
+
+
 def _pdf_engine() -> str:
     """Return preferred LaTeX engine."""
     if shutil.which("xelatex"):
@@ -70,12 +109,34 @@ def doc_convert(
     tgt_fmt = to_format.lower()
     _check_format(src_fmt, "from_format")
     _check_format(tgt_fmt, "to_format")
+    extra = _validate_extra_args(extra_args)
 
     # pandoc is always required; a TeX engine only for pdf output
     dep_err = _check_deps(tgt_fmt == "pdf")
     if dep_err:
         return {"success": False, "error": dep_err}
 
+    # pandoc converts to PDF, never from it: extract the text first, then
+    # convert the extracted markdown. Scanned pages come back OCR'd, so this
+    # works where a bare `pandoc -f pdf` cannot exist at all.
+    pandoc_src, pandoc_fmt, tmp_md = str(src), src_fmt, None
+    if src_fmt == "pdf":
+        try:
+            text = _extract_pdf(src)
+        except Exception as e:
+            return {
+                "success": False,
+                "error": f"could not extract text from PDF: {type(e).__name__}: {e}",
+            }
+        if not text.strip():
+            return {"success": False, "error": f"PDF has no extractable text: {src}"}
+        with tempfile.NamedTemporaryFile(
+            "w", suffix=".md", delete=False, encoding="utf-8"
+        ) as fh:
+            fh.write(text)
+            tmp_md = fh.name
+        pandoc_src, pandoc_fmt = tmp_md, "markdown"
+
     # Determine output path
     if output_path:
         out_file = Path(output_path).expanduser().resolve()
@@ -94,25 +155,11 @@ def doc_convert(
         )
 
     # Build pandoc command
-    cmd = ["pandoc", str(src), "-o", str(out_file), "-f", src_fmt, "-t", tgt_fmt]
+    cmd = ["pandoc", pandoc_src, "-o", str(out_file), "-f", pandoc_fmt, "-t", tgt_fmt]
     if tgt_fmt == "pdf":
         engine = _pdf_engine()
         cmd.extend(["--pdf-engine", engine])
-    if extra_args:
-        # strict allowlist — pandoc can execute arbitrary code via --filter/
-        # --lua-filter/--pdf-engine, so only formatting flags are honored
-        # (catalog review #2026-10-16, finding 1).
-        allowed = {"--toc", "--number-sections"}
-        for a in extra_args:
-            if a in allowed:
-                cmd.append(a)
-            elif re.match(r"^-V\S*=", a):
-                cmd.append(a)
-            else:
-                raise ValueError(
-                    f"unsupported pandoc argument {a!r}: extra_args allows only "
-                    "--toc, --number-sections and -V <key>=<value>"
-                )
+    cmd.extend(extra)
 
     try:
         result = subprocess.run(cmd, capture_output=True, text=True, timeout=300)
@@ -125,6 +172,9 @@ def doc_convert(
         return {"success": False, "error": "pandoc timed out after 5 minutes."}
     except Exception as e:
         return {"success": False, "error": f"pandoc error: {e}"}
+    finally:
+        if tmp_md:
+            Path(tmp_md).unlink(missing_ok=True)
 
     if not out_file.exists():
         return {"success": False, "error": f"Output file was not created: {out_file}"}
@@ -134,6 +184,7 @@ def doc_convert(
         "output_path": str(out_file),
         "from_format": src_fmt,
         "to_format": tgt_fmt,
+        "extracted_text": src_fmt == "pdf",
         "pdf_engine": _pdf_engine() if tgt_fmt == "pdf" else None,
         "message": f"MEDIA:{out_file}\n\nConverted {src.name} → {tgt_fmt}: {out_file}",
     }
@@ -144,7 +195,9 @@ def _infer_format(ext: str) -> str:
     mapping = {
         "md": "markdown",
         "markdown": "markdown",
-        "txt": "plain",
+        # pandoc has no "plain" *reader*; markdown is the closest faithful
+        # reading of a text file (headings/lists if present, prose otherwise).
+        "txt": "markdown",
         "html": "html",
         "htm": "html",
         "docx": "docx",

{tabella_docs-2.0.3 → tabella_docs-2.0.5}/tabella/read.py

@@ -23,19 +23,6 @@ TEXT_SUFFIXES = {
     ".rst", ".fountain", ".log", ".py", ".js", ".ts", ".css",
 }
 
-# Formats anydoc handles (office + text PDF).
-# Source: anydoc README — supported formats table.
-ANYDOC_SUFFIXES = {
-    ".doc", ".docx", ".docm",
-    ".ppt", ".pps", ".pot", ".pptx", ".pptm", ".ppsx", ".ppsm",
-    ".xls", ".xlsx", ".xlsm", ".xlsb",
-    ".odt", ".ods", ".odp",
-    ".rtf",
-    ".epub",
-    ".pdf",
-    ".csv",
-}
-
 # Image formats that need OCR (LiteParse + Tesseract).
 IMAGE_SUFFIXES = {
     ".jpg", ".jpeg", ".png", ".tif", ".tiff", ".webp", ".bmp", ".gif",
@@ -104,7 +91,8 @@ def read(path: str, max_chars: Optional[int] = None, extract_images: bool = True
       1. Plain text → direct file read (fast path)
       2. Office formats + text PDFs → anydoc (Markdown output)
       3. Images → LiteParse (OCR)
-      4. PDFs that anydoc returns empty → LiteParse (OCR fallback for scanned PDFs)
+      4. PDFs with no text layer — anydoc returns empty or raises NeedsOcrError →
+         LiteParse (OCR fallback for scanned PDFs)
     """
     suffix = Path(path).suffix.lower()
 
@@ -120,31 +108,36 @@ def read(path: str, max_chars: Optional[int] = None, extract_images: bool = True
             text = text[:max_chars]
         return text
 
-    # 3. Office formats + PDFs → anydoc first
-    if suffix in ANYDOC_SUFFIXES or suffix not in TEXT_SUFFIXES:
-        text = ""
-        anydoc_error = None
+    # 3. Everything left — office formats, PDFs, unknown extensions → anydoc.
+    #    (Text returned above, so the old `or suffix not in TEXT_SUFFIXES`
+    #    tail was dead.)
+    text = ""
+    anydoc_error = None
+    try:
+        text = _run_anydoc(path)
+    except Exception as e:
+        # A fallback boundary: any primary-engine failure means "try the other
+        # engine". anydoc raises NeedsOcrError for a PDF with no text layer, and
+        # its hierarchy (NeedsOcrError -> ConvertError -> Exception) is theirs,
+        # not ours — enumerating it is what made the OCR lane unreachable for
+        # scanned PDFs.
+        anydoc_error = f"{type(e).__name__}: {e}"
+
+    # 4. No text layer (scanned PDF) or anydoc failed → LiteParse OCR
+    if not text.strip():
         try:
-            text = _run_anydoc(path)
-        except (RuntimeError, ImportError) as e:
-            anydoc_error = str(e)
-
-        # 4. If anydoc returned empty text (scanned PDF) or failed, try LiteParse OCR
-        if not text.strip():
-            try:
-                data = _run_liteparse(path, extract_images=extract_images)
-                text = data.get("text") or ""
-            except (RuntimeError, ImportError) as liteparse_err:
-                if anydoc_error:
-                    raise RuntimeError(f"anydoc failed: {anydoc_error}; liteparse fallback also failed: {liteparse_err}")
-                raise RuntimeError(f"both anydoc and liteparse returned no text. liteparse: {liteparse_err}")
-
-        if max_chars:
-            text = text[:max_chars]
-        return text
-
-    # Fallback: unknown format, try plain text read
-    return _read_text(path, max_chars)
+            data = _run_liteparse(path, extract_images=extract_images)
+            text = data.get("text") or ""
+        except Exception as liteparse_err:
+            if anydoc_error:
+                raise RuntimeError(
+                    f"anydoc failed: {anydoc_error}; liteparse fallback also failed: {liteparse_err}"
+                )
+            raise RuntimeError(f"both anydoc and liteparse returned no text. liteparse: {liteparse_err}")
+
+    if max_chars:
+        text = text[:max_chars]
+    return text
 
 
 def read_meta(path: str) -> Dict[str, Any]:

tabella_docs-2.0.5/tabella/toolspec.py

@@ -0,0 +1,238 @@
+"""The MCP tool surface: one table, one dispatcher, both transports.
+
+The stdio server and the self-hosted HTTP server serve the same five tools and
+used to carry byte-identical copies of this file's contents — 220 lines twice,
+one string apart. Anything that changes a schema or a result shape changes it
+here, once, and both transports move together.
+"""
+
+import json
+
+# One protocol version for both transports. The client's requested version is
+# echoed back when it is one we speak, which is what the spec asks for — the
+# stdio server used to advertise 2024-11-05 while HTTP advertised 2025-06-18
+# for the same tool surface.
+PROTOCOL_VERSION = "2025-06-18"
+SUPPORTED_PROTOCOLS = ("2025-06-18", "2025-03-26", "2024-11-05")
+
+TOOLS = [
+    {
+        "name": "doc_read",
+        "description": (
+            "Read and extract text from documents. Uses anydoc for office formats "
+            "(DOCX, XLSX, PPTX, ODT, RTF, EPUB, PDF → Markdown) and LiteParse for OCR "
+            "(scanned PDFs, images). Plain text files read directly."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "path": {
+                    "type": "string",
+                    "description": "Absolute path to the document.",
+                },
+                "max_chars": {
+                    "type": "integer",
+                    "description": "Maximum characters to return.",
+                    "default": 1000000,
+                },
+                "extract_images": {
+                    "type": "boolean",
+                    "description": "Extract text from images via OCR (LiteParse + Tesseract).",
+                    "default": True,
+                },
+            },
+            "required": ["path"],
+        },
+    },
+    {
+        "name": "doc_read_meta",
+        "description": "Read document metadata (PDF info, image EXIF, etc.) via LiteParse.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "path": {
+                    "type": "string",
+                    "description": "Absolute path to the document.",
+                },
+            },
+            "required": ["path"],
+        },
+    },
+    {
+        "name": "doc_convert",
+        "description": (
+            "Convert documents between formats (PDF, DOCX, HTML, ODT, EPUB, etc.) "
+            "using pandoc + LaTeX. Requires system pandoc and texlive-xetex for PDF output."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "input_path": {
+                    "type": "string",
+                    "description": "Absolute path to the source document.",
+                },
+                "to_format": {
+                    "type": "string",
+                    "description": "Target format: pdf, docx, html, odt, epub, etc.",
+                },
+                "from_format": {
+                    "type": "string",
+                    "description": "Optional source format hint (e.g. markdown, html). Pandoc infers from extension if omitted.",
+                },
+                "output_path": {
+                    "type": "string",
+                    "description": "Optional absolute output path. Defaults to the documents directory (DOCS_OUTPUT_DIR or ~/Documents).",
+                },
+                "extra_args": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Optional extra pandoc CLI flags.",
+                },
+                "category": {
+                    "type": "string",
+                    "description": "Optional subfolder under documents/ (e.g. 'reports').",
+                },
+            },
+            "required": ["input_path", "to_format"],
+        },
+    },
+    {
+        "name": "doc_create_document",
+        "description": (
+            "Create .docx, .xlsx, .pptx, .pdf, .odt, .ods, or .odp documents. "
+            "For PDFs: pass structured JSON for document-style output, or pass "
+            '{\"html\": \"<html>...</html>\"} with full CSS (Grid, Flexbox, gradients, '
+            "themes) for visual/print-ready PDFs via weasyprint. "
+            "Supports page_size, header, footer, page_numbers options."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "format": {
+                    "type": "string",
+                    "enum": ["docx", "xlsx", "pptx", "pdf", "odt", "ods", "odp"],
+                    "description": "Output document format.",
+                },
+                "content": {
+                    "anyOf": [
+                        {"type": "string", "description": "Plain text or HTML content (auto-detected and normalized)."},
+                        {"type": "object", "description": "Structured content dict. Format-specific schema."},
+                    ],
+                    "description": "Document content. Accepts plain text, HTML, or structured dict.",
+                },
+                "output_path": {
+                    "type": "string",
+                    "description": "Absolute path for the output file. Defaults to the documents directory.",
+                },
+                "template": {
+                    "type": "string",
+                    "description": "Optional template path — honored by docx (.docx/.dotx) and pptx (.pptx/.potx) creation: styles, theme, headers/footers and slide layouts load from the file. Ignored by every other format.",
+                },
+                "options": {
+                    "type": "object",
+                    "description": "Optional format-specific options (title, page_size, auto_size, etc.)",
+                },
+            },
+            "required": ["format", "content"],
+        },
+    },
+    {
+        "name": "doc_edit_pdf",
+        "description": "Edit a PDF page using search-and-replace via PyMuPDF. Provide a natural language instruction like 'change <search> to <replace>'.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "path": {
+                    "type": "string",
+                    "description": "Absolute path to the PDF file.",
+                },
+                "page": {
+                    "type": "integer",
+                    "description": "Page number to edit (1-indexed).",
+                    "default": 1,
+                },
+                "instruction": {
+                    "type": "string",
+                    "description": "Natural language instruction for the edit (e.g. 'change \"foo\" to \"bar\"').",
+                },
+                "output_path": {
+                    "type": "string",
+                    "description": "Optional output path. Defaults to <original>_edited.pdf",
+                },
+            },
+            "required": ["path", "instruction"],
+        },
+    },
+]
+
+
+# ── Dispatch ────────────────────────────────────────────────
+
+def handle_tool(name: str, args: dict) -> str:
+    """Dispatch a tool call to the appropriate handler and return JSON result."""
+    try:
+        if name == "doc_read":
+            from tabella.read import read
+            text = read(
+                args["path"],
+                max_chars=args.get("max_chars", 1_000_000),
+                extract_images=args.get("extract_images", True),
+            )
+            return json.dumps({
+                "success": True,
+                "path": args["path"],
+                "text": text,
+                "length": len(text),
+                "message": f"Read {len(text)} chars from {args['path']}",
+            })
+
+        elif name == "doc_read_meta":
+            from tabella.read import read_meta
+            meta = read_meta(args["path"])
+            return json.dumps({"success": True, "path": args["path"], "metadata": meta})
+
+        elif name == "doc_convert":
+            from tabella.convert import doc_convert
+            result = doc_convert(
+                input_path=args["input_path"],
+                to_format=args["to_format"],
+                from_format=args.get("from_format"),
+                output_path=args.get("output_path"),
+                extra_args=args.get("extra_args"),
+                category=args.get("category"),
+            )
+            return json.dumps(result)
+
+        elif name == "doc_create_document":
+            from tabella.create import create_document
+            output_path = args.get("output_path")
+            if not output_path:
+                from tabella import get_output_dir
+                import time
+                ts = int(time.time())
+                fmt = args["format"]
+                output_path = str(get_output_dir() / f"doc_{ts}.{fmt}")
+            result = create_document(
+                format=args["format"],
+                content=args["content"],
+                output_path=output_path,
+                template=args.get("template"),
+                options=args.get("options"),
+            )
+            return json.dumps(result)
+
+        elif name == "doc_edit_pdf":
+            from tabella.create import _edit_pdf_text
+            result = _edit_pdf_text(
+                path=args["path"],
+                page=args.get("page", 1),
+                instruction=args["instruction"],
+                output_path=args.get("output_path"),
+            )
+            return json.dumps(result)
+
+        else:
+            return json.dumps({"success": False, "error": f"Unknown tool: {name}"})
+
+    except Exception as e:
+        return json.dumps({"success": False, "error": f"{type(e).__name__}: {e}"})

{tabella_docs-2.0.3 → tabella_docs-2.0.5}/tabella_docs.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tabella-docs
-Version: 2.0.3
+Version: 2.0.5
 Summary: Portable document lifecycle suite — create (.docx/.xlsx/.pptx/.pdf/.odt/.ods/.odp), convert (pandoc), and read (anydoc + LiteParse OCR) documents. Agent Plugins v1 compatible.
 Author-email: D Yiapanis <d@yiapanis.co>
 License-Expression: MIT
@@ -142,9 +142,10 @@ sections, sheets, slides, tables, images, and page breaks.
 ### Convert
 
 Format conversion via pandoc + LaTeX (page size, margins, headers/footers
-configurable). **Pandoc 3.1 supports 44 input and 54 output formats** —
-`doc_convert` passes your `from`/`to` through, so all of them work. The
-everyday set:
+configurable). **Pandoc 3.1.11 reports 44 input and 65 output formats** —
+`doc_convert` passes your `from`/`to` through, so all of them work. (The counts
+move between pandoc minors; run `pandoc --list-input-formats` to check yours.)
+The everyday set:
 
 | Format | In | Out | Notes |
 |---|---|---|---|
@@ -152,13 +153,13 @@ everyday set:
 | HTML | ✅ | ✅ | html4/html5, chunkedhtml |
 | DOCX (Word) | ✅ | ✅ | |
 | ODT | ✅ | ✅ | + `opendocument` |
-| PDF | ✅ | ✅ | in: text-based PDFs (pandoc's pdf reader); out: needs `pdflatex`/`xelatex` (texlive) — engine auto-selected |
+| PDF | ✅ | ✅ | in: pandoc cannot read PDF, so the text layer is extracted first (OCR when the page is a scan) and the result is converted; out: needs `pdflatex`/`xelatex` (texlive) — engine auto-selected |
 | LaTeX (`.tex`) | ✅ | ✅ | incl. beamer slides out |
 | RST | ✅ | ✅ | |
 | EPUB | ✅ | ✅ | out: epub2/epub3 |
 | CSV / TSV | ✅ | ✅ | out via markdown/AST route |
 | RTF | ✅ | ✅ | |
-| Plain text (`.txt`) | ✅ | ✅ | |
+| Plain text (`.txt`) | ✅ | ✅ | read as markdown — pandoc has no `plain` *reader*, so headings and lists in a `.txt` survive |
 | Org-mode, MediaWiki, Jira wiki, Textile, DocBook, FB2, OPML, IPynb, JATS | ✅ | ✅ | writers for most |
 | Typst / man / ms / texinfo / AsciiDoc | ✅ | ✅ | typst in+out |
 | Presentations | — | ✅ | beamer, revealjs, slidy, s5, dzslides (from any reader, Markdown especially) |
@@ -242,7 +243,7 @@ brew install cairo pango gdk-pixbuf
 
 ### Windows
 
-tabella runs natively on Windows 10/11 (64-bit, Python 3.10+); all five MCP
+tabella runs natively on Windows 10/11 (64-bit, Python 3.11+); all five MCP
 tools are exercised on `windows-latest` in CI. Native dependencies, installed
 per feature:
 
@@ -291,7 +292,7 @@ required. The bootstrap runs once; subsequent startups use the existing venv.
 ### Create a PDF from HTML/CSS
 
 ```python
-from agent_docs.create import create_document
+from tabella.create import create_document
 
 result = create_document(
     format="pdf",
@@ -304,7 +305,7 @@ result = create_document(
 ### Read a DOCX file
 
 ```python
-from agent_docs.read import read
+from tabella.read import read
 
 text = read("/path/to/document.docx")
 # Returns GitHub-Flavored Markdown
@@ -313,7 +314,7 @@ text = read("/path/to/document.docx")
 ### Convert Markdown to PDF
 
 ```python
-from agent_docs.convert import doc_convert
+from tabella.convert import doc_convert
 
 result = doc_convert(
     input_path="/path/to/input.md",

{tabella_docs-2.0.3 → tabella_docs-2.0.5}/tabella_docs.egg-info/SOURCES.txt

@@ -6,6 +6,7 @@ tabella/bootstrap.py
 tabella/convert.py
 tabella/create.py
 tabella/read.py
+tabella/toolspec.py
 tabella/utils.py
 tabella_docs.egg-info/PKG-INFO
 tabella_docs.egg-info/SOURCES.txt
@@ -13,7 +14,11 @@ tabella_docs.egg-info/dependency_links.txt
 tabella_docs.egg-info/requires.txt
 tabella_docs.egg-info/top_level.txt
 tests/test_bootstrap_paths.py
+tests/test_convert_pdf_input.py
 tests/test_ensure_venv_win.py
+tests/test_mcp_handshake.py
 tests/test_odt_table.py
+tests/test_read_ocr_fallback.py
 tests/test_security_gates.py
-tests/test_text_section_alias.py
+tests/test_text_section_alias.py
+tests/test_version_sync.py

tabella_docs-2.0.5/tests/test_convert_pdf_input.py

@@ -0,0 +1,80 @@
+"""doc_convert must read PDFs, not hand them to a pandoc that cannot.
+
+pandoc converts *to* PDF only. A PDF input used to fail with "Unknown input
+format pdf"; the route now extracts text through the read lane (text layer, or
+OCR for a scan) and converts the extracted markdown, so .pdf joins the input
+column honestly.
+"""
+
+import shutil
+
+import pytest
+
+pytest.importorskip("PIL")
+pytest.importorskip("docx")
+
+from pathlib import Path  # noqa: E402
+
+from tabella.convert import doc_convert  # noqa: E402
+
+needs_pandoc = pytest.mark.skipif(
+    shutil.which("pandoc") is None, reason="pandoc not installed"
+)
+
+
+def _assert_docx_text(path: Path, needle: str) -> None:
+    from docx import Document
+
+    text = "\n".join(p.text for p in Document(str(path)).paragraphs)
+    assert needle.lower() in text.lower(), f"{needle!r} missing from {path}: {text[:200]!r}"
+
+
+@needs_pandoc
+def test_image_only_pdf_converts_to_docx(tmp_path):
+    from PIL import Image, ImageDraw, ImageFont
+
+    img = Image.new("RGB", (1200, 400), "white")
+    draw = ImageDraw.Draw(img)
+    try:
+        font = ImageFont.truetype(
+            "/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf", 64
+        )
+    except OSError:
+        font = ImageFont.load_default(size=64)
+    draw.text((60, 120), "SCANNED HELLO 42", fill="black", font=font)
+    pdf = tmp_path / "scan.pdf"
+    img.save(pdf, "PDF", resolution=150.0)
+
+    out = doc_convert(str(pdf), to_format="docx", output_path=str(tmp_path / "scan.docx"))
+
+    assert out["success"], out
+    assert out["from_format"] == "pdf"
+    assert out["extracted_text"] is True
+    _assert_docx_text(Path(out["output_path"]), "SCANNED HELLO 42")
+
+
+@needs_pandoc
+def test_plain_text_is_readable_as_markdown(tmp_path):
+    # pandoc has no "plain" *reader*; .txt must not be handed to it as one.
+    src = tmp_path / "notes.txt"
+    src.write_text("# Heading\n\nSome prose.", encoding="utf-8")
+
+    out = doc_convert(str(src), to_format="docx", output_path=str(tmp_path / "notes.docx"))
+
+    assert out["success"], out
+    assert out["from_format"] == "markdown"
+    _assert_docx_text(Path(out["output_path"]), "Some prose")
+
+
+def test_hostile_extra_arg_is_rejected_before_the_dependency_check(monkeypatch, tmp_path):
+    """A bad flag must raise as invalid, not come back as "pandoc is missing".
+
+    The allowlist used to run after _check_deps(), so on a pandoc-less host an
+    untrusted --lua-filter looked like a harmless dependency error.
+    """
+    src = tmp_path / "x.md"
+    src.write_text("# hi", encoding="utf-8")
+    monkeypatch.setattr(shutil, "which", lambda name: None)
+
+    with pytest.raises(ValueError, match="unsupported pandoc argument"):
+        doc_convert(str(src), to_format="docx", extra_args=["--lua-filter=evil.lua"])

tabella_docs-2.0.5/tests/test_mcp_handshake.py

@@ -0,0 +1,42 @@
+"""A stdio client must see the real version and its own protocol back.
+
+Guards the two drift bugs that shipped: the handshake hardcoded 2024-11-05 in
+one transport while the other said 2025-06-18, and both hardcoded a version
+number that had to be bumped by hand in five places.
+"""
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+import tabella
+
+ROOT = Path(__file__).resolve().parent.parent
+SERVER = ROOT / "mcp_server.py"
+
+
+@pytest.mark.skipif(not SERVER.exists(), reason="server not present")
+def test_initialize_reports_version_and_echoes_protocol():
+    env = dict(os.environ, TABELL_REEXEC="1")  # already running in a venv
+    req = {
+        "jsonrpc": "2.0",
+        "id": 1,
+        "method": "initialize",
+        "params": {"protocolVersion": "2025-03-26", "capabilities": {}},
+    }
+    proc = subprocess.run(
+        [sys.executable, str(SERVER)],
+        input=json.dumps(req) + "\n",
+        capture_output=True,
+        text=True,
+        timeout=60,
+        env=env,
+    )
+    line = proc.stdout.strip().splitlines()[0]
+    info = json.loads(line)["result"]
+    assert info["serverInfo"]["version"] == tabella.__version__
+    assert info["protocolVersion"] == "2025-03-26", "the client's version must be echoed"

tabella_docs-2.0.5/tests/test_read_ocr_fallback.py

@@ -0,0 +1,49 @@
+"""doc_read on an image-only PDF must reach the OCR lane, not raise.
+
+anydoc signals a missing text layer by *raising* NeedsOcrError (MRO:
+NeedsOcrError -> ConvertError -> Exception, so not a RuntimeError), where the
+fallback was gated on empty text and caught only RuntimeError/ImportError.
+Net effect: the fallback was unreachable for exactly the input it exists for.
+
+Runs the real pipeline — PIL makes the page, Tesseract reads it — because a
+mocked empty return is what let this ship.
+"""
+
+from pathlib import Path
+
+import pytest
+
+pytest.importorskip("PIL")
+pytest.importorskip("anydoc")
+pytest.importorskip("liteparse")
+
+from PIL import Image, ImageDraw, ImageFont  # noqa: E402
+
+
+def _page(tmp_path: Path):
+    img = Image.new("RGB", (1200, 400), "white")
+    draw = ImageDraw.Draw(img)
+    try:
+        font = ImageFont.truetype(
+            "/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf", 64
+        )
+    except OSError:
+        font = ImageFont.load_default(size=64)
+    draw.text((60, 120), "SCANNED HELLO 42", fill="black", font=font)
+    return img
+
+
+def test_image_only_pdf_falls_back_to_ocr(tmp_path):
+    png, pdf = tmp_path / "scan.png", tmp_path / "scan.pdf"
+    img = _page(tmp_path)
+    img.save(png)
+    img.save(pdf, "PDF", resolution=150.0)
+
+    from tabella.read import read
+
+    from_png = " ".join(read(str(png)).split())
+    from_pdf = " ".join(read(str(pdf)).split())
+
+    assert "HELLO" in from_png.upper(), f"OCR lane itself is broken: {from_png!r}"
+    assert from_pdf, "image-only PDF returned no text"
+    assert from_pdf == from_png, f"PDF and PNG disagree: {from_pdf!r} vs {from_png!r}"

tabella_docs-2.0.5/tests/test_version_sync.py

@@ -0,0 +1,45 @@
+"""One version, or a released package that lies about itself.
+
+pyproject.toml is the source; tabella.__version__ reads it back (via installed
+metadata when available) and both transports report that value. plugin.json
+must carry the same literal because a manifest cannot compute it.
+"""
+
+import json
+import re
+from pathlib import Path
+
+import tabella
+
+ROOT = Path(__file__).resolve().parent.parent
+
+
+def _pyproject_version() -> str:
+    text = (ROOT / "pyproject.toml").read_text(encoding="utf-8")
+    match = re.search(r'^version = "([^"]+)"', text, re.MULTILINE)
+    assert match, "pyproject.toml has no version line"
+    return match.group(1)
+
+
+def test_version_is_read_from_pyproject():
+    assert tabella.__version__ == _pyproject_version()
+
+
+def test_plugin_manifest_agrees_with_the_package():
+    manifest = json.loads((ROOT / "plugin.json").read_text(encoding="utf-8"))
+    assert manifest["version"] == tabella.__version__
+
+
+def test_documented_imports_resolve():
+    """README/SPECS show `from tabella.x import y` — those must exist."""
+    from tabella.convert import doc_convert  # noqa: F401
+    from tabella.create import create_document  # noqa: F401
+    from tabella.read import read, read_meta  # noqa: F401
+
+
+def test_both_transports_import_the_same_surface():
+    """The stdio and HTTP servers used to carry two copies of the tool table."""
+    for path in (ROOT / "mcp_server.py", ROOT / "scripts" / "mcp_http_server.py"):
+        source = path.read_text(encoding="utf-8")
+        assert "from tabella.toolspec import" in source, f"{path} does not use the shared surface"
+        assert "TOOLS = [" not in source, f"{path} still defines its own tool table"