extract-cli 0.1.0__tar.gz

extract_cli-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+
+# Build artifacts
+build/
+dist/
+
+# Test / type / coverage caches
+.pytest_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Virtualenvs
+.venv/
+venv/
+
+# Local LLM config (never commit credentials)
+config/llm.json
+
+# OS
+.DS_Store

extract_cli-0.1.0/ARCHITECTURE.md

@@ -0,0 +1,95 @@
+# Architecture
+
+`extract-cli` is one file, `extract_cli.py`, stdlib-only. This document is the
+map.
+
+## Pipeline
+
+```
+load_source(path)                       extension/content sniff → reader
+  ├─ .md/.txt  → utf-8 decode
+  ├─ .docx     → python-docx (if [docx]) else stdlib zipfile/XML reader
+  └─ .pdf      → pypdf (if [pdf]) else stdlib zlib + text-operator reader
+        │
+        ▼  (raw_bytes, text, format, warnings)
+build_extraction(text, raw, fmt, src)   the DETERMINISTIC tier (always on)
+  ├─ extract_parties          "between X and Y", with role parentheticals
+  ├─ extract_dates            effective / expiration, ISO-normalized
+  ├─ extract_term             length / auto_renew / notice_period_days
+  ├─ extract_governing_law    "governed by the laws of …"
+  ├─ extract_clauses          detect_clauses cascade → canonical mapping
+  ├─ extract_defined_terms    quoted / parenthetical Capitalized terms
+  └─ extract_value            headline monetary amount
+        │
+        ▼  result : dict (the output contract)
+llm_enrich(result, text, args)          the LLM tier — only if --llm
+        │
+        ▼
+render_json | render_table              stdout (JSON is the machine payload)
+```
+
+Each extracted scalar is wrapped by `_field(value, confidence, source)` into a
+`{value, confidence, source}` envelope; "not found" is the canonical
+`{value: null, confidence: 0.0, source: "none"}`. Lists (`parties`, `clauses`,
+`defined_terms`) carry per-item `confidence`/`source`. `_meta` records the
+extractor version, the tiers that ran, and whether the LLM was used. This is
+the "verify, not trust" contract downstream tools consume.
+
+## The clause map
+
+`detect_clauses(text)` is a faithful port of template-vault-cli's three-tier
+cascade; the first tier that fires wins so fallbacks never shadow real
+structure:
+
+1. **`h2`** — `## Heading` (Markdown-native). Needs ≥ 1 match.
+2. **`bold-numbered`** — `**1. Purpose**`, `**Section 4. Term**` (typical of
+   DOCX → text). Needs ≥ 2 matches.
+3. **`all-caps`** — blank-line-framed `CONFIDENTIALITY` lines (typical of legal
+   PDFs), with the single-token-≥-4-letters rule. Needs ≥ 2 matches.
+
+`_strip_clause_number` removes leading numbering, including Roman numerals
+1–39 (`_ROMAN_RE` lists longer alternatives first so the engine doesn't
+short-circuit on a prefix — bare `V`/`X` match).
+
+`_canonicalize_clause` then maps each detected title onto the suite's shared
+vocabulary via `CANONICAL_CLAUSE_ALIASES` (canonical_title → [alias, …]):
+exact normalized match first, then a containment fallback. Unmapped clauses are
+kept with `mapped: false` and a lower confidence so nothing is silently
+dropped. template-vault stores this map *per template*; a foreign document has
+none, so extract-cli ships a built-in default — that's the differentiator.
+
+## Readers: degrade up, not down
+
+The playbook gates heavy parsing behind `[docx]`/`[pdf]`. We honor the spirit
+(extras improve fidelity) while keeping `.docx`/`.pdf` working with zero extras
+via stdlib readers, because the hard rule is "fully functional with zero
+extras + degrade gracefully" — and a best-effort reader serves that better than
+refusing the format. See the decision note in
+[CHANGELOG.md](CHANGELOG.md). A scanned/image-only PDF yields no text → a
+stderr warning and exit code `1` (a "finding"), never a crash.
+
+## LLM tier
+
+Opt-in only (`--llm`), never in a hot path. `load_llm_config()` reads the
+suite-shared config (`~/.config/contract-ops/llm.json` then `./config/llm.json`).
+`_llm_request` posts via stdlib `urllib` to Anthropic or an OpenAI-compatible
+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.
+
+## The output contract
+
+`output_schema()` is the single source of truth for the JSON Schema. `extract
+schema` prints it; `docs/spec/extract-output.schema.json` is the committed copy
+(`make spec-check` asserts they're identical). Tests validate every fixture's
+output against it with a vendored, dependency-free validator
+(`tests/_schema_validator.py`).
+
+## Conventions
+
+UTF-8 stdout/stderr is forced in `main()` (locale-safe on macOS CI). Color
+auto-detects a TTY and honors `NO_COLOR`/`FORCE_COLOR`. stdout is reserved for
+the machine payload; `--why`, warnings, and errors go to stderr. Exit codes:
+`0` success, `1` low-signal document, `2` bad usage / user-actionable error.

extract_cli-0.1.0/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+All notable changes to `extract-cli` are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this project adheres
+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.0] - 2026-05-21
+
+Initial release — the open-loop front door of the contract-ops CLI suite.
+
+### Added
+- Single-file, stdlib-only CLI `extract_cli.py` (`extract` entry point).
+- `extract <path>` — parse `.md`/`.txt`/`.docx`/`.pdf` into structured JSON.
+- `extract schema` / `fields` / `demo` / `completion` subcommands; hidden
+  `__complete` handler for shell completion.
+- **Two explicit extraction tiers**: a deterministic, network-free default
+  (parties, dates, defined terms, clause map, governing law, best-effort
+  term/notice/value) and an opt-in `--llm` tier for fuzzy fields. Every field
+  carries a `confidence` and a `source` ∈ {deterministic, llm, none}.
+- **Clause map**: ported template-vault-cli's three-tier clause-detection
+  cascade (H2 → bold-numbered → ALL-CAPS, Roman numerals 1–39 with longer
+  alternatives first) plus a built-in canonical clause-alias vocabulary that
+  normalizes a foreign document's clause titles onto the suite's shared names.
+- Cross-CLI output contract published as JSON Schema 2020-12 at
+  [`docs/spec/extract-output.schema.json`](docs/spec/extract-output.schema.json)
+  and registered in [`docs/INTEROP.md`](docs/INTEROP.md).
+- Suite UX conventions: `--json`/`--why`/`-q`/`--silent`/`--no-color`
+  (`NO_COLOR`/`FORCE_COLOR` honored)/`--demo`/`-V`; meaningful exit codes
+  (0/1/2); locale-safe UTF-8 stdout/stderr; ASCII-safe output.
+- Shared LLM config lookup (`~/.config/contract-ops/llm.json` → `./config/llm.json`)
+  with `config/llm.json.example`.
+- Test suite: per-tier unit tests, seeded property-based invariants (stdlib
+  `random.Random`, no hypothesis), a real-contract fixture corpus spanning all
+  input formats and clause tiers with `.expected.json` goldens, and a
+  schema-conformance test using a dependency-free JSON Schema validator.
+- CI matrix (Ubuntu × macOS × Python 3.9–3.12) + typecheck + build-smoke jobs;
+  PyPI Trusted Publishing workflow on `v*` tags. `Makefile` and
+  `scripts/release.py`.
+
+### Decisions (documented per the autonomous-build playbook)
+- **`.docx`/`.pdf` work without their extras.** The playbook says heavy parsing
+  lives behind `[docx]`/`[pdf]`; we honor the spirit (extras enhance fidelity)
+  while degrading *up*, not down: stdlib `zipfile`/XML reads `.docx` and a
+  stdlib `zlib`/text-operator reader reads `.pdf` out of the box. The extras
+  (`python-docx`, `pypdf`) are preferred when installed. Rationale: the
+  playbook's hard rule is "fully functional on `.md`/`.txt` with zero extras
+  and degrade gracefully" — a stdlib best-effort reader satisfies that *and*
+  the graceful-degradation rule better than refusing the format outright.
+- **`[llm]` extra is empty.** LLM enrichment uses only stdlib `urllib`, so no
+  runtime dependency is required; the extra exists for suite parity.
+- **Schema validation in tests uses a vendored mini-validator**, not
+  `jsonschema`, to keep the dev surface stdlib-aligned (dev extra is just
+  pytest/coverage/mypy/build).
+- **`--no-confidence`** produces a reduced convenience projection that is
+  intentionally *not* governed by the output schema (the schema describes the
+  full default output).
+
+[0.1.0]: https://github.com/DrBaher/extract-cli/releases/tag/v0.1.0

