Overview
Kordoc is a comprehensive, production-grade library and CLI tool designed for parsing, analyzing, comparing, and generating Korean public documents. Originating from the practical needs of government administrative work, it addresses the technical challenges of handling legacy and modern document formats commonly used in South Korea, such as HWP (3.x/5.x), HWPX, HWPML, PDF, XLS, XLSX, and DOCX. It is architected to facilitate AI agent integration via the Model Context Protocol (MCP) and provides non-destructive "round-trip" editing capabilities that preserve original document formatting.

Core Methodology and Technical Architecture
Kordoc employs a modular, multi-format parsing engine that converts diverse document structures into a unified Intermediate Representation (IR) consisting of IRBlock types (e.g., heading, paragraph, table, list, image, separator).

• Document Parsing and Restoration:
  • HWP 5.x/HWPX: The library leverages patchHwpx and patchHwp APIs to perform in-place edits. Unlike standard conversions, it performs binary-level surgery or XML-tree manipulation, ensuring that only the target text (e.g., a specific paragraph or table cell) is modified while preserving 100% of the original formatting (fonts, alignment, spacing).
  • HWP 3.0 Support: It includes a TypeScript-ported implementation of the legacy 1996–2002 HWP binary format, handling the conversion of "Sangyong" (commercial) johab character sets to Unicode through a lookup table of 5,893 Hanja/symbols.
  • PDF Analysis: Kordoc implements an advanced heuristic engine that combines line-based detection (extracting horizontal/vertical strokes) with X-coordinate clustering and baseline grouping. It generates quality signals ($Q$) for each page, defined by metrics such as the ratio of control characters ($C_{ratio}$) and PUA characters ($P_{ratio}$):

$Q = \{ \text{needsOcr} : (\text{low\_text} \lor \text{high\_pua} \lor \text{high\_control}) \}$

• Form Processing: The extractFormSchema and fillForm utilities use type inference to map label-value pairs. It identifies fields across seven data types (text, date, phone, email, amount, checkbox, idnum) to automate administrative workflows without breaking template integrity.

• Data Integrity and Security:
  • Incremental Patching: The HwpxSession enables incremental document editing via block indices. The system ensures equivalence through strict CI gate checks, where the final byte sequence must maintain parity with the original document's structure, excluding the patched content.
  • Security Hardening: The engine integrates multiple defensive layers to prevent common vulnerabilities, including ZIP bombs, XXE (Billion Laughs) attacks, and Path Traversal. It implements strict memory limits for buildTableDirect and uses cfb parsers to safely decompress or decode encrypted HWP/HWPX documents, specifically handling legacy distribution-restricted (DRM-like) files via COM fallback mechanisms on Windows.

• Comparison Engine:
  • The compare function calculates the differences between document versions at the IRBlock level. It computes similarity scores and generates a BlockDiff object, which tracks added, removed, and modified status for both text and individual table cells, allowing for the automatic generation of "new-versus-old" comparison tables (shin-gu-dae-jo-pyo).

Summary of Technical Features

• Round-Trip Workflow: Transforms HWPX/HWP to Markdown for LLM analysis, then patches the edits back into the original binary/XML with 100% formatting preservation.
• MCP Integration: Provides 8 specialized tools (e.g., parse_document, parse_table, fill_form) that allow AI agents to interact with proprietary document formats as structured data.
• High Precision: Achieves near-perfect benchmarks in table structure reconstruction ($100\%$ accuracy in nested table cells) and text reproduction ($99.998\%$) based on a corpus of 324 actual government documents.