sigdetect 0.1.0__py3-none-any.whl

sigdetect/__init__.py

@@ -0,0 +1,24 @@
+"""sigdetect – PDF e-sign detection & role attribution."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    import warnings
+
+    from pypdf.errors import PdfReadWarning
+
+    warnings.filterwarnings(
+        "ignore",
+        message=r"Multiple definitions in dictionary.*key /Subtype",
+        category=PdfReadWarning,
+    )
+except Exception:
+    # Never fail imports because of warnings setup
+    pass
+
+try:
+    __version__ = version("sigdetect")
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "0.0.0"
+
+DEFAULT_ENGINE = "pypdf2"

sigdetect/api.py

@@ -0,0 +1,139 @@
+"""Public helpers for programmatic use of the signature detection engine."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Iterable, Iterator, Literal
+
+from sigdetect.config import DetectConfiguration
+from sigdetect.detector import BuildDetector
+
+EngineName = Literal["pypdf2", "pypdf", "pymupdf"]
+ProfileName = Literal["hipaa", "retainer"]
+
+
+def DetectPdf(
+    pdfPath: str | Path,
+    *,
+    profileName: ProfileName = "hipaa",
+    engineName: EngineName = "pypdf2",
+    includePseudoSignatures: bool = True,
+    recurseXObjects: bool = True,
+) -> dict[str, Any]:
+    """Detect signature evidence and assign roles for a single PDF."""
+
+    resolvedPath = Path(pdfPath)
+
+    configuration = DetectConfiguration(
+        PdfRoot=resolvedPath.parent,
+        OutputDirectory=None,
+        Engine=engineName,
+        PseudoSignatures=includePseudoSignatures,
+        RecurseXObjects=recurseXObjects,
+        Profile=profileName,
+    )
+
+    detector = BuildDetector(configuration)
+    result = detector.Detect(resolvedPath)
+    return _ToPlainDictionary(result)
+
+
+def _ToPlainDictionary(candidate: Any) -> dict[str, Any]:
+    """Convert pydantic/dataclass instances to plain dictionaries."""
+
+    if hasattr(candidate, "to_dict"):
+        return candidate.to_dict()
+    if hasattr(candidate, "model_dump"):
+        return candidate.model_dump()  # type: ignore[attr-defined]
+    if hasattr(candidate, "dict"):
+        return candidate.dict()  # type: ignore[attr-defined]
+    try:
+        from dataclasses import asdict, is_dataclass
+
+        if is_dataclass(candidate):
+            return asdict(candidate)
+    except Exception:
+        pass
+    if isinstance(candidate, dict):
+        return {key: _ToPlainValue(candidate[key]) for key in candidate}
+    raise TypeError(f"Unsupported result type: {type(candidate)!r}")
+
+
+def _ToPlainValue(value: Any) -> Any:
+    """Best effort conversion for nested structures."""
+
+    if hasattr(value, "to_dict"):
+        return value.to_dict()
+    if hasattr(value, "model_dump") or hasattr(value, "dict"):
+        return _ToPlainDictionary(value)
+    try:
+        from dataclasses import asdict, is_dataclass
+
+        if is_dataclass(value):
+            return asdict(value)
+    except Exception:
+        pass
+    if isinstance(value, list):
+        return [_ToPlainValue(item) for item in value]
+    if isinstance(value, tuple):
+        return tuple(_ToPlainValue(item) for item in value)
+    if isinstance(value, dict):
+        return {key: _ToPlainValue(result) for key, result in value.items()}
+    return value
+
+
+def DetectMany(
+    pdfPaths: Iterable[str | Path],
+    **kwargs: Any,
+) -> Iterator[dict[str, Any]]:
+    """Yield :func:`DetectPdf` results for each path in ``pdfPaths``."""
+
+    for pdfPath in pdfPaths:
+        yield DetectPdf(pdfPath, **kwargs)
+
+
+def ScanDirectory(
+    pdfRoot: str | Path,
+    *,
+    globPattern: str = "**/*.pdf",
+    **kwargs: Any,
+) -> Iterator[dict[str, Any]]:
+    """Walk ``pdfRoot`` and yield detection output for every matching PDF."""
+
+    rootDirectory = Path(pdfRoot)
+    iterator = (
+        rootDirectory.rglob(globPattern.replace("**/", "", 1))
+        if globPattern.startswith("**/")
+        else rootDirectory.glob(globPattern)
+    )
+    for pdfPath in iterator:
+        if pdfPath.is_file() and pdfPath.suffix.lower() == ".pdf":
+            yield DetectPdf(pdfPath, **kwargs)
+
+
+def ToCsvRow(result: dict[str, Any]) -> dict[str, Any]:
+    """Return a curated subset of keys suitable for CSV export."""
+
+    return {
+        "file": result.get("file"),
+        "size_kb": result.get("size_kb"),
+        "pages": result.get("pages"),
+        "esign_found": result.get("esign_found"),
+        "scanned_pdf": result.get("scanned_pdf"),
+        "mixed": result.get("mixed"),
+        "sig_count": result.get("sig_count"),
+        "sig_pages": result.get("sig_pages"),
+        "roles": result.get("roles"),
+        "hints": result.get("hints"),
+    }
+
+
+def Version() -> str:
+    """Expose the installed package version without importing the CLI stack."""
+
+    try:
+        from importlib.metadata import version as resolveVersion
+
+        return resolveVersion("sigdetect")
+    except Exception:
+        return "0.0.0-dev"

