Build and run agents you can see, understand and trust.
Python agentchatbotlarge-language-modelsllmllm-agentmcpmulti-agentmulti-modalreact-agentrealtime-agentvoice-agentvoice-assistant
feat(rag): add Word file parser for the RAG module (#2025)
qbc811425c01b32
diff --git a/README.md b/README.mdindex 70c0521c2..5c721dc09 100644--- a/README.md+++ b/README.md@@ -73,6 +73,7 @@ rather than constraining them with strict prompts and opinionated orchestrations## News<!-- BEGIN NEWS -->+- **[2026-07] `INTE`:** K8s, OpenSandbox-based workspace/sandbox supported. [Docs](https://docs.agentscope.io/latest/en/building-blocks/workspace)- **[2026-07] `INTE`:** ReMe long-term memory supported. [Example](https://github.com/agentscope-ai/agentscope/tree/main/examples/long_term_memory/reme) | [Docs](https://docs.agentscope.io/latest/en/building-blocks/long-term-memory)- **[2026-06] `FEAT`:** Agentic Memory supported. [Example](https://github.com/agentscope-ai/agentscope/tree/main/examples/long_term_memory/agentic_memory) | [Docs](https://docs.agentscope.io/latest/en/building-blocks/long-term-memory)- **[2026-06] `FEAT`:** Distributed & Multi-Tenancy & Multi-Session RAG service supported. [Docs](https://docs.agentscope.io/latest/en/deploy/agent-team)diff --git a/README_zh.md b/README_zh.mdindex 766e51464..081cac7d8 100644--- a/README_zh.md+++ b/README_zh.md@@ -79,6 +79,7 @@ AgentScope 2.0 是一款面向生产、易于使用的智能体框架,提供## 新闻<!-- BEGIN NEWS -->+- **[2026-07] `集成`:** 集成 K8s,OpenSandbox 工作区/沙箱实现。 [文档](https://docs.agentscope.io/latest/en/building-blocks/workspace)- **[2026-07] `集成`:** 集成 ReMe 长期记忆。 [样例](https://github.com/agentscope-ai/agentscope/tree/main/examples/long_term_memory/reme) | [文档](https://docs.agentscope.io/latest/zh/building-blocks/long-term-memory)- **[2026-06] `功能`:** 支持 Agentic Memory。 [样例](https://github.com/agentscope-ai/agentscope/tree/main/examples/long_term_memory/agentic_memory) | [文档](https://docs.agentscope.io/latest/zh/building-blocks/long-term-memory)- **[2026-06] `功能`:** 支持分布式 & 多租户 & 多会话 RAG 服务。 [文档](https://docs.agentscope.io/latest/en/deploy/agent-team)diff --git a/pyproject.toml b/pyproject.tomlindex e2c3f7ad8..744e971e2 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -84,6 +84,7 @@ rag = ["qdrant-client","pypdf","python-pptx",+ "python-docx","openpyxl>=3.1.5","xlrd>=2.0","pandas",diff --git a/src/agentscope/rag/__init__.py b/src/agentscope/rag/__init__.pyindex 96cc9fdb0..659c073ab 100644--- a/src/agentscope/rag/__init__.py+++ b/src/agentscope/rag/__init__.py@@ -12,6 +12,7 @@ from ._parser import (PDFParser,PPTParser,TextParser,+ WordParser,ExcelParser,)from ._vdb import (@@ -36,6 +37,7 @@ __all__ = ["PDFParser","PPTParser","TextParser",+ "WordParser","ExcelParser","Section","VectorStoreBase",diff --git a/src/agentscope/rag/_parser/__init__.py b/src/agentscope/rag/_parser/__init__.pyindex 3a310b6a2..f461b0470 100644--- a/src/agentscope/rag/_parser/__init__.py+++ b/src/agentscope/rag/_parser/__init__.py@@ -6,6 +6,7 @@ from ._image import ImageParserfrom ._pdf import PDFParserfrom ._ppt import PPTParserfrom ._text import TextParser+from ._word import WordParserfrom ._excel import ExcelParser__all__ = [@@ -14,5 +15,6 @@ __all__ = ["PPTParser","ImageParser","TextParser",+ "WordParser","ExcelParser",]diff --git a/src/agentscope/rag/_parser/_word.py b/src/agentscope/rag/_parser/_word.pynew file mode 100644index 000000000..c230caff8--- /dev/null+++ b/src/agentscope/rag/_parser/_word.py@@ -0,0 +1,341 @@+# -*- coding: utf-8 -*-+# pylint: disable=protected-access+"""Word (.docx) file parser.++Walks the document element-by-element and emits one :class:`Section`+per contiguous content block — adjacent paragraphs (and, by default,+tables) are merged into a single text section; embedded images are+emitted as their own :class:`DataBlock` sections.++Supported options: ``include_image``, ``separate_table``,+``table_format``. Chunking is **not** done here — long text stays+intact inside a section and is split downstream by a+:class:`~agentscope.rag.ChunkerBase`.+"""+from __future__ import annotations++import base64+import io+from typing import Literal, TYPE_CHECKING++from ..._logging import logger+from ...message import Base64Source, DataBlock, TextBlock+from .._document import Section+from ._base import ParserBase+from ._utils import (+ _guess_image_media_type,+ _table_to_json,+ _table_to_markdown,+)++if TYPE_CHECKING:+ from docx.table import Table as DocxTable+ from docx.text.paragraph import Paragraph as DocxParagraph++_VML_NS = "{urn:schemas-microsoft-com:vml}"+++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.+ """+ 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()+++def _extract_table_data(table: DocxTable) -> list[list[str]]:+ """Extract table data from a python-docx Table, preserving line breaks+ within cells.++ Horizontal merges (``w:gridSpan``) are expanded with empty strings so+ that every row has the same number of columns. Vertically merged+ continuation cells (``w:vMerge`` without ``val="restart"``) are kept+ as-is — their XML content is typically empty, which is the desired+ behaviour for downstream renderers.+ """+ from docx.oxml.ns import qn++ table_data: list[list[str]] = []+ for tr in table._element.findall(qn("w:tr")):+ row_data: list[str] = []+ for tc in tr.findall(qn("w:tc")):+ paragraphs: list[str] = []+ for p_elem in tc.findall(qn("w:p")):+ texts: list[str] = []+ for t_elem in p_elem.findall(".//" + qn("w:t")):+ if t_elem.text:+ texts.append(t_elem.text)+ para_text = "".join(texts)+ if para_text:+ paragraphs.append(para_text)+ row_data.append("\n".join(paragraphs))++ tc_pr = tc.find(qn("w:tcPr"))+ if tc_pr is not None:+ gs = tc_pr.find(qn("w:gridSpan"))+ if gs is not None:+ span = int(+ gs.get(qn("w:val"), gs.get("val", "1")),+ )+ row_data.extend([""] * (span - 1))++ table_data.append(row_data)+ return table_data+++def _extract_image_blocks(+ para: DocxParagraph,+ filename: str,+) -> list[DataBlock]:+ """Extract image blocks from a paragraph (both modern ``w:drawing``+ and legacy ``w:pict`` / VML formats)."""+ from docx.oxml.ns import qn++ blocks: list[DataBlock] = []++ for drawing in para._element.findall(".//" + qn("w:drawing")):+ for blip in drawing.findall(".//" + qn("a:blip")):+ embed = blip.get(qn("r:embed"))+ if not embed:+ continue+ try:+ part = para.part.related_parts[embed]+ media_type = part.content_type or _guess_image_media_type(+ part.blob,+ )+ blocks.append(+ DataBlock(+ source=Base64Source(+ media_type=media_type,+ data=base64.b64encode(part.blob).decode("utf-8"),+ ),+ name=filename,+ ),+ )+ except Exception as e:+ logger.warning("Failed to extract image: %s", e)++ for pict in para._element.findall(".//" + qn("w:pict")):+ for imagedata in pict.findall(".//" + _VML_NS + "imagedata"):+ rel_id = imagedata.get(qn("r:id"))+ if not rel_id:+ continue+ try:+ part = para.part.related_parts[rel_id]+ media_type = part.content_type or _guess_image_media_type(+ part.blob,+ )+ blocks.append(+ DataBlock(+ source=Base64Source(+ media_type=media_type,+ data=base64.b64encode(part.blob).decode("utf-8"),+ ),+ name=filename,+ ),+ )+ except Exception as e:+ logger.warning("Failed to extract VML image: %s", e)++ return blocks+++class WordParser(ParserBase):+ """Parser for Word ``.docx`` files.++ Document order is preserved. Elements are visited sequentially and+ grouped into a minimum number of sections:++ - **Paragraphs** contribute to one running text section.+ - **Tables** are rendered as Markdown or JSON and, depending on+ ``separate_table``, either merged into the running text or emitted+ as standalone text sections.+ - **Images** emit standalone :class:`Section` instances holding a+ :class:`DataBlock` with the base64-encoded image bytes.+ """++ supported_media_types: list[str] = [+ "application/vnd.openxmlformats-officedocument.wordprocessingml"+ ".document",+ ]++ @classmethod+ def supported_extensions(cls) -> list[str]:+ """Return ``[".docx"]`` — the only format ``python-docx`` reads."""+ return [".docx"]++ def __init__(+ self,+ include_image: bool = True,+ separate_table: bool = False,+ table_format: Literal["markdown", "json"] = "markdown",+ ) -> None:+ """Initialize the Word parser.++ Args:+ include_image (`bool`, defaults to ``True``):+ When ``True``, embedded images are emitted as+ :class:`DataBlock` sections. Set to ``False`` to keep+ a text-only index.+ separate_table (`bool`, defaults to ``False``):+ When ``True``, each table becomes its own text section,+ never merged with surrounding paragraphs.+ table_format (`Literal["markdown", "json"]`, defaults to+ ``"markdown"``):+ How to render tables. ``"markdown"`` uses pipe-table+ syntax; ``"json"`` emits a JSON array prefixed with a+ ``<system-info>`` marker.++ Raises:+ `ValueError`: If ``table_format`` is not one of+ ``"markdown"`` / ``"json"``.+ """+ if table_format not in ("markdown", "json"):+ raise ValueError(+ "The table_format must be one of 'markdown' or 'json', "+ f"got {table_format!r}.",+ )+ self.include_image = include_image+ self.separate_table = separate_table+ self.table_format = table_format++ async def parse(+ self,+ file: bytes | str,+ filename: str,+ ) -> list[Section]:+ """Parse a DOCX file into a list of :class:`Section` objects.++ Args:+ file (`bytes | str`):+ Either the raw DOCX bytes, or a filesystem path to the+ DOCX file.+ filename (`str`):+ The source filename, copied into each Section's+ :attr:`Section.source`.++ Returns:+ `list[Section]`:+ Sections in document order.++ Raises:+ `FileNotFoundError`: If ``file`` is a ``str`` pointing to+ a path that does not exist.+ `ImportError`: If :mod:`python-docx` is not installed.+ `ValueError`: If the bytes cannot be parsed.+ """+ try:+ from docx import Document as DocxDocument+ from docx.oxml import CT_P, CT_Tbl+ from docx.text.paragraph import Paragraph+ from docx.table import Table+ from docx.oxml.ns import qn+ except ImportError as e:+ raise ImportError(+ "Please install python-docx to use the Word parser. "+ "You can install it by `pip install python-docx` (or "+ "`pip install agentscope[rag]`).",+ ) from e++ if isinstance(file, str):+ doc = DocxDocument(file)+ else:+ doc = DocxDocument(io.BytesIO(file))++ sections: list[Section] = []+ text_buffer: list[str] = []++ def flush_text() -> None:+ if not text_buffer:+ return+ sections.append(+ Section(+ content=TextBlock(text="\n".join(text_buffer)),+ source=filename,+ metadata={},+ ),+ )+ text_buffer.clear()++ for element in doc.element.body:+ if isinstance(element, CT_P):+ para = Paragraph(element, doc)++ text = _extract_text_from_paragraph(para)+ if text:+ text_buffer.append(text)++ if self.include_image:+ has_drawing = bool(+ para._element.findall(".//" + qn("w:drawing")),+ )+ has_pict = bool(+ para._element.findall(".//" + qn("w:pict")),+ )+ if has_drawing or has_pict:+ flush_text()+ for block in _extract_image_blocks(para, filename):+ sections.append(+ Section(+ content=block,+ source=filename,+ metadata={+ "media_type": (+ block.source.media_type+ ),+ },+ ),+ )++ elif isinstance(element, CT_Tbl):+ table_data = _extract_table_data(Table(element, doc))+ rendered = (+ _table_to_markdown(table_data)+ if self.table_format == "markdown"+ else _table_to_json(table_data)+ )+ if not rendered:+ continue++ if self.separate_table:+ flush_text()+ sections.append(+ Section(+ content=TextBlock(text=rendered),+ source=filename,+ metadata={},+ ),+ )+ else:+ text_buffer.append(rendered)++ flush_text()+ return sectionsdiff --git a/tests/rag_parser_test.py b/tests/rag_parser_test.pyindex de0b8686f..2a2232fe4 100644--- a/tests/rag_parser_test.py+++ b/tests/rag_parser_test.py@@ -17,6 +17,7 @@ from agentscope.rag import (PDFParser,PPTParser,TextParser,+ WordParser,ExcelParser,)@@ -110,6 +111,54 @@ def _make_pptx_rich() -> bytes:return buffer.getvalue()+def _make_docx_simple(paragraphs: list[str]) -> bytes:+ """Build a DOCX in memory with plain text paragraphs."""+ from docx import Document as DocxDocument++ doc = DocxDocument()+ for text in paragraphs:+ doc.add_paragraph(text)+ buffer = io.BytesIO()+ doc.save(buffer)+ return buffer.getvalue()+++def _make_docx_with_table() -> bytes:+ """Build a DOCX with a paragraph, a 2x2 table, and a trailing+ paragraph."""+ from docx import Document as DocxDocument++ doc = DocxDocument()+ doc.add_paragraph("Before table")++ table = doc.add_table(rows=2, cols=2)+ table.cell(0, 0).text = "A"+ table.cell(0, 1).text = "B"+ table.cell(1, 0).text = "1"+ table.cell(1, 1).text = "2"++ doc.add_paragraph("After table")++ buffer = io.BytesIO()+ doc.save(buffer)+ return buffer.getvalue()+++def _make_docx_with_image() -> bytes:+ """Build a DOCX with a paragraph and an embedded PNG image."""+ from docx import Document as DocxDocument+ from docx.shared import Inches++ doc = DocxDocument()+ doc.add_paragraph("Text before image")+ doc.add_picture(io.BytesIO(_PNG_PIXEL), width=Inches(1))+ doc.add_paragraph("Text after image")++ buffer = io.BytesIO()+ doc.save(buffer)+ return buffer.getvalue()++def _make_xlsx_simple(sheets: dict[str, list[list[str]]],) -> bytes:@@ -940,3 +989,206 @@ class ExcelParserTest(IsolatedAsyncioTestCase):"""Unknown ``table_format`` raises :class:`ValueError`."""with self.assertRaises(ValueError):ExcelParser(table_format="csv") # type: ignore[arg-type]+++class WordParserTest(IsolatedAsyncioTestCase):+ """Behavioural coverage for :class:`WordParser`."""++ async def test_simple_paragraphs(self) -> None:+ """Plain paragraphs are merged into a single text Section."""+ docx_bytes = _make_docx_simple(["Hello", "World"])+ parser = WordParser(include_image=False)+ sections = await parser.parse(docx_bytes, "demo.docx")++ self.assertEqual(+ [s.model_dump() for s in sections],+ [+ {+ "content": {+ "type": "text",+ "text": "Hello\nWorld",+ "id": AnyString(),+ },+ "source": "demo.docx",+ "metadata": {},+ },+ ],+ )++ async def test_table_merges_by_default(self) -> None:+ """``separate_table=False`` merges the table into surrounding+ text."""+ docx_bytes = _make_docx_with_table()+ parser = WordParser(include_image=False, separate_table=False)+ sections = await parser.parse(docx_bytes, "demo.docx")++ self.assertEqual(+ [s.model_dump() for s in sections],+ [+ {+ "content": {+ "type": "text",+ "text": (+ "Before table\n"+ "| A | B |\n"+ "| --- | --- |\n"+ "| 1 | 2 |\n\n"+ "After table"+ ),+ "id": AnyString(),+ },+ "source": "demo.docx",+ "metadata": {},+ },+ ],+ )++ async def test_table_separated(self) -> None:+ """``separate_table=True`` isolates the table from surrounding+ paragraphs."""+ docx_bytes = _make_docx_with_table()+ parser = WordParser(include_image=False, separate_table=True)+ sections = await parser.parse(docx_bytes, "demo.docx")++ self.assertEqual(+ [s.model_dump() for s in sections],+ [+ {+ "content": {+ "type": "text",+ "text": "Before table",+ "id": AnyString(),+ },+ "source": "demo.docx",+ "metadata": {},+ },+ {+ "content": {+ "type": "text",+ "text": (+ "| A | B |\n" "| --- | --- |\n" "| 1 | 2 |\n"+ ),+ "id": AnyString(),+ },+ "source": "demo.docx",+ "metadata": {},+ },+ {+ "content": {+ "type": "text",+ "text": "After table",+ "id": AnyString(),+ },+ "source": "demo.docx",+ "metadata": {},+ },+ ],+ )++ async def test_table_json_format(self) -> None:+ """``table_format="json"`` emits JSON instead of Markdown."""+ docx_bytes = _make_docx_with_table()+ parser = WordParser(+ include_image=False,+ separate_table=True,+ table_format="json",+ )+ sections = await parser.parse(docx_bytes, "demo.docx")++ self.assertEqual(+ [s.model_dump() for s in sections],+ [+ {+ "content": {+ "type": "text",+ "text": "Before table",+ "id": AnyString(),+ },+ "source": "demo.docx",+ "metadata": {},+ },+ {+ "content": {+ "type": "text",+ "text": (+ "<system-info>A table loaded as a JSON "+ "array:</system-info>\n"+ '[["A", "B"], ["1", "2"]]'+ ),+ "id": AnyString(),+ },+ "source": "demo.docx",+ "metadata": {},+ },+ {+ "content": {+ "type": "text",+ "text": "After table",+ "id": AnyString(),+ },+ "source": "demo.docx",+ "metadata": {},+ },+ ],+ )++ async def test_image_emits_data_block(self) -> None:+ """Embedded images become DataBlock sections."""+ docx_bytes = _make_docx_with_image()+ parser = WordParser(include_image=True)+ sections = await parser.parse(docx_bytes, "rich.docx")++ data_sections = [s for s in sections if s.content.type == "data"]+ self.assertGreaterEqual(len(data_sections), 1)+ ds = data_sections[0]+ self.assertEqual(ds.source, "rich.docx")+ self.assertEqual(ds.content.name, "rich.docx")+ self.assertIn("media_type", ds.metadata)++ async def test_image_excluded_when_disabled(self) -> None:+ """``include_image=False`` keeps only text sections."""+ docx_bytes = _make_docx_with_image()+ parser = WordParser(include_image=False)+ sections = await parser.parse(docx_bytes, "rich.docx")++ self.assertEqual(+ [s.model_dump() for s in sections],+ [+ {+ "content": {+ "type": "text",+ "text": "Text before image\nText after image",+ "id": AnyString(),+ },+ "source": "rich.docx",+ "metadata": {},+ },+ ],+ )++ async def test_string_input_treated_as_path(self) -> None:+ """``str`` is interpreted as a filesystem path to the DOCX."""+ import tempfile++ docx_bytes = _make_docx_simple(["Alpha"])+ with tempfile.NamedTemporaryFile(+ suffix=".docx",+ delete=False,+ ) as f:+ f.write(docx_bytes)+ path = f.name+ try:+ parser = WordParser(include_image=False)+ sections = await parser.parse(path, "demo.docx")+ self.assertEqual(len(sections), 1)+ finally:+ os.unlink(path)++ async def test_supported_extensions(self) -> None:+ """``.docx`` is the only extension."""+ self.assertEqual(WordParser.supported_extensions(), [".docx"])++ async def test_table_format_validation(self) -> None:+ """Unknown ``table_format`` raises :class:`ValueError`."""+ with self.assertRaises(ValueError):+ WordParser(table_format="csv") # type: ignore[arg-type]