ite-agent 0.0.23__tar.gz

ite_agent-0.0.23/.agents/skills/docx/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: docx
+description: Create, inspect, edit, and validate Microsoft Word .docx documents. Use for reading .docx content, generating reports, memos, or letters as Word files, editing existing documents, and converting Word documents into structured text or a new polished .docx.
+tags:
+  - office
+  - documents
+  - word
+author: ite
+argument-hint: "[INPUT=<path>] [OUTPUT=<path>]"
+---
+
+# DOCX workflow
+
+Use this skill whenever the user is working with a `.docx` file or explicitly wants a Word document as output.
+
+## Core rules
+
+- Do not use `read_file` directly on `.docx`; it is a packaged binary file.
+- Resolve all script paths relative to this skill directory.
+- Prefer a workspace-local scratch directory such as `./.ite/tmp/docx/<job-id>/` over `/tmp/`.
+- Keep the source document intact unless the user explicitly asks to overwrite it.
+- Validate any newly created or repacked `.docx` before presenting it as finished.
+- If LibreOffice and Poppler are available, render pages for visual review before final delivery.
+
+## Default workflows
+
+### Inspect or extract text
+
+Inspect first when the goal is to understand the file quickly:
+
+```bash
+python <skill_dir>/scripts/inspect_docx.py input.docx
+```
+
+Then use the extractor when you need readable content:
+
+```bash
+python <skill_dir>/scripts/extract_docx.py input.docx --format markdown --output extracted.md
+```
+
+Use `--format text` for a plain transcript or `--format json` for machine-readable sections.
+
+### Unpack for structured editing
+
+```bash
+python <skill_dir>/scripts/unpack_docx.py input.docx ./.ite/tmp/docx/job-123/unpacked
+```
+
+Edit the unpacked XML only when a simple text replacement is not enough.
+
+### Simple text replacement
+
+For straightforward content changes inside `word/document.xml`, use:
+
+```bash
+python <skill_dir>/scripts/replace_text.py input.docx output.docx --replace "Old text" "New text"
+```
+
+This is for direct text substitutions, not layout-heavy edits.
+
+### Create a new document
+
+For letters, memos, and simple reports, start from a markdown or text draft:
+
+```bash
+python <skill_dir>/scripts/write_docx.py draft.md output.docx --title "Quarterly Update"
+```
+
+Templates in `templates/` are starter content, not strict requirements.
+
+```bash
+python <skill_dir>/scripts/write_docx.py output.docx --template memo --title "Quarterly Update"
+```
+
+### Visual review
+
+When layout matters, render the document to page images:
+
+```bash
+python <skill_dir>/scripts/render_docx.py input.docx --output_dir ./.ite/tmp/docx/job-123/rendered
+```
+
+If the required system tools are unavailable, say so clearly and call out layout risk.
+
+### Repack and validate
+
+```bash
+python <skill_dir>/scripts/pack_docx.py ./.ite/tmp/docx/job-123/unpacked output.docx
+python <skill_dir>/scripts/validate_docx.py output.docx
+```
+
+Validation is required before presenting the result as complete.
+
+## Choosing the path
+
+- Need to read or summarize a `.docx`: extract text.
+- Need a polished new `.docx`: write a new document from structured content.
+- Need a small wording change: replace text.
+- Need deeper changes: unpack, edit carefully, repack, validate.
+- Need to check pagination, tables, or spacing: render the pages and inspect them.
+
+## Output expectations
+
+- Tell the user what file was created or updated.
+- Summarize the structural approach used.
+- Mention validation status.
+- If a limitation blocks the requested formatting, say so explicitly instead of silently improvising.

ite_agent-0.0.23/.agents/skills/docx/references/document-recipes.md

@@ -0,0 +1,12 @@
+# DOCX recipes
+
+Use the bundled scripts for these common jobs:
+
+- Inspect a document: `extract_docx.py`
+- Unpack for XML edits: `unpack_docx.py`
+- Repack the edited package: `pack_docx.py`
+- Validate a generated file: `validate_docx.py`
+- Create a simple memo or report from a text draft: `write_docx.py`
+- Apply direct wording swaps: `replace_text.py`
+
+Prefer a workspace-local scratch directory under `./.ite/tmp/docx/` so shell commands remain inside the project sandbox.

ite_agent-0.0.23/.agents/skills/docx/references/ooxml-notes.md

