sigdetect 0.1.0__py3-none-any.whl

sigdetect-0.1.0.dist-info/METADATA

@@ -0,0 +1,394 @@
+Metadata-Version: 2.4
+Name: sigdetect
+Version: 0.1.0
+Summary: Signature detection and role attribution for PDFs
+Author-email: BT Asmamaw <basmamaw@angeiongroup.com>
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: pypdf>=4.0.0
+Requires-Dist: pandas>=2.0
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.12
+Requires-Dist: pydantic>=2.5
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: pymupdf
+Requires-Dist: pymupdf>=1.23; extra == "pymupdf"
+
+# CaseWorks.Automation.CaseDocumentIntake
+
+## sigdetect
+
+`sigdetect` is a small Python library + CLI that detects **e-signature evidence** in PDFs and infers the **signer role** (e.g., _patient_, _attorney_, _representative_).
+
+It looks for:
+
+- Real signature **form fields** (`/Widget` annotations with `/FT /Sig`)
+- **AcroForm** signature fields present only at the document level
+- Common **vendor markers** (e.g., DocuSign, “Signature Certificate”)
+- Page **labels** (like “Signature of Patient” or “Signature of Parent/Guardian”)
+
+It returns a structured summary per file (pages, counts, roles, hints, etc.) that  can be used downstream.
+
+---
+
+## Contents
+
+- [Quick start](#quick-start)
+- [CLI usage](#cli-usage)
+- [Library usage](#library-usage)
+- [Result schema](#result-schema)
+- [Configuration & rules](#configuration--rules)
+- [Smoke tests](#smoke-tests)
+- [Dev workflow](#dev-workflow)
+- [Troubleshooting](#troubleshooting)
+- [License](#license)
+
+---
+
+## Quick start
+
+### Requirements
+
+- Python **3.9+** (developed & tested on **3.11**)
+- macOS / Linux / WSL
+
+### Setup
+
+~~~bash
+# 1) Create and activate a virtualenv (example uses Python 3.11)
+python3.11 -m venv .venv
+source .venv/bin/activate
+
+# 2) Install in editable (dev) mode
+python -m pip install --upgrade pip
+pip install -e .
+~~~
+
+### Sanity check
+
+~~~bash
+# Run unit & smoke tests
+pytest -q
+~~~
+
+---
+
+## CLI usage
+
+The project ships a Typer-based CLI (exposed either as `sigdetect` or runnable via `python -m sigdetect.cli`, depending on how it is installed).
+
+~~~bash
+sigdetect --help
+# or
+python -m sigdetect.cli --help
+~~~
+
+### Detect (per-file summary)
+
+~~~bash
+# Execute detection according to the YAML configuration
+sigdetect detect \
+  --config ./sample_data/config.yml \
+  --profile hipaa            # or: retainer
+~~~
+
+### Notes
+
+- The config file controls `pdf_root`, `out_dir`, `engine`, `pseudo_signatures`, `recurse_xobjects`, etc.
+- `--engine` supports **pypdf2** (default); a **pymupdf** engine placeholder exists and may be included in a future build.  
+- `--pseudo-signatures` enables a vendor/Acro-only pseudo-signature when no actual `/Widget` is present (useful for DocuSign / Acrobat Sign receipts).  
+- `--recurse-xobjects` allows scanning Form XObjects for vendor markers and labels embedded in page resources. 
+- `--profile` selects tuned role logic:
+  - `hipaa` → patient / representative / attorney
+  - `retainer` → client / firm (prefers detecting two signatures)
+- If the executable is not on `PATH`, you can always fall back to `python -m sigdetect.cli ...`.
+
+### EDA (quick aggregate stats)
+
+~~~bash
+sigdetect eda \
+  --config ./sample_data/config.yml
+
+~~~
+
+---
+
+## Library usage
+
+~~~python
+from pathlib import Path
+from sigdetect.config import DetectConfiguration
+from sigdetect.detector.pypdf2_engine import PyPDF2Detector
+
+configuration = DetectConfiguration(
+    PdfRoot=Path("/path/to/pdfs"),
+    OutputDirectory=Path("./out"),
+    Engine="pypdf2",
+    PseudoSignatures=True,
+    RecurseXObjects=True,
+    Profile="retainer",   # or "hipaa"
+)
+
+detector = PyPDF2Detector(configuration)
+result = detector.Detect(Path("/path/to/pdfs/example.pdf"))
+print(result.to_dict())
+~~~
+
+`Detect(Path)` returns a **FileResult** dataclass; call `.to_dict()` for the JSON-friendly representation (see [Result schema](#result-schema)).
+
+---
+
+## Library API (embed in another script)
+
+Minimal, plug-and-play API
+Import from `sigdetect.api` and get plain dicts out (JSON-ready), 
+with no I/O side effects by default:
+
+~~~python
+from sigdetect.api import DetectPdf, DetectMany, ScanDirectory, ToCsvRow, Version
+
+print("sigdetect", Version())
+
+# 1) Single file → dict
+result = DetectPdf(
+    "/path/to/file.pdf",
+    profileName="retainer",
+    includePseudoSignatures=True,
+    recurseXObjects=True,
+)
+print(
+    result["file"],
+    result["pages"],
+    result["esign_found"],
+    result["sig_count"],
+    result["sig_pages"],
+    result["roles"],
+    result["hints"],
+)
+
+
+# 2) Directory walk (generator of dicts)
+for res in ScanDirectory(
+    "/path/to/pdfs",
+    profileName="hipaa",
+    includePseudoSignatures=True,
+    recurseXObjects=True,
+):
+    # store in DB, print, etc.
+    pass
+
+~~~
+
+
+## Result schema
+
+High-level summary (per file):
+
+~~~json
+{
+  "file": "example.pdf",
+  "size_kb": 123.4,
+  "pages": 3,
+  "esign_found": true,
+  "scanned_pdf": false,
+  "mixed": false,
+  "sig_count": 2,
+  "sig_pages": "1,3",
+  "roles": "patient;representative",
+  "hints": "AcroSig:sig_patient;VendorText:DocuSign\\s+Envelope\\s+ID",
+  "signatures": [
+    {
+      "page": 1,
+      "field_name": "sig_patient",
+      "role": "patient",
+      "score": 5,
+      "scores": { "field": 3, "page_label": 2 },
+      "evidence": ["field:patient", "page_label:patient"],
+      "hint": "AcroSig:sig_patient"
+    },
+    {
+      "page": null,
+      "field_name": "vendor_or_acro_detected",
+      "role": "representative",
+      "score": 6,
+      "scores": { "page_label": 4, "general": 2 },
+      "evidence": ["page_label:representative(parent/guardian)", "pseudo:true"],
+      "hint": "VendorOrAcroOnly"
+    }
+  ]
+}
+~~~
+
+### Field notes
+
+- **`esign_found`** is `true` if any signature widget, AcroForm `/Sig` field, or vendor marker is detected.  
+- **`scanned_pdf`** is a heuristic: pages with images only and no extractable text.  
+- **`mixed`** means both `esign_found` and `scanned_pdf` are `true`.  
+- **`roles`** summarizes unique non-`unknown` roles across signatures.
+- In retainer profile, emitter prefers two signatures (client + firm), often on the same page.
+
+---
+
+## Configuration & rules
+
+Built-in rules live under **`src/sigdetect/data/`**:
+
+- **`vendor_patterns.yml`** – vendor byte/text patterns (e.g., DocuSign, Acrobat Sign).  
+- **`role_rules.yml`** – signer-role logic:  
+  - `labels` – strong page labels (e.g., “Signature of Patient”, including Parent/Guardian cases)  
+  - `general` – weaker role hints in surrounding text  
+  - `field_hints` – field-name keywords (e.g., `sig_patient`)  
+  - `doc_hard` – strong document-level triggers (relationship to patient, “minor/unable to sign”, first-person consent)  
+  - `weights` – scoring weights for the above  
+- **`role_rules.retainer.yml`** – retainer-specific rules (labels for client/firm, general tokens, and field hints).
+
+You can keep one config YAML per dataset, e.g.:
+~~~yaml
+# ./sample_data/config.yml (example)
+pdf_root: ./pdfs
+out_dir: ./sigdetect_out
+engine: pypdf2
+pseudo_signatures: true
+recurse_xobjects: true
+profile: retainer    # or: hipaa
+~~~
+
+YAML files can be customized or load at runtime (see CLI `--config`, if available, or import and pass patterns into engine).
+
+### Key detection behaviors
+
+- **Widget-first in mixed docs:** if a real `/Widget` exists, no pseudo “VendorOrAcroOnly” signature is emitted.  
+- **Acro-only dedupe:** multiple `/Sig` fields at the document level collapse to a single pseudo signature.  
+- **Parent/Guardian label:** “Signature of Parent/Guardian” maps to the `representative` role.  
+- **Field-name fallbacks:** role hints are pulled from `/T`, `/TU`, or `/TM` (in that order).
+  - Retainer heuristics:
+  - Looks for client and firm labels/tokens; boosts pages with law-firm markers (LLP/LLC/PA/PC) and “By:” blocks.
+  - Applies an anti-front-matter rule to reduce page-1 false positives (e.g., letterheads, firm mastheads).
+  - When only vendor/Acro clues exist (no widgets), it will emit two pseudo signatures targeting likely pages.
+
+---
+
+## Smoke tests
+
+Drop-in smoke tests live under **`tests/`** and cover:
+
+- Vendor-only (multiple markers)  
+- Acro-only (single pseudo with multiple `/Sig`)  
+- Mixed (real widget + vendor markers → widget role, no pseudo)  
+- Field-name fallbacks (`/TU`, `/TM`)  
+- Parent/Guardian label → `representative`  
+- Encrypted PDFs (graceful handling)
+
+Run a subset:
+
+~~~bash
+pytest -q -k smoke
+# or specific files:
+pytest -q tests/test_mixed_widget_vendor_smoke.py
+~~~
+
+---
+
+## Debugging
+If you need to debug or inspect the detection logic, you can run the CLI with `--debug`:
+~~~python
+from pathlib import Path
+from sigdetect.config import DetectConfiguration
+from sigdetect.detector.pypdf2_engine import PyPDF2Detector
+
+pdf = Path("/path/to/one.pdf")
+configuration = DetectConfiguration(
+    PdfRoot=pdf.parent,
+    OutputDirectory=Path("."),
+    Engine="pypdf2",
+    Profile="retainer",
+    PseudoSignatures=True,
+    RecurseXObjects=True,
+)
+print(PyPDF2Detector(configuration).Detect(pdf).to_dict())
+
+~~~
+
+---
+
+## Dev workflow
+
+### Project layout
+
+~~~text
+src/
+  sigdetect/
+    detector/
+      base.py
+      pypdf2_engine.py
+    data/
+      role_rules.yml
+      vendor_patterns.yml
+    cli.py
+tests/
+pyproject.toml
+.pre-commit-config.yaml
+~~~
+
+### Formatting & linting (pre-commit)
+
+~~~bash
+# one-time
+pip install pre-commit
+pre-commit install
+
+# run on all files
+pre-commit run --all-files
+~~~
+
+Hooks: `black`, `isort`, `ruff`, plus `pytest` (optional).  
+Ensure your virtualenv folders are excluded in `.pre-commit-config.yaml` (e.g., `^\.venv`).
+
+### Typical loop
+
+~~~bash
+# run tests
+pytest -q
+
+# run only smoke tests while iterating
+pytest -q -k smoke
+~~~
+
+---
+
+## Troubleshooting
+
+**Using the wrong Python**
+
+~~~bash
+which python
+python -V
+~~~
+
+If you see 3.8 or system Python, recreate the venv with 3.11.
+
+**ModuleNotFoundError: typer / click / pytest**
+
+~~~bash
+pip install typer click pytest
+~~~
+
+**Pre-commit reformats files in `.venv`**
+
+~~~yaml
+exclude: |
+  ^(\.venv|\.venv311|dist|build)/
+~~~
+
+**Vendor markers not detected**  
+Set `--recurse-xobjects true` and enable pseudo signatures. Many providers embed markers in Form XObjects or compressed streams.
+
+**Parent/Guardian not recognized**  
+The rules already include a fallback for “Signature of Parent/Guardian”; if your variant differs, add it to `role_rules.yml → labels.representative`.
+
+---
+
+## License
+MIT
+

sigdetect-0.1.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+sigdetect/__init__.py,sha256=LhY78mDZ1ClYVNTxW_qtE-vqJoN9N7N5ZcNRDUI_3ss,575
+sigdetect/api.py,sha256=Un4SaZHNAmRLPh1aF9bzOfT6ibilT_y9C0xVmNlqHtI,4248
+sigdetect/cli.py,sha256=jm7aStuv64MCcZZkzv8ncNVGGg8FYIFKjkTPNfXWUgs,3136
+sigdetect/config.py,sha256=d3_AlAEFUHBoXyTbUAHQLTARVqM8q4I8q4xfwakPE0M,4165
+sigdetect/eda.py,sha256=S92G1Gjmepri__D0n_V6foq0lQgH-RXI9anW8A58jfw,4681
+sigdetect/logging_setup.py,sha256=LMF8ao_a-JwH0S522T6aYTFX3e8Ajjv_5ODS2YiBcHA,6404
+sigdetect/utils.py,sha256=T9rubLf5T9JmjOHYMOba1j34fhOJaWocAXccnGTxRUE,5198
+sigdetect/data/role_rules.retainer.yml,sha256=IFdwKnDBXR2cTkdfrsZ6ku6CXD8S_dg5A3vKRKLW5h8,2532
+sigdetect/data/role_rules.yml,sha256=HuLKsZR_A6sD9XvY4NHiY_VG3dS5ERNCBF9-Mxawomw,2751
+sigdetect/data/vendor_patterns.yml,sha256=NRbZNQxcx_GuL6n1jAphBn6MM6ChCpeWGCsjbRx-PEo,384
+sigdetect/detector/__init__.py,sha256=up2FCmD09f2bRHcS4WbY-clx3GQbWuk1PM2JlxgusHg,1608
+sigdetect/detector/base.py,sha256=L-iXWXqsTetDc4jRZo_wOdbNpKqOY20mX9FefrugdT0,263
+sigdetect/detector/base_detector.py,sha256=GmAgUWO_fQgIfnihZSoyhR3wpnwZ-X3hS0Kuyz4G6Ys,608
+sigdetect/detector/file_result_model.py,sha256=j2gTc9Sw3fJOHlexYsR_m5DiwHA8DzIzAMToESfvo4A,1767
+sigdetect/detector/pymupdf_engine.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sigdetect/detector/pypdf2_engine.py,sha256=e3JasLxI8K10IkpMcijES2EjA7RluNpKq6027oNROPU,45770
+sigdetect/detector/signature_model.py,sha256=nApd53aDRMZhOLdUlmoEPjHO1hs8leM6NysG10v-jVc,857
+sigdetect-0.1.0.dist-info/METADATA,sha256=7au6ZW0VN_y3JyZQJux6zEUO8BMBEp6qVn0HO86aXlU,10363
+sigdetect-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+sigdetect-0.1.0.dist-info/entry_points.txt,sha256=iqtfKjBU44-omM7Sh-idGz2ahw19oAvpvSyKZVArG3o,48
+sigdetect-0.1.0.dist-info/top_level.txt,sha256=PKlfwUobkRC0viwiSXmhtw83G26FSNpimWYC1Uy00FY,10
+sigdetect-0.1.0.dist-info/RECORD,,

sigdetect-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sigdetect-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+sigdetect = sigdetect.cli:app

sigdetect-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sigdetect