docx-json-converter 0.1.0

Convert .docx files to structured JSON and back.

docx_json_converter

A robust Python package for converting .docx files into structured JSON and back again. Designed for AI agents that need to read or generate Microsoft Word documents with high fidelity.

Features

• Round-Trip Formatting: Preserves Bold, Italic, Underline, and Font Size.
• Run-Level Precision: Handles mixed formatting within paragraphs (e.g., "Hello World").
• Column Support: Detects and applies document-wide column layouts (e.g., 2-column newsletters).
• Structure: Supports Paragraphs, Bullet Lists, and Headers.
• AI-Ready: Generates optimized JSON schemas for LLMs.

Installation

pip install docx_json_converter

(Or install locally for development):

pip install -e .

Quick Start

1. Python API

from docx_json_converter import convert_docx_to_json, convert_json_to_docx

# Convert DOCX -> JSON
data = convert_docx_to_json("input.docx")
# data = {"metadata": {"columns": 1}, "blocks": [...]}

# Convert JSON -> DOCX
convert_json_to_docx(data, "output.docx")

Simplified Mode (Text Only):

# Returns blocks without detailed formatting/runs
data = convert_docx_to_json("input.docx", include_formatting=False)

2. CLI for AI Prompts

To teach an LLM (like ChatGPT or Claude) how to generate documents using this package, generate the system prompt file:

docx-json-prompt

This creates llm.txt with the JSON schema and rules.

The Zen of docx_json_converter

import docx_json_converter
docx_json_converter.zen()

JSON Schema Example

{
  "metadata": {
    "columns": 2
  },
  "blocks": [
    {
      "text": "My Title",
      "block_type": "title",
      "formatting": { "alignment": "center" },
      "runs": [
        { "text": "My Title", "formatting": { "bold": true, "font_size": 16.0 } }
      ]
    },
    {
      "text": "Bullet point 1",
      "block_type": "list_item",
      "formatting": { "alignment": "left" }
    }
  ]
}

License

MIT