docuhand 0.1.0.dev1__py3-none-any.whl

docuhand/safety/__init__.py

@@ -0,0 +1,10 @@
+"""Safety layer: allowlist enforcement + JSONL audit log.
+
+Per 开工包 decision #4 this is structural (registered around every tool),
+not a "remember to call it" convention.
+"""
+
+from .allowlist import check_allowed, get_allowlist
+from .audit import record
+
+__all__ = ["check_allowed", "get_allowlist", "record"]

docuhand/safety/allowlist.py

@@ -0,0 +1,41 @@
+"""Path allowlist — env-driven, enforced before any tool runs.
+
+``DOCUHAND_ALLOWLIST``: os.pathsep-separated absolute directories.
+Empty/absent (the v0.1 default) = allow everything: the user launches the
+server themselves, which per spec IS the explicit consent ("默认：用户显式
+传入的目录"). Setting the env var locks the server to those subtrees.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from ..errors import PathNotAllowedError
+
+
+def get_allowlist() -> list[Path]:
+    raw = os.environ.get("DOCUHAND_ALLOWLIST", "")
+    entries: list[Path] = []
+    for part in raw.split(os.pathsep):
+        if part.strip():
+            entries.append(Path(part.strip()).expanduser().resolve())
+    return entries
+
+
+def check_allowed(path: str) -> None:
+    entries = get_allowlist()
+    if not entries:
+        return
+    p = Path(path).expanduser()
+    try:
+        resolved = p.resolve()
+    except OSError:
+        resolved = p.absolute()
+    for root in entries:
+        try:
+            resolved.relative_to(root)
+            return
+        except ValueError:
+            continue
+    raise PathNotAllowedError(str(p), [str(e) for e in entries])

docuhand/safety/audit.py

@@ -0,0 +1,52 @@
+"""JSONL audit log — every operation lands here, user can disable it.
+
+Set ``DOCUHAND_AUDIT=off`` to disable, ``DOCUHAND_AUDIT_PATH`` to relocate
+(default: %LOCALAPPDATA%/docuhand/audit.jsonl). Audit failures are swallowed:
+logging must never break a document operation.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from pathlib import Path
+
+_ENABLED = os.environ.get("DOCUHAND_AUDIT", "on").strip().lower() not in ("off", "0", "false", "no")
+
+
+def _log_path() -> Path:
+    env = os.environ.get("DOCUHAND_AUDIT_PATH")
+    if env:
+        return Path(env)
+    base = os.environ.get("LOCALAPPDATA") or str(Path.home())
+    return Path(base) / "docuhand" / "audit.jsonl"
+
+
+def record(
+    tool: str,
+    path: str,
+    *,
+    ok: bool,
+    duration_ms: float,
+    engine: str | None = None,
+    error_code: str | None = None,
+) -> None:
+    if not _ENABLED:
+        return
+    entry = {
+        "ts": time.strftime("%Y-%m-%dT%H:%M:%S"),
+        "tool": tool,
+        "path": path,
+        "ok": ok,
+        "duration_ms": round(duration_ms),
+        "engine": engine,
+        "error_code": error_code,
+    }
+    try:
+        target = _log_path()
+        target.parent.mkdir(parents=True, exist_ok=True)
+        with target.open("a", encoding="utf-8") as f:
+            f.write(json.dumps(entry, ensure_ascii=False) + "\n")
+    except Exception:
+        pass

docuhand/safety/policy.py

@@ -0,0 +1,29 @@
+"""Global write policy — the ``--read-only`` mode as data, not discipline.
+
+Set ``DOCUHAND_READONLY=1`` to lock the server into read-only operation.
+Blocked: document-mutating tools (edit_open_document, fill_template,
+merge_documents, convert_documents).  Allowed: pure readers (inspect_document,
+extract_content) and new-artifact exporters (export_pdf never touches the
+source document).
+"""
+
+from __future__ import annotations
+
+from ..errors import ReadOnlyError
+
+_TRUTHY = {"1", "true", "yes", "on"}
+
+
+def is_readonly() -> bool:
+    raw = ""
+    try:
+        raw = __import__("os").environ.get("DOCUHAND_READONLY", "")
+    except Exception:
+        return False
+    return raw.strip().lower() in _TRUTHY
+
+
+def ensure_writable(tool: str) -> None:
+    """Raise ReadOnlyError when the server runs in read-only mode."""
+    if is_readonly():
+        raise ReadOnlyError(tool)

