python-hwpx-automation 6.0.3__py3-none-any.whl

hwpx_automation/office/exam/profile.py

@@ -0,0 +1,123 @@
+"""Profile a school form: resolve role->style and classify the body region.
+
+Grounded by the measure-first A_form probe (scripts/exam_profile_a_form.py).
+No style-by-name API exists, so we build a name->Style index ourselves."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+from hwpx.document import HwpxDocument
+from hwpx.oxml import Style
+
+DEFAULT_ROLE_STYLE_NAMES: dict[str, str] = {
+    "normal": "바탕글",
+    "number": "문항자동번호넣기",
+    "choice1": "1행답항",
+    "choice2": "2행답항",
+    "choice3": "3행답항",
+    "choice5": "5행답항",
+    "box_guide": "(보기)박스안내용",
+    "box": "박스안내용",
+}
+# Roles that MUST exist for composition (others are optional conveniences).
+REQUIRED_ROLES = ("normal", "number", "choice1", "choice5")
+
+
+class FormProfileError(ValueError):
+    pass
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedStyle:
+    name: str
+    style_id: str
+    para_pr_id: str | None
+    char_pr_id: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class FormProfile:
+    role_styles: dict[str, ResolvedStyle]
+    admin_box_index: int
+    body_start: int
+    body_end: int
+    replaceable_indices: tuple[int, ...]
+    structural_indices: tuple[int, ...]
+    ambiguous_indices: tuple[int, ...]
+
+
+def _name_index(doc: HwpxDocument) -> dict[str, Style]:
+    index: dict[str, Style] = {}
+    for style in doc.styles.values():
+        if style.name:
+            index.setdefault(style.name, style)
+    return index
+
+
+def profile_form(
+    doc: HwpxDocument,
+    *,
+    role_style_names: Mapping[str, str] | None = None,
+) -> FormProfile:
+    names = dict(DEFAULT_ROLE_STYLE_NAMES)
+    if role_style_names:
+        names.update(role_style_names)
+
+    by_name = _name_index(doc)
+    role_styles: dict[str, ResolvedStyle] = {}
+    for role, style_name in names.items():
+        style = by_name.get(style_name)
+        if style is None:
+            if role in REQUIRED_ROLES:
+                raise FormProfileError(
+                    f"required role '{role}' style {style_name!r} not found in form"
+                )
+            continue
+        role_styles[role] = ResolvedStyle(
+            name=style_name,
+            style_id=str(style.id if style.id is not None else style.raw_id),
+            para_pr_id=None
+            if style.para_pr_id_ref is None
+            else str(style.para_pr_id_ref),
+            char_pr_id=None
+            if style.char_pr_id_ref is None
+            else str(style.char_pr_id_ref),
+        )
+
+    # Anchor the body region on the QUESTION/ANSWER styles ONLY. 바탕글(normal)
+    # also clothes the 관리박스 [0] and the trailing footer/essay zone, so it
+    # cannot delimit the body (measured: A_form [0] and [71..100] are all 바탕글;
+    # the question/answer slots span [1..70], footer marker sits at [99]).
+    anchor_names = {rs.name for role, rs in role_styles.items() if role != "normal"}
+    section = doc.sections[0]
+    paragraphs = section.paragraphs
+
+    anchors: list[int] = []
+    for idx, para in enumerate(paragraphs):
+        if idx == 0:  # 관리박스 (never replaceable)
+            continue
+        sid = para.style_id_ref
+        style = doc.style(sid) if sid is not None else None
+        if style is not None and style.name in anchor_names:
+            anchors.append(idx)
+
+    if not anchors:
+        raise FormProfileError(
+            "no question/answer-style body paragraphs found (form profile failed)"
+        )
+
+    body_start, body_end = anchors[0], anchors[-1]
+    # The whole [body_start..body_end] span is recomposed from the exam IR
+    # (inline 바탕글 lines + 논술형 scaffolding within it included); 관리박스 [0]
+    # and the tail [body_end+1..] (footer / essay answer space) are preserved.
+    return FormProfile(
+        role_styles=role_styles,
+        admin_box_index=0,
+        body_start=body_start,
+        body_end=body_end,
+        replaceable_indices=tuple(range(body_start, body_end + 1)),
+        structural_indices=(),
+        ambiguous_indices=(),  # v1: the body span is recomposed wholesale from the IR
+    )

hwpx_automation/office/form_fill/__init__.py

@@ -0,0 +1,66 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Canonical automation owner for application-level form-fill behavior."""
+
+import hwpx_automation.office.form_fill.fit as fit
+from .fill_residue import (
+    ResidueFinding,
+    ResidueReport,
+    inspect_fill_residue,
+)
+from .guidance import (
+    Candidate,
+    CellLoc,
+    GuidanceReport,
+    LegendBinding,
+    ScannedParagraph,
+    is_form_instruction,
+    scan_form_guidance,
+)
+from .quality import (
+    NEEDS_REVIEW,
+    UNVERIFIED,
+    AxisScore,
+    ScoreCard,
+    score_form_fill,
+)
+from .split_run import (
+    FillReport,
+    HeterogeneousWarning,
+    Placeholder,
+    TextFragment,
+    fill_section_bytes,
+    find_split_placeholders,
+    heterogeneous_warnings,
+)
+from .template_formfit import (
+    analyze_template_formfit,
+    apply_template_formfit,
+)
+
+__all__ = [
+    "NEEDS_REVIEW",
+    "UNVERIFIED",
+    "AxisScore",
+    "Candidate",
+    "CellLoc",
+    "FillReport",
+    "GuidanceReport",
+    "HeterogeneousWarning",
+    "LegendBinding",
+    "Placeholder",
+    "ResidueFinding",
+    "ResidueReport",
+    "ScannedParagraph",
+    "ScoreCard",
+    "TextFragment",
+    "analyze_template_formfit",
+    "apply_template_formfit",
+    "fill_section_bytes",
+    "find_split_placeholders",
+    "fit",
+    "heterogeneous_warnings",
+    "inspect_fill_residue",
+    "is_form_instruction",
+    "scan_form_guidance",
+    "score_form_fill",
+]