sigdetect/cli.py

@@ -0,0 +1,98 @@
+"""Command line interface for the signature detection tool."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, is_dataclass
+from pathlib import Path
+
+import typer
+
+from . import __version__
+from .config import LoadConfiguration
+from .detector import BuildDetector
+from .eda import RunExploratoryAnalysis
+from .logging_setup import ConfigureLogging
+
+Logger = ConfigureLogging()
+
+CliApplication = typer.Typer(help="Signature detection & role attribution for PDFs")
+
+
+def _JsonSerializer(candidate):
+    """Ensure dataclasses and paths remain JSON serialisable."""
+
+    if hasattr(candidate, "to_dict"):
+        return candidate.to_dict()
+    if is_dataclass(candidate):
+        return asdict(candidate)
+    if isinstance(candidate, Path):
+        return str(candidate)
+    return str(candidate)
+
+
+@CliApplication.command(name="detect")
+def Detect(
+    configurationPath: Path | None = typer.Option(
+        None, "--config", "-c", help="Path to YAML config"
+    ),
+    profileOverride: str | None = typer.Option(None, "--profile", "-p", help="hipaa or retainer"),
+) -> None:
+    """Run detection for the configured directory and emit ``results.json``."""
+
+    configuration = LoadConfiguration(configurationPath)
+    if profileOverride in {"hipaa", "retainer"}:
+        configuration = configuration.model_copy(update={"Profile": profileOverride})
+
+    try:
+        detector = BuildDetector(configuration)
+    except ValueError as exc:
+        Logger.error(
+            "Detector initialisation failed",
+            extra={"engine": configuration.Engine, "error": str(exc)},
+        )
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(code=2) from exc
+
+    pdfFiles = list(configuration.PdfRoot.glob("*.pdf"))
+    if not pdfFiles:
+        raise SystemExit(f"No PDFs found in {configuration.PdfRoot}")
+
+    results = [detector.Detect(pdfPath) for pdfPath in pdfFiles]
+
+    # Allow configuration to suppress file output entirely (out_dir: none / SIGDETECT_OUT_DIR=none)
+    if configuration.OutputDirectory is None:
+        payload = json.dumps(results, indent=2, ensure_ascii=False, default=_JsonSerializer)
+        typer.echo(payload)
+        typer.echo("Detection completed with output disabled (out_dir=none)")
+        return
+
+    outputDirectory = configuration.OutputDirectory
+    outputDirectory.mkdir(parents=True, exist_ok=True)
+
+    with open(outputDirectory / "results.json", "w", encoding="utf-8") as handle:
+        json.dump(results, handle, indent=2, ensure_ascii=False, default=_JsonSerializer)
+
+    typer.echo(f"Wrote {outputDirectory / 'results.json'}")
+
+
+@CliApplication.command(name="eda")
+def ExploratoryAnalysis(
+    configurationPath: Path | None = typer.Option(
+        None, "--config", "-c", help="Path to YAML config"
+    ),
+) -> None:
+    """Generate a compact exploratory summary for the dataset."""
+
+    configuration = LoadConfiguration(configurationPath)
+    RunExploratoryAnalysis(configuration)
+
+
+@CliApplication.command(name="version")
+def Version() -> None:
+    """Print the installed package version."""
+
+    typer.echo(__version__)
+
+
+app = CliApplication

sigdetect/config.py

@@ -0,0 +1,117 @@
+"""Configuration loading utilities for the signature detection service."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Literal
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+EngineName = Literal["pypdf2", "pypdf", "pymupdf"]
+ProfileName = Literal["hipaa", "retainer"]
+
+
+class DetectConfiguration(BaseModel):
+    """Runtime settings governing signature detection.
+
+    The fields use PascalCase to comply with the CaseWorks standards while aliases keep
+    compatibility with the existing YAML configuration keys and environment variables.
+    """
+
+    model_config = ConfigDict(populate_by_name=True, frozen=True)
+
+    PdfRoot: Path = Field(default=Path("hipaa_results"), alias="pdf_root")
+    OutputDirectory: Path | None = Field(default=Path("out"), alias="out_dir")
+    Engine: EngineName = Field(default="pypdf2", alias="engine")
+    Profile: ProfileName = Field(default="hipaa", alias="profile")
+    MaxWorkers: int = Field(default=8, alias="max_workers", ge=1, le=64)
+    PseudoSignatures: bool = Field(default=True, alias="pseudo_signatures")
+    RecurseXObjects: bool = Field(default=True, alias="recurse_xobjects")
+
+    @field_validator("PdfRoot", "OutputDirectory", mode="before")
+    @classmethod
+    def _CoercePath(cls, value: str | Path | None) -> Path | None:
+        """Allow configuration values to be provided as ``str`` or ``Path``.
+
+        :param value: The candidate value from YAML or environment variables.
+        :returns: ``Path`` instances (or ``None`` for optional directories).
+        """
+
+        if value is None:
+            return None
+        if isinstance(value, Path):
+            return value
+        return Path(value)
+
+    # Expose legacy snake_case property names for gradual migration
+    @property
+    def pdf_root(self) -> Path:  # pragma: no cover - simple passthrough
+        return self.PdfRoot
+
+    @property
+    def out_dir(self) -> Path | None:  # pragma: no cover - simple passthrough
+        return self.OutputDirectory
+
+    @property
+    def engine(self) -> EngineName:  # pragma: no cover - simple passthrough
+        return self.Engine
+
+    @property
+    def profile(self) -> ProfileName:  # pragma: no cover - simple passthrough
+        return self.Profile
+
+    @property
+    def max_workers(self) -> int:  # pragma: no cover - simple passthrough
+        return self.MaxWorkers
+
+    @property
+    def pseudo_signatures(self) -> bool:  # pragma: no cover - simple passthrough
+        return self.PseudoSignatures
+
+    @property
+    def recurse_xobjects(self) -> bool:  # pragma: no cover - simple passthrough
+        return self.RecurseXObjects
+
+
+def LoadConfiguration(path: Path | None) -> DetectConfiguration:
+    """Load configuration from ``path`` while applying environment overrides.
+
+    Environment variables provide the final say and follow the existing naming:
+
+    ``SIGDETECT_ENGINE``
+        Override the PDF parsing engine.
+    ``SIGDETECT_PDF_ROOT``
+        Directory that will be scanned for PDF files.
+    ``SIGDETECT_OUT_DIR``
+        Output directory for generated artefacts. Use ``"none"`` to disable writes.
+    ``SIGDETECT_PROFILE``
+        Runtime profile that controls which heuristics are applied.
+    """
+
+    env_engine = os.getenv("SIGDETECT_ENGINE")
+    env_pdf_root = os.getenv("SIGDETECT_PDF_ROOT")
+    env_out_dir = os.getenv("SIGDETECT_OUT_DIR")
+    env_profile = os.getenv("SIGDETECT_PROFILE")
+
+    raw_data: dict[str, object] = {}
+    if path and Path(path).exists():
+        with open(path, encoding="utf-8") as handle:
+            raw_data = yaml.safe_load(handle) or {}
+
+    if env_engine:
+        raw_data["engine"] = env_engine
+    if env_pdf_root:
+        raw_data["pdf_root"] = env_pdf_root
+    if env_out_dir:
+        raw_data["out_dir"] = None if env_out_dir.lower() == "none" else env_out_dir
+    if env_profile in {"hipaa", "retainer"}:
+        raw_data["profile"] = env_profile
+
+    configuration = DetectConfiguration(**raw_data)
+
+    if configuration.OutputDirectory is not None:
+        configuration.OutputDirectory.mkdir(parents=True, exist_ok=True)
+
+    return configuration

