Skip to content

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

feat(rag): add Word file parser for the RAG module (#2025)

qbc811425c01b32
diff --git a/README.md b/README.md
index 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.md
index 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.toml
index 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__.py
index 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__.py
index 3a310b6a2..f461b0470 100644
--- a/src/agentscope/rag/_parser/__init__.py
+++ b/src/agentscope/rag/_parser/__init__.py
@@ -6,6 +6,7 @@ from ._image import ImageParser
from ._pdf import PDFParser
from ._ppt import PPTParser
from ._text import TextParser
+from ._word import WordParser
from ._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.py
new file mode 100644
index 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 sections
diff --git a/tests/rag_parser_test.py b/tests/rag_parser_test.py
index 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]