extract-cli 0.1.3__tar.gz → 0.1.5__tar.gz

{extract_cli-0.1.3 → extract_cli-0.1.5}/ARCHITECTURE.md

@@ -80,7 +80,12 @@ endpoint. Any failure (no config, network error, unparseable JSON) is caught:
 a warning to stderr, deterministic output untouched. The LLM only *adds* fuzzy
 fields (`term.renewal_mechanics`, `obligations`) and fills `governing_law` only
 when the deterministic tier found nothing — it never overwrites a deterministic
-value.
+value. As a **clause-map fallback**, when the deterministic cascade returned no
+clauses the LLM is asked for the section headings (the clause keys are added to
+the prompt only then); the titles are normalized through the same
+`_canonicalize_clause` vocabulary, located in the text for a best-effort span,
+and emitted with `tier: "llm"` / `source: "llm"`. This covers DOCX that
+auto-number with no heading style (their numbers live only in `numbering.xml`).
 
 ## The output contract
 

{extract_cli-0.1.3 → extract_cli-0.1.5}/CHANGELOG.md

@@ -6,6 +6,47 @@ to [Semantic Versioning](https://semver.org/). Per the suite convention
 (see [`docs/INTEROP.md`](docs/INTEROP.md)), **backward-incompatible changes to
 the output schema require a major version bump**; new optional fields are minor.
 
+## [0.1.5] - 2026-05-21
+
+### Added
+- **LLM clause-map fallback** (opt-in, `--llm` only). When the deterministic
+  cascade detects no clauses — e.g. a `.docx` that auto-numbers via Word's
+  numbering with no heading style, the limitation noted in 0.1.4 — the LLM is
+  asked for the section headings (the clause request is added to the prompt
+  only in that case). Returned titles are normalized through the same canonical
+  vocabulary as the deterministic path, located in the document for a
+  best-effort span, and emitted with `tier: "llm"`, `source: "llm"`, and a
+  modest confidence. The LLM is never consulted for clauses the deterministic
+  cascade already found, and the deterministic core remains fully useful with
+  no LLM. No schema change (the clause `tier`/`source` enums already allow
+  `llm`).
+
+## [0.1.4] - 2026-05-21
+
+DOCX clause detection, driven by testing against 20 real `.docx` contracts
+(Common Paper / Bonterms / YC templates via open-agreements, plus government
+samples) — the format we expect most.
+
+### Fixed
+- **The DOCX reader now honors Word heading styles.** Real Word contracts carry
+  their clause structure in `Heading1`–`Heading9`/`Title` paragraph styles with
+  *auto-generated* numbers (absent from the raw text), so the prior cascade
+  found almost no clauses. Heading-styled paragraphs are now emitted as `##`
+  headings (detected by the strongest tier); run-in headings
+  (`Payment.  Customer will pay …`) are split into title + body, and a full
+  sentence that merely carries a heading style is rejected (not a clause).
+  Across the 20-doc sample this took heading-styled agreements from ~0 clauses
+  to a clean 14–21 distinct suite-vocabulary clauses each.
+- Binary DOCX test fixtures are now generated deterministically (fixed zip
+  timestamp) so their sha256 — and the goldens — are stable across regenerations.
+
+### Known limitations (documented)
+- DOCX that auto-number clauses via `numbering.xml` with **no heading style and
+  no bold lead** (some Bonterms/older templates use a flat `Plain`/`ListParagraph`
+  style) still yield no clause map: the heading text carries no detectable
+  signal without reconstructing Word's numbering counters. Parties/dates/
+  governing-law still extract.
+
 ## [0.1.3] - 2026-05-21
 
 Clause-map de-noising and party cleanup, driven by testing against 10 more
@@ -140,6 +181,8 @@ Initial release — the open-loop front door of the contract-ops CLI suite.
   intentionally *not* governed by the output schema (the schema describes the
   full default output).
 
+[0.1.5]: https://github.com/DrBaher/extract-cli/releases/tag/v0.1.5
+[0.1.4]: https://github.com/DrBaher/extract-cli/releases/tag/v0.1.4
 [0.1.3]: https://github.com/DrBaher/extract-cli/releases/tag/v0.1.3
 [0.1.2]: https://github.com/DrBaher/extract-cli/releases/tag/v0.1.2
 [0.1.1]: https://github.com/DrBaher/extract-cli/releases/tag/v0.1.1

{extract_cli-0.1.3 → extract_cli-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: extract-cli
-Version: 0.1.3
+Version: 0.1.5
 Summary: Open-loop front door of the contract-ops CLI suite: ingest any contract (.md/.txt/.html/.docx/.pdf) and emit structured JSON.
 Project-URL: Homepage, https://cli.drbaher.com/
 Project-URL: Repository, https://github.com/DrBaher/extract-cli
@@ -102,6 +102,15 @@ opt-in, never in a hot path, and gated behind an explicit flag and a config
 file — if no config is present, `--llm` degrades gracefully with a warning and
 you still get the full deterministic output.
 
+**Clause-map fallback.** Some documents (e.g. `.docx` that auto-number clauses
+via Word's numbering with no heading style) carry no signal the deterministic
+cascade can see, so its clause map comes back empty. When `--llm` is set *and*
+no clauses were detected, the LLM is asked for the section headings; the result
+is normalized through the same canonical vocabulary and emitted with
+`tier: "llm"`, `source: "llm"`, and a modest confidence (verify, not trust).
+When the deterministic cascade already found clauses, the LLM is not consulted
+for them.
+
 ## Commands
 
 ```bash

{extract_cli-0.1.3 → extract_cli-0.1.5}/README.md

@@ -64,6 +64,15 @@ opt-in, never in a hot path, and gated behind an explicit flag and a config
 file — if no config is present, `--llm` degrades gracefully with a warning and
 you still get the full deterministic output.
 
+**Clause-map fallback.** Some documents (e.g. `.docx` that auto-number clauses
+via Word's numbering with no heading style) carry no signal the deterministic
+cascade can see, so its clause map comes back empty. When `--llm` is set *and*
+no clauses were detected, the LLM is asked for the section headings; the result
+is normalized through the same canonical vocabulary and emitted with
+`tier: "llm"`, `source: "llm"`, and a modest confidence (verify, not trust).
+When the deterministic cascade already found clauses, the LLM is not consulted
+for them.
+
 ## Commands
 
 ```bash

{extract_cli-0.1.3 → extract_cli-0.1.5}/extract_cli.py

@@ -43,11 +43,11 @@ import urllib.request
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple
 
-__version__ = "0.1.3"
+__version__ = "0.1.5"
 
 # Bumped independently of the package version when the *extraction logic*
 # changes in a way downstream consumers should notice. Embedded in `_meta`.
-EXTRACTOR_VERSION = "0.1.3"
+EXTRACTOR_VERSION = "0.1.5"
 
 # JSON Schema version of the output contract (docs/spec/extract-output.schema.json).
 SCHEMA_VERSION = 1
@@ -950,6 +950,39 @@ def _read_docx(path: Path, raw: bytes, prefer_optional: bool = True) -> Tuple[st
         return "", warnings
 
 
+def _docx_paragraph_style(ppr: Any, w: str) -> Optional[str]:
+    if ppr is None:
+        return None
+    st = ppr.find(w + "pStyle")
+    return st.get(w + "val") if st is not None else None
+
+
+def _is_heading_style(style: Optional[str]) -> bool:
+    """True for Word built-in heading/title styles (Heading1-9, Title, and the
+    'H1'/'H2' shorthands). These mark clause headings whose visible numbers are
+    auto-generated and absent from the raw text."""
+    if not style:
+        return False
+    s = style.lower()
+    return "heading" in s or s == "title" or bool(re.fullmatch(r"h[1-9]", s))
+
+
+def _docx_heading_title(text: str) -> Optional[str]:
+    """Pull the clause title out of a heading paragraph. Many contracts use a
+    run-in heading -- 'Performing Services.  Contractor will ...' -- where the
+    title is the lead before the first sentence break; a standalone header
+    ('Services & Restrictions') has no such break and is used whole.
+
+    Returns None when the paragraph is really a full sentence that merely
+    carries a heading style (no run-in title) -- those would otherwise become
+    garbage clause titles and mis-map under substring matching."""
+    m = re.match(r"\s*(.{2,80}?)[.:]\s+[A-Z(\"“]", text)
+    title = m.group(1).strip() if m else text.strip()
+    if len(title) > 70 or len(title.split()) > 9:
+        return None
+    return title
+
+
 def _read_docx_stdlib(raw: bytes) -> str:
     import io
     import zipfile
@@ -962,6 +995,7 @@ def _read_docx_stdlib(raw: bytes) -> str:
     paras: List[str] = []
     # iter over w:p in document order (includes paragraphs inside table cells).
     for p in root.iter(w + "p"):
+        style = _docx_paragraph_style(p.find(w + "pPr"), w)
         run_texts: List[str] = []
         any_text = False
         all_bold = True
@@ -978,6 +1012,17 @@ def _read_docx_stdlib(raw: bytes) -> str:
         if not line:
             paras.append("")
             continue
+        # Word heading styles carry the clause structure (their numbers are
+        # auto-generated, so absent from text). Emit them as H2 so the clause
+        # cascade's strongest tier detects them; keep any run-in body too.
+        if _is_heading_style(style):
+            title = _docx_heading_title(line)
+            if title is not None:
+                paras.append(f"## {title}")
+                if len(title) < len(line):
+                    paras.append(line[len(title):].lstrip(" .:\t"))
+                continue
+            # Sentence carrying a heading style -> treat as ordinary body text.
         if any_text and all_bold:
             line = f"**{line}**"
         paras.append(line)
@@ -1230,15 +1275,29 @@ def load_llm_config() -> Optional[JSON]:
     return None
 
 
-_LLM_PROMPT = (
-    "You are a contract-extraction assistant. Given the contract text, return "
-    "ONLY a compact JSON object with keys: renewal_mechanics (string or null), "
-    "obligations (array of short strings, max 5), governing_law (string or "
-    "null). Base answers strictly on the text. No prose, JSON only.\n\n"
-    "CONTRACT:\n"
+_LLM_PROMPT_KEYS = (
+    "renewal_mechanics (string or null), obligations (array of short strings, "
+    "max 5), governing_law (string or null)"
+)
+# Requested only when the deterministic clause cascade found nothing (e.g. a
+# DOCX that auto-numbers with no heading style): ask the model for the section
+# headings so we can still produce a clause map.
+_LLM_PROMPT_CLAUSES = (
+    ", clauses (array, max 40, of objects {\"title\": \"<the section/clause "
+    "heading, verbatim if possible>\"} in document order, top-level sections "
+    "only)"
 )
 
 
+def _build_llm_prompt(text: str, want_clauses: bool) -> str:
+    keys = _LLM_PROMPT_KEYS + (_LLM_PROMPT_CLAUSES if want_clauses else "")
+    return (
+        "You are a contract-extraction assistant. Given the contract text, "
+        "return ONLY a compact JSON object with keys: " + keys + ". Base answers "
+        "strictly on the text. No prose, JSON only.\n\nCONTRACT:\n" + text[:16000]
+    )
+
+
 def _llm_request(cfg: JSON, prompt: str, timeout: float = 30.0) -> Optional[str]:
     provider = str(cfg.get("provider", "anthropic")).lower()
     model = cfg.get("model") or ("claude-sonnet-4-6" if provider == "anthropic" else "gpt-4o-mini")
@@ -1292,8 +1351,44 @@ def _extract_json_object(s: str) -> Optional[JSON]:
         return None
 
 
+def _llm_clause_map(raw: Any, text: str) -> List[JSON]:
+    """Convert LLM-returned clause titles into schema-conformant clause objects.
+    Titles are canonicalized through the same suite vocabulary the deterministic
+    path uses, located in the document for a best-effort span, and marked
+    tier/source = 'llm' with a modest confidence (verify, not trust)."""
+    if not isinstance(raw, list):
+        return []
+    low = text.lower()
+    out: List[JSON] = []
+    seen: set[str] = set()
+    for item in raw[:40]:
+        title: Any = item.get("title") if isinstance(item, dict) else item
+        if not isinstance(title, str) or not title.strip():
+            continue
+        title = re.sub(r"\s+", " ", title.strip())
+        key = _norm_clause_key(title)
+        if not key or key in seen or _is_noise_clause_title(title):
+            continue
+        seen.add(key)
+        canonical, mapped = _canonicalize_clause(title)
+        idx = low.find(title.lower())
+        span = ({"start": idx, "end": min(idx + len(title), len(text))}
+                if idx >= 0 else {"start": 0, "end": 0})
+        out.append({
+            "canonical_title": canonical,
+            "detected_title": title,
+            "tier": "llm",
+            "span": span,
+            "confidence": 0.5,
+            "source": "llm",
+            "mapped": mapped,
+        })
+    return out
+
+
 def llm_enrich(result: JSON, text: str, args_ns: argparse.Namespace) -> None:
-    """Opt-in enrichment of fuzzy fields. Mutates `result` in place. Any
+    """Opt-in enrichment of fuzzy fields, plus a clause-map fallback when the
+    deterministic cascade found no clauses. Mutates `result` in place. Any
     failure (no config, network error, bad JSON) degrades gracefully: a warning
     to stderr and the deterministic output is left untouched."""
     cfg = load_llm_config()
@@ -1301,7 +1396,8 @@ def llm_enrich(result: JSON, text: str, args_ns: argparse.Namespace) -> None:
         _warn(args_ns, "no LLM config found (~/.config/contract-ops/llm.json or "
                        "./config/llm.json); skipping --llm enrichment")
         return
-    prompt = _LLM_PROMPT + text[:12000]
+    want_clauses = not result["clauses"]
+    prompt = _build_llm_prompt(text, want_clauses)
     try:
         raw = _llm_request(cfg, prompt)
     except (urllib.error.URLError, TimeoutError, OSError, ValueError) as e:
@@ -1331,6 +1427,11 @@ def llm_enrich(result: JSON, text: str, args_ns: argparse.Namespace) -> None:
     if isinstance(gl, str) and gl.strip() and result["governing_law"]["source"] == "none":
         result["governing_law"] = _field(gl.strip(), 0.6, "llm")
         enriched = True
+    if want_clauses:
+        cmap = _llm_clause_map(obj.get("clauses"), text)
+        if cmap:
+            result["clauses"] = cmap
+            enriched = True
 
     result["_meta"]["llm_used"] = True
     if enriched and "llm" not in result["_meta"]["tiers_used"]:
@@ -1613,7 +1714,8 @@ FIELD_CATALOG: Tuple[Tuple[str, str, str], ...] = (
     ("term.notice_period_days", "deterministic", "Notice period in days, best-effort"),
     ("term.auto_renew", "deterministic", "Auto-renewal flag, best-effort"),
     ("governing_law", "deterministic", "Governing law / jurisdiction"),
-    ("clauses", "deterministic", "Clause map normalized to the suite's canonical vocabulary"),
+    ("clauses", "deterministic", "Clause map normalized to the suite's canonical vocabulary "
+                                 "(LLM fallback under --llm when no headings are detected)"),
     ("defined_terms", "deterministic", "Defined-term inventory (quoted / parenthetical)"),
     ("value", "deterministic", "Headline monetary value"),
     ("term.renewal_mechanics", "llm", "Renewal mechanics (fuzzy; --llm only)"),

{extract_cli-0.1.3 → extract_cli-0.1.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "extract-cli"
-version = "0.1.3"
+version = "0.1.5"
 description = "Open-loop front door of the contract-ops CLI suite: ingest any contract (.md/.txt/.html/.docx/.pdf) and emit structured JSON."
 readme = "README.md"
 requires-python = ">=3.9"

{extract_cli-0.1.3 → extract_cli-0.1.5}/tests/_fixtures_build.py

@@ -42,14 +42,36 @@ _DOCX_PARAS = [
 _W = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
 
 
-def _docx_paragraph(text: str, bold: bool) -> str:
+def _docx_paragraph(text: str, bold: bool = False, style: str = "") -> str:
+    ppr = f'<w:pPr><w:pStyle w:val="{style}"/></w:pPr>' if style else ""
     rpr = "<w:rPr><w:b/></w:rPr>" if bold else ""
-    return (f"<w:p><w:r>{rpr}"
+    return (f"<w:p>{ppr}<w:r>{rpr}"
             f'<w:t xml:space="preserve">{escape(text)}</w:t></w:r></w:p>')
 
 
-def build_docx() -> bytes:
-    body = "".join(_docx_paragraph(t, b) for t, b in _DOCX_PARAS)
+# A Word-styled agreement: clause structure carried by Heading1 styles (their
+# numbers are auto-generated, absent from text), including a run-in heading and
+# a full sentence that merely carries the heading style (must be rejected).
+_HEADING_DOCX_PARAS = [
+    ('Cloud Service Agreement', False, "Title"),
+    ('This Cloud Service Agreement is entered into as of April 4, 2024, by and '
+     'between Initech Software, Inc. (the "Provider") and Globex Corporation '
+     '(the "Customer").', False, ""),
+    ('Confidentiality', False, "Heading1"),
+    ('Each party will protect the other party’s Confidential Information.', False, ""),
+    ('Payment.  Customer will pay the fees set out in the Order Form within '
+     'thirty (30) days.', False, "Heading1"),
+    ('Term & Termination', False, "Heading1"),
+    ('The term of this Agreement is two (2) years and will automatically renew '
+     'for successive one-year terms.', False, ""),
+    ('Either party may terminate this Agreement upon material breach that '
+     'remains uncured for thirty days after written notice.', False, "Heading1"),
+    ('Governing Law', False, "Heading1"),
+    ('This Agreement is governed by the laws of the State of New York.', False, ""),
+]
+
+
+def _docx_package(body: str) -> bytes:
     document = (
         '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
         f'<w:document xmlns:w="{_W}"><w:body>{body}<w:sectPr/></w:body></w:document>'
@@ -70,14 +92,29 @@ def build_docx() -> bytes:
         'Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" '
         'Target="word/document.xml"/></Relationships>'
     )
+    # Deterministic: a fixed timestamp on every entry so regenerating the
+    # fixture produces byte-identical output (stable sha256 -> stable goldens).
     buf = io.BytesIO()
     with zipfile.ZipFile(buf, "w", zipfile.ZIP_DEFLATED) as z:
-        z.writestr("[Content_Types].xml", content_types)
-        z.writestr("_rels/.rels", rels)
-        z.writestr("word/document.xml", document)
+        for name, data in (("[Content_Types].xml", content_types),
+                           ("_rels/.rels", rels),
+                           ("word/document.xml", document)):
+            info = zipfile.ZipInfo(name, date_time=(1980, 1, 1, 0, 0, 0))
+            info.compress_type = zipfile.ZIP_DEFLATED
+            z.writestr(info, data)
     return buf.getvalue()
 
 
+def build_docx() -> bytes:
+    return _docx_package("".join(_docx_paragraph(t, b) for t, b in _DOCX_PARAS))
+
+
+def build_heading_docx() -> bytes:
+    return _docx_package(
+        "".join(_docx_paragraph(t, b, style=s) for t, b, s in _HEADING_DOCX_PARAS)
+    )
+
+
 # --- PDF: a software license with ALL-CAPS headings (Tier 3) ----------------
 
 _PDF_TEXT = """SOFTWARE LICENSE AGREEMENT
@@ -156,6 +193,7 @@ def build_scanned_pdf() -> bytes:
 
 _BINARY_FIXTURES = {
     "employment_docx.docx": build_docx,
+    "heading_docx.docx": build_heading_docx,
     "license_pdf.pdf": build_pdf,
     "scanned.pdf": build_scanned_pdf,
 }

{extract_cli-0.1.3 → extract_cli-0.1.5}/tests/_make_goldens.py

@@ -20,8 +20,8 @@ from tests._fixtures_build import ensure_binary_fixtures  # noqa: E402
 FIXTURES = Path(__file__).resolve().parent / "fixtures"
 
 DOCS = ["nda_h2.md", "services_bold.txt", "lease_allcaps.txt",
-        "employment_docx.docx", "license_pdf.pdf", "services_html.html",
-        "scanned.pdf"]
+        "employment_docx.docx", "heading_docx.docx", "license_pdf.pdf",
+        "services_html.html", "scanned.pdf"]
 
 
 def golden_for(name: str) -> dict:

{extract_cli-0.1.3 → extract_cli-0.1.5}/tests/conftest.py

@@ -25,6 +25,7 @@ CORPUS: Tuple[Tuple[str, str, str], ...] = (
     ("services_bold.txt", "bold-numbered", "text"),
     ("lease_allcaps.txt", "all-caps", "text"),
     ("employment_docx.docx", "bold-numbered", "docx"),
+    ("heading_docx.docx", "h2", "docx"),
     ("license_pdf.pdf", "all-caps", "pdf"),
     ("services_html.html", "numbered", "html"),
 )

{extract_cli-0.1.3 → extract_cli-0.1.5}/tests/fixtures/employment_docx.docx.expected.json

@@ -2,7 +2,7 @@
   "document": {
     "title": "EMPLOYMENT AGREEMENT",
     "format": "docx",
-    "sha256": "1ba94a7bfd5a32a6d080cc6704cefb786e26dc16a8985857d562182da5f7298f",
+    "sha256": "f50e4b9b0cb77250280eb4c26225009de063b5f4a2318e9e53784d3730d20bd1",
     "source_path": "employment_docx.docx"
   },
   "parties": [
@@ -138,7 +138,7 @@
     "source": "deterministic"
   },
   "_meta": {
-    "extractor_version": "0.1.3",
+    "extractor_version": "0.1.5",
     "tiers_used": [
       "deterministic"
     ],

extract_cli-0.1.5/tests/fixtures/heading_docx.docx.expected.json

@@ -0,0 +1,142 @@
+{
+  "document": {
+    "title": "Cloud Service Agreement",
+    "format": "docx",
+    "sha256": "23a3b14196cdca6b58d14c7a6836fe28ff6d2be6c2fd852badb03ab6b6e84056",
+    "source_path": "heading_docx.docx"
+  },
+  "parties": [
+    {
+      "name": "Initech Software, Inc.",
+      "confidence": 0.9,
+      "source": "deterministic",
+      "role": "Provider"
+    },
+    {
+      "name": "Globex Corporation",
+      "confidence": 0.9,
+      "source": "deterministic",
+      "role": "Customer"
+    }
+  ],
+  "dates": {
+    "effective": {
+      "value": "2024-04-04",
+      "confidence": 0.85,
+      "source": "deterministic"
+    },
+    "expiration": {
+      "value": null,
+      "confidence": 0.0,
+      "source": "none"
+    }
+  },
+  "term": {
+    "length": {
+      "value": "2 years",
+      "confidence": 0.7,
+      "source": "deterministic"
+    },
+    "auto_renew": {
+      "value": true,
+      "confidence": 0.65,
+      "source": "deterministic"
+    },
+    "notice_period_days": {
+      "value": null,
+      "confidence": 0.0,
+      "source": "none"
+    }
+  },
+  "governing_law": {
+    "value": "State of New York",
+    "confidence": 0.85,
+    "source": "deterministic"
+  },
+  "clauses": [
+    {
+      "canonical_title": "Cloud Service Agreement",
+      "detected_title": "## Cloud Service Agreement",
+      "tier": "h2",
+      "span": {
+        "start": 0,
+        "end": 191
+      },
+      "confidence": 0.71,
+      "source": "deterministic",
+      "mapped": false
+    },
+    {
+      "canonical_title": "Confidentiality",
+      "detected_title": "## Confidentiality",
+      "tier": "h2",
+      "span": {
+        "start": 191,
+        "end": 280
+      },
+      "confidence": 0.95,
+      "source": "deterministic",
+      "mapped": true
+    },
+    {
+      "canonical_title": "Payment",
+      "detected_title": "## Payment",
+      "tier": "h2",
+      "span": {
+        "start": 280,
+        "end": 371
+      },
+      "confidence": 0.95,
+      "source": "deterministic",
+      "mapped": true
+    },
+    {
+      "canonical_title": "Termination",
+      "detected_title": "## Term & Termination",
+      "tier": "h2",
+      "span": {
+        "start": 371,
+        "end": 622
+      },
+      "confidence": 0.95,
+      "source": "deterministic",
+      "mapped": true
+    },
+    {
+      "canonical_title": "Governing Law",
+      "detected_title": "## Governing Law",
+      "tier": "h2",
+      "span": {
+        "start": 622,
+        "end": 704
+      },
+      "confidence": 0.95,
+      "source": "deterministic",
+      "mapped": true
+    }
+  ],
+  "defined_terms": [
+    {
+      "term": "Provider",
+      "confidence": 0.6,
+      "source": "deterministic"
+    },
+    {
+      "term": "Customer",
+      "confidence": 0.6,
+      "source": "deterministic"
+    }
+  ],
+  "value": {
+    "value": null,
+    "confidence": 0.0,
+    "source": "none"
+  },
+  "_meta": {
+    "extractor_version": "0.1.5",
+    "tiers_used": [
+      "deterministic"
+    ],
+    "llm_used": false
+  }
+}

{extract_cli-0.1.3 → extract_cli-0.1.5}/tests/fixtures/lease_allcaps.txt.expected.json

@@ -133,7 +133,7 @@
     "source": "deterministic"
   },
   "_meta": {
-    "extractor_version": "0.1.3",
+    "extractor_version": "0.1.5",
     "tiers_used": [
       "deterministic"
     ],

{extract_cli-0.1.3 → extract_cli-0.1.5}/tests/fixtures/license_pdf.pdf.expected.json

@@ -133,7 +133,7 @@
     "source": "deterministic"
   },
   "_meta": {
-    "extractor_version": "0.1.3",
+    "extractor_version": "0.1.5",
     "tiers_used": [
       "deterministic"
     ],

{extract_cli-0.1.3 → extract_cli-0.1.5}/tests/fixtures/nda_h2.md.expected.json

@@ -143,7 +143,7 @@
     "source": "none"
   },
   "_meta": {
-    "extractor_version": "0.1.3",
+    "extractor_version": "0.1.5",
     "tiers_used": [
       "deterministic"
     ],

{extract_cli-0.1.3 → extract_cli-0.1.5}/tests/fixtures/scanned.pdf.expected.json

@@ -48,7 +48,7 @@
     "source": "none"
   },
   "_meta": {
-    "extractor_version": "0.1.3",
+    "extractor_version": "0.1.5",
     "tiers_used": [
       "deterministic"
     ],

{extract_cli-0.1.3 → extract_cli-0.1.5}/tests/fixtures/services_bold.txt.expected.json

@@ -133,7 +133,7 @@
     "source": "deterministic"
   },
   "_meta": {
-    "extractor_version": "0.1.3",
+    "extractor_version": "0.1.5",
     "tiers_used": [
       "deterministic"
     ],

{extract_cli-0.1.3 → extract_cli-0.1.5}/tests/fixtures/services_html.html.expected.json

@@ -148,7 +148,7 @@
     "source": "deterministic"
   },
   "_meta": {
-    "extractor_version": "0.1.3",
+    "extractor_version": "0.1.5",
     "tiers_used": [
       "deterministic"
     ],

{extract_cli-0.1.3 → extract_cli-0.1.5}/tests/test_llm.py

@@ -67,6 +67,41 @@ def test_enrich_fills_only_missing_governing_law(monkeypatch: pytest.MonkeyPatch
     assert result["governing_law"] == {"value": "France", "confidence": 0.6, "source": "llm"}
 
 
+def test_llm_clause_fallback_when_deterministic_empty(monkeypatch: pytest.MonkeyPatch) -> None:
+    from tests._schema_validator import validate
+    monkeypatch.setattr(ex, "load_llm_config",
+                        lambda: {"provider": "anthropic", "api_key": "x"})
+    monkeypatch.setattr(ex, "_llm_request", lambda cfg, prompt, timeout=30.0: json.dumps(
+        {"clauses": [{"title": "Confidentiality"}, {"title": "Governing Law"},
+                     {"title": "Special Widget Terms"}]}))
+    # A document with no detectable clause headings -> 0 deterministic clauses.
+    text = ("This Agreement is made between Acme Co and Beta Co. The parties agree "
+            "to maintain confidentiality. Governed by the laws of Delaware.")
+    result = ex.build_extraction(text, text.encode("utf-8"), "text", "x.txt")
+    assert result["clauses"] == []
+    ex.llm_enrich(result, text, _ns())
+    cl = result["clauses"]
+    assert [c["canonical_title"] for c in cl] == ["Confidentiality", "Governing Law", "Special Widget Terms"]
+    assert all(c["tier"] == "llm" and c["source"] == "llm" for c in cl)
+    assert cl[0]["mapped"] is True and cl[2]["mapped"] is False
+    assert result["_meta"]["llm_used"] is True and "llm" in result["_meta"]["tiers_used"]
+    assert validate(result, ex.output_schema()) == []  # llm clauses are schema-conformant
+
+
+def test_llm_does_not_replace_deterministic_clauses(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(ex, "load_llm_config",
+                        lambda: {"provider": "anthropic", "api_key": "x"})
+    monkeypatch.setattr(ex, "_llm_request", lambda cfg, prompt, timeout=30.0: json.dumps(
+        {"clauses": [{"title": "Should Not Appear"}]}))
+    text = ex.DEMO_DOCUMENT  # has H2 clauses
+    result = ex.build_extraction(text, text.encode("utf-8"), "markdown", "d.md")
+    assert result["clauses"] and all(c["tier"] == "h2" for c in result["clauses"])
+    ex.llm_enrich(result, text, _ns())
+    # Deterministic clauses are kept; the LLM clause was never requested/used.
+    assert all(c["tier"] == "h2" for c in result["clauses"])
+    assert not any(c["detected_title"] == "Should Not Appear" for c in result["clauses"])
+
+
 def test_request_error_degrades(monkeypatch: pytest.MonkeyPatch,
                                 capsys: pytest.CaptureFixture[str]) -> None:
     monkeypatch.setattr(ex, "load_llm_config",

{extract_cli-0.1.3 → extract_cli-0.1.5}/tests/test_misc.py

@@ -142,6 +142,37 @@ def test_pdf_unescape() -> None:
     assert ex._pdf_unescape(r"\101\102") == "AB"  # octal escapes
 
 
+def test_docx_heading_style_helpers() -> None:
+    assert ex._is_heading_style("Heading1")
+    assert ex._is_heading_style("Heading 2".replace(" ", ""))
+    assert ex._is_heading_style("Title")
+    assert ex._is_heading_style("h3")
+    assert not ex._is_heading_style("Plain")
+    assert not ex._is_heading_style(None)
+    # Run-in heading: title is the lead before the sentence body.
+    assert ex._docx_heading_title("Payment.  Customer will pay the fees.") == "Payment"
+    assert ex._docx_heading_title("Governing Law") == "Governing Law"
+    # A full sentence carrying a heading style is rejected (not a clause title).
+    assert ex._docx_heading_title(
+        "Either party may terminate this Agreement upon material breach that "
+        "remains uncured for thirty days.") is None
+
+
+def test_docx_heading_styles_drive_clause_map() -> None:
+    """The Word-styled fixture's clauses come from Heading1 styles (their
+    numbers are auto-generated), detected via the H2 tier; the sentence that
+    merely carries a heading style is not a clause."""
+    raw, text, fmt, _w = ex.load_source(FIXTURES / "heading_docx.docx", prefer_optional=False)
+    result = ex.build_extraction(text, raw, fmt, "heading_docx.docx")
+    assert result["clauses"], "heading-styled docx should yield clauses"
+    canon = {c["canonical_title"] for c in result["clauses"]}
+    assert {"Confidentiality", "Payment", "Governing Law"} <= canon
+    assert all(c["tier"] == "h2" for c in result["clauses"])
+    # The full-sentence "Either party may terminate ..." must not appear.
+    assert not any("terminate this Agreement" in c["detected_title"] for c in result["clauses"])
+    assert [p["name"] for p in result["parties"]] == ["Initech Software, Inc.", "Globex Corporation"]
+
+
 def test_html_extraction() -> None:
     raw, text, fmt, _w = ex.load_source(FIXTURES / "services_html.html")
     assert fmt == "html"