hwpx_automation/office/form_fill/classification.py

@@ -0,0 +1,108 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Leaf table extraction and classification policy shared by form workflows."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from hwpx.table_patch import (
+    build_grid,
+    iter_table_spans,
+    read_source_bytes,
+    section_parts,
+    table_text,
+)
+
+
+@dataclass
+class _Table:
+    section: str
+    index: int
+    bytes: bytes
+    rows: int
+    cols: int
+    first_row: list[str]
+    heading: str
+    text: str
+
+
+def _tables(source: str | Path | bytes) -> list[_Table]:
+    data = read_source_bytes(source)
+    out: list[_Table] = []
+    for section_path, section in sorted(section_parts(data).items()):
+        spans = iter_table_spans(section)
+        for table_index, (start, end) in enumerate(spans):
+            table = section[start:end]
+            grid, report = build_grid(table)
+            first: list[str] = []
+            for column in range(report.col_count):
+                cell = grid.get((0, column))
+                first.append(
+                    " ".join(
+                        table_text(table[cell.start : cell.end]).split()
+                    )
+                    if cell
+                    else ""
+                )
+            deduplicated: list[str] = []
+            for cell_text in first:
+                if not deduplicated or deduplicated[-1] != cell_text:
+                    deduplicated.append(cell_text)
+            window_start = max(0, start - 8000)
+            heading = " ".join(
+                table_text(section[window_start:start]).split()
+            )[-80:]
+            out.append(
+                _Table(
+                    section=section_path,
+                    index=table_index,
+                    bytes=table,
+                    rows=report.row_count,
+                    cols=report.col_count,
+                    first_row=deduplicated,
+                    heading=heading,
+                    text=" ".join(table_text(table).split()),
+                )
+            )
+    return out
+
+
+def _classify(table: _Table) -> str:
+    """Coarse table type from its first-row and heading signature."""
+
+    first_row = " | ".join(table.first_row)
+    text = table.text
+    if (
+        table.rows == 1
+        and table.first_row
+        and table.first_row[0].strip().isdigit()
+    ):
+        return "other"
+    if "석차등급" in first_row and "원점수" in first_row:
+        return "seokcha"
+    if "제출" in first_row and ("모아찍기" in text or "인쇄물" in text):
+        return "submit"
+    if table.rows == 1 and table.cols == 1 and table.text.startswith("★유의"):
+        return "notice_star"
+    if first_row.startswith("교육과정 성취기준") and "평가기준" in first_row:
+        return "achievement"
+    if first_row.startswith("성취수준") and "일반적 특성" in first_row:
+        return "level"
+    if first_row.startswith("교육과정성취기준"):
+        return "rubric"
+    if "최소 능력" in first_row or "최소 성취수준" in first_row:
+        return "minlevel"
+    if "성취기준별 성취수준" in first_row and "최소" not in first_row:
+        return "achievement"
+    if "학기 단위 성취수준" in first_row:
+        return "level"
+    if first_row.startswith("평가 영역명") and "영역 만점" in first_row:
+        return "rubric"
+    if "평가 종류" in first_row or (
+        "수행평가" in first_row and "합계" in first_row
+    ):
+        return "ratio"
+    if "성취율" in first_row and "성취도" in first_row:
+        return "achieve_rate"
+    return "other"

