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

{extract_cli-0.1.4 → 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.4 → extract_cli-0.1.5}/CHANGELOG.md

@@ -6,6 +6,21 @@ 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
@@ -166,6 +181,7 @@ 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: extract-cli
-Version: 0.1.4
+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.4 → 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.4 → 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.4"
+__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.4"
+EXTRACTOR_VERSION = "0.1.5"
 
 # JSON Schema version of the output contract (docs/spec/extract-output.schema.json).
 SCHEMA_VERSION = 1
@@ -1275,13 +1275,27 @@ 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]:
@@ -1337,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()
@@ -1346,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:
@@ -1376,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"]:
@@ -1658,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.4 → extract_cli-0.1.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "extract-cli"
-version = "0.1.4"
+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.4 → extract_cli-0.1.5}/tests/fixtures/employment_docx.docx.expected.json

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

{extract_cli-0.1.4 → extract_cli-0.1.5}/tests/fixtures/heading_docx.docx.expected.json

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

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

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

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

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

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

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

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

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

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

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

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

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

{extract_cli-0.1.4 → 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",