sigdetect/data/role_rules.retainer.yml

@@ -0,0 +1,61 @@
+# --- vendor markers
+bytes:
+  - '/DocuSign'
+  - '/DSS'
+  - '/DocTimeStamp'
+  - '/Adobe\.PPKLite'
+
+text:
+  - 'DocuSign\s+Envelope\s+ID'
+  - 'Signature\s+Certificate'
+  - 'PandaDoc'
+  - 'Signed\s+with\s+PandaDoc'
+  - 'Reference\s+number'
+
+# --- labels near signature lines/boxes ---
+labels:
+  client: '(client\s*signature|name\s+of\s+client|client\s+print\s+name|client\s+signature:)'
+  firm: '(signature\s+of\s+(the\s+)?attorney|attorney''?s?\s+signature|counsel\s+signature|by:\s+.*(llp|llc|law|attorney|esq))'
+  patient: '(client\s*signature|name\s+of\s+client|client\s+print\s+name|client\s+signature:)'
+  representative: '(parent\s*/\s*guardian|guardian\s+signature|parent\s+signature)'
+  attorney: '(signature\s+of\s+(the\s+)?attorney|attorney''?s?\s+signature|counsel\s+signature|by:\s+.*(llp|llc|law|attorney|esq))'
+
+# --- general tokens allowed across a page ---
+general:
+  client: '\bclient\b|\bclient''?s\b'
+  firm: '\besq\.?\b|\battorney\b|\blaw\s*f(?:irm)?\b|\bllp\b|\bllc\b|\bpartner\b'
+  patient: '\bclient\b|\bclient''?s\b'
+  representative: '\brepresentative\b|\bguardian\b|\bparent\b'
+  attorney: '\besq\.?\b|\battorney\b|\blaw\s*f(?:irm)?\b|\bllp\b|\bllc\b|\bpartner\b'
+
+# --- field-name hints (/T, /TU, /TM) ---
+field_hints:
+  client: ['client', 'clientname', 'clientsignature', 'name_of_client', 'client_signature']
+  firm: ['attorney', 'lawyer', 'counsel', 'firm', 'partner']
+  patient: ['client', 'clientname', 'clientsignature', 'name_of_client', 'client_signature']
+  representative: ['parent', 'guardian', 'representative']
+  attorney: ['attorney', 'lawyer', 'counsel', 'firm', 'partner']
+
+# --- doc-level rules  ---
+doc_hard:
+  rel_label: 'relationship\s+to\s+(patient|client)'
+  kin: '\b(mother|father|mom|dad|child|son|daughter|spouse|husband|wife|guardian|parent|grandmother|grandfather|grandparent|step[-\s]?parent|stepmother|stepfather|next\s+of\s+kin|conservator|custodian|caregiver)\b'
+  minor: '\bminor\b|patient\s+was\s+unable\s+to\s+sign|unable\s+to\s+sign'
+  first_person: 'I\s*,?\s*[A-Za-z.\-''\s]{1,80}\s*,?\s+authorize\b'
+
+# --- weights  ---
+weights:
+  field: 3
+  page_label: 2
+  general: 1
+  doc_hint_strong: 3
+  doc_hint_weak: 2
+
+# --- retainer-only helpers: used to pick the most likely signature pages ---
+retain:
+  signature_zone: '(signature\b|signed\s*:|by\s*:|date\b)'
+  exclude_page: '(signature\s+certificate|pandadoc)'
+
+markers:
+  client: 'client\\s*(printed\\s*)?signature|signature\\s*:\\s*client'
+  firm:   'law\\s*firm|attorney\\s*signature|quinn\\s+emanuel|ventur[a|o]\\s+law'

