tabella-docs 2.0.1__py3-none-any.whl

tabella/__init__.py

@@ -0,0 +1,53 @@
+"""tabella — Document lifecycle suite.
+
+Three modules:
+  - create  — Generate .docx/.xlsx/.pptx/.pdf/.odt/.ods/.odp from structured JSON
+  - convert — Format conversion via pandoc + LaTeX
+  - read    — Extract text and metadata from any document via LiteParse
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+__version__ = "1.0.0"
+
+# ── Configuration ─────────────────────────────────────────────
+
+def get_docs_venv_python() -> str:
+    """Path to the Python binary in the docs venv.
+
+    Resolution order:
+    1. DOCS_VENV_PYTHON env var (explicit override)
+    2. PLUGIN_DATA/venv/bin/python (v1 client-managed data directory)
+    3. ~/.venvs/docs/bin/python (fallback)
+    """
+    explicit = os.environ.get("DOCS_VENV_PYTHON")
+    if explicit and Path(explicit).exists():
+        return explicit
+
+    plugin_data = os.environ.get("PLUGIN_DATA")
+    if plugin_data:
+        p = Path(plugin_data) / "venv" / "bin" / "python"
+        if p.exists():
+            return str(p)
+
+    return str(Path.home() / ".venvs" / "docs" / "bin" / "python")
+
+
+def get_output_dir() -> Path:
+    """Default output directory for generated documents.
+
+    Override with DOCS_OUTPUT_DIR env var. Defaults to ~/Documents.
+    """
+    d = os.environ.get("DOCS_OUTPUT_DIR")
+    if d:
+        p = Path(d).expanduser()
+    else:
+        p = Path.home() / "Documents"
+    p.mkdir(parents=True, exist_ok=True)
+    return p
+
+
+__all__ = ["get_docs_venv_python", "get_output_dir"]

tabella/convert.py

@@ -0,0 +1,187 @@
+"""documents.convert — Document format conversion via pandoc + LaTeX.
+
+Supports: markdown → PDF/DOCX/HTML/ODT/EPUB and any pandoc-supported format pair.
+Output directory is configurable via DOCS_OUTPUT_DIR (defaults to ~/Documents).
+Merged from the doc_convert plugin.
+"""
+
+import json
+import logging
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Optional
+
+from .utils import _get_output_dir, _is_in_output_dir, _resolve_output_dir
+
+logger = logging.getLogger(__name__)
+
+
+def _check_deps() -> Optional[str]:
+    """Return error string if pandoc or LaTeX is missing, else None."""
+    if not shutil.which("pandoc"):
+        return "pandoc is not installed. Install it (e.g. `sudo apt install pandoc`)."
+    if not shutil.which("pdflatex") and not shutil.which("xelatex"):
+        return "No LaTeX engine found. Install texlive (e.g. `sudo apt install texlive-xetex`)."
+    return None
+
+
+def _pdf_engine() -> str:
+    """Return preferred LaTeX engine."""
+    if shutil.which("xelatex"):
+        return "xelatex"
+    return "pdflatex"
+
+
+# ── tool ──
+def doc_convert(
+    input_path: str,
+    to_format: str,
+    from_format: str = None,
+    output_path: str = None,
+    extra_args: list = None,
+    category: str = None,
+) -> dict:
+    """Convert a document from one format to another using pandoc.
+
+    Args:
+        input_path: Absolute path to the source document.
+        to_format: Target format (e.g. "pdf", "docx", "html", "odt", "epub").
+        from_format: Optional source format hint (e.g. "markdown", "html").
+                     When omitted, pandoc infers from file extension.
+        output_path: Optional absolute path for the output file.
+                     When omitted, writes to the user's documents directory.
+        extra_args:  Optional extra pandoc CLI flags (e.g. ["--toc", "-V", "geometry:margin=1in"]).
+        category:    Optional subfolder under ~/documents/ (e.g. "reports", "invoices").
+
+    Returns:
+        {"success": bool, "output_path": str, "from_format": str, "to_format": str,
+         "pdf_engine": str | None, "message": str}
+    """
+    dep_err = _check_deps()
+    if dep_err:
+        return {"success": False, "error": dep_err}
+
+    src = Path(input_path).expanduser().resolve()
+    if not src.exists():
+        return {"success": False, "error": f"Source file not found: {src}"}
+
+    # Determine formats
+    src_fmt = from_format or _infer_format(src.suffix.lstrip(".").lower())
+    tgt_fmt = to_format.lower()
+
+    # Determine output path
+    if output_path:
+        out_file = Path(output_path).expanduser().resolve()
+        out_file.parent.mkdir(parents=True, exist_ok=True)
+    else:
+        out_dir = _resolve_output_dir(category)
+        stem = src.stem
+        out_file = out_dir / f"{stem}.{tgt_fmt}"
+
+    # Warn if output is outside the configured output directory
+    if not _is_in_output_dir(out_file):
+        logger.warning(
+            "doc_convert: output file %s is outside the configured output directory. "
+            "Files saved here may not be synced.",
+            out_file,
+        )
+
+    # Build pandoc command
+    cmd = ["pandoc", str(src), "-o", str(out_file), "-f", src_fmt, "-t", tgt_fmt]
+    if tgt_fmt == "pdf":
+        engine = _pdf_engine()
+        cmd.extend(["--pdf-engine", engine])
+    if extra_args:
+        cmd.extend(extra_args)
+
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=300)
+        if result.returncode != 0:
+            return {
+                "success": False,
+                "error": f"pandoc failed (exit {result.returncode}): {result.stderr.strip()}",
+            }
+    except subprocess.TimeoutExpired:
+        return {"success": False, "error": "pandoc timed out after 5 minutes."}
+    except Exception as e:
+        return {"success": False, "error": f"pandoc error: {e}"}
+
+    if not out_file.exists():
+        return {"success": False, "error": f"Output file was not created: {out_file}"}
+
+    return {
+        "success": True,
+        "output_path": str(out_file),
+        "from_format": src_fmt,
+        "to_format": tgt_fmt,
+        "pdf_engine": _pdf_engine() if tgt_fmt == "pdf" else None,
+        "message": f"MEDIA:{out_file}\n\nConverted {src.name} → {tgt_fmt}: {out_file}",
+    }
+
+
+def _infer_format(ext: str) -> str:
+    """Map common extensions to pandoc format names."""
+    mapping = {
+        "md": "markdown",
+        "markdown": "markdown",
+        "txt": "plain",
+        "html": "html",
+        "htm": "html",
+        "docx": "docx",
+        "odt": "odt",
+        "pdf": "pdf",
+        "tex": "latex",
+        "rst": "rst",
+        "epub": "epub",
+    }
+    return mapping.get(ext, ext)
+
+
+def _handle_doc_convert(args: dict, **kwargs) -> str:
+    """Handler wrapper for doc_convert tool."""
+    result = doc_convert(**args)
+    if isinstance(result, dict):
+        return json.dumps(result)
+    return result
+
+
+# ── Hermes plugin registration ──
+def register(registry):
+    registry.register_tool(
+        name="doc_convert",
+        toolset="doc-convert",
+        schema={
+            "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 user's documents directory.",
+                },
+                "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"],
+        },
+        handler=_handle_doc_convert,
+        description="Convert documents between formats (PDF, DOCX, HTML, ODT, EPUB, etc.) using pandoc + LaTeX.",
+    )