@@ -0,0 +1,10 @@
+# OOXML notes
+
+A `.docx` file is a ZIP package. The most important members for this skill are:
+
+- `[Content_Types].xml`
+- `_rels/.rels`
+- `word/document.xml`
+
+The first-party `ite` docx skill only guarantees safe handling of plain paragraph content in `word/document.xml`.
+If the user needs advanced layout, section, comment, or tracked-change behavior, say that the request exceeds the current bundled workflow and avoid fabricating support.

ite_agent-0.0.23/.agents/skills/docx/scripts/__init__.py

@@ -0,0 +1 @@
+"""Helper scripts for the bundled ite docx skill."""

ite_agent-0.0.23/.agents/skills/docx/scripts/_docx_core.py

@@ -0,0 +1,223 @@
+from __future__ import annotations
+
+from pathlib import Path
+from zipfile import ZIP_DEFLATED
+from zipfile import ZipFile
+import shutil
+import tempfile
+import xml.etree.ElementTree as ET
+import json
+
+W_NS = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
+NS = {"w": W_NS}
+ET.register_namespace("w", W_NS)
+
+REQUIRED_MEMBERS = {
+    "[Content_Types].xml",
+    "_rels/.rels",
+    "word/document.xml",
+}
+
+
+def load_document_tree(docx_path: Path) -> ET.ElementTree:
+    with ZipFile(docx_path) as archive:
+        with archive.open("word/document.xml") as handle:
+            return ET.parse(handle)
+
+
+def write_document_tree(source_docx: Path, output_docx: Path, tree: ET.ElementTree) -> None:
+    with tempfile.TemporaryDirectory(prefix="ite-docx-") as temp_dir:
+        temp_root = Path(temp_dir)
+        unpack_to_directory(source_docx, temp_root)
+        document_path = temp_root / "word" / "document.xml"
+        tree.write(document_path, encoding="utf-8", xml_declaration=True)
+        pack_directory(temp_root, output_docx)
+
+
+def unpack_to_directory(docx_path: Path, output_dir: Path) -> None:
+    output_dir.mkdir(parents=True, exist_ok=True)
+    with ZipFile(docx_path) as archive:
+        archive.extractall(output_dir)
+
+
+def pack_directory(source_dir: Path, output_docx: Path) -> None:
+    output_docx.parent.mkdir(parents=True, exist_ok=True)
+    temp_output = output_docx.with_suffix(output_docx.suffix + ".tmp")
+    if temp_output.exists():
+        temp_output.unlink()
+    with ZipFile(temp_output, "w", compression=ZIP_DEFLATED) as archive:
+        for path in sorted(source_dir.rglob("*")):
+            if path.is_dir():
+                continue
+            archive.write(path, path.relative_to(source_dir).as_posix())
+    shutil.move(str(temp_output), str(output_docx))
+
+
+def paragraph_texts(tree: ET.ElementTree) -> list[str]:
+    paragraphs: list[str] = []
+    for paragraph in tree.findall(".//w:body/w:p", NS):
+        texts = [node.text or "" for node in paragraph.findall(".//w:t", NS)]
+        line = "".join(texts).strip()
+        if line:
+            paragraphs.append(line)
+    return paragraphs
+
+
+def inspect_docx(path: Path) -> dict[str, object]:
+    tree = load_document_tree(path)
+    paragraphs = paragraph_texts(tree)
+    preview = paragraphs[:5]
+    return {
+        "path": str(path.resolve()),
+        "size_bytes": path.stat().st_size,
+        "paragraph_count": len(paragraphs),
+        "preview": preview,
+        "validation_errors": validate_docx(path),
+    }
+
+
+def set_paragraphs(tree: ET.ElementTree, paragraphs: list[str]) -> ET.ElementTree:
+    root = tree.getroot()
+    body = root.find("w:body", NS)
+    if body is None:
+        raise ValueError("word/document.xml does not contain w:body")
+
+    sect_pr = body.find("w:sectPr", NS)
+    for child in list(body):
+        body.remove(child)
+
+    for text in paragraphs:
+        body.append(_paragraph_element(text))
+
+    if sect_pr is not None:
+        body.append(sect_pr)
+    return tree
+
+
+def replace_in_paragraphs(
+    paragraphs: list[str],
+    replacements: list[tuple[str, str]],
+) -> tuple[list[str], int]:
+    updated = list(paragraphs)
+    total_replacements = 0
+    for old, new in replacements:
+        next_paragraphs: list[str] = []
+        for paragraph in updated:
+            occurrences = paragraph.count(old)
+            if occurrences:
+                total_replacements += occurrences
+            next_paragraphs.append(paragraph.replace(old, new))
+        updated = next_paragraphs
+    return updated, total_replacements
+
+
+def json_dump(payload: dict[str, object]) -> str:
+    return json.dumps(payload, indent=2)
+
+
+def build_simple_document(paragraphs: list[str], title: str | None = None) -> bytes:
+    document = ET.Element(f"{{{W_NS}}}document")
+    body = ET.SubElement(document, f"{{{W_NS}}}body")
+    all_paragraphs = list(paragraphs)
+    if title:
+        all_paragraphs.insert(0, title.strip())
+    for paragraph in all_paragraphs:
+        body.append(_paragraph_element(paragraph))
+    sect_pr = ET.SubElement(body, f"{{{W_NS}}}sectPr")
+    pg_sz = ET.SubElement(sect_pr, f"{{{W_NS}}}pgSz")
+    pg_sz.set(f"{{{W_NS}}}w", "12240")
+    pg_sz.set(f"{{{W_NS}}}h", "15840")
+    pg_mar = ET.SubElement(sect_pr, f"{{{W_NS}}}pgMar")
+    for key, value in {
+        "top": "1440",
+        "right": "1440",
+        "bottom": "1440",
+        "left": "1440",
+        "header": "720",
+        "footer": "720",
+        "gutter": "0",
+    }.items():
+        pg_mar.set(f"{{{W_NS}}}{key}", value)
+
+    document_xml = ET.tostring(document, encoding="utf-8", xml_declaration=True)
+    return _package_document_xml(document_xml)
+
+
+def _package_document_xml(document_xml: bytes) -> bytes:
+    with tempfile.TemporaryDirectory(prefix="ite-docx-build-") as temp_dir:
+        root = Path(temp_dir)
+        (root / "_rels").mkdir(parents=True, exist_ok=True)
+        (root / "word").mkdir(parents=True, exist_ok=True)
+        (root / "[Content_Types].xml").write_text(
+            """<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">
+  <Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>
+  <Default Extension="xml" ContentType="application/xml"/>
+  <Override PartName="/word/document.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml"/>
+  <Override PartName="/docProps/core.xml" ContentType="application/vnd.openxmlformats-package.core-properties+xml"/>
+  <Override PartName="/docProps/app.xml" ContentType="application/vnd.openxmlformats-officedocument.extended-properties+xml"/>
+</Types>
+""",
+            encoding="utf-8",
+        )
+        (root / "_rels" / ".rels").write_text(
+            """<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
+  <Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="word/document.xml"/>
+  <Relationship Id="rId2" Type="http://schemas.openxmlformats.org/package/2006/relationships/metadata/core-properties" Target="docProps/core.xml"/>
+  <Relationship Id="rId3" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/extended-properties" Target="docProps/app.xml"/>
+</Relationships>
+""",
+            encoding="utf-8",
+        )
+        (root / "word" / "document.xml").write_bytes(document_xml)
+        (root / "docProps").mkdir(parents=True, exist_ok=True)
+        (root / "docProps" / "core.xml").write_text(
+            """<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<cp:coreProperties xmlns:cp="http://schemas.openxmlformats.org/package/2006/metadata/core-properties" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcterms="http://purl.org/dc/terms/" xmlns:dcmitype="http://purl.org/dc/dcmitype/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+  <dc:title>ite document</dc:title>
+  <dc:creator>ite</dc:creator>
+</cp:coreProperties>
+""",
+            encoding="utf-8",
+        )
+        (root / "docProps" / "app.xml").write_text(
+            """<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<Properties xmlns="http://schemas.openxmlformats.org/officeDocument/2006/extended-properties" xmlns:vt="http://schemas.openxmlformats.org/officeDocument/2006/docPropsVTypes">
+  <Application>ite</Application>
+</Properties>
+""",
+            encoding="utf-8",
+        )
+        output = root / "out.docx"
+        pack_directory(root, output)
+        return output.read_bytes()
+
+
+def validate_docx(path: Path) -> list[str]:
+    errors: list[str] = []
+    try:
+        with ZipFile(path) as archive:
+            members = set(archive.namelist())
+            missing = REQUIRED_MEMBERS - members
+            if missing:
+                errors.append(f"missing required members: {', '.join(sorted(missing))}")
+            for member in sorted(REQUIRED_MEMBERS & members):
+                with archive.open(member) as handle:
+                    try:
+                        ET.parse(handle)
+                    except ET.ParseError as exc:
+                        errors.append(f"{member}: invalid XML ({exc})")
+    except Exception as exc:
+        errors.append(str(exc))
+    return errors
+
+
+def _paragraph_element(text: str) -> ET.Element:
+    paragraph = ET.Element(f"{{{W_NS}}}p")
+    run = ET.SubElement(paragraph, f"{{{W_NS}}}r")
+    text_node = ET.SubElement(run, f"{{{W_NS}}}t")
+    if text.startswith(" ") or text.endswith(" "):
+        text_node.set("{http://www.w3.org/XML/1998/namespace}space", "preserve")
+    text_node.text = text
+    return paragraph

