docketry 0.1.0__py3-none-any.whl

docketry/__init__.py

@@ -0,0 +1,8 @@
+"""Docketry: a local, gate-enforced port that email flows into.
+
+Working name — Docketry is the base layer of a family of small open-source
+legal workflow tools. It never reaches into a mailbox the firm works from;
+it drains a dedicated intake mailbox the firm forwards into, normalizes each
+message, and enforces guardrail gates before anything moves downstream.
+"""
+__version__ = "0.1.0"

docketry/cite.py

@@ -0,0 +1,253 @@
+"""Citation verification: the existence + name + quote + pin check.
+
+Four factual checks against CourtListener, and nothing else:
+
+1. The cited case exists (volume/reporter/page resolves).
+2. The case NAME matches what that reporter cite actually resolves to —
+   the hallucination class where a real citation carries an invented name.
+3. Quoted language attributed to the case actually appears in the opinion.
+4. A pin cite points at the page where the quoted language sits (via the
+   opinion's star pagination, when the source provides it).
+
+This module never says anything is good law, current, binding, or apt. It
+reports that a citation string does not match the document it points to, and
+it degrades loudly: no network means extraction-only, never a silent pass.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+_GENERIC_TOKENS = {
+    "state", "company", "companies", "insurance", "corp", "corporation",
+    "inc", "llc", "llp", "co", "of", "the", "and", "in", "re", "ex", "rel",
+    "et", "al", "v", "vs", "a", "an", "county", "city", "board", "dept",
+    "department", "america", "american", "national", "united", "states",
+}
+
+_QUOTE_RX = re.compile(r'[“"]([^“”"]{25,}?)[”"]')
+_STAR_RX = re.compile(r'<span[^>]*class="star-pagination"[^>]*label="(\d+)"[^>]*>')
+_TAG_RX = re.compile(r"<[^>]+>")
+
+
+class CiteError(RuntimeError):
+    pass
+
+
+@dataclass
+class Citation:
+    text: str            # the citation as written, e.g. "260 So. 3d 323"
+    plaintiff: str
+    defendant: str
+    pin_page: int | None
+    span: tuple[int, int]  # character span in the source text
+
+
+@dataclass
+class Lookup:
+    exists: bool
+    case_name: str = ""
+    cluster_id: int | None = None
+
+
+@dataclass
+class CiteFinding:
+    citation: str
+    check: str           # exists | name | quote | pin
+    severity: str        # fail | warn | info
+    summary: str
+
+
+@dataclass
+class Report:
+    citations: list[Citation]
+    short_citations: int = 0
+    findings: list[CiteFinding] = field(default_factory=list)
+
+    @property
+    def failed(self) -> bool:
+        return any(f.severity == "fail" for f in self.findings)
+
+
+def _normalize(s: str) -> str:
+    s = s.replace("“", '"').replace("”", '"')
+    s = s.replace("‘", "'").replace("’", "'")
+    return re.sub(r"\s+", " ", s).strip().lower()
+
+
+def _tokens(name: str) -> set[str]:
+    return {
+        t for t in re.findall(r"[a-z0-9]+", name.lower())
+        if len(t) > 2 and t not in _GENERIC_TOKENS
+    }
+
+
+def extract_citations(text: str) -> list[Citation]:
+    """Full case citations via eyecite. Needs the 'cite' extra."""
+    return _extract(text)[0]
+
+
+def citation_inventory(text: str) -> tuple[list[Citation], int]:
+    """(full citations, count of short-form/supra/id citations).
+
+    Short-form cites ("329 So. 3d at 153") depend on an antecedent full cite;
+    when the fulls live outside the document (a redline, an excerpt, a brief
+    section), the shorts are UNVERIFIABLE AS WRITTEN — and that must be said
+    loudly, never reported as "0 citations found".
+    """
+    return _extract(text)
+
+
+def _extract(text: str) -> tuple[list[Citation], int]:
+    try:
+        import eyecite
+        from eyecite.models import (
+            FullCaseCitation, IdCitation, ShortCaseCitation, SupraCitation,
+        )
+    except ImportError:
+        raise CiteError(
+            "citation extraction needs the 'cite' extra:"
+            " pip install 'docketry[cite]'"
+        ) from None
+
+    out: list[Citation] = []
+    n_short = 0
+    for cite in eyecite.get_citations(text):
+        if isinstance(cite, (ShortCaseCitation, SupraCitation, IdCitation)):
+            n_short += 1
+            continue
+        if not isinstance(cite, FullCaseCitation):
+            continue
+        meta = cite.metadata
+        pin = None
+        if meta.pin_cite:
+            m = re.search(r"\d+", meta.pin_cite)
+            pin = int(m.group()) if m else None
+        out.append(
+            Citation(
+                text=cite.corrected_citation(),
+                plaintiff=meta.plaintiff or "",
+                defendant=meta.defendant or "",
+                pin_page=pin,
+                span=cite.span(),
+            )
+        )
+    return out, n_short
+
+
+def name_matches(plaintiff: str, defendant: str, resolved_name: str) -> bool:
+    """Side-aware significant-token check of the cited name vs the resolved one.
+
+    Every cited side that has significant tokens must land at least one of
+    them in the corresponding side of the resolved caption (either order, to
+    tolerate cross-appeals); a consolidated/inre caption without "v." is
+    checked against the whole name.
+    """
+    cited = [(i, s) for i, s in enumerate((_tokens(plaintiff), _tokens(defendant))) if s]
+    if not cited:
+        return True  # nothing asserted, nothing to contradict
+    resolved_sides = [
+        _tokens(part) for part in re.split(r"\s+v\.?\s+", resolved_name, maxsplit=1)
+    ]
+    if len(resolved_sides) == 2:
+        if all(toks & resolved_sides[i] for i, toks in cited):
+            return True
+        # A full swap is a legitimate cross-appeal caption; a single cited
+        # side matching only the OPPOSITE side is the classic wrong-name
+        # hallucination (e.g. the defendant's surname promoted to plaintiff),
+        # so the swap is only honored when BOTH sides swap cleanly.
+        if len(cited) == 2 and all(toks & resolved_sides[1 - i] for i, toks in cited):
+            return True
+        return False
+    whole = _tokens(resolved_name)
+    return all(toks & whole for _, toks in cited)
+
+
+def quotes_near(text: str, span: tuple[int, int], *, window: int = 600) -> list[str]:
+    """Quoted passages (>=25 chars) in the window before the citation."""
+    region = text[max(0, span[0] - window):span[0]]
+    return [m.group(1) for m in _QUOTE_RX.finditer(region)]
+
+
+def star_pages(opinion_html: str) -> list[tuple[int, str]]:
+    """(page_label, normalized text of the segment that FOLLOWS it)."""
+    out: list[tuple[int, str]] = []
+    matches = list(_STAR_RX.finditer(opinion_html))
+    for i, m in enumerate(matches):
+        end = matches[i + 1].start() if i + 1 < len(matches) else len(opinion_html)
+        segment = _TAG_RX.sub(" ", opinion_html[m.end():end])
+        out.append((int(m.group(1)), _normalize(segment)))
+    return out
+
+
+def verify(text: str, client) -> Report:
+    """Run the four checks over every full citation in `text`.
+
+    `client` provides lookup(citation_text) -> Lookup and
+    opinion_text(cluster_id) -> (plain_text, html_or_None).
+    """
+    citations, n_short = citation_inventory(text)
+    report = Report(citations=citations, short_citations=n_short)
+    if n_short and not citations:
+        report.findings.append(CiteFinding(
+            "(short-form)", "exists", "fail",
+            f"{n_short} short-form citation(s) (e.g. '329 So. 3d at 153') with"
+            " no full citation anywhere in this document — unverifiable as"
+            " written; a filed brief must carry the full cites",
+        ))
+    elif n_short:
+        report.findings.append(CiteFinding(
+            "(short-form)", "exists", "info",
+            f"{n_short} short-form citation(s) ride on the full citations"
+            " verified above",
+        ))
+    for cite in citations:
+        lookup: Lookup = client.lookup(cite.text)
+        if not lookup.exists:
+            report.findings.append(
+                CiteFinding(cite.text, "exists", "fail",
+                            f"{cite.text}: no case found at this citation")
+            )
+            continue
+        cited_name = f"{cite.plaintiff} v. {cite.defendant}".strip(" v.")
+        if not name_matches(cite.plaintiff, cite.defendant, lookup.case_name):
+            report.findings.append(
+                CiteFinding(
+                    cite.text, "name", "fail",
+                    f"cited as \"{cited_name}\" but {cite.text} resolves to"
+                    f" \"{lookup.case_name}\"",
+                )
+            )
+        quotes = quotes_near(text, cite.span)
+        if quotes and lookup.cluster_id is not None:
+            opinion_plain, opinion_html = client.opinion_text(lookup.cluster_id)
+            norm_opinion = _normalize(opinion_plain)
+            pages = star_pages(opinion_html) if opinion_html else []
+            for q in quotes:
+                nq = _normalize(q).rstrip(".;:,!?")
+                if nq not in norm_opinion and not any(nq in seg for _, seg in pages):
+                    report.findings.append(
+                        CiteFinding(
+                            cite.text, "quote", "fail",
+                            f"quoted language not found in {lookup.case_name}:"
+                            f" \"{q[:80]}...\"" if len(q) > 80 else
+                            f"quoted language not found in {lookup.case_name}:"
+                            f" \"{q}\"",
+                        )
+                    )
+                elif cite.pin_page is not None and pages:
+                    hit = [label for label, seg in pages if nq in seg]
+                    if hit and cite.pin_page not in hit:
+                        report.findings.append(
+                            CiteFinding(
+                                cite.text, "pin", "warn",
+                                f"pin cite says p. {cite.pin_page} but the"
+                                f" quoted language sits at p. {hit[0]}",
+                            )
+                        )
+        if not report.findings or report.findings[-1].citation != cite.text:
+            report.findings.append(
+                CiteFinding(cite.text, "exists", "info",
+                            f"{cite.text} -> {lookup.case_name}")
+            )
+    return report

docketry/cite_client.py

@@ -0,0 +1,68 @@
+"""CourtListener client for citation verification. Needs the 'cite' extra.
+
+Thin and honest: the user's own token (COURTLISTENER_TOKEN), tight timeouts,
+and every network failure surfaces as CiteError — offline degrades to
+extraction-only in the CLI, never to a silent pass.
+"""
+from __future__ import annotations
+
+import os
+
+from .cite import CiteError, Lookup
+
+BASE = "https://www.courtlistener.com/api/rest/v4"
+
+
+class CourtListenerClient:
+    def __init__(self, token: str | None = None, base_url: str = BASE, timeout: float = 30.0):
+        try:
+            import httpx
+        except ImportError:
+            raise CiteError(
+                "network verification needs the 'cite' extra:"
+                " pip install 'docketry[cite]'"
+            ) from None
+        headers = {"User-Agent": "docketry cite-verify"}
+        token = token or os.environ.get("COURTLISTENER_TOKEN")
+        if token:
+            headers["Authorization"] = f"Token {token}"
+        self._http = httpx.Client(base_url=base_url, headers=headers, timeout=timeout)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def lookup(self, citation_text: str) -> Lookup:
+        try:
+            resp = self._http.post("/citation-lookup/", data={"text": citation_text})
+            resp.raise_for_status()
+            results = resp.json()
+        except Exception as e:
+            raise CiteError(f"citation lookup failed for {citation_text!r}: {e}") from e
+        for row in results:
+            if row.get("status") == 200 and row.get("clusters"):
+                cluster = row["clusters"][0]
+                return Lookup(
+                    exists=True,
+                    case_name=cluster.get("case_name", ""),
+                    cluster_id=cluster.get("id"),
+                )
+        return Lookup(exists=False)
+
+    def opinion_text(self, cluster_id: int) -> tuple[str, str | None]:
+        try:
+            resp = self._http.get(
+                "/opinions/", params={"cluster__id": cluster_id, "fields": "plain_text,xml_harvard,html_with_citations"}
+            )
+            resp.raise_for_status()
+            rows = resp.json().get("results", [])
+        except Exception as e:
+            raise CiteError(f"opinion fetch failed for cluster {cluster_id}: {e}") from e
+        if not rows:
+            return "", None
+        op = rows[0]
+        html = op.get("xml_harvard") or op.get("html_with_citations") or None
+        plain = op.get("plain_text") or ""
+        if not plain and html:
+            import re
+            plain = re.sub(r"<[^>]+>", " ", html)
+        return plain, html

docketry/classify.py

@@ -0,0 +1,60 @@
+"""Deterministic litigation-document classifier.
+
+Types a filed document from its title first (high confidence), body anchors
+second (medium), and falls back to correspondence (low). No model calls, no
+network, no cost — LLMs are a last resort that this module deliberately is
+not. The classifier only ever PROPOSES: writes are staged for approval and
+applied fill-only by a human with the declared authority (see store/CLI).
+"""
+from __future__ import annotations
+
+import re
+
+LABELS = (
+    "amended_complaint", "complaint", "answer",
+    "motion_msj", "motion_dismiss", "motion_compel", "motion",
+    "order", "notice_of_hearing", "notice",
+    "discovery_request", "discovery_response",
+    "subpoena", "deposition", "correspondence",
+)
+
+_T = [  # title anchors, ordered: first match wins
+    ("amended_complaint", r"amended\s+(?:complaint|petition)"),
+    ("order", r"^(?:agreed\s+|proposed\s+)?order\b|order\s+(?:granting|denying|on|setting)"),
+    ("motion_msj", r"motion\s+for\s+(?:final\s+)?summary\s+judgment"),
+    ("motion_dismiss", r"motion\s+to\s+dismiss"),
+    ("motion_compel", r"motion\s+to\s+compel"),
+    ("deposition", r"(?:notice\s+of\s+taking\s+)?deposition\s+of|depo(?:sition)?\s+transcript"),
+    ("notice_of_hearing", r"notice\s+of\s+hearing"),
+    ("subpoena", r"subpoena"),
+    ("discovery_response", r"(?:response|objection)s?\s+to\s+.*(?:interrogator|production|admission|discovery)"),
+    ("discovery_request", r"interrogator|request\s+(?:for|to)\s+produc|request\s+for\s+admission"),
+    ("answer", r"\banswer\b.*affirmative\s+defenses|\banswer\s+to\b|defendant'?s?\s+answer"),
+    ("motion", r"\bmotion\b"),
+    ("complaint", r"\b(?:complaint|petition)\b"),
+    ("notice", r"\bnotice\b"),
+]
+_TITLE_ANCHORS = [(label, re.compile(rx, re.IGNORECASE)) for label, rx in _T]
+
+_B = [  # body anchors, checked in the first 3000 chars
+    ("order", r"ORDERED\s+AND\s+ADJUDGED|it\s+is\s+hereby\s+ORDERED"),
+    ("complaint", r"COMES\s+NOW.{0,200}(?:complaint|sues?\s+defendant)"),
+    ("discovery_request", r"propounds?\s+the\s+following\s+interrogator"),
+    ("answer", r"answers?\s+the\s+complaint\s+and\s+(?:asserts?\s+)?affirmative\s+defenses"),
+    ("deposition", r"APPEARANCES.{0,600}(?:COURT\s+REPORTER|STENOGRAPH)"),
+]
+_BODY_ANCHORS = [(label, re.compile(rx, re.IGNORECASE | re.DOTALL)) for label, rx in _B]
+
+
+def classify(title: str, text: str = "") -> tuple[str, str]:
+    """(label, tier) — tier: high (title anchor) / medium (body) / low."""
+    title = (title or "").replace("_", " ").replace("-", " ")
+    for label, rx in _TITLE_ANCHORS:
+        if rx.search(title):
+            return label, "high"
+    head = (text or "")[:3000]
+    if head:
+        for label, rx in _BODY_ANCHORS:
+            if rx.search(head):
+                return label, "medium"
+    return "correspondence", "low"