@_vrsen/openswarm 0.1.0

package/docs_agent/tools/utils/doc_file_utils.py

@@ -0,0 +1,29 @@
+"""Utilities for managing document project directories."""
+
+import re
+from pathlib import Path
+
+
+def get_mnt_dir() -> Path:
+    return Path("/app/mnt") if Path("/.dockerenv").is_file() else Path(__file__).parents[3] / "mnt"
+
+
+def get_project_dir(project_name: str) -> Path:
+    return get_mnt_dir() / project_name / "documents"
+
+
+def next_docx_version(desired: Path) -> Path:
+    """Return desired if it doesn't exist, otherwise the next free _vN path.
+
+    Strips any existing _vN suffix before searching so passing report_v2.docx
+    when that file already exists yields report_v3.docx, not report_v2_v2.docx.
+    """
+    if not desired.exists():
+        return desired
+    base = re.sub(r"_v\d+$", "", desired.stem)
+    n = 2
+    while True:
+        candidate = desired.parent / f"{base}_v{n}{desired.suffix}"
+        if not candidate.exists():
+            return candidate
+        n += 1

package/docs_agent/tools/utils/html_docx_blocks.py

@@ -0,0 +1,262 @@
+from typing import Dict, Optional
+
+from bs4.element import Comment, NavigableString, Tag
+from docx.oxml.ns import qn
+from docx.shared import Pt
+
+from .html_docx_constants import _BLOCK_TAGS, _INHERITABLE_STYLES, _INLINE_TAGS
+from .html_docx_css import _parse_background_color, _parse_border_left, _parse_padding
+from .html_docx_images import _add_image_run, _add_svg_run
+from .html_docx_paragraphs import (
+    _apply_paragraph_style,
+    _apply_run_style,
+    _apply_ul_margin_indent,
+    _resolve_list_indent_pt,
+)
+from .html_docx_selectors import _compute_style_map
+
+
+_SKIP_TAGS = {"style", "script", "head", "meta", "link", "title", "noscript"}
+
+
+def _handle_block(node, target, css_rules, parent_style: Dict[str, str], table_auto_widths) -> None:
+    target_container = _ensure_container(target)
+    if isinstance(node, Comment):
+        return
+    if isinstance(node, Tag) and node.name in _SKIP_TAGS:
+        return
+    if isinstance(node, NavigableString):
+        text = node.strip()
+        if not text:
+            return
+        paragraph = _ensure_paragraph(target_container)
+        _apply_paragraph_style(paragraph, parent_style)
+        run = paragraph.add_run(_transform_text(_normalize_text(text), parent_style))
+        _apply_run_style(run, parent_style)
+        return
+
+    if not isinstance(node, Tag):
+        return
+
+    if node.name == "img":
+        paragraph = _ensure_paragraph(target_container)
+        _apply_paragraph_style(paragraph, parent_style)
+        _add_image_run(paragraph, node, parent_style)
+        return
+
+    if node.name == "svg":
+        paragraph = _ensure_paragraph(target_container)
+        _apply_paragraph_style(paragraph, parent_style)
+        _add_svg_run(paragraph, node, parent_style)
+        return
+
+    if node.name == "table":
+        from .html_docx_tables import _handle_table
+
+        _handle_table(node, target_container, css_rules, parent_style, table_auto_widths)
+        return
+
+    if node.name in _BLOCK_TAGS:
+        current_style = _merge_styles(parent_style, _compute_style_map(node, css_rules))
+
+        if _should_wrap_container(node, current_style):
+            container = _add_container(
+                target_container, node, current_style, css_rules, table_auto_widths
+            )
+            for child in node.children:
+                _handle_block(child, container, css_rules, current_style, table_auto_widths)
+            return
+
+        if _has_block_children(node):
+            for child in node.children:
+                _handle_block(child, target_container, css_rules, current_style, table_auto_widths)
+            return
+
+        paragraph = _ensure_paragraph(
+            target_container,
+            style="List Bullet" if node.name == "li" else None,
+        )
+        _apply_paragraph_style(paragraph, current_style)
+        if node.name == "li":
+            paragraph.paragraph_format.space_before = Pt(0)
+            paragraph.paragraph_format.space_after = Pt(0)
+            # Apply the parent <ul> margin-left as additional left indent so the
+            # list is offset the same amount it is in the HTML rendering.
+            _apply_ul_margin_indent(paragraph, _resolve_list_indent_pt(parent_style))
+        _add_inline_runs(node, paragraph, css_rules, current_style)
+        return
+
+    if node.name in _INLINE_TAGS:
+        paragraph = _ensure_paragraph(target_container)
+        _add_inline_runs(node, paragraph, css_rules, parent_style)
+        return
+
+    for child in node.children:
+        _handle_block(child, target_container, css_rules, parent_style, table_auto_widths)
+
+
+def _add_inline_runs(node, paragraph, css_rules, parent_style: Dict[str, str]) -> None:
+    if isinstance(node, Comment):
+        return
+    if isinstance(node, NavigableString):
+        raw_text = str(node)
+        if not raw_text.strip():
+            paragraph.add_run(" ")
+            return
+        normalized = _normalize_inline_text(raw_text)
+        if not paragraph.text and normalized.startswith(" "):
+            normalized = normalized.lstrip()
+        if not normalized:
+            return
+        run = paragraph.add_run(_transform_text(normalized, parent_style))
+        _apply_run_style(run, parent_style)
+        return
+
+    if not isinstance(node, Tag):
+        return
+
+    if node.name == "img":
+        _add_image_run(paragraph, node, parent_style)
+        return
+
+    if node.name == "svg":
+        _add_svg_run(paragraph, node, parent_style)
+        return
+
+    if node.name == "br":
+        paragraph.add_run().add_break()
+        return
+
+    current_style = _merge_styles(parent_style, _compute_style_map(node, css_rules))
+
+    if node.name in _INLINE_TAGS:
+        if node.name in {"strong", "b"}:
+            current_style = {**current_style, "font-weight": "bold"}
+        if node.name in {"em", "i"}:
+            current_style = {**current_style, "font-style": "italic"}
+        if node.name == "u":
+            current_style = {**current_style, "text-decoration": "underline"}
+
+    for child in node.children:
+        _add_inline_runs(child, paragraph, css_rules, current_style)
+
+
+def _transform_text(text: str, style_map: Dict[str, str]) -> str:
+    transform = style_map.get("text-transform", "").strip().lower()
+    if transform == "uppercase":
+        return text.upper()
+    if transform == "lowercase":
+        return text.lower()
+    if transform == "capitalize":
+        return " ".join(word.capitalize() for word in text.split())
+    return text
+
+
+def _has_block_children(node: Tag) -> bool:
+    for child in node.children:
+        if isinstance(child, Tag) and child.name in _BLOCK_TAGS:
+            return True
+    return False
+
+
+def _merge_styles(parent_style: Dict[str, str], own_style: Dict[str, str]) -> Dict[str, str]:
+    merged: Dict[str, str] = {}
+    for key in _INHERITABLE_STYLES:
+        if key in parent_style:
+            merged[key] = parent_style[key]
+    for key, value in own_style.items():
+        merged[key] = value
+    return merged
+
+
+def _should_wrap_container(node: Tag, style_map: Dict[str, str]) -> bool:
+    if style_map.get("display", "").strip().lower() == "flex":
+        return True
+    if _parse_background_color(style_map) is not None:
+        return True
+    if _parse_border_left(style_map) is not None:
+        return True
+    padding = _parse_padding(style_map.get("padding", ""))
+    if padding and any(v > 0 for v in padding):
+        return True
+    if node.name in {"header", "section"}:
+        return True
+    return False
+
+
+def _add_container(target, node: Tag, style_map: Dict[str, str], css_rules, table_auto_widths):
+    from .html_docx_tables import _apply_cell_styles, _apply_table_styles
+
+    if style_map.get("display", "").strip().lower() == "flex":
+        children = [child for child in node.children if isinstance(child, Tag)]
+        if len(children) == 2:
+            table = target.add_table(rows=1, cols=2)
+            _apply_table_styles(table, style_map)
+            left_cell = table.cell(0, 0)
+            right_cell = table.cell(0, 1)
+            _apply_cell_styles(left_cell, style_map)
+            _apply_cell_styles(right_cell, style_map)
+            for child in children[0].children:
+                _handle_block(child, left_cell, css_rules, style_map, table_auto_widths)
+            for child in children[1].children:
+                _handle_block(child, right_cell, css_rules, style_map, table_auto_widths)
+            return table
+
+    table = target.add_table(rows=1, cols=1)
+    _apply_table_styles(table, style_map)
+    cell = table.cell(0, 0)
+    _apply_cell_styles(cell, style_map)
+    return cell
+
+
+def _ensure_container(target):
+    if hasattr(target, "add_paragraph"):
+        return target
+    if hasattr(target, "cell"):
+        return target.cell(0, 0)
+    return target
+
+
+def _ensure_paragraph(container, style: Optional[str] = None):
+    if hasattr(container, "paragraphs") and container.paragraphs:
+        last = container.paragraphs[-1]
+        if not last.text and len(last.runs) == 0 and _is_pristine_paragraph(last):
+            if style is not None:
+                last.style = style
+            return last
+    return container.add_paragraph(style=style)
+
+
+def _is_pristine_paragraph(paragraph) -> bool:
+    """Return True only for the unformatted initial placeholder paragraph.
+
+    We must not reuse paragraphs that carry visual formatting (borders, exact
+    spacing, shading) from a previously processed block element, otherwise the
+    next element would overwrite that formatting.  A pristine paragraph is one
+    whose pPr contains only a pStyle declaration (or nothing at all).
+    """
+    p_pr = paragraph._p.find(qn("w:pPr"))
+    if p_pr is None:
+        return True
+    _ALLOWED_TAGS = {qn("w:pStyle"), qn("w:rPr")}
+    return all(child.tag in _ALLOWED_TAGS for child in p_pr)
+
+
+def _normalize_text(text: str) -> str:
+    return " ".join(text.split())
+
+
+def _normalize_inline_text(text: str) -> str:
+    text = text.replace("\xa0", " ")
+    if not text:
+        return ""
+    lead_space = text[:1].isspace()
+    trail_space = text[-1:].isspace()
+    collapsed = " ".join(text.split())
+    if not collapsed and (lead_space or trail_space):
+        return " "
+    if lead_space:
+        collapsed = " " + collapsed
+    if trail_space:
+        collapsed = collapsed + " "
+    return collapsed