hwpx_automation/office/form_fill/fill_residue.py

@@ -0,0 +1,242 @@
+"""채움본 잔존물 zero-체크 — 범용 form-fill goal Stage 3의 기계 게이트.
+
+2026-07-06 평가계획 거짓 수렴(빨간 지시문 ~15곳·타과목 샘플·placeholder 잔존이
+스코어 94.9를 통과)의 결함 유형을 **양식 불문 신호**로 검사한다. 도메인 어휘 없음:
+
+- **삭제색 잔존**(ERROR): blank의 범례가 "삭제"로 선언한 색의 런 텍스트가
+  produced에 남아 있음(예: 빨간 지시문).
+- **미수정 샘플**(ERROR): 범례가 "수정"으로 선언한 색의 blank 런 텍스트가
+  produced에 **그대로** 남아 있음 — 코드 없는 prose 샘플(음악 '연주', 한국사
+  '전근대사' 등)을 잡는 일반 신호.
+- **placeholder 잔존**: ◯◯◯·□□□(2연속 이상)=ERROR. 리터럴 ``**``는 각주
+  표식("경비** 집행 불가")과 중의적이라 NEEDS_REVIEW(2026-07-07 신청서 실측).
+- **고아 마커**(NEEDS_REVIEW): 텍스트가 목록 마커('-', '•', '가.' 류)뿐인 문단 —
+  의도적으로 남긴 하위 항목 자리일 수 있어 사람 판단으로 넘긴다.
+
+이 게이트는 필요조건이다 — 통과해도 "제출 가능" 확언은 렌더 PDF를 사람이 전
+페이지 본 뒤에만 한다(철칙).
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from hwpx.document import HwpxDocument
+
+from .guidance import _Walker, _color_family, scan_form_guidance
+
+__all__ = ["ResidueFinding", "ResidueReport", "inspect_fill_residue"]
+
+_PLACEHOLDER_RES = {
+    "circle_blank": re.compile(r"[◯○〇]{2,}"),
+    "square_blank": re.compile(r"□{2,}"),
+}
+# ``**``는 placeholder(**과목)일 수도, 각주 표식(경비**)일 수도 있어 사람 판단으로.
+_AMBIGUOUS_RES = {
+    "double_star": re.compile(r"\*\*"),
+}
+_MARKER_ONLY = re.compile(
+    r"^\s*(?:[-•‧∙·]|[가나다라마바사아자차카타파하]\.|\(\d+\)|\d+\))\s*$"
+)
+_MIN_SAMPLE_LEN = 4  # 이보다 짧은 수정색 텍스트(숫자·기호 등)는 미수정 판정에서 제외
+
+
+@dataclass(slots=True)
+class ResidueFinding:
+    kind: str  # delete_color_residue / unmodified_sample / placeholder / marker_only
+    severity: str  # error / needs_review
+    location: str
+    text_preview: str
+    signal: str
+
+
+@dataclass(slots=True)
+class ResidueReport:
+    produced: str
+    errors: list[ResidueFinding] = field(default_factory=list)
+    needs_review: list[ResidueFinding] = field(default_factory=list)
+    stats: dict = field(default_factory=dict)
+
+    @property
+    def ok(self) -> bool:
+        return not self.errors
+
+    def to_dict(self) -> dict:
+        def d(f: ResidueFinding) -> dict:
+            return {
+                "kind": f.kind,
+                "severity": f.severity,
+                "location": f.location,
+                "textPreview": f.text_preview,
+                "signal": f.signal,
+            }
+
+        return {
+            "ok": self.ok,
+            "errors": [d(f) for f in self.errors],
+            "needsReview": [d(f) for f in self.needs_review],
+            "stats": self.stats,
+        }
+
+
+def _scan_paragraphs(source: str | Path | HwpxDocument):
+    doc = source if isinstance(source, HwpxDocument) else HwpxDocument.open(str(source))
+    chars = doc._root.char_properties
+    out = []
+    for s_idx, section in enumerate(doc.sections):
+        walker = _Walker(chars)
+        for b_idx, p in enumerate(section.paragraphs):
+            walker.walk_paragraph(p.element, s_idx, b_idx, None)
+        out.extend(walker.out)
+    return out
+
+
+def _collect_blank_residue_texts(
+    blank: str | Path,
+) -> tuple[list[tuple[str, str]], list[tuple[str, str]]]:
+    """(blank_delete_texts, blank_modify_texts) -- (text, 위치 힌트) pairs from the
+    blank's legend-declared delete/modify color families."""
+
+    blank_report = scan_form_guidance(blank)
+    delete_families = {b.family for b in blank_report.legend if b.action == "delete"}
+    modify_families = {b.family for b in blank_report.legend if b.action == "modify"}
+    blank_delete_texts: list[tuple[str, str]] = []
+    blank_modify_texts: list[tuple[str, str]] = []
+    for bp in _scan_paragraphs(blank):
+        for _, hex_color, text in bp.spans:
+            t = text.strip()
+            if not t:
+                continue
+            fam = _color_family(hex_color)
+            if fam in delete_families:
+                blank_delete_texts.append((t, bp.location()))
+            elif fam in modify_families and len(t) >= _MIN_SAMPLE_LEN:
+                blank_modify_texts.append((t, bp.location()))
+    return blank_delete_texts, blank_modify_texts
+
+
+def _check_delete_color_residue(
+    blank_delete_texts: list[tuple[str, str]], produced_text: str
+) -> list[ResidueFinding]:
+    """삭제색 잔존: blank의 삭제색 텍스트가 produced에 남음."""
+
+    findings: list[ResidueFinding] = []
+    seen: set[str] = set()
+    for t, loc in blank_delete_texts:
+        if t in seen:
+            continue
+        seen.add(t)
+        if t in produced_text:
+            findings.append(
+                ResidueFinding(
+                    "delete_color_residue",
+                    "error",
+                    loc,
+                    t[:80],
+                    "blank 범례가 '삭제'로 선언한 색의 텍스트가 잔존",
+                )
+            )
+    return findings
+
+
+def _check_unmodified_sample(
+    blank_modify_texts: list[tuple[str, str]], produced_text: str
+) -> list[ResidueFinding]:
+    """미수정 샘플: 수정색 텍스트가 blank와 동일하게 잔존."""
+
+    findings: list[ResidueFinding] = []
+    seen: set[str] = set()
+    for t, loc in blank_modify_texts:
+        if t in seen:
+            continue
+        seen.add(t)
+        if t in produced_text:
+            findings.append(
+                ResidueFinding(
+                    "unmodified_sample",
+                    "error",
+                    loc,
+                    t[:80],
+                    "blank 범례가 '수정'으로 선언한 텍스트가 그대로 잔존(샘플 미교체)",
+                )
+            )
+    return findings
+
+
+def _check_placeholder_residue(
+    paras: list,
+) -> tuple[list[ResidueFinding], list[ResidueFinding]]:
+    """placeholder 잔존 (errors, needs_review)."""
+
+    errors: list[ResidueFinding] = []
+    needs_review: list[ResidueFinding] = []
+    for p in paras:
+        text = p.text
+        if not text.strip():
+            continue
+        for name, pat in _PLACEHOLDER_RES.items():
+            if pat.search(text):
+                errors.append(
+                    ResidueFinding(
+                        "placeholder",
+                        "error",
+                        p.location(),
+                        text.strip()[:80],
+                        f"placeholder:{name}",
+                    )
+                )
+        for name, pat in _AMBIGUOUS_RES.items():
+            if pat.search(text):
+                needs_review.append(
+                    ResidueFinding(
+                        "placeholder_ambiguous",
+                        "needs_review",
+                        p.location(),
+                        text.strip()[:80],
+                        f"placeholder?:{name} — 각주 표식일 수 있음",
+                    )
+                )
+        if _MARKER_ONLY.match(text):
+            needs_review.append(
+                ResidueFinding(
+                    "marker_only",
+                    "needs_review",
+                    p.location(),
+                    text.strip()[:20],
+                    "목록 마커만 있는 문단 — 의도된 빈 자리인지 사람 판단",
+                )
+            )
+    return errors, needs_review
+
+
+def inspect_fill_residue(
+    produced: str | Path,
+    blank: str | Path | None = None,
+) -> ResidueReport:
+    """채움본(produced)의 잔존물을 검사한다. blank가 있으면 범례 기반 신호까지."""
+    report = ResidueReport(produced=str(produced))
+    paras = _scan_paragraphs(produced)
+    produced_text = "\n".join(p.text for p in paras)
+
+    blank_delete_texts: list[tuple[str, str]] = []
+    blank_modify_texts: list[tuple[str, str]] = []
+    if blank is not None:
+        blank_delete_texts, blank_modify_texts = _collect_blank_residue_texts(blank)
+
+    report.errors.extend(_check_delete_color_residue(blank_delete_texts, produced_text))
+    report.errors.extend(_check_unmodified_sample(blank_modify_texts, produced_text))
+
+    placeholder_errors, placeholder_needs_review = _check_placeholder_residue(paras)
+    report.errors.extend(placeholder_errors)
+    report.needs_review.extend(placeholder_needs_review)
+
+    report.stats = {
+        "paragraphs": len(paras),
+        "blankDeleteTexts": len({t for t, _ in blank_delete_texts}),
+        "blankModifyTexts": len({t for t, _ in blank_modify_texts}),
+        "errors": len(report.errors),
+        "needsReview": len(report.needs_review),
+    }
+    return report