sigdetect/data/role_rules.yml

@@ -0,0 +1,71 @@
+bytes:
+  - '/DocuSign'
+  - '/Adobe\.PPKLite'
+  - '/DocTimeStamp'
+  - '/DSS'
+  - '/AcrobatSign'
+  - '/HelloSign'
+  - '/Vinesign'
+
+text:
+  - 'DocuSign\s+Envelope\s+ID'
+  - 'Signature\s+Certificate'
+  - 'Electronic\s+Record\s+and\s+Signature\s+Disclosure'
+  - 'Adobe\s+Acrobat\s+Sign|Acrobat\s+Sign'
+  - 'HelloSign|Dropbox\s+Sign'
+  - 'Vinesign'
+
+# LABELS: only “Signature of …” style phrases (keep narrow)
+labels:
+  patient: '(signature\s+of\s+(the\s+)?patient|patient''?s?\s+signature|patient\s+signature)'
+  attorney: '(signature\s+of\s+(the\s+)?attorney|attorney''?s?\s+signature|attorney\s+signature|counsel\s+signature)'
+  representative: '(signature\s+of\s+(the\s+)?(authorized\s+)?representative|representative''?s?\s+signature|parent\s*(/|\s+and\s+)?\s*guardian\s+signature|guardian\s+signature|executor\s+signature|custodian\s+signature|conservator\s+signature)'
+
+# GENERAL tokens (broader, weaker than labels)
+general:
+  attorney: '\battorney''?s?\b'
+  representative: '\brepresentative\b|\bparent\b|\bguardian\b'
+  patient: '\b(patient|self)\b|I\s*,?\s*[A-Za-z.\-''\s]{1,60}\s*,?\s+authorize\b'
+
+# Field-name hints used for /T, /TU, /TM
+field_hints:
+  patient: ['patient', 'plaintiff', 'self', 'claimant']
+  attorney: ['attorney', 'lawyer', 'counsel']
+  representative: ['representative', 'rep', 'guardian', 'parent', 'executor', 'custodian', 'conservator', 'poa', 'powerofattorney']
+
+# Hard rules used in vendor/Acro-only pseudo signatures
+doc_hard:
+  rel_label: 'relationship\s+to\s+patient(\s*\(.*?\))?'
+  kin: '\b(mother|father|mom|dad|child|son|daughter|spouse|husband|wife|guardian|parent|grandmother|grandfather|grandparent|step[-\s]?parent|stepmother|stepfather|next\s+of\s+kin|conservator|custodian|caregiver)\b'
+  minor: '\bminor\b|patient\s+was\s+unable\s+to\s+sign|unable\s+to\s+sign'
+  first_person: 'I\s*,?\s*[A-Za-z.\-''\s]{1,80}\s*,?\s+authorize\b'
+
+# Document-level hints for vendor-only pseudo (multiplicative scoring)
+doc_hints_strong:
+  representative:
+    - '\bparent\s*/\s*guardian\b'
+    - '\brelationship\s+to\s+patient\b'
+    - '\bnext\s+of\s+kin\b'
+    - '\bminor\b'
+    - 'reason\s+patient\s+was\s+unable\s+to\s+sign'
+    - '\bauthorized\s+representative\b'
+    - '\b(power\s+of\s+attorney|P\.?O\.?A)\b'
+    - '\blegal\s+representative\b'
+  patient:
+    - '\bsigned?\s*\(\s*patient\b'
+    - '\bpatient''?s?\s*signature\b'
+  attorney:
+    - '(signature\s+of\s+(the\s+)?attorney|attorney''?s?\s+signature|counsel\s+signature)'
+    - '\besq\.?\b|\bbar\s+no\.?\b'
+
+doc_hints_weak:
+  representative: ['\bguardian\b', '\brepresentative\b', '\bparent\b']
+  patient: ['\bpatient\b', '\bself\b']
+  # no weak attorney on purpose
+
+weights:
+  field: 3
+  page_label: 2
+  general: 1
+  doc_hint_strong: 3
+  doc_hint_weak: 2