package/docs_agent/tools/utils/html_docx_constants.py

@@ -0,0 +1,78 @@
+_BLOCK_TAGS = {
+    "h1",
+    "h2",
+    "h3",
+    "h4",
+    "h5",
+    "h6",
+    "p",
+    "li",
+    "div",
+    "section",
+    "header",
+    "ul",
+    "ol",
+    "table",
+}
+_INLINE_TAGS = {"span", "a", "strong", "em", "b", "i", "u", "small", "sup", "sub"}
+_INHERITABLE_STYLES = {
+    "font-family",
+    "font-size",
+    "color",
+    "font-weight",
+    "font-style",
+    "text-decoration",
+    "text-transform",
+    "text-align",
+    "line-height",
+}
+
+_NAMED_COLORS = {
+    "white": (255, 255, 255),
+    "black": (0, 0, 0),
+    "gray": (128, 128, 128),
+    "grey": (128, 128, 128),
+    "lightgray": (211, 211, 211),
+    "lightgrey": (211, 211, 211),
+    "darkgray": (169, 169, 169),
+    "darkgrey": (169, 169, 169),
+    "red": (255, 0, 0),
+    "green": (0, 128, 0),
+    "blue": (0, 0, 255),
+    "navy": (0, 0, 128),
+    "purple": (128, 0, 128),
+    "teal": (0, 128, 128),
+    "orange": (255, 165, 0),
+    "yellow": (255, 255, 0),
+}
+
+_PADDING_SCALE = 0.7
+_BORDER_SCALE = 1.5
+
+_PAGE_SIZES_PT = {
+    "a4": (595.3, 841.9),
+    "letter": (612.0, 792.0),
+}
+
+_LIST_BASE_LEFT_TWIPS = 360
+_LIST_BASE_HANGING_TWIPS = 360  # matches ilvl-0 hanging in the default Word template abstractNum
+
+_UA_RESET_STYLE = """<style>
+        /* UA reset to neutralize browser defaults */
+        * {
+            margin: 0;
+            padding: 0;
+            border: 0;
+            font: inherit;
+            vertical-align: baseline;
+        }
+        h1, h2, h3, h4, h5, h6 {
+            font-weight: normal;
+        }
+        p, ul, ol, li {
+            margin: 0;
+            padding: 0;
+        }
+        ul { list-style: disc; padding-left: 20px; }
+        ol { list-style: decimal; padding-left: 20px; }
+    </style>"""