extract_cli-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,74 @@
+# Contributing to extract-cli
+
+Thanks for helping with the contract-ops suite's front door.
+
+## Ground rules (suite conventions)
+
+- **Stdlib-only core.** `extract_cli.py` must import nothing outside the
+  standard library. Heavy parsing goes behind the `[docx]`/`[pdf]` optional
+  extras and must degrade gracefully when they're absent.
+- **Single file.** All CLI logic lives in `extract_cli.py`.
+- **The LLM tier is opt-in.** Never call it in a default code path; it must be
+  fully skippable and the deterministic tier must stand alone.
+- **stdout is the machine payload.** JSON only. Diagnostics, `--why`, and
+  errors go to stderr. Don't mix them.
+- **ASCII-safe, locale-safe output.** `ensure_ascii=True` for JSON; no raw
+  unicode in table output.
+
+## Dev setup
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+make install        # editable install with [dev] extra
+```
+
+## Before you push
+
+```bash
+make typecheck      # mypy --strict must be clean
+make test           # full suite must be green
+make coverage       # keep coverage healthy
+make spec-check     # docs/spec schema must match `extract schema`
+make smoke          # wheel installs+runs in a clean venv
+```
+
+CI runs the matrix (Ubuntu × macOS × Python 3.9–3.12) plus a typecheck job and
+a build-smoke job. All must pass.
+
+## Changing the output schema
+
+The output JSON is a **cross-CLI data contract** (see
+[`docs/INTEROP.md`](docs/INTEROP.md)). Semver matters:
+
+- **New optional field** → minor bump.
+- **Removing/renaming a field, narrowing a type** → major bump.
+
+Edit `output_schema()` in `extract_cli.py` (the source of truth), then:
+
+```bash
+make spec-update    # regenerate docs/spec/extract-output.schema.json
+make goldens        # regenerate .expected.json (review the diff!)
+```
+
+## Tests
+
+- Per-tier unit tests in `tests/test_deterministic.py`, `tests/test_clause_map.py`.
+- Property-based invariants in `tests/test_property.py` use stdlib
+  `random.Random(seed)` — **no hypothesis**.
+- The fixture corpus (`tests/fixtures/`) spans all input formats and clause
+  tiers, each with a `.expected.json` golden. Binary fixtures are generated by
+  `tests/_fixtures_build.py` (run `make fixtures`).
+- `tests/test_schema_conformance.py` validates every fixture against the schema
+  using the vendored validator in `tests/_schema_validator.py`.
+
+Add a fixture + golden for any new format or clause-shape you teach it to read.
+
+## Commits
+
+Commit identity for this repo is **`DrBaher <Drbaher@gmail.com>`**. The
+`scripts/release.py` flow sets it; for manual commits run:
+
+```bash
+git config user.name "DrBaher"
+git config user.email "Drbaher@gmail.com"
+```

extract_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DrBaher
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

extract_cli-0.1.0/Makefile

@@ -0,0 +1,84 @@
+# extract-cli -- developer tasks. Stdlib-only project; these wrap the toolchain.
+PYTHON ?= python3
+PIP    ?= $(PYTHON) -m pip
+SPEC   := docs/spec/extract-output.schema.json
+
+.PHONY: help install test test-quick coverage typecheck build smoke \
+        spec-check fixtures goldens release clean
+
+help:
+	@echo "extract-cli make targets:"
+	@echo "  install     editable install with [dev] extra"
+	@echo "  test        run the full test suite"
+	@echo "  test-quick  run tests, stop on first failure (-x), skip slow property runs"
+	@echo "  coverage    run tests under coverage and print a report"
+	@echo "  typecheck   mypy --strict"
+	@echo "  build       build wheel + sdist into dist/"
+	@echo "  smoke       build, install the wheel in a clean venv, and run it"
+	@echo "  spec-check  assert docs/spec schema == 'extract schema' output"
+	@echo "  fixtures    regenerate binary (.docx/.pdf) test fixtures"
+	@echo "  goldens     regenerate .expected.json golden files"
+	@echo "  release     make release VERSION=X.Y.Z"
+	@echo "  clean       remove build/test artifacts"
+
+install:
+	$(PIP) install -e ".[dev]"
+
+test:
+	$(PYTHON) -m pytest
+
+test-quick:
+	$(PYTHON) -m pytest -x -q -k "not property"
+
+coverage:
+	$(PYTHON) -m coverage run --source=extract_cli -m pytest -q
+	$(PYTHON) -m coverage report -m
+
+typecheck:
+	$(PYTHON) -m mypy --strict extract_cli.py
+
+build: clean
+	$(PYTHON) -m build
+
+smoke: build
+	@set -e; \
+	tmp=$$(mktemp -d); \
+	echo "smoke venv: $$tmp"; \
+	$(PYTHON) -m venv $$tmp/venv; \
+	whl=$$(ls dist/*.whl | head -1); \
+	$$tmp/venv/bin/python -m pip install -q --upgrade pip; \
+	$$tmp/venv/bin/python -m pip install -q "$$whl"; \
+	echo "--- extract --version ---"; $$tmp/venv/bin/extract --version; \
+	echo "--- extract demo (validate against spec) ---"; \
+	$$tmp/venv/bin/extract demo --no-color | $(PYTHON) scripts/validate_against_spec.py; \
+	echo "smoke OK"; \
+	rm -rf $$tmp
+
+spec-check:
+	@$(PYTHON) extract_cli.py schema > /tmp/extract-spec-check.json
+	@if diff -q /tmp/extract-spec-check.json $(SPEC) >/dev/null 2>&1; then \
+		echo "spec-check OK: $(SPEC) matches 'extract schema'"; \
+	else \
+		echo "spec-check FAILED: $(SPEC) is stale. Run: make spec-update"; \
+		diff $(SPEC) /tmp/extract-spec-check.json || true; \
+		exit 1; \
+	fi
+
+.PHONY: spec-update
+spec-update:
+	$(PYTHON) extract_cli.py schema > $(SPEC)
+	@echo "wrote $(SPEC)"
+
+fixtures:
+	$(PYTHON) tests/_fixtures_build.py
+
+goldens:
+	$(PYTHON) tests/_make_goldens.py
+
+release:
+	@test -n "$(VERSION)" || { echo "usage: make release VERSION=X.Y.Z"; exit 2; }
+	$(PYTHON) scripts/release.py $(VERSION)
+
+clean:
+	rm -rf dist build *.egg-info .pytest_cache .mypy_cache .coverage htmlcov
+	find . -type d -name __pycache__ -prune -exec rm -rf {} + 2>/dev/null || true

extract_cli-0.1.0/PKG-INFO

@@ -0,0 +1,225 @@
+Metadata-Version: 2.4
+Name: extract-cli
+Version: 0.1.0
+Summary: Open-loop front door of the contract-ops CLI suite: ingest any contract (.md/.txt/.docx/.pdf) and emit structured JSON.
+Project-URL: Homepage, https://cli.drbaher.com/
+Project-URL: Repository, https://github.com/DrBaher/extract-cli
+Project-URL: Suite interop, https://github.com/DrBaher/extract-cli/blob/main/docs/INTEROP.md
+Author-email: DrBaher <Drbaher@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: clause,cli,contract,extraction,json,legal,nda
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Legal Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Text Processing :: Markup
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: coverage>=7.0; extra == 'dev'
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Provides-Extra: docx
+Requires-Dist: python-docx>=0.8.11; extra == 'docx'
+Provides-Extra: llm
+Provides-Extra: pdf
+Requires-Dist: pypdf>=3.9.0; extra == 'pdf'
+Description-Content-Type: text/markdown
+
+# extract-cli
+
+> Part of the contract-ops CLI suite. **extract-cli** is the suite's
+> *passport control* — the **open-loop front door**. The rest of the suite is a
+> closed loop that only handles documents it authored from its own templates;
+> `extract-cli` ingests **any** document (yours or a counterparty's foreign
+> paper) and emits a structured representation the pipeline can consume:
+> [**template-vault-cli**](https://github.com/DrBaher/template-vault-CLI) (storage) feeds
+> [**draft-cli**](https://github.com/DrBaher/draft-cli) (fill placeholders) →
+> [**nda-review-cli**](https://github.com/DrBaher/nda-review-cli) (review, redline, negotiate) →
+> [**docx2pdf-cli**](https://github.com/DrBaher/docx2pdf-cli) (DOCX → PDF) →
+> [**sign-cli**](https://github.com/DrBaher/sign-cli) (signing + audit).
+> Cross-version drift detection via [**compare-cli**](https://github.com/DrBaher/compare-cli).
+> [Showcase site](https://cli.drbaher.com/).
+>
+> `extract-cli` sits **upstream of review**: it turns foreign paper into the
+> suite's canonical, structured vocabulary. Its output is a **cross-CLI data
+> contract** — see [`docs/INTEROP.md`](docs/INTEROP.md) and
+> [`docs/spec/extract-output.schema.json`](docs/spec/extract-output.schema.json).
+
+```
+ingest (extract) → review → diff → convert → sign
+   ^you are here
+```
+
+## What it does
+
+Give it a contract in **`.md` / `.txt`** (native), **`.docx`**, or **`.pdf`**,
+and it returns structured JSON: the parties, dates, term, governing law, a
+**clause map** normalized onto the suite's canonical clause vocabulary, a
+defined-term inventory, and a headline value. Every field carries a
+`confidence` and a `source` so downstream tools **verify, don't trust**.
+
+It is **stdlib-only**, single-file, terminal-first, and composable. No DB, no
+daemon, no network in the default path.
+
+## Install
+
+```bash
+pip install extract-cli                 # core: .md/.txt + best-effort .docx/.pdf
+pip install "extract-cli[docx]"         # higher-fidelity .docx (python-docx)
+pip install "extract-cli[pdf]"          # higher-fidelity .pdf (pypdf)
+pip install "extract-cli[docx,pdf]"     # both
+```
+
+The core has **zero runtime dependencies** and is fully functional on `.md`/`.txt`
+with no extras. `.docx` and `.pdf` work out of the box via stdlib readers; the
+`[docx]`/`[pdf]` extras improve fidelity on complex documents (see
+[ARCHITECTURE.md](ARCHITECTURE.md)).
+
+## The two extraction tiers
+
+`extract-cli` is explicit about *how* it knows each field — encoded in every
+field's `source` and in `_meta.tiers_used`.
+
+| Tier | When | Fields | Network? |
+|---|---|---|---|
+| **deterministic** | always on (default) | parties, dates, defined terms, **clause map**, governing law, best-effort term/notice/value | none |
+| **llm** | opt-in via `--llm` only | renewal mechanics, obligation phrasing, ambiguous governing law | yes (your provider) |
+
+The deterministic core is **fully useful without the LLM**. The LLM tier is
+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.
+
+## Commands
+
+```bash
+extract <path>            # parse a document → structured JSON on stdout (default)
+extract schema            # print the output JSON Schema (the cross-CLI contract)
+extract fields            # list extractable fields and their tier
+extract demo              # run on a bundled fixture and show the narrative
+extract completion bash   # emit a shell-completion script (bash|zsh)
+```
+
+### Flags
+
+| Flag | Meaning |
+|---|---|
+| `--llm` | Opt-in LLM enrichment of fuzzy fields (off by default) |
+| `--fields a,b,c` | Emit only a subset of top-level fields (e.g. `parties,clauses`) |
+| `--format json\|table` | Output format (default `json`) |
+| `--no-confidence` | Omit confidence/source markers (reduced convenience view) |
+| `--json` | Force JSON to stdout (the default) |
+| `--why` | Rationale block on **stderr** |
+| `-q`, `--silent`, `--quiet` | Suppress non-error diagnostics |
+| `--no-color` | Disable ANSI color (also honors `NO_COLOR` / `FORCE_COLOR`) |
+| `-V`, `--version` | Print `extract-cli X.Y.Z` |
+
+Streams follow the suite convention: **stdout** is the machine payload (JSON),
+**stderr** is for humans (`--why`, warnings, errors). Exit codes: `0` success,
+`1` low-signal document (e.g. a scanned/empty PDF), `2` bad usage.
+
+## Output shape (abridged)
+
+```jsonc
+{
+  "document":   { "title": "...", "format": "markdown", "sha256": "…", "source_path": "nda.md" },
+  "parties":    [ { "name": "Acme Robotics, Inc.", "role": "Disclosing Party", "confidence": 0.9, "source": "deterministic" } ],
+  "dates":      { "effective": { "value": "2024-03-01", "confidence": 0.85, "source": "deterministic" }, "expiration": { "value": null, "confidence": 0.0, "source": "none" } },
+  "term":       { "length": { "value": "3 years", ... }, "auto_renew": { "value": true, ... }, "notice_period_days": { "value": 60, ... } },
+  "governing_law": { "value": "State of Delaware", "confidence": 0.85, "source": "deterministic" },
+  "clauses":    [ { "canonical_title": "Confidentiality", "detected_title": "## Confidentiality Obligations", "tier": "h2", "span": {"start": 0, "end": 120}, "confidence": 0.95, "source": "deterministic", "mapped": true } ],
+  "defined_terms": [ { "term": "Confidential Information", "confidence": 0.6, "source": "deterministic" } ],
+  "value":      { "value": "$50,000", "confidence": 0.6, "source": "deterministic" },
+  "_meta":      { "extractor_version": "0.1.0", "tiers_used": ["deterministic"], "llm_used": false }
+}
+```
+
+## The clause map (the differentiator)
+
+A counterparty's "SECTION 7. NON-DISCLOSURE" and your template's
+"## Confidentiality" are the same clause. `extract-cli` reuses
+template-vault-cli's **clause-detection cascade** (Tier 1 `## H2` headings →
+Tier 2 bold-numbered `**1. …**` → Tier 3 ALL-CAPS lines) and a built-in
+**canonical alias vocabulary** to normalize foreign clause titles onto the
+names the rest of the suite already speaks. Clauses it can't map are kept with
+`mapped: false` (and a `*` in the table view) so nothing is silently dropped.
+
+```bash
+extract counterparty.pdf | jq '.clauses[] | {canonical_title, detected_title, mapped}'
+```
+
+## Composability — piping into the rest of the suite
+
+`extract-cli` is built to be the first stage of a Unix pipe. Its JSON is the
+contract every downstream tool reads.
+
+```bash
+# 1) Foreign NDA → review. extract normalizes clauses; nda-review runs policy.
+extract counterparty_nda.pdf | nda-review review --from-extract -
+
+# 2) Pull just the clause map and feed compare-cli to diff a foreign doc
+#    against your canonical template's structure.
+extract their_msa.docx --fields clauses | compare-cli align --stdin \
+  --against msa/standard
+
+# 3) Archive structured metadata for any inbound paper into the post-signature
+#    vault, keyed by content hash.
+extract signed_contract.pdf | contract-vault put --from-extract - \
+  --id "$(extract signed_contract.pdf | jq -r .document.sha256)"
+
+# 4) Triage a folder of inbound contracts: list governing law + parties.
+for f in inbox/*.pdf; do
+  extract "$f" --fields parties,governing_law --no-confidence \
+    | jq -c '{file: input_filename, gov: .governing_law, parties: [.parties[].name]}'
+done
+
+# 5) Gate a workflow on extraction confidence.
+extract draft.docx | jq -e '.clauses | all(.confidence > 0.7)' && echo "ok to review"
+```
+
+> The `--from-extract`/`--stdin` flags above are the consumption points the
+> sibling CLIs expose (or are adopting) for this contract; see
+> [`docs/INTEROP.md`](docs/INTEROP.md) for the shared conventions and the
+> versioning commitment on the schema.
+
+## LLM configuration (opt-in)
+
+`--llm` reads a shared suite config, in this order:
+
+1. `~/.config/contract-ops/llm.json`  (suite-wide — preferred)
+2. `./config/llm.json`                 (repo-local override)
+
+Copy [`config/llm.json.example`](config/llm.json.example) to one of those
+paths. Configure it once and every suite tool that adopts the same lookup gets
+LLM features for free. Without it, `--llm` just warns and returns the
+deterministic output.
+
+## Development
+
+```bash
+make install      # editable install with the [dev] extra
+make test         # full suite
+make coverage     # suite + coverage report
+make typecheck    # mypy --strict
+make build        # wheel + sdist
+make smoke        # build, install the wheel in a clean venv, run it
+make spec-check   # assert docs/spec schema == `extract schema`
+make release VERSION=X.Y.Z
+```
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) and [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT — see [LICENSE](LICENSE).