docuhand/server.py

@@ -0,0 +1,221 @@
+"""MCP stdio entry point — deliberately a thin layer.
+
+Protocol concerns live here; all real logic lives in engine/ and tools/.
+If MCP is ever replaced (see 开工包 附录 decision #6), only this file and
+the tool registration move — the engine carries zero MCP dependencies.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from mcp.server.fastmcp import FastMCP
+
+from ._compat import fix_stdio
+from .tools.convert import run as convert_documents_run
+from .tools.edit_open import run as edit_open_document_run
+from .tools.export_pdf import run as export_pdf_run
+from .tools.extract import run as extract_content_run
+from .tools.fill_template import run as fill_template_run
+from .tools.inspect import run as inspect_document_run
+from .tools.merge import run as merge_documents_run
+
+fix_stdio()
+
+mcp = FastMCP(
+    "docuhand",
+    instructions=(
+        "DocuHand drives REAL Microsoft Word / WPS Office via COM on Windows. "
+        "Use inspect_document as the pre-flight health check for any Word "
+        "document: it reports the true format (legacy .doc vs .docx vs a "
+        "renamed file), lock state (open in Word right now?), page/word/paragraph "
+        "counts, corruption suspicion, password protection, editor restriction "
+        "mode, bookmarks and field codes. Use convert_documents to batch-convert "
+        "a whole directory of legacy .doc files to modern .docx (or the reverse) "
+        "in one call — Microsoft Word is used when present and WPS Office is the "
+        "automatic fallback. Use fill_template to produce a filled copy of a "
+        "template via bookmarks, {{placeholders}} or content controls with CJK "
+        "font protection; export_pdf for print-fidelity PDFs (optionally a page "
+        "range); extract_content to pull text, tables (as JSON grids) or the "
+        "heading outline out of legacy .doc files; merge_documents for "
+        "mail-merge-style batch generation from data rows; and "
+        "edit_open_document to edit a document the user has open RIGHT NOW "
+        "(changes stay visible in their window; it never saves unless asked). "
+        "Results are structured JSON; every error carries an llm_hint "
+        "describing the next corrective step."
+    ),
+)
+
+
+@mcp.tool()
+def convert_documents(
+    directory: str,
+    to_format: str = "docx",
+    recursive: bool = False,
+    overwrite: str = "skip",
+    output_dir: str | None = None,
+) -> dict:
+    """Batch-convert every .doc/.docx file in a directory in ONE call.
+
+    Drives the real Word/WPS engine per file (Word first, WPS fallback when
+    Word is absent or crashes). Files already in the target format are
+    reported as already_target and left untouched; other extensions are
+    ignored. Sources are NEVER deleted. One unreadable file fails alone
+    with a structured error instead of killing the batch; only a total
+    engine-launch failure aborts the run.
+
+    Args:
+        directory: Absolute Windows path to the folder holding the documents.
+        to_format: Target format — "docx" (recommended) or "doc".
+        recursive: Also descend into subdirectories.
+        overwrite: "skip" (default) never touches an existing target file;
+            "overwrite" replaces existing targets deliberately.
+        output_dir: Optional target folder. Omit to convert in place (the
+            converted file lands next to its source).
+    """
+    return convert_documents_run(
+        directory,
+        to_format=to_format,
+        recursive=recursive,
+        overwrite=overwrite,
+        output_dir=output_dir,
+    )
+
+
+@mcp.tool()
+def inspect_document(path: str) -> dict:
+    """Health-check a Word document before touching it.
+
+    Opens the document READ-ONLY in a hidden Word/WPS instance and reports:
+    true format vs extension (catches renamed or pseudo-.doc files), page /
+    word / paragraph counts, lock state (file currently open elsewhere),
+    corruption suspicion, password protection, protection mode, bookmarks
+    and field codes. Works on legacy .doc binaries that XML libraries cannot
+    read, and on files currently open in Word/WPS.
+
+    Args:
+        path: Absolute Windows path to the document (e.g. D:\\\\Reports\\\\a.doc).
+    """
+    return inspect_document_run(path)
+
+
+@mcp.tool()
+def fill_template(
+    template_path: str,
+    data: dict,
+    output_path: str | None = None,
+    mode: str = "auto",
+    bookmarks: list[str] | None = None,
+) -> dict:
+    """Fill a Word template with data and save a NEW document.
+
+    Produces template_filled.<ext> next to the template by default (the
+    template itself is never modified). Fill mechanisms, tried in 'auto':
+    content controls (Tag/Title = key), bookmarks (name = key), and literal
+    {{key}} placeholder tokens. Layout and East-Asian fonts are protected
+    through the fill (NameFarEast re-assertion before AND after save).
+
+    Args:
+        template_path: Absolute Windows path to the .doc/.docx template.
+        data: JSON object mapping keys to replacement text, e.g.
+            {"name": "张三", "amount": "1234.56"} fills {{name}}/{{amount}},
+            a bookmark named 'name', or a content control tagged 'name'.
+        output_path: Where to write the filled document (.doc/.docx).
+        mode: "auto" (default), "placeholders", "bookmarks" or "content_controls".
+        bookmarks: Optional explicit bookmark name list (mode auto/bookmarks).
+    """
+    return fill_template_run(template_path, data, output_path, mode, bookmarks)
+
+
+@mcp.tool()
+def export_pdf(path: str, output_path: str | None = None, page_range: str | None = None) -> dict:
+    """Export a print-fidelity PDF using the real Word/WPS layout engine.
+
+    The PDF matches what would come out of the printer — not a re-layout by
+    a converter library. Works on legacy .doc files and preserves CJK
+    pagination. The source document is opened read-only and never modified.
+
+    Args:
+        path: Absolute Windows path to the document.
+        output_path: Target .pdf path; defaults to the source name with .pdf.
+        page_range: "all" (default), a single page "7", or a contiguous
+            range "3-9" (1-based). Split comma lists into separate calls.
+    """
+    return export_pdf_run(path, output_path, page_range)
+
+
+@mcp.tool()
+def extract_content(path: str, what: str = "text") -> dict:
+    """Extract text, tables or the heading outline from a Word document.
+
+    Reads legacy .doc binaries that XML libraries cannot open, in a hidden
+    READ-ONLY Word/WPS instance.
+
+    Args:
+        path: Absolute Windows path to the document.
+        what: "text" — full plain text; "tables" — every table as a
+            row-major JSON grid (merged cells repeat their origin text so
+            the grid stays rectangular); "outline" — headings as
+            [{level, text}] via locale-independent outline levels.
+    """
+    return extract_content_run(path, what)
+
+
+@mcp.tool()
+def edit_open_document(path_or_title: str, operations: list, save: str = "ask") -> dict:
+    """Edit a document the user has OPEN in Word/WPS right now.
+
+    Attaches to the user's running instance (not a hidden copy), finds the
+    document by absolute path or window title, and applies small operations
+    in order. The user SEES the changes happen in their window — this is
+    the only Office MCP capability that works on live, locked files.
+
+    Args:
+        path_or_title: Absolute path, or the document's window title / file name.
+        operations: Ordered list, each one of:
+            {"op": "replace_all", "find": "2023", "replace": "2024"}
+            {"op": "insert_text", "text": "Appendix", "where": "end"|"start"}
+            {"op": "save"}
+        save: "ask" (default) — do NOT save, report the dirty state and let
+            the user decide; "save" — write changes to disk when done.
+    """
+    return edit_open_document_run(path_or_title, operations, save)
+
+
+@mcp.tool()
+def merge_documents(
+    template_path: str,
+    data_rows: list,
+    output_dir: str | None = None,
+    name_pattern: str = "{i}_{name}",
+) -> dict:
+    """Mail-merge style batch generation: one template × N data rows.
+
+    Generates one filled document per row into output_dir (default:
+    merged_<template-stem>/ next to the template). Rows fail in isolation —
+    one bad row never stops the batch. Name outputs with {i} (1-based row,
+    zero-padded) and any {field} tokens; names are sanitized.
+
+    Args:
+        template_path: Absolute Windows path to the .doc/.docx template with
+            {{field}} placeholders and/or bookmarks.
+        data_rows: Array of row objects, e.g. [{"name": "张三", "dept": "财务"},
+            {"name": "李四", "dept": "法务"}] → one document each.
+        output_dir: Target folder; created if missing.
+        name_pattern: Output file name pattern (default "{i}_{name}").
+    """
+    return merge_documents_run(template_path, data_rows, output_dir, name_pattern)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="docuhand")
+    sub = parser.add_subparsers(dest="command")
+    sub.add_parser("serve", help="run the MCP stdio server (default)")
+    args = parser.parse_args()
+    if args.command not in (None, "serve"):
+        parser.error(f"unknown command: {args.command}")
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

docuhand/tools/__init__.py

@@ -0,0 +1,7 @@
+"""MCP-facing tools: pydantic-checked args + LLM-facing behaviour.
+
+v0.1 scope: inspect_document only. Each tool module pairs the safety
+wrappers (allowlist/audit) with the engine call and returns structured
+dicts — errors included (architecture decision #3: errors are data the
+agent reads to self-correct, not tracebacks it drowns in).
+"""

docuhand/tools/convert.py

@@ -0,0 +1,228 @@
+"""convert_documents — batch .doc ↔ .docx through the real engine.
+
+Tool-layer responsibilities (the engine stays MCP-free):
+- validate + normalize arguments into structured errors
+- plan the batch with pure helpers (engine/convert_plan.py)
+- run each conversion on the COM STA worker (threading contract)
+- enforce the overwrite policy BEFORE any engine call
+- keep every source file (never delete) and report that explicitly
+- wrap every failure into a per-file structured entry — one bad file in a
+  500-file batch must not kill the batch. Only a total engine launch
+  failure aborts the whole run (nothing else can succeed either).
+"""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+from typing import Any
+
+from ..engine import convert_plan, get_engine, get_worker
+from ..engine.office_app import engine_order_names, sniff_format
+from ..errors import (
+    DocuhandError,
+    EngineUnavailableError,
+    FileNotFoundError,
+    InternalError,
+    InvalidParamError,
+)
+from ..safety import allowlist, audit
+
+TOOL_NAME = "convert_documents"
+
+
+def run(
+    directory: str,
+    to_format: str = "docx",
+    recursive: bool = False,
+    overwrite: str = "skip",
+    output_dir: str | None = None,
+) -> dict[str, Any]:
+    t0 = time.perf_counter()
+
+    # -- argument validation -------------------------------------------------
+    try:
+        fmt = convert_plan.normalize_to_format(to_format)
+    except ValueError as exc:
+        return InvalidParamError(
+            str(exc),
+            llm_hint="Use to_format='docx' (recommended, modern format) or 'doc'.",
+        ).to_dict()
+
+    if overwrite not in ("skip", "overwrite"):
+        return InvalidParamError(
+            f"overwrite must be 'skip' or 'overwrite', got {overwrite!r}",
+            llm_hint="Default 'skip' never destroys an existing file; "
+            "'overwrite' replaces existing target files deliberately.",
+        ).to_dict()
+
+    root = Path(directory).expanduser()
+    if not root.exists():
+        return FileNotFoundError(str(root)).to_dict()
+    if not root.is_dir():
+        return InvalidParamError(
+            f"Not a directory: {root}",
+            llm_hint="Pass the directory that contains the documents. "
+            "For a single file, put it in a directory or use inspect_document first.",
+        ).to_dict()
+    root = root.resolve()  # canonical form in payloads; the engine needs absolutes
+
+    out_root: Path | None = None
+    if output_dir:
+        out_root = Path(output_dir).expanduser()
+        try:
+            out_root.mkdir(parents=True, exist_ok=True)
+        except OSError as exc:
+            return DocuhandError(
+                f"Cannot create output directory {out_root}: {exc}",
+                llm_hint="Check the path (drive letter, permissions). "
+                "Omit output_dir to convert in place, next to each source.",
+                details={"output_dir": str(out_root)},
+            ).to_dict()
+
+    # -- safety gates ----------------------------------------------------------
+    try:
+        allowlist.check_allowed(str(root))
+        if out_root is not None:
+            allowlist.check_allowed(str(out_root))
+    except DocuhandError as exc:
+        audit.record(TOOL_NAME, str(root), ok=False, duration_ms=0, error_code=exc.error_code)
+        return exc.to_dict()
+
+    wd_format = convert_plan.TO_FORMATS[fmt]
+
+    # -- plan ------------------------------------------------------------------
+    pattern = root.rglob("*") if recursive else root.glob("*")
+    try:
+        candidates = sorted(p for p in pattern if p.is_file())
+    except OSError as exc:
+        return InternalError(
+            f"Cannot list directory: {exc}",
+            details={"directory": str(root)},
+        ).to_dict()
+
+    results: list[dict[str, Any]] = []
+    counts = {
+        "to_convert": 0,
+        "already_target": 0,
+        "skipped_existing": 0,
+        "converted": 0,
+        "failed": 0,
+    }
+    ignored = 0
+
+    planned: list[tuple[Path, Path]] = []
+    for src in candidates:
+        kind = convert_plan.classify_source(src.suffix, fmt)
+        if kind == "unsupported_source":
+            ignored += 1
+            continue
+        if kind == "already_target":
+            counts["already_target"] += 1
+            results.append({"source": str(src), "target": None, "status": "already_target"})
+            continue
+        counts["to_convert"] += 1
+        planned.append((src, convert_plan.resolve_target(src, fmt, out_root)))
+
+    # -- execute -----------------------------------------------------------------
+    worker = get_worker()
+    engine = get_engine()
+    aborted: dict[str, Any] | None = None
+
+    for src, target in planned:
+        if target.exists() and overwrite == "skip":
+            counts["skipped_existing"] += 1
+            results.append(
+                {
+                    "source": str(src),
+                    "target": str(target),
+                    "status": "skipped_existing",
+                    "reason": "target exists (overwrite='skip')",
+                }
+            )
+            continue
+
+        try:
+            info = worker.submit(engine.convert_document, str(src), str(target), wd_format)
+        except EngineUnavailableError as exc:
+            counts["failed"] += 1
+            results.append(
+                {"source": str(src), "target": str(target), "status": "failed", "error": exc.to_dict()["error"]}
+            )
+            audit.record(TOOL_NAME, str(src), ok=False, duration_ms=0, error_code=exc.error_code)
+            aborted = exc.to_dict()
+            break
+        except DocuhandError as exc:
+            counts["failed"] += 1
+            results.append(
+                {"source": str(src), "target": str(target), "status": "failed", "error": exc.to_dict()["error"]}
+            )
+            audit.record(TOOL_NAME, str(src), ok=False, duration_ms=0, error_code=exc.error_code)
+            continue
+        except Exception as exc:  # unknown engine crash — still structured
+            err = InternalError(
+                f"Unexpected error converting {src.name}: {type(exc).__name__}: {exc}",
+                llm_hint="Retry once. If it persists, report error_code and details to the DocuHand repository.",
+                details={"source": str(src)},
+            )
+            counts["failed"] += 1
+            results.append(
+                {"source": str(src), "target": str(target), "status": "failed", "error": err.to_dict()["error"]}
+            )
+            audit.record(TOOL_NAME, str(src), ok=False, duration_ms=0, error_code=err.error_code)
+            continue
+
+        # Verify the artifact really is the claimed container format.
+        try:
+            with open(target, "rb") as f:
+                verified = sniff_format(f.read(8))
+        except OSError:
+            verified = "unreadable"
+
+        counts["converted"] += 1
+        results.append(
+            {
+                "source": str(src),
+                "target": str(target),
+                "status": "converted",
+                "engine": info.get("engine"),
+                "target_verified_format": verified,
+                "target_size_bytes": target.stat().st_size if target.exists() else None,
+                "duration_ms": info.get("duration_ms"),
+            }
+        )
+        audit.record(
+            TOOL_NAME,
+            str(src),
+            ok=True,
+            duration_ms=info.get("duration_ms") or 0,
+            engine=info.get("engine"),
+        )
+
+    total_found = counts["already_target"] + counts["to_convert"]
+    payload: dict[str, Any] = {
+        "ok": aborted is None,
+        "tool": TOOL_NAME,
+        "directory": str(root),
+        "output_dir": str(out_root) if out_root else None,
+        "to_format": fmt,
+        "recursive": recursive,
+        "overwrite": overwrite,
+        "engine_order": engine_order_names(),
+        "sources_deleted": False,
+        "summary": {
+            **counts,
+            "doc_files_found": total_found,
+            "ignored_other_extensions": ignored,
+            "duration_ms": round((time.perf_counter() - t0) * 1000),
+        },
+        "results": results,
+    }
+    if aborted is not None:
+        payload["error"] = aborted["error"]
+        payload["llm_hint"] = (
+            "No Office engine could be launched, so the batch aborted before "
+            "touching the remaining files. Install/repair Microsoft Word or "
+            "WPS Office (or close a stuck first-run dialog), then retry."
+        )
+    return payload

docuhand/tools/edit_open.py

@@ -0,0 +1,92 @@
+"""edit_open_document — edit a document the user has open RIGHT NOW.
+
+Attaches to the live Word/WPS instance on the STA worker, resolves the
+document by path or window title, validates the whole operation batch up
+front (edit_plan.py), applies it, and reports the saved/dirty state.
+Default is NOT to save ('ask') — the agent tells the user what changed.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+from ..engine import edit_plan, get_worker
+from ..engine.live_edit import edit_open_document as engine_edit
+from ..errors import DocuhandError, InvalidParamError, InternalError
+from ..safety import allowlist, audit
+from ..safety.policy import ensure_writable
+
+TOOL_NAME = "edit_open_document"
+
+
+def run(
+    path_or_title: str,
+    operations: list[dict[str, Any]],
+    save: str = "ask",
+) -> dict[str, Any]:
+    t0 = time.perf_counter()
+
+    # -- validate the whole batch BEFORE any COM call --------------------------
+    try:
+        clean_ops = edit_plan.validate_operations(operations)
+    except ValueError as exc:
+        return InvalidParamError(str(exc), llm_hint="Fix the operations list and retry.").to_dict()
+    if save not in ("ask", "save"):
+        return InvalidParamError(
+            f"save must be 'ask' or 'save' (got {save!r})",
+            llm_hint="Default 'ask' never writes without the user knowing; 'save' persists the changes.",
+        ).to_dict()
+
+    # -- safety gates ------------------------------------------------------------
+    # allowlist applies to the file path when resolvable; title matches are
+    # allowed only because the user opened that document themselves.
+    p = None
+    from pathlib import Path
+
+    try:
+        p = Path(path_or_title).expanduser()
+        if p.exists():
+            allowlist.check_allowed(str(p.resolve()))
+    except DocuhandError as exc:
+        audit.record(TOOL_NAME, str(path_or_title), ok=False, duration_ms=0, error_code=exc.error_code)
+        return exc.to_dict()
+    except OSError:
+        pass  # a window title, not a path — the user opened it themselves
+
+    try:
+        ensure_writable(TOOL_NAME)
+    except DocuhandError as exc:
+        audit.record(TOOL_NAME, str(path_or_title), ok=False, duration_ms=0, error_code=exc.error_code)
+        return exc.to_dict()
+
+    # -- execute on the STA worker -------------------------------------------------
+    worker = get_worker()
+    try:
+        result = worker.submit(engine_edit, path_or_title, clean_ops, save)
+    except DocuhandError as exc:
+        audit.record(
+            TOOL_NAME,
+            str(path_or_title),
+            ok=False,
+            duration_ms=(time.perf_counter() - t0) * 1000,
+            error_code=exc.error_code,
+        )
+        return exc.to_dict()
+    except Exception as exc:
+        err = InternalError(
+            f"Unexpected error editing open document: {type(exc).__name__}: {exc}",
+            llm_hint="Retry once. If it persists, report error_code and details to the DocuHand repository.",
+            details={"path_or_title": path_or_title},
+        )
+        audit.record(TOOL_NAME, str(path_or_title), ok=False, duration_ms=(time.perf_counter() - t0) * 1000, error_code=err.error_code)
+        return err.to_dict()
+
+    audit.record(
+        TOOL_NAME,
+        result.get("document", str(path_or_title)),
+        ok=True,
+        duration_ms=result.get("duration_ms") or 0,
+        engine=result.get("engine"),
+    )
+    return result