hwpx_automation/office/form_fill/fit/__init__.py

@@ -0,0 +1,36 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Form-fit decision, reporting, and geometry owned by the automation layer."""
+
+import hwpx_automation.office.form_fill.fit.seal as seal
+import hwpx_automation.office.form_fill.fit.wordbox as wordbox
+from .engine import FitEngine
+from .measure import (
+    DEFAULT_SAFETY,
+    Measurement,
+    SlotMetrics,
+    estimate_lines,
+    estimate_text_width,
+    measure,
+    resolve_slot_metrics,
+)
+from .policy import FitMode, FitPolicy, OverflowAction
+from .report import FIELD_OVERFLOW, FitResult, to_form_report
+
+__all__ = [
+    "DEFAULT_SAFETY",
+    "FIELD_OVERFLOW",
+    "FitEngine",
+    "FitMode",
+    "FitPolicy",
+    "FitResult",
+    "Measurement",
+    "OverflowAction",
+    "SlotMetrics",
+    "estimate_lines",
+    "estimate_text_width",
+    "measure",
+    "resolve_slot_metrics",
+    "seal",
+    "to_form_report",
+    "wordbox",
+]

hwpx_automation/office/form_fill/fit/apply.py

@@ -0,0 +1,24 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Re-export of the neutral fit cell application helper that python-hwpx owns.
+
+This module used to be a copy. The two versions were behaviourally identical —
+comparing normalised syntax trees showed no semantic difference across the five
+fit-contract modules, only comment alignment and whether a forward reference was
+quoted — so maintaining both bought nothing and cost a drift risk that had
+already come due elsewhere in this stack.
+
+Slot measurement and the keep/wrap/shrink ladder are format reasoning, not
+application policy: core's own table and field APIs call them. What this layer
+owns is the application half — seal placement, PDF extraction, institutional
+rules — which stays here and is not re-exported from core.
+"""
+
+from __future__ import annotations
+
+from hwpx.form_fit.apply import (  # noqa: F401 - re-exported public surface
+    fit_cell_text,
+)
+
+__all__ = [
+    "fit_cell_text",
+]

