xorbitsai/xagent/docx-report-editorial

Editorial Report (.docx)

You will generate one .docx file via python-docx by writing a Python program and running it through the execute_python_code tool. The blocks below are parts of that one program, not separate runs -- later ones use the doc, palette and helpers the earlier ones define, so assemble them into a single script before executing. Save to the workspace, then report the path + a 1-line content summary.

📦 Required runtime packages

The sandboxed execute_python_code ships with pandas, numpy, matplotlib, openpyxl, and `python-docx>=1.1.0` preinstalled — no extra installation step is needed. The import name is `docx`, not python_docx:

from docx import Document          # ✅ correct
import python_docx                 # ❌ ModuleNotFoundError

Note: execute_python_code accepts only code and

capture_output arguments; there is no packages parameter.

All required libraries are already available in the sandbox image.

💾 Saving and reporting the file

execute_python_code runs with the task's output directory as the working directory, so save with a plain filename — no /workspace, no nested output/, no BytesIO round-trip:

doc.save("market_expansion_report.docx")

Then verify content, not size: an empty Document() is already ~36 KB, so a byte threshold proves nothing. Re-open and check what you wrote.

from docx import Document
check = Document("market_expansion_report.docx")
# Cell text is not in check.paragraphs, so a table-only document would
# otherwise look empty and you would report a failure that did not happen.
has_text = any(p.text.strip() for p in check.paragraphs) or any(
    cell.text.strip()
    for tbl in check.tables
    for row in tbl.rows
    for cell in row.cells
)
assert has_text, "document has no text"

Assert the shape the request asked for, never a fixed minimum — a multi-section report can also check its tables and headings, but a one-page memo has neither, and padding one to clear a threshold breaks rule 5.

🔗 Make it clickable — REQUIRED

The executor response carries a markdown_link for each file it wrote (in file_refs[]). Use that string verbatim as the first line of your answer, as bare markdown:

market_expansion_report.docx

Never fabricate the UUID, never wrap the link in backticks (it stops rendering as a chip), and never restate it as a file_id: field. get_file_info() does not return one — the reference is already on the executor result.

⚠️ Hard rules — NO exceptions

1. MATCH THE USER'S LANGUAGE. If the prompt is Chinese (中文), ALL

document text (cover kicker, headings, body, table headers, captions, footer) must be in Chinese. Translate template phrases like EXECUTIVE SUMMARY → 摘要, FINDINGS → 调查结果, RECOMMENDATIONS → 建议, As of YYYY-MM-DD → 截至 YYYY-MM-DD. Never leave English kickers in a Chinese report.

1. One palette only. Pick one of the 5 palettes below; use only its

4 hex values (ink, paper, paper_tint, ink_tint). Define a palette = {...} dict ONCE at the top of the script and reference palette["ink"] etc. everywhere — do not copy literal hex values into individual styling calls.

1. Two fonts only. Headings = Georgia (serif, present on all OSes).

Body = Calibri (sans, Word default). No custom fonts — recipients won't have them and Word falls back to Times. For Chinese documents: both render Chinese via system fallback (PingFang on macOS, Microsoft YaHei on Windows) — do not switch fonts.

1. Use real Word styles, not manual formatting. Headings must use the

built-in Heading 1 / Heading 2 / Heading 3 styles so Word's navigation pane and auto table-of-contents work. A document where every heading is just bold 18pt body text is broken — it has no outline.

1. Forbidden:

• WordArt, drop shadows, glow, 3-D effects, gradient fills
• clipart, emoji as decoration, stock-photo placeholders
• centered body paragraphs (left-align / justify only)
• all-caps body text (kickers and labels only)
• Comic Sans, Arial Black, Times New Roman as a deliberate choice

1. Real content only. No lorem ipsum, no [Title here] placeholders,

no fabricated statistics, no fake citations. If a section has no user data, drop the section rather than padding it.

1. Failure honesty — NEVER fake the deliverable.

• If execute_python_code raises after multiple retries, STOP and report

the actual error. Do not write a stub file like write_file("report.docx", "placeholder") to make the chip appear.

• The final answer must reflect what was actually written. Do not

describe sections or tables that aren't in the saved .docx.

🎨 Palettes — pick ONE

Same palettes as pdf-report-editorial and pptx-editorial — keep the editorial family visually consistent. Each: ink (body text + rules), paper (text on an ink band), paper_tint (table band + callout bg), ink_tint (kickers, captions, footer). The keys are underscored — the dict below is what every snippet indexes into.

• Monocle (default / business / tech / policy)

ink 0A0A0B · paper F1EFEA · paper_tint E8E5DE · ink_tint 18181A

• Indigo Porcelain (research / data-heavy)

ink 0A1F3D · paper F1F3F5 · paper_tint E4E8EC · ink_tint 152A4A

• Forest Ink (sustainability / impact)

ink 1A2E1F · paper F5F1E8 · paper_tint ECE7DA · ink_tint 253D2C

• Kraft Paper (humanities / qualitative)

ink 2A1E13 · paper EEDFC7 · paper_tint E0D0B6 · ink_tint 3A2A1D

• Dune (art / design / fashion criticism)

ink 1F1A14 · paper F0E6D2 · paper_tint E3D7BF · ink_tint 2D2620

Define it once at the top of the script, then index it everywhere:

palette = {"ink": "0A0A0B", "paper": "F1EFEA",
           "paper_tint": "E8E5DE", "ink_tint": "18181A"}   # Monocle

