artifice-draft 0.1.0__py3-none-any.whl

artifice_draft/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: 2026 Maurice Casey
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later

artifice_draft/_diff.py

@@ -0,0 +1,58 @@
+# SPDX-FileCopyrightText: 2026 Maurice Casey
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Word-level diff ranges between an original and an edited paragraph.
+
+Used by the web review screen to highlight what an LLM edit actually changed,
+the same way a track-changes view would, without waiting for Word to open the
+file. Built on the standard library's ``difflib`` — no new dependency.
+"""
+
+from __future__ import annotations
+
+import difflib
+import re
+
+_WORD_RE = re.compile(r"\S+|\s+")
+
+
+def _tokenize(text: str) -> list[str]:
+    """Split into words and whitespace runs, so ranges land on word boundaries."""
+    return _WORD_RE.findall(text)
+
+
+def diff_ranges(original: str, edited: str) -> tuple[list[tuple[int, int, str]], list[tuple[int, int, str]]]:
+    """Return (original_ranges, edited_ranges), each a list of (start, end, tag)
+    character offsets into the respective string. ``tag`` is one of
+    "delete_" (present in original, removed), "insert_" (present in edited,
+    added), or "replace_" (changed on both sides) — matching the CSS class
+    names the review screen's ``mark.hl-*`` rules key off.
+    """
+    orig_tokens = _tokenize(original)
+    edit_tokens = _tokenize(edited)
+    matcher = difflib.SequenceMatcher(a=orig_tokens, b=edit_tokens, autojunk=False)
+
+    orig_ranges: list[tuple[int, int, str]] = []
+    edit_ranges: list[tuple[int, int, str]] = []
+    orig_pos = 0
+    edit_pos = 0
+
+    for op, a0, a1, b0, b1 in matcher.get_opcodes():
+        orig_span = sum(len(t) for t in orig_tokens[a0:a1])
+        edit_span = sum(len(t) for t in edit_tokens[b0:b1])
+
+        if op == "equal":
+            pass
+        elif op == "delete":
+            orig_ranges.append((orig_pos, orig_pos + orig_span, "delete_"))
+        elif op == "insert":
+            edit_ranges.append((edit_pos, edit_pos + edit_span, "insert_"))
+        elif op == "replace":
+            orig_ranges.append((orig_pos, orig_pos + orig_span, "replace_"))
+            edit_ranges.append((edit_pos, edit_pos + edit_span, "replace_"))
+
+        orig_pos += orig_span
+        edit_pos += edit_span
+
+    return orig_ranges, edit_ranges

artifice_draft/_track_changes.py

@@ -0,0 +1,170 @@
+# SPDX-FileCopyrightText: 2026 Maurice Casey
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Apply tracked insertions/deletions to a .docx using docx-revisions.
+
+Uses the document-level API from ``docx_revisions``: each edit is applied via
+``RevisionDocument.find_and_replace_tracked``, producing real
+<w:ins>/<w:del> revision elements and persisting them when the file is saved.
+
+Each paragraph's edit is applied as a separate call so that different edits
+can target different paragraphs independently, while still producing a single
+revision document with all changes tracked under one author.
+
+Paragraphs containing inline images (<w:drawing>) are handled by temporarily
+removing drawings before the text replacement and re-injecting them into the
+resulting <w:ins> element so that images survive the edit.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import tempfile
+
+from docx_revisions import RevisionDocument
+
+from artifice_draft.write_utils import write_plain_docx
+
+logger = logging.getLogger(__name__)
+
+NSMAP = {
+    "w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main",
+    "a": "http://schemas.openxmlformats.org/drawingml/2006/main",
+    "pic": "http://schemas.openxmlformats.org/drawingml/2006/picture",
+    "wp": "http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing",
+}
+
+
+def _paragraph_has_drawing(para_elem) -> bool:
+    return len(para_elem.findall(".//w:drawing", NSMAP)) > 0
+
+
+def _remove_drawings(para_elem):
+    """Remove all <w:drawing> elements from a paragraph XML element.
+
+    Returns the list of extracted drawing LXML elements so they can be
+    re-injected later.
+    """
+    drawings = para_elem.findall(".//w:drawing", NSMAP)
+    clones = []
+    for d in drawings:
+        parent = d.getparent()
+        if parent is not None:
+            clones.append(d)
+            parent.remove(d)
+    return clones
+
+
+def _reinject_drawings_into_ins(para_elem, clones) -> None:
+    """Re-inject drawing elements into the first <w:ins><w:r> found."""
+    if not clones:
+        return
+    ins_elements = para_elem.findall(".//w:ins", NSMAP)
+    for ins in ins_elements:
+        runs = ins.findall("w:r", NSMAP)
+        if runs:
+            target_run = runs[0]
+            for clone in clones:
+                target_run.append(clone)
+            return
+
+
+def _apply_edit_preserving_images(
+    rdoc,
+    original: str,
+    edited_text: str,
+    author: str,
+) -> None:
+    """Replace text in a paragraph while preserving inline drawings."""
+    for para in rdoc._iter_all_paragraphs():
+        if para.text.strip() != original:
+            continue
+
+        para_elem = para._element
+        if not _paragraph_has_drawing(para_elem):
+            rdoc.find_and_replace_tracked(
+                search_text=original,
+                replace_text=edited_text,
+                author=author,
+            )
+            return
+
+        clones = _remove_drawings(para_elem)
+        rdoc.find_and_replace_tracked(
+            search_text=original,
+            replace_text=edited_text,
+            author=author,
+        )
+        _reinject_drawings_into_ins(para_elem, clones)
+        return
+
+
+def apply_track_changes_to_docx(
+    input_path: str | None,
+    paragraphs: list[dict],
+    changes: dict[int, str],
+    output_path: str,
+    author: str = "ArtificeDraft",
+) -> None:
+    """Apply tracked changes to a .docx file using docx-revisions.
+
+    Args:
+        input_path: path to the original .docx (loaded for find_and_replace_tracked).
+                    If ``None``, reconstructs from paragraph data via a temp file.
+        paragraphs: List of paragraph dicts from doc_parser.parse_docx().
+        changes: Dict mapping paragraph index to the replacement text.
+        output_path: path for the resulting .docx
+        author: author name shown in tracked changes (default: "ArtificeDraft").
+    """
+    if not changes:
+        return
+
+    tmp_path = None
+    try:
+        if input_path:
+            logger.debug("Loading original document: %s", input_path)
+            rdoc = RevisionDocument(input_path)
+        else:
+            tmp_path = tempfile.mktemp(suffix=".docx")
+            logger.debug("No input_path; writing temp plain docx to %s", tmp_path)
+            write_plain_docx(paragraphs, tmp_path)
+            rdoc = RevisionDocument(tmp_path)
+
+        for i, entry in enumerate(paragraphs):
+            original = entry["text"]
+            edited_text = changes.get(i)
+
+            if edited_text is not None:
+                has_imgs = bool(entry.get("images"))
+                if has_imgs and input_path:
+                    logger.debug(
+                        "Applying edit with image preservation on paragraph %d", i
+                    )
+                    _apply_edit_preserving_images(
+                        rdoc, original, edited_text, author,
+                    )
+                else:
+                    logger.debug(
+                        "Replacing paragraph %d: %r → %r",
+                        i,
+                        original[:50],
+                        edited_text[:50],
+                    )
+                    rdoc.find_and_replace_tracked(
+                        search_text=original,
+                        replace_text=edited_text,
+                        author=author,
+                    )
+
+        rdoc.save(output_path)
+        logger.info("Saved tracked-changes document to %s", output_path)
+    finally:
+        if tmp_path and os.path.exists(tmp_path):
+            os.remove(tmp_path)
+            logger.debug("Cleaned up temp file: %s", tmp_path)
+
+
+if __name__ == "__main__":
+    print("Track changes module — used internally by doc_writer.py")

artifice_draft/abbreviations.py

@@ -0,0 +1,70 @@
+# SPDX-FileCopyrightText: 2026 Maurice Casey
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Abbreviation extraction and validation module for academic papers."""
+
+from __future__ import annotations
+
+import re
+from typing import TypedDict
+
+
+class AbbreviationIssue(TypedDict):
+    paragraph_index: int
+    abbreviation: str
+    message: str
+
+
+def check_abbreviations(paragraphs: list[dict]) -> list[AbbreviationIssue]:
+    """Scan paragraphs for uppercase abbreviations (2-6 letters) and verify
+
+    whether they are introduced with a definition on first use.
+    """
+    issues: list[AbbreviationIssue] = []
+    seen_defs: set[str] = set()
+
+    # Pattern for uppercase acronyms: 2 to 6 capital letters
+    acronym_pattern = re.compile(r'\b[A-Z]{2,6}\b')
+
+    for entry in paragraphs:
+        text = entry.get("text", "")
+        idx = entry.get("paragraph_index", 0)
+
+        matches = acronym_pattern.findall(text)
+        for acr in matches:
+            # Common false positives in academic writing
+            if acr in {"I", "A", "THE", "AND", "FOR", "BUT", "OR", "IN", "ON", "BY", "WITH"}:
+                continue
+
+            # Check if defined in this paragraph or earlier
+            # Definition pattern: "Full Name (ACR)" or "ACR (Full Name)"
+            def_pattern1 = re.compile(rf'.*?\(({acr})\)')
+            def_pattern2 = re.compile(rf'({acr})\s+\(.*?\)')
+
+            if acr in seen_defs:
+                continue
+
+            if def_pattern1.search(text) or def_pattern2.search(text):
+                seen_defs.add(acr)
+            else:
+                # If not seen yet and not defined here, flag it as potentially undefined
+                # (unless it's a very standard abbreviation like US, UK, etc.)
+                if acr not in {"US", "UK", "EU", "UN", "BCE", "CE", "AD", "BC"}:
+                    # Check if defined later or earlier across document
+                    is_defined_elsewhere = False
+                    for other in paragraphs:
+                        otext = other.get("text", "")
+                        if def_pattern1.search(otext) or def_pattern2.search(otext):
+                            is_defined_elsewhere = True
+                            break
+
+                    if not is_defined_elsewhere and acr not in seen_defs:
+                        seen_defs.add(acr) # Report once per document to avoid spam
+                        issues.append({
+                            "paragraph_index": idx,
+                            "abbreviation": acr,
+                            "message": f"Abbreviation '{acr}' used without explicit definition/expansion.",
+                        })
+
+    return issues