hwpx_automation/office/form_fill/fit/engine.py

@@ -0,0 +1,24 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Re-export of the neutral fit keep/wrap/shrink ladder that python-hwpx owns.
+
+This module used to be a copy. The two versions were behaviourally identical —
+comparing normalised syntax trees showed no semantic difference across the five
+fit-contract modules, only comment alignment and whether a forward reference was
+quoted — so maintaining both bought nothing and cost a drift risk that had
+already come due elsewhere in this stack.
+
+Slot measurement and the keep/wrap/shrink ladder are format reasoning, not
+application policy: core's own table and field APIs call them. What this layer
+owns is the application half — seal placement, PDF extraction, institutional
+rules — which stays here and is not re-exported from core.
+"""
+
+from __future__ import annotations
+
+from hwpx.form_fit.engine import (  # noqa: F401 - re-exported public surface
+    FitEngine,
+)
+
+__all__ = [
+    "FitEngine",
+]

hwpx_automation/office/form_fill/fit/measure.py

@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Re-export of the neutral fit measurement model that python-hwpx owns.
+
+This module used to be a copy. The two versions were behaviourally identical —
+comparing normalised syntax trees showed no semantic difference across the five
+fit-contract modules, only comment alignment and whether a forward reference was
+quoted — so maintaining both bought nothing and cost a drift risk that had
+already come due elsewhere in this stack.
+
+Slot measurement and the keep/wrap/shrink ladder are format reasoning, not
+application policy: core's own table and field APIs call them. What this layer
+owns is the application half — seal placement, PDF extraction, institutional
+rules — which stays here and is not re-exported from core.
+"""
+
+from __future__ import annotations
+
+from hwpx.form_fit.measure import (  # noqa: F401 - re-exported public surface
+    Confidence,
+    DEFAULT_LINE_SPACING_RATIO,
+    DEFAULT_SAFETY,
+    GROSS_ROW_GROWTH_FACTOR,
+    MIN_LINE_SPACING_RATIO,
+    MIN_ROW_GROWTH_LINES,
+    Measurement,
+    SlotMetrics,
+    char_advance,
+    classify_char,
+    estimate_lines,
+    estimate_text_width,
+    measure,
+    resolve_slot_metrics,
+)
+
+__all__ = [
+    "Confidence",
+    "DEFAULT_LINE_SPACING_RATIO",
+    "DEFAULT_SAFETY",
+    "GROSS_ROW_GROWTH_FACTOR",
+    "MIN_LINE_SPACING_RATIO",
+    "MIN_ROW_GROWTH_LINES",
+    "Measurement",
+    "SlotMetrics",
+    "char_advance",
+    "classify_char",
+    "estimate_lines",
+    "estimate_text_width",
+    "measure",
+    "resolve_slot_metrics",
+]