python-docx takes hex without the # prefix, via RGBColor.from_string(palette["ink"]).

✒️ Typography (python-docx Pt sizes)

📐 Page setup

Set margins, size and orientation on each section before adding content.

from docx import Document
from docx.shared import Pt, Cm, RGBColor
from docx.enum.section import WD_ORIENT
doc = Document()
sec = doc.sections[0]
# A4 portrait with editorial margins
sec.page_width, sec.page_height = Cm(21.0), Cm(29.7)
sec.orientation = WD_ORIENT.PORTRAIT
sec.top_margin, sec.bottom_margin = Cm(2.5), Cm(2.5)
sec.left_margin, sec.right_margin = Cm(2.2), Cm(2.2)

⚠️ Orientation gotcha: setting sec.orientation = WD_ORIENT.LANDSCAPE does NOT swap the page dimensions — Word reads the width/height, not the flag. You must swap them yourself:

sec.orientation = WD_ORIENT.LANDSCAPE
sec.page_width, sec.page_height = Cm(29.7), Cm(21.0)   # swap explicitly

Set the default body font once on the Normal style so every paragraph inherits it:

from docx.shared import Pt, RGBColor
normal = doc.styles["Normal"]
normal.font.name = "Calibri"
normal.font.size = Pt(11)
normal.font.color.rgb = RGBColor.from_string(palette["ink"])
normal.paragraph_format.line_spacing = 1.4
normal.paragraph_format.space_after = Pt(8)

Do not pin w:eastAsia to a named CJK face. Rule 2 is that Chinese renders through each platform's own fallback — writing Microsoft YaHei into the style hard-codes a font that is absent on macOS and Linux, which is the substitution the rule exists to prevent. Leaving the attribute unset is what lets Word pick PingFang, YaHei or Noto per platform.

🏛️ Cover page pattern

The cover is its own section, so the body starts on a fresh page and can later be given its own header, footer or page numbering without touching the cover. Structure: kicker → title → dek → meta row.

from docx.oxml.ns import qn
from docx.shared import Pt, RGBColor
def strip_style_border(doc, style_name):
    """Drop a built-in style's decorative border.
    The border lives on the *style*, not on paragraphs using it, so clearing
    a paragraph's own pPr does nothing -- it never had one. Title and Intense
    Quote both ship an accent-blue w:pBdr that is in none of the palettes.
    """
    style_pPr = doc.styles[style_name].element.get_or_add_pPr()
    for bdr in style_pPr.findall(qn("w:pBdr")):
        style_pPr.remove(bdr)
def add_kicker(doc, text):
    p = doc.add_paragraph()
    run = p.add_run(text.upper())
    run.font.name, run.font.size, run.font.bold = "Calibri", Pt(9), True
    run.font.color.rgb = RGBColor.from_string(palette["ink_tint"])
    return p
# --- cover ---
doc.add_paragraph().paragraph_format.space_after = Pt(160)  # vertical push
add_kicker(doc, "Research Brief")
# Title and Intense Quote ship an accent-blue border, and Intense Quote and
# Caption default to bold. None of that is in the palette. Clearing the border
# once on the style covers every paragraph that uses it.
strip_style_border(doc, "Title")
strip_style_border(doc, "Intense Quote")
title = doc.add_paragraph(style="Title")
title_run = title.add_run("Agent Infrastructure in 2026")
title_run.font.name, title_run.font.size = "Georgia", Pt(40)
title_run.font.color.rgb = RGBColor.from_string(palette["ink"])
dek = doc.add_paragraph()
dek_run = dek.add_run("Market shape, adoption curves, and the shift to "
                      "production-grade systems.")
dek_run.font.name, dek_run.font.size, dek_run.font.italic = "Calibri", Pt(14), True
meta = doc.add_paragraph()
meta_run = meta.add_run("Xagent Team · 2026-05-14")   # middle dot, not hyphen
meta_run.font.size = Pt(10)
meta_run.font.color.rgb = RGBColor.from_string(palette["ink_tint"])
# A new section, not just a page break: the body gets its own section
# properties, so a header, footer or page numbering added later applies to
# it without touching the cover.
from docx.enum.section import WD_SECTION
doc.add_section(WD_SECTION.NEW_PAGE)

🔠 Heading hierarchy

Always use the built-in styles, then restyle the style object once — not each heading individually:

from docx.oxml.ns import qn
from docx.shared import Pt, RGBColor
def use_font(style, family):
    """Set a style's font and drop the template's theme fonts.
    `.font.name` only adds w:ascii/w:hAnsi. The default headings also carry
    w:asciiTheme="majorHAnsi" etc., and Word prefers the theme attributes --
    so without this the headings stay in the template font, not Georgia.
    """
    style.font.name = family
    rpr = style.element.get_or_add_rPr()
    rfonts = rpr.get_or_add_rFonts()
    for theme in ("asciiTheme", "hAnsiTheme", "eastAsiaTheme", "cstheme"):
        rfonts.attrib.pop(qn(f"w:{theme}"), None)
for name, family, size in (("Heading 1", "Georgia", 22),
                           ("Heading 2", "Georgia", 16),
                           ("Heading 3", "Calibri", 12)):
    st = doc.styles[name]
    use_font(st, family)
    st.font.size = Pt(size)
    st.font.color.rgb = RGBColor.from_string(palette["ink"])
    st.font.bold = (name == "Heading 3")
    st.paragraph_format.space_before = Pt(18)
    st.paragraph_format.space_after = Pt(6)