sigdetect/data/vendor_patterns.yml

@@ -0,0 +1,16 @@
+bytes:
+  - "/DocuSign"
+  - "/Adobe.PPKLite"
+  - "/DocTimeStamp"
+  - "/DSS"
+  - "/AcrobatSign"
+  - "/HelloSign"
+  - "/Vinesign"
+text:
+  - "DocuSign\\s+Envelope\\s+ID"
+  - "Digitally\\s+signed\\s+by"
+  - "Adobe\\s+Acrobat\\s+Sign|Acrobat\\s+Sign"
+  - "HelloSign|Dropbox\\s+Sign"
+  - "Vinesign"
+  - "Electronic\\s+Record\\s+and\\s+Signature\\s+Disclosure"
+  - "Signature\\s+Certificate"

sigdetect/detector/__init__.py

@@ -0,0 +1,55 @@
+"""Detector exports and factory helpers."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Type
+
+from .base_detector import Detector
+from .file_result_model import FileResult
+from .pypdf2_engine import PyPDF2Detector
+from .signature_model import Signature
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from sigdetect.config import DetectConfiguration
+
+
+ENGINE_REGISTRY: dict[str, Type[Detector]] = {
+    PyPDF2Detector.Name: PyPDF2Detector,
+}
+
+# Accept modern engine alias alongside legacy configuration default.
+ENGINE_REGISTRY.setdefault("pypdf", PyPDF2Detector)
+
+try:  # pragma: no cover - optional dependency
+    from .pymupdf_engine import PyMuPDFDetector  # type: ignore
+
+    if getattr(PyMuPDFDetector, "Name", None):
+        ENGINE_REGISTRY[PyMuPDFDetector.Name] = PyMuPDFDetector
+except Exception:
+    PyMuPDFDetector = None  # type: ignore
+
+
+def BuildDetector(configuration: DetectConfiguration) -> Detector:
+    """Instantiate the configured engine or raise a clear error."""
+
+    engine_name = (
+        getattr(configuration, "Engine", None)
+        or getattr(configuration, "engine", None)
+        or PyPDF2Detector.Name
+    )
+    normalized = engine_name.lower()
+
+    detector_cls = ENGINE_REGISTRY.get(normalized)
+    if detector_cls is None:
+        available = ", ".join(sorted(ENGINE_REGISTRY)) or "<none>"
+        raise ValueError(f"Unsupported engine '{engine_name}'. Available engines: {available}")
+    return detector_cls(configuration)
+
+
+__all__ = [
+    "BuildDetector",
+    "Detector",
+    "ENGINE_REGISTRY",
+    "FileResult",
+    "Signature",
+]

sigdetect/detector/base.py

@@ -0,0 +1,9 @@
+"""Compatibility module exporting detector primitives."""
+
+from __future__ import annotations
+
+from .base_detector import Detector
+from .file_result_model import FileResult
+from .signature_model import Signature
+
+__all__ = ["Detector", "FileResult", "Signature"]

sigdetect/detector/base_detector.py

@@ -0,0 +1,22 @@
+"""Abstract base class for signature detection engines."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .file_result_model import FileResult
+
+
+class Detector:
+    """Common interface implemented by concrete detectors."""
+
+    Name: str = "base"
+
+    def Detect(self, pdfPath: Path) -> FileResult:  # pragma: no cover
+        """Analyse ``pdfPath`` and return detection results."""
+
+        raise NotImplementedError
+
+    # Provide backwards compatibility for snake_case callers
+    def detect(self, pdfPath: Path) -> FileResult:  # pragma: no cover
+        return self.Detect(pdfPath)