package/docs_agent/tools/utils/html_docx_core.py

@@ -0,0 +1,138 @@
+from pathlib import Path
+from typing import Optional
+
+from bs4 import BeautifulSoup
+from bs4.element import Comment, NavigableString, Tag
+from docx import Document
+from docx.oxml import OxmlElement
+from docx.oxml.ns import qn
+from docx.shared import Pt
+
+from .html_docx_blocks import _handle_block
+from .html_docx_page import (
+    _apply_page_background,
+    _apply_page_settings,
+    _ensure_display_background_shape,
+)
+from .html_docx_playwright import _annotate_tables, _compute_table_auto_widths
+from .html_docx_selectors import _compute_style_map, _extract_css_rules
+from .html_docx_shared import _remove_trailing_empty_paragraph
+
+
+def html_to_docx(html_content: str, output_path: Path) -> None:
+    doc = Document()
+    _set_default_paragraph_style(doc)
+    _apply_page_settings(doc, html_content)
+    _remove_trailing_empty_paragraph(doc)
+    soup = BeautifulSoup(html_content, "html.parser")
+    table_auto_widths = _compute_table_auto_widths(_annotate_tables(soup))
+    css_rules = _extract_css_rules(soup)
+
+    body = soup.body or soup
+    body_style = _compute_style_map(body, css_rules)
+    _apply_page_background(doc, body_style)
+    _ensure_display_background_shape(doc)
+    content_root = _unwrap_layout_table(body) or body
+    for child in content_root.children:
+        _handle_block(child, doc, css_rules, body_style, table_auto_widths)
+
+    # When the document body starts with a table, Word renders an implicit gap above it.
+    # Inserting a 1pt-height anchor paragraph before the first table eliminates that gap.
+    _insert_top_anchor_paragraph(doc)
+
+    doc.save(str(output_path))
+
+
+_SKIP_TAGS = {"style", "script", "head", "meta", "link", "title", "noscript"}
+
+
+def _unwrap_layout_table(body: Tag) -> Optional[Tag]:
+    """Return the single content cell of the outer centered layout table.
+
+    Many generated docs wrap the entire body in a single-row, single-cell table
+    purely to constrain width (`width:547pt; margin:auto`). In DOCX this turns
+    the whole document into one giant table cell, which makes Word paginate
+    nested content poorly. When we detect that specific wrapper, process the
+    cell's children directly at the document body level instead.
+    """
+    content_children = [
+        child
+        for child in body.children
+        if not isinstance(child, Comment)
+        and not (isinstance(child, NavigableString) and not child.strip())
+        and not (isinstance(child, Tag) and child.name in _SKIP_TAGS)
+    ]
+    if len(content_children) != 1:
+        return None
+
+    table = content_children[0]
+    if not isinstance(table, Tag) or table.name != "table":
+        return None
+    if not _is_layout_wrapper_table(table):
+        return None
+
+    rows = _direct_rows(table)
+    if len(rows) != 1:
+        return None
+
+    cells = rows[0].find_all(["td", "th"], recursive=False)
+    if len(cells) != 1:
+        return None
+
+    return cells[0]
+
+
+def _is_layout_wrapper_table(table: Tag) -> bool:
+    style = (table.get("style") or "").replace(" ", "").lower()
+    return (
+        "width:547pt" in style
+        and "margin-left:auto" in style
+        and "margin-right:auto" in style
+    )
+
+
+def _direct_rows(table: Tag) -> list[Tag]:
+    rows = table.find_all("tr", recursive=False)
+    if rows:
+        return rows
+
+    rows = []
+    for section in table.find_all(["thead", "tbody", "tfoot"], recursive=False):
+        rows.extend(section.find_all("tr", recursive=False))
+    return rows
+
+
+def _insert_top_anchor_paragraph(doc: Document) -> None:
+    """Insert a near-zero-height paragraph before the first body-level table."""
+    body_el = doc._body._body
+    first = body_el[0] if len(body_el) else None
+    if first is None or first.tag != qn("w:tbl"):
+        return
+
+    p_el = OxmlElement("w:p")
+    p_pr = OxmlElement("w:pPr")
+    spacing = OxmlElement("w:spacing")
+    spacing.set(qn("w:before"), "0")
+    spacing.set(qn("w:after"), "0")
+    spacing.set(qn("w:line"), "20")    # 1pt exact
+    spacing.set(qn("w:lineRule"), "exact")
+    ctx = OxmlElement("w:contextualSpacing")
+    r_pr = OxmlElement("w:rPr")
+    sz = OxmlElement("w:sz")
+    sz.set(qn("w:val"), "2")           # 1pt font
+    r_pr.append(sz)
+    p_pr.append(spacing)
+    p_pr.append(ctx)
+    p_pr.append(r_pr)
+    p_el.append(p_pr)
+    body_el.insert(0, p_el)
+
+
+def _set_default_paragraph_style(doc: Document) -> None:
+    try:
+        normal = doc.styles["Normal"]
+    except KeyError:
+        return
+    normal_pf = normal.paragraph_format
+    normal_pf.space_before = Pt(0)
+    normal_pf.space_after = Pt(0)