feat: export a report as Word (.docx)

Add a to_docx export that walks the report views and writes headings, markdown, native tables and chart images into a Word document, wired into the export menu and the mobile SpeedDial. python-docx is an optional dependency: to_docx checks for it via try_import and raises a clear error if it is missing, and the module no longer imports docx at load time.

Author: ghostiee-11

lumen/ai/export.py

@@ -133,3 +133,58 @@ def export_notebook(outputs: list[Viewable], preamble: str = ""):
     cells, extensions = render_cells(outputs)
     cells = make_preamble(preamble, extensions=extensions) + cells
     return write_notebook(cells)
+
+
+def _docx_add_runs(paragraph, text: str):
+    """Add text to a paragraph, rendering ``**bold**`` spans as bold runs."""
+    for i, part in enumerate(re.split(r'\*\*(.+?)\*\*', text)):
+        if not part:
+            continue
+        run = paragraph.add_run(part)
+        if i % 2 == 1:
+            run.bold = True
+
+
+def docx_add_markdown(doc, text: str):
+    """Render basic markdown (headings, bullets, bold) into a docx document."""
+    for line in text.splitlines():
+        stripped = line.strip()
+        if not stripped:
+            continue
+        if stripped.startswith('#'):
+            level = len(stripped) - len(stripped.lstrip('#'))
+            doc.add_heading(stripped.lstrip('# ').strip(), level=min(level, 4))
+        elif stripped.startswith(('- ', '* ')):
+            _docx_add_runs(doc.add_paragraph(style='List Bullet'), stripped[2:])
+        else:
+            _docx_add_runs(doc.add_paragraph(), stripped)
+
+
+def docx_add_table(doc, df, max_rows: int = 50):
+    """Render a DataFrame as a native Word table (header + capped rows)."""
+    table = doc.add_table(rows=1, cols=len(df.columns))
+    table.style = 'Table Grid'
+    for cell, col in zip(table.rows[0].cells, df.columns, strict=False):
+        cell.text = str(col)
+    for _, record in df.head(max_rows).iterrows():
+        cells = table.add_row().cells
+        for cell, value in zip(cells, record, strict=False):
+            cell.text = '' if value is None else str(value)
+    if len(df) > max_rows:
+        doc.add_paragraph(f'... {len(df) - max_rows} more rows')
+
+
+def docx_add_chart(doc, editor) -> bool:
+    """Embed a chart editor as a PNG image; return True if one was added."""
+    from docx.shared import Inches
+
+    if 'png' not in editor.export_formats:
+        return False
+    try:
+        png = editor.export('png')
+    except Exception:
+        # Best-effort: a chart we cannot render should not abort the document.
+        return False
+    png.seek(0)
+    doc.add_picture(png, width=Inches(6))
+    return True

lumen/ai/report.py

@@ -29,6 +29,7 @@
 
 from ..config import config
 from ..pipeline import Pipeline
+from ..util import try_import
 from ..views.base import Panel, View
 from .actor import (
     Actor, ContextProvider, NullStep, TContext,
@@ -939,6 +940,7 @@ def _init_view(self):
             items=[
                 {"label": "Notebook (.ipynb)", "format": "ipynb", "icon": "description"},
                 {"label": "HTML (.html)", "format": "html", "icon": "language"},
+                {"label": "Word (.docx)", "format": "docx", "icon": "article"},
             ],
             on_click=lambda _: self._download._transfer(),
             icon_size="36px",
@@ -1030,6 +1032,7 @@ def _init_view(self):
                 {"label": "Switch Report/Story View", "icon": "swap_horiz"},
                 {"label": "Export as Notebook", "icon": "description", "format": "ipynb"},
                 {"label": "Export as HTML", "icon": "language", "format": "html"},
+                {"label": "Export as Word", "icon": "article", "format": "docx"},
                 {"label": "Configure Report", "icon": "settings"}
             ],
             color="default",
@@ -1081,7 +1084,7 @@ async def _trigger_event(self, item: dict):
             self._open_arrange_dialog()
         elif icon == "swap_horiz":
             self._toggle_view()
-        elif icon in ("description", "language"):
+        elif icon in ("description", "language", "article"):
             fmt = item.get("format", "ipynb")
             self._export.value = {"format": fmt}
             self._download._transfer()
@@ -1261,15 +1264,83 @@ def to_html(self):
         self._export_view().save(buf, title=self.title or "Report")
         return buf.getvalue()
 
+    def to_docx(self) -> bytes:
+        """
+        Returns the Word (.docx) representation of the report as bytes.
+        """
+        if len(self) and self.status != "success":
+            raise RuntimeError(
+                "Report has not been executed, run report before exporting to docx."
+            )
+        if try_import("docx") is None:
+            raise ImportError(
+                "Exporting a report to Word requires python-docx; install it with "
+                "`pip install python-docx`."
+            )
+        from docx import Document
+
+        from .export import docx_add_chart, docx_add_markdown, docx_add_table
+
+        doc = Document()
+        pending: list[tuple[int, str]] = []
+
+        def flush_headers():
+            for level, heading in pending:
+                doc.add_heading(heading, level=level or 1)
+            pending.clear()
+
+        for out in self._export_views:
+            if isinstance(out, Typography):
+                obj = out.object or ""
+                if out.variant and out.variant.startswith('h'):
+                    level, heading = int(out.variant[1:]), obj
+                elif obj.startswith('#'):
+                    level = len(obj) - len(obj.lstrip('#'))
+                    heading = obj.lstrip('# ').strip()
+                else:
+                    level, heading = 1, obj
+                pending.append((min(level, 4), heading))
+                continue
+            if isinstance(out, LumenEditor):
+                has_chart = 'png' in out.export_formats
+                data = getattr(out.component, 'data', None)
+                if not has_chart and data is None:
+                    continue
+                flush_headers()
+                # Prefer the chart as an image; fall back to a data table when
+                # there is no renderable chart.
+                if not (has_chart and docx_add_chart(doc, out)) and data is not None:
+                    docx_add_table(doc, data)
+                continue
+            if isinstance(out, Markdown):
+                text = out.object
+            elif isinstance(out, str):
+                text = out
+            elif isinstance(out, ChatMessage):
+                inner = out.object
+                text = inner.object if isinstance(inner, Markdown) else (inner if isinstance(inner, str) else None)
+            else:
+                text = None
+            if text is None:
+                continue
+            flush_headers()
+            docx_add_markdown(doc, text)
+
+        buf = io.BytesIO()
+        doc.save(buf)
+        return buf.getvalue()
+
     async def _export_report(self, item=None):
         if len(self) and self.status not in ("success", "cancelled", "error"):
             await self.execute()
         fmt = item.get("format", "ipynb") if isinstance(item, dict) else "ipynb"
         title = self.title or "Report"
-        ext = "html" if fmt == "html" else "ipynb"
+        ext = {"html": "html", "docx": "docx"}.get(fmt, "ipynb")
         self._download.filename = f"{title}.{ext}"
         if fmt == "html":
             return io.StringIO(self.to_html())
+        if fmt == "docx":
+            return io.BytesIO(self.to_docx())
         return io.StringIO(self.to_notebook())
 
     def _expand_all(self, event=None):