sigdetect/detector/file_result_model.py

@@ -0,0 +1,59 @@
+"""Result container returned from detection engines."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from .signature_model import Signature
+
+
+@dataclass(slots=True)
+class FileResult:
+    """Aggregated detection outcome for a single PDF file."""
+
+    File: str
+    SizeKilobytes: float | None
+    PageCount: int
+    ElectronicSignatureFound: bool
+    ScannedPdf: bool | None
+    MixedContent: bool | None
+    SignatureCount: int
+    SignaturePages: str
+    Roles: str
+    Hints: str
+    Signatures: list[Signature] = field(default_factory=list)
+
+    # Backwards-compatible attribute aliases
+    @property
+    def Pages(self) -> int:  # pragma: no cover - simple passthrough
+        return self.PageCount
+
+    @property
+    def pages(self) -> int:  # pragma: no cover - simple passthrough
+        return self.PageCount
+
+    @property
+    def sig_pages(self) -> str:  # pragma: no cover - simple passthrough
+        return self.SignaturePages
+
+    @property
+    def sig_count(self) -> int:  # pragma: no cover - simple passthrough
+        return self.SignatureCount
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return the legacy snake_case representation used by existing clients."""
+
+        return {
+            "file": self.File,
+            "size_kb": self.SizeKilobytes,
+            "pages": self.PageCount,
+            "esign_found": self.ElectronicSignatureFound,
+            "scanned_pdf": self.ScannedPdf,
+            "mixed": self.MixedContent,
+            "sig_count": self.SignatureCount,
+            "sig_pages": self.SignaturePages,
+            "roles": self.Roles,
+            "hints": self.Hints,
+            "signatures": [signature.to_dict() for signature in self.Signatures],
+        }