Skip to content

Build and run agents you can see, understand and trust.

fix(rag): read a Word text box once, and as its own block (#2662)

Lukasd3354af5ca77
diff --git a/src/agentscope/rag/_parser/_word.py b/src/agentscope/rag/_parser/_word.py
index 26a080d85..900d5b438 100644
--- a/src/agentscope/rag/_parser/_word.py
+++ b/src/agentscope/rag/_parser/_word.py
@@ -16,7 +16,8 @@ from __future__ import annotations
import base64
import io
-from typing import Literal, TYPE_CHECKING
+from collections.abc import Iterator
+from typing import Any, Literal, TYPE_CHECKING
from ..._logging import logger
from ...message import Base64Source, DataBlock, TextBlock
@@ -33,42 +34,75 @@ if TYPE_CHECKING:
from docx.text.paragraph import Paragraph as DocxParagraph
_VML_NS = "{urn:schemas-microsoft-com:vml}"
+_MC_ALTERNATE_CONTENT = (
+ "{http://schemas.openxmlformats.org/markup-compatibility/2006}"
+ "AlternateContent"
+)
def _extract_text_from_paragraph(para: DocxParagraph) -> str:
- """Extract text from a paragraph, including text in text boxes and
- VML shapes.
-
- Tries three methods in order:
- 1. All ``w:t`` elements in the paragraph XML (covers revisions,
- hyperlinks, etc.).
- 2. The standard ``para.text`` property.
- 3. Text inside ``w:txbxContent`` and VML ``v:textbox`` elements.
+ """Extract text from a paragraph, including any text box anchored to it.
+
+ The paragraph's own runs come first, then each text box once, as its own
+ line. Reading every ``w:t`` under the paragraph in one pass would splice a
+ text box into the middle of the surrounding sentence, and would read the
+ ``mc:Fallback`` copy of a text box as a second occurrence of the same text.
+ Each ``mc:AlternateContent`` containing a text box uses the first branch
+ with readable Word text, retaining the fallback when its choices cannot
+ supply any text. Other paragraph content keeps its original behavior.
+
+ Args:
+ para (`DocxParagraph`):
+ The python-docx paragraph to read.
+
+ Returns:
+ `str`:
+ The paragraph's text, with each text box on its own line.
"""
from docx.oxml.ns import qn
- text = ""
- for t_elem in para._element.findall(".//" + qn("w:t")):
- if t_elem.text:
- text += t_elem.text
-
- if not text:
- text = para.text.strip()
-
- if not text:
- for txbx in para._element.findall(".//" + qn("w:txbxContent")):
- for p_elem in txbx.findall(".//" + qn("w:p")):
- for t_elem in p_elem.findall(".//" + qn("w:t")):
- if t_elem.text:
- text += t_elem.text
-
- for vml_tb in para._element.findall(".//" + _VML_NS + "textbox"):
- for p_elem in vml_tb.findall(".//" + qn("w:p")):
- for t_elem in p_elem.findall(".//" + qn("w:t")):
- if t_elem.text:
- text += t_elem.text
-
- return text.strip()
+ text_tag = qn("w:t")
+ text_box_tag = qn("w:txbxContent")
+ root = para._element
+
+ def iter_text(element: Any) -> Iterator[Any]:
+ """Visit text in one readable branch of each AlternateContent."""
+ if element.tag == text_tag:
+ yield element
+ elif (
+ element.tag == _MC_ALTERNATE_CONTENT
+ and element.find(".//" + text_box_tag) is not None
+ ):
+ texts: list[Any] = []
+ for branch in element:
+ texts = list(iter_text(branch))
+ if any(t.text and t.text.strip() for t in texts):
+ break
+ yield from texts
+ else:
+ for child in element:
+ yield from iter_text(child)
+
+ own_parts: list[str] = []
+ text_boxes: dict[Any, list[str]] = {}
+ for text in iter_text(root):
+ if not text.text:
+ continue
+ parts = own_parts
+ for ancestor in text.iterancestors():
+ if ancestor is root:
+ break
+ if ancestor.tag == text_box_tag:
+ parts = text_boxes.setdefault(ancestor, [])
+ break
+ parts.append(text.text)
+
+ own_text = "".join(own_parts)
+ if not own_text and not text_boxes:
+ # python-docx also reads characters such as w:noBreakHyphen.
+ own_text = para.text
+ blocks = [own_text, *("".join(parts) for parts in text_boxes.values())]
+ return "\n".join(block.strip() for block in blocks if block.strip())
def _extract_table_data(table: DocxTable) -> list[list[str]]:
diff --git a/tests/rag_parser_test.py b/tests/rag_parser_test.py
index 41f66d221..82b02020c 100644
--- a/tests/rag_parser_test.py
+++ b/tests/rag_parser_test.py
@@ -303,6 +303,115 @@ def _make_docx_with_special_table_cells() -> bytes:
return buffer.getvalue()
+_DOCX_TEXT_BOX_NS = " ".join(
+ f'xmlns:{prefix}="{uri}"'
+ for prefix, uri in (
+ ("w", "http://schemas.openxmlformats.org/wordprocessingml/2006/main"),
+ ("mc", "http://schemas.openxmlformats.org/markup-compatibility/2006"),
+ (
+ "wps",
+ "http://schemas.microsoft.com/office/word/2010/"
+ "wordprocessingShape",
+ ),
+ ("a", "http://schemas.openxmlformats.org/drawingml/2006/main"),
+ (
+ "wp",
+ "http://schemas.openxmlformats.org/drawingml/2006/"
+ "wordprocessingDrawing",
+ ),
+ ("v", "urn:schemas-microsoft-com:vml"),
+ )
+)
+
+_DOCX_MODERN_TEXT_BOX = """
+<w:p {ns}>
+ <w:r><w:t>{before}</w:t></w:r>
+ <w:r><w:drawing><wp:inline distT="0" distB="0" distL="0" distR="0">
+ <wp:extent cx="2743200" cy="914400"/>
+ <wp:docPr id="1" name="Text Box 1"/>
+ <a:graphic><a:graphicData
+ uri="http://schemas.microsoft.com/office/word/2010/wordprocessingShape">
+ <wps:wsp><wps:txbx><w:txbxContent>
+ <w:p><w:r><w:t>{inside}</w:t></w:r></w:p>
+ </w:txbxContent></wps:txbx></wps:wsp>
+ </a:graphicData></a:graphic>
+ </wp:inline></w:drawing></w:r>
+</w:p>
+"""
+
+_DOCX_TEXT_BOX_WITH_VML_FALLBACK = """
+<w:p {ns}>
+ <w:r><w:t>{before}</w:t></w:r>
+ <w:r><mc:AlternateContent>
+ <mc:Choice Requires="wps"><w:drawing>
+ <wp:inline distT="0" distB="0" distL="0" distR="0">
+ <wp:extent cx="2743200" cy="914400"/>
+ <wp:docPr id="1" name="Text Box 1"/>
+ <a:graphic><a:graphicData
+ uri="http://schemas.microsoft.com/office/word/2010/wordprocessingShape">
+ <wps:wsp><wps:txbx><w:txbxContent>
+ <w:p><w:r><w:t>{inside}</w:t></w:r></w:p>
+ </w:txbxContent></wps:txbx></wps:wsp>
+ </a:graphicData></a:graphic>
+ </wp:inline></w:drawing></mc:Choice>
+ <mc:Fallback><w:pict>
+ <v:shape id="_x0000_s1026" type="#_x0000_t202"><v:textbox>
+ <w:txbxContent>
+ <w:p><w:r><w:t>{inside}</w:t></w:r></w:p>
+ </w:txbxContent>
+ </v:textbox></v:shape>
+ </w:pict></mc:Fallback>
+ </mc:AlternateContent></w:r>
+</w:p>
+"""
+
+
+def _make_docx_with_text_box(
+ template: str,
+ before: str = "Paragraph text",
+ inside: str = "Callout",
+ text_box_count: int = 1,
+) -> bytes:
+ """Build a paragraph anchoring independently created text boxes."""
+ import docx
+ from lxml import etree
+
+ document = docx.Document()
+ body = document.element.body
+ xml = template.format(
+ ns=_DOCX_TEXT_BOX_NS,
+ before=before,
+ inside=inside,
+ ).strip()
+ paragraph = etree.fromstring(xml)
+ for _ in range(1, text_box_count):
+ # Each template ends with the run that anchors its text box.
+ paragraph.append(etree.fromstring(xml)[-1])
+ body.insert(len(body) - 1, paragraph)
+ document.add_paragraph("After")
+
+ buffer = io.BytesIO()
+ document.save(buffer)
+ return buffer.getvalue()
+
+
+def _expected_word_sections(text: str) -> list[dict]:
+ """Return the complete expected output for a single Word text section."""
+ return [
+ {
+ "content": {
+ "type": "text",
+ "text": text,
+ "id": AnyString(),
+ "created_at": AnyString(),
+ "finished_at": None,
+ },
+ "source": "demo.docx",
+ "metadata": {},
+ },
+ ]
+
+
def _make_docx_with_image() -> bytes:
"""Build a DOCX with a paragraph and an embedded PNG image."""
from docx import Document as DocxDocument
@@ -2676,3 +2785,111 @@ class WordParserTest(IsolatedAsyncioTestCase):
"""Unknown ``table_format`` raises :class:`ValueError`."""
with self.assertRaises(ValueError):
WordParser(table_format="csv") # type: ignore[arg-type]
+
+
+class WordParserParagraphTest(IsolatedAsyncioTestCase):
+ """Regression coverage for paragraph and text-box extraction."""
+
+ async def test_text_boxes_are_separate_and_read_once(self) -> None:
+ """Read modern text boxes once, with or without a VML fallback."""
+ for name, template in (
+ ("modern", _DOCX_MODERN_TEXT_BOX),
+ ("with_fallback", _DOCX_TEXT_BOX_WITH_VML_FALLBACK),
+ ):
+ with self.subTest(shape=name):
+ sections = await WordParser(include_image=False).parse(
+ _make_docx_with_text_box(template),
+ "demo.docx",
+ )
+ self.assertEqual(
+ [section.model_dump() for section in sections],
+ _expected_word_sections("Paragraph text\nCallout\nAfter"),
+ )
+
+ async def test_text_box_fallback_is_used_without_readable_choice(
+ self,
+ ) -> None:
+ """Keep fallback text when Choice has no readable Word text."""
+ for choice_xml in ("", "<w:t/>", "<w:t> </w:t>"):
+ with self.subTest(choice_xml=choice_xml):
+ template = _DOCX_TEXT_BOX_WITH_VML_FALLBACK.replace(
+ "<w:t>{inside}</w:t>",
+ choice_xml,
+ 1,
+ )
+ sections = await WordParser(include_image=False).parse(
+ _make_docx_with_text_box(template),
+ "demo.docx",
+ )
+ self.assertEqual(
+ [section.model_dump() for section in sections],
+ _expected_word_sections("Paragraph text\nCallout\nAfter"),
+ )
+
+ async def test_distinct_text_boxes_with_identical_text_are_kept(
+ self,
+ ) -> None:
+ """Deduplicate alternate representations, not equal text boxes."""
+ sections = await WordParser(include_image=False).parse(
+ _make_docx_with_text_box(
+ _DOCX_TEXT_BOX_WITH_VML_FALLBACK,
+ text_box_count=2,
+ ),
+ "demo.docx",
+ )
+ self.assertEqual(
+ [section.model_dump() for section in sections],
+ _expected_word_sections("Paragraph text\nCallout\nCallout\nAfter"),
+ )
+
+ async def test_paragraph_with_only_nonbreaking_hyphens_is_kept(
+ self,
+ ) -> None:
+ """The paragraph text fallback preserves non-w:t characters."""
+ from docx import Document as DocxDocument
+ from docx.oxml import OxmlElement
+
+ document = DocxDocument()
+ document.add_paragraph("Before")
+ run = document.add_paragraph().add_run()
+ for _ in range(3):
+ # pylint: disable-next=protected-access
+ run._r.append(OxmlElement("w:noBreakHyphen"))
+ document.add_paragraph("After")
+ buffer = io.BytesIO()
+ document.save(buffer)
+ sections = await WordParser(include_image=False).parse(
+ buffer.getvalue(),
+ "demo.docx",
+ )
+ self.assertEqual(
+ [section.model_dump() for section in sections],
+ _expected_word_sections("Before\n---\nAfter"),
+ )
+
+ async def test_non_textbox_alternatives_are_unchanged(self) -> None:
+ """Branch selection must not affect content outside text boxes."""
+ from docx import Document as DocxDocument
+ from docx.oxml import parse_xml
+
+ document = DocxDocument()
+ document.element.body.insert(
+ 0,
+ parse_xml(
+ f"<w:p {_DOCX_TEXT_BOX_NS}><w:r><mc:AlternateContent>"
+ '<mc:Choice Requires="wps"><w:t>Choice</w:t></mc:Choice>'
+ "<mc:Fallback><w:t>Fallback</w:t></mc:Fallback>"
+ "</mc:AlternateContent></w:r></w:p>",
+ ),
+ )
+ document.add_paragraph("After")
+ buffer = io.BytesIO()
+ document.save(buffer)
+ sections = await WordParser(include_image=False).parse(
+ buffer.getvalue(),
+ "demo.docx",
+ )
+ self.assertEqual(
+ [section.model_dump() for section in sections],
+ _expected_word_sections("ChoiceFallback\nAfter"),
+ )