artifice_draft/accessibility.py

@@ -0,0 +1,55 @@
+# SPDX-FileCopyrightText: 2026 Maurice Casey
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Accessibility and structural document hierarchy checker."""
+
+from __future__ import annotations
+
+from typing import TypedDict
+
+
+class AccessibilityIssue(TypedDict):
+    paragraph_index: int
+    issue_type: str
+    message: str
+
+
+def check_accessibility(paragraphs: list[dict]) -> list[AccessibilityIssue]:
+    """Check heading hierarchy (no skipped levels like Heading 1 to Heading 3)
+
+    and verify images have descriptions/alt text where applicable.
+    """
+    issues: list[AccessibilityIssue] = []
+    last_heading_level = 0
+
+    for entry in paragraphs:
+        idx = entry.get("paragraph_index", 0)
+        style_name = entry.get("style_name", "")
+        images = entry.get("images", [])
+
+        # Check heading hierarchy
+        if style_name.startswith("Heading "):
+            try:
+                level = int(style_name.replace("Heading ", ""))
+                if last_heading_level > 0 and level > last_heading_level + 1:
+                    issues.append({
+                        "paragraph_index": idx,
+                        "issue_type": "heading_hierarchy",
+                        "message": f"Skipped heading level: Heading {level} follows Heading {last_heading_level}.",
+                    })
+                last_heading_level = level
+            except ValueError:
+                pass
+
+        # Check images for alt text / descriptions
+        if images:
+            for img in images:
+                if not img.get("description"):
+                    issues.append({
+                        "paragraph_index": idx,
+                        "issue_type": "missing_alt_text",
+                        "message": f"Embedded image '{img.get('filename', 'unknown')}' lacks descriptive alt text for accessibility.",
+                    })
+
+    return issues

artifice_draft/archival_refs.py

@@ -0,0 +1,113 @@
+# SPDX-FileCopyrightText: 2026 Maurice Casey
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Archival citation format validation."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from artifice_draft.style_guides import load_guide
+
+# Patterns for common archival citation elements
+_ARCHIVE_RE = re.compile(
+    r"\b(archive|archives|repository|fonds|collection|group|series)\b",
+    re.IGNORECASE,
+)
+
+_BOX_FOLDER_RE = re.compile(
+    r"\b(Box|Folders?|File|Item|Folder)\s+[\d\w]",
+    re.IGNORECASE,
+)
+
+_DATE_PATTERN_RE = re.compile(
+    r"\b\d{1,2}\s+(?:January|February|March|April|May|June|July|August|"
+    r"September|October|November|December)\s+\d{4}\b",
+    re.IGNORECASE,
+)
+
+# Patterns suggesting an incomplete archival reference
+_INCOMPLETE_RE = re.compile(
+    r"(?:Box|Folders?|File)\s+\d+",
+    re.IGNORECASE,
+)
+
+_REPOSITORY_ABBREVS = re.compile(
+    r"\b(NARA|TNA|PRO|LC|LOC|Yale|Harvard|Princeton|Columbia)\b"
+)
+
+
+@dataclass
+class ArchivalAdvisory:
+    """A single archival reference advisory."""
+
+    paragraph_index: int
+    rule: str
+    message: str
+    severity: str  # "warning" | "info"
+    suggested_fix: str | None = None
+
+
+def check_archival_refs(
+    paragraphs: list[dict],
+    guide_name: str = "",
+) -> list[ArchivalAdvisory]:
+    """Check archival citation formatting.
+
+    Validates that archival references include the essential components:
+    repository name, collection/fonds, box/folder, and date.
+
+    Args:
+        paragraphs: Parsed paragraph dicts from doc_parser.
+        guide_name: Name of the active style guide.
+
+    Returns:
+        List of ArchivalAdvisory objects.
+    """
+    advisories: list[ArchivalAdvisory] = []
+
+    for para in paragraphs:
+        idx = para["paragraph_index"]
+        text = para["text"]
+
+        has_box_folder = bool(_BOX_FOLDER_RE.search(text))
+        has_date = bool(_DATE_PATTERN_RE.search(text))
+        has_archive_word = bool(_ARCHIVE_RE.search(text))
+        has_repository = bool(_REPOSITORY_ABBREVS.search(text))
+
+        # If a box/folder reference exists but no date
+        if has_box_folder and not has_date:
+            advisories.append(ArchivalAdvisory(
+                paragraph_index=idx,
+                rule="archival_missing_date",
+                message="Archival reference includes box/folder but no date — add the date range of the materials.",
+                severity="warning",
+            ))
+
+        # If archival language is used but no repository name
+        if has_archive_word and not has_repository and not has_box_folder:
+            advisories.append(ArchivalAdvisory(
+                paragraph_index=idx,
+                rule="archival_missing_repository",
+                message="Reference mentions archives but does not identify the repository — add the full repository name.",
+                severity="info",
+            ))
+
+        # If box/folder is referenced without a collection name
+        if has_box_folder and not has_archive_word and not has_repository:
+            # Check if there's context that looks like a collection name nearby
+            box_match = _INCOMPLETE_RE.search(text)
+            if box_match:
+                advisories.append(ArchivalAdvisory(
+                    paragraph_index=idx,
+                    rule="archival_incomplete_reference",
+                    message=(
+                        f"Archival reference near '{box_match.group()}' may be incomplete — "
+                        f"include repository name, collection name, and date."
+                    ),
+                    severity="info",
+                ))
+
+    return advisories

artifice_draft/captions.py

@@ -0,0 +1,68 @@
+# SPDX-FileCopyrightText: 2026 Maurice Casey
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Figure and table caption normalization and validation module."""
+
+from __future__ import annotations
+
+import re
+from typing import TypedDict
+
+
+class CaptionIssue(TypedDict):
+    paragraph_index: int
+    caption_type: str
+    message: str
+
+
+def check_captions(paragraphs: list[dict]) -> list[CaptionIssue]:
+    """Validate figure and table captions for consistent numbering and style."""
+    issues: list[CaptionIssue] = []
+
+    fig_pattern = re.compile(r'^(Figure|Fig\.?)\s+(\d+)', re.IGNORECASE)
+    table_pattern = re.compile(r'^(Table|Tab\.?)\s+(\d+)', re.IGNORECASE)
+
+    fig_numbers: list[int] = []
+    table_numbers: list[int] = []
+
+    for entry in paragraphs:
+        text = entry.get("text", "").strip()
+        idx = entry.get("paragraph_index", 0)
+
+        f_match = fig_pattern.match(text)
+        if f_match:
+            num = int(f_match.group(2))
+            fig_numbers.append(num)
+            # Check style prefix
+            prefix = f_match.group(1)
+            if prefix.lower() == "fig" and not prefix.endswith("."):
+                issues.append({
+                    "paragraph_index": idx,
+                    "caption_type": "figure",
+                    "message": f"Abbreviated figure prefix '{prefix}' should include a period ('Fig.') or be spelled out ('Figure').",
+                })
+
+        t_match = table_pattern.match(text)
+        if t_match:
+            num = int(t_match.group(2))
+            table_numbers.append(num)
+
+    # Check for sequential numbering
+    for i in range(1, len(fig_numbers)):
+        if fig_numbers[i] != fig_numbers[i - 1] + 1:
+            issues.append({
+                "paragraph_index": -1,
+                "caption_type": "figure",
+                "message": f"Figure numbers are not strictly sequential: found {fig_numbers[i-1]} followed by {fig_numbers[i]}.",
+            })
+
+    for i in range(1, len(table_numbers)):
+        if table_numbers[i] != table_numbers[i - 1] + 1:
+            issues.append({
+                "paragraph_index": -1,
+                "caption_type": "table",
+                "message": f"Table numbers are not strictly sequential: found {table_numbers[i-1]} followed by {table_numbers[i]}.",
+            })
+
+    return issues