ite_agent-0.0.23/.agents/skills/docx/scripts/extract_docx.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from _docx_core import load_document_tree
+from _docx_core import paragraph_texts
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Extract readable content from a .docx file.")
+    parser.add_argument("input", type=Path, help="Path to the source .docx file")
+    parser.add_argument(
+        "--format",
+        choices=("text", "markdown", "json"),
+        default="text",
+        help="Output format",
+    )
+    parser.add_argument("--output", type=Path, help="Optional file to write extracted content to")
+    args = parser.parse_args()
+
+    tree = load_document_tree(args.input)
+    paragraphs = paragraph_texts(tree)
+    if args.format == "json":
+        content = json.dumps({"paragraphs": paragraphs}, indent=2)
+    elif args.format == "markdown":
+        content = "\n\n".join(paragraphs)
+    else:
+        content = "\n".join(paragraphs)
+
+    if args.output:
+        args.output.write_text(content, encoding="utf-8")
+    else:
+        print(content)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ite_agent-0.0.23/.agents/skills/docx/scripts/inspect_docx.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from _docx_core import inspect_docx
+from _docx_core import json_dump
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Inspect a .docx file and report basic metadata.")
+    parser.add_argument("input", type=Path, help="Path to the source .docx file")
+    args = parser.parse_args()
+
+    print(json_dump(inspect_docx(args.input)))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ite_agent-0.0.23/.agents/skills/docx/scripts/pack_docx.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from _docx_core import pack_directory
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Pack an unpacked OOXML directory into a .docx file.")
+    parser.add_argument("input_dir", type=Path, help="Directory containing the unpacked document")
+    parser.add_argument("output", type=Path, help="Output .docx file")
+    args = parser.parse_args()
+
+    pack_directory(args.input_dir, args.output)
+    print(args.output.resolve())
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ite_agent-0.0.23/.agents/skills/docx/scripts/render_docx.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+import shutil
+import subprocess
+import tempfile
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Render a DOCX file to page PNGs using LibreOffice and Poppler.")
+    parser.add_argument("input", type=Path, help="Source .docx file")
+    parser.add_argument("--output_dir", type=Path, required=True, help="Directory for rendered page images")
+    parser.add_argument("--dpi", type=int, default=144, help="Rasterization DPI")
+    args = parser.parse_args()
+
+    for tool in ("soffice", "pdftoppm"):
+        if shutil.which(tool) is None:
+            raise SystemExit(f"missing required system tool: {tool}")
+
+    args.output_dir.mkdir(parents=True, exist_ok=True)
+    with tempfile.TemporaryDirectory(prefix="ite-docx-render-") as temp_dir:
+        temp_root = Path(temp_dir)
+        pdf_dir = temp_root / "pdf"
+        pdf_dir.mkdir(parents=True, exist_ok=True)
+        profile_dir = temp_root / "profile"
+        profile_dir.mkdir(parents=True, exist_ok=True)
+
+        subprocess.run(
+            [
+                "soffice",
+                f"-env:UserInstallation=file://{profile_dir}",
+                "--headless",
+                "--convert-to",
+                "pdf",
+                "--outdir",
+                str(pdf_dir),
+                str(args.input),
+            ],
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+
+        pdf_path = pdf_dir / f"{args.input.stem}.pdf"
+        if not pdf_path.is_file():
+            raise SystemExit("failed to produce an intermediate PDF")
+
+        prefix = args.output_dir / "page"
+        subprocess.run(
+            [
+                "pdftoppm",
+                "-png",
+                "-r",
+                str(args.dpi),
+                str(pdf_path),
+                str(prefix),
+            ],
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+
+    for path in sorted(args.output_dir.glob("page-*.png")):
+        print(path.resolve())
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ite_agent-0.0.23/.agents/skills/docx/scripts/replace_text.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from _docx_core import load_document_tree
+from _docx_core import paragraph_texts
+from _docx_core import replace_in_paragraphs
+from _docx_core import set_paragraphs
+from _docx_core import write_document_tree
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Apply direct string replacements inside a .docx document.")
+    parser.add_argument("input", type=Path, help="Source .docx file")
+    parser.add_argument("output", type=Path, help="Output .docx file")
+    parser.add_argument(
+        "--replace",
+        nargs=2,
+        metavar=("OLD", "NEW"),
+        action="append",
+        required=True,
+        help="Pair of strings to replace in order",
+    )
+    args = parser.parse_args()
+
+    tree = load_document_tree(args.input)
+    paragraphs = paragraph_texts(tree)
+    updated, replacement_count = replace_in_paragraphs(paragraphs, args.replace)
+    if replacement_count == 0:
+        raise SystemExit("no matching text was found for replacement")
+    set_paragraphs(tree, updated)
+    write_document_tree(args.input, args.output, tree)
+    print(f"{args.output.resolve()} ({replacement_count} replacements)")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ite_agent-0.0.23/.agents/skills/docx/scripts/unpack_docx.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from _docx_core import unpack_to_directory
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Unpack a .docx file into a directory.")
+    parser.add_argument("input", type=Path, help="Path to the source .docx file")
+    parser.add_argument("output_dir", type=Path, help="Directory to receive the unpacked package")
+    args = parser.parse_args()
+
+    unpack_to_directory(args.input, args.output_dir)
+    print(args.output_dir.resolve())
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ite_agent-0.0.23/.agents/skills/docx/scripts/validate_docx.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from _docx_core import validate_docx
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Validate the basic shape of a .docx file.")
+    parser.add_argument("input", type=Path, help="Path to the .docx file")
+    args = parser.parse_args()
+
+    errors = validate_docx(args.input)
+    if errors:
+        for error in errors:
+            print(error)
+        return 1
+    print("ok")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ite_agent-0.0.23/.agents/skills/docx/scripts/write_docx.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from _docx_core import build_simple_document
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Create a simple .docx file from text or markdown.")
+    parser.add_argument("input", type=Path, nargs="?", help="Source text or markdown file")
+    parser.add_argument("output", type=Path, help="Output .docx path")
+    parser.add_argument("--title", help="Optional document title inserted as the first paragraph")
+    parser.add_argument(
+        "--template",
+        choices=("memo", "letter"),
+        help="Use a bundled starter template when no input file is provided",
+    )
+    args = parser.parse_args()
+
+    if args.input is None and args.template is None:
+        raise SystemExit("provide either an input file or --template")
+
+    source_path = args.input
+    if source_path is None:
+        source_path = Path(__file__).resolve().parent.parent / "templates" / f"{args.template}.md"
+
+    source = source_path.read_text(encoding="utf-8")
+    paragraphs = [line.strip() for line in source.splitlines() if line.strip()]
+    if not paragraphs:
+        raise SystemExit("input did not contain any non-empty lines")
+    payload = build_simple_document(paragraphs, title=args.title)
+    args.output.parent.mkdir(parents=True, exist_ok=True)
+    args.output.write_bytes(payload)
+    print(args.output.resolve())
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ite_agent-0.0.23/.agents/skills/docx/templates/letter.md

@@ -0,0 +1,11 @@
+Letter Title
+
+Recipient
+
+Opening
+
+Body paragraph one.
+
+Body paragraph two.
+
+Closing

ite_agent-0.0.23/.agents/skills/docx/templates/memo.md

@@ -0,0 +1,13 @@
+Team Memo
+
+Summary
+
+Add the short executive summary here.
+
+Details
+
+Add the supporting details here.
+
+Next steps
+
+List the follow-up actions here.