mindforge-cc 11.8.2 → 11.9.0

package/.mindforge/skills/osint-investigation/scripts/fetch_ofac_sdn.py

@@ -0,0 +1,175 @@
+#!/usr/bin/env python3
+"""Fetch OFAC SDN list (CSV format) and normalize.
+
+Public endpoint: https://www.treasury.gov/ofac/downloads/sdn.csv
+Format reference: https://ofac.treasury.gov/specially-designated-nationals-and-blocked-persons-list-sdn-human-readable-lists
+
+The SDN CSV uses a specific 12-column format with no header row:
+    ent_num, sdn_name, sdn_type, program, title, call_sign, vess_type,
+    tonnage, grt, vess_flag, vess_owner, remarks
+Address and AKA records live in separate files. We fetch all three and join.
+"""
+from __future__ import annotations
+
+import argparse
+import csv
+import io
+import sys
+from collections import defaultdict
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from _http import get  # noqa: E402
+
+SDN_URL = "https://www.treasury.gov/ofac/downloads/sdn.csv"
+ADD_URL = "https://www.treasury.gov/ofac/downloads/add.csv"
+ALT_URL = "https://www.treasury.gov/ofac/downloads/alt.csv"
+
+SDN_COLS = [
+    "ent_num", "sdn_name", "sdn_type", "program", "title",
+    "call_sign", "vess_type", "tonnage", "grt", "vess_flag",
+    "vess_owner", "remarks",
+]
+ADD_COLS = [
+    "ent_num", "add_num", "address", "city_state_zip", "country", "add_remarks",
+]
+ALT_COLS = [
+    "ent_num", "alt_num", "alt_type", "alt_name", "alt_remarks",
+]
+
+COLUMNS = [
+    "entity_id",
+    "name",
+    "entity_type",
+    "program_list",
+    "title",
+    "nationalities",
+    "aka_list",
+    "addresses",
+    "dob",
+    "pob",
+    "remarks",
+    "last_updated",
+]
+
+_TYPE_MAP = {
+    "individual": "individual",
+    "entity": "entity",
+    "vessel": "vessel",
+    "aircraft": "aircraft",
+}
+
+
+def _read_csv(url: str, columns: list[str]) -> list[dict[str, str]]:
+    body = get(url, timeout=60).decode("latin-1", errors="replace")
+    reader = csv.reader(io.StringIO(body))
+    out = []
+    for row in reader:
+        if not row:
+            continue
+        # Pad/truncate to expected width.
+        row = row[: len(columns)] + [""] * (len(columns) - len(row))
+        out.append(dict(zip(columns, row)))
+    return out
+
+
+def _strip_quotes(s: str) -> str:
+    s = s.strip()
+    if s.startswith('"') and s.endswith('"'):
+        s = s[1:-1]
+    if s == "-0-":
+        return ""
+    return s
+
+
+def fetch(
+    program: str | None,
+    entity_type: str | None,
+    out_path: str,
+) -> int:
+    sdn = _read_csv(SDN_URL, SDN_COLS)
+    addresses = _read_csv(ADD_URL, ADD_COLS)
+    akas = _read_csv(ALT_URL, ALT_COLS)
+
+    addr_by_ent: dict[str, list[str]] = defaultdict(list)
+    for a in addresses:
+        ent = _strip_quotes(a["ent_num"])
+        parts = [
+            _strip_quotes(a[c])
+            for c in ("address", "city_state_zip", "country")
+            if _strip_quotes(a[c])
+        ]
+        if parts:
+            addr_by_ent[ent].append(", ".join(parts))
+
+    aka_by_ent: dict[str, list[str]] = defaultdict(list)
+    for k in akas:
+        ent = _strip_quotes(k["ent_num"])
+        name = _strip_quotes(k["alt_name"])
+        if name:
+            aka_by_ent[ent].append(name)
+
+    rows: list[dict[str, str]] = []
+    for r in sdn:
+        ent_num = _strip_quotes(r["ent_num"])
+        if not ent_num:
+            continue
+        sdn_type = _TYPE_MAP.get(_strip_quotes(r["sdn_type"]).lower(), _strip_quotes(r["sdn_type"]))
+        if entity_type and sdn_type != entity_type:
+            continue
+        progs = _strip_quotes(r["program"])
+        if program and program.upper() not in progs.upper().split(";"):
+            continue
+        remarks = _strip_quotes(r["remarks"])
+        # DOB / POB are commonly embedded in remarks for individuals.
+        dob = ""
+        pob = ""
+        if sdn_type == "individual" and remarks:
+            for chunk in remarks.split(";"):
+                ch = chunk.strip()
+                if ch.upper().startswith("DOB"):
+                    dob = ch.split(maxsplit=1)[1] if " " in ch else ""
+                elif ch.upper().startswith("POB"):
+                    pob = ch.split(maxsplit=1)[1] if " " in ch else ""
+        rows.append(
+            {
+                "entity_id": ent_num,
+                "name": _strip_quotes(r["sdn_name"]),
+                "entity_type": sdn_type,
+                "program_list": "; ".join(p.strip() for p in progs.split(";") if p.strip()),
+                "title": _strip_quotes(r["title"]),
+                "nationalities": "",  # not in this CSV; available in XML format
+                "aka_list": "; ".join(aka_by_ent.get(ent_num, [])),
+                "addresses": "; ".join(addr_by_ent.get(ent_num, [])),
+                "dob": dob,
+                "pob": pob,
+                "remarks": remarks,
+                "last_updated": "",
+            }
+        )
+
+    Path(out_path).parent.mkdir(parents=True, exist_ok=True)
+    with open(out_path, "w", newline="", encoding="utf-8") as fh:
+        w = csv.DictWriter(fh, fieldnames=COLUMNS)
+        w.writeheader()
+        w.writerows(rows)
+    return len(rows)
+
+
+def main() -> int:
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument("--program", help="Filter to specific sanctions program (e.g. SDGT, IRAN)")
+    p.add_argument(
+        "--entity-type",
+        choices=["individual", "entity", "vessel", "aircraft"],
+        help="Filter to a specific entity type",
+    )
+    p.add_argument("--out", required=True)
+    a = p.parse_args()
+    n = fetch(program=a.program, entity_type=a.entity_type, out_path=a.out)
+    print(f"Wrote {n} OFAC SDN rows to {a.out}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/.mindforge/skills/osint-investigation/scripts/fetch_opencorporates.py

@@ -0,0 +1,191 @@
+#!/usr/bin/env python3
+"""Search OpenCorporates company registry data.
+
+OpenCorporates aggregates ~200M companies from 130+ jurisdictions. The
+public API requires an API token (free tier: 500 calls/month). Set
+OPENCORPORATES_API_TOKEN in env or pass --token.
+
+Without a token, this script falls back to scraping the public HTML
+search page (limited fields, more brittle, no jurisdiction filter).
+"""
+from __future__ import annotations
+
+import argparse
+import csv
+import os
+import re
+import sys
+import urllib.parse
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from _http import get, get_json  # noqa: E402
+
+API_URL = "https://api.opencorporates.com/v0.4/companies/search"
+HTML_URL = "https://opencorporates.com/companies"
+
+COLUMNS = [
+    "name",
+    "company_number",
+    "jurisdiction_code",
+    "jurisdiction_name",
+    "incorporation_date",
+    "dissolution_date",
+    "company_type",
+    "status",
+    "registered_address",
+    "opencorporates_url",
+    "officers_count",
+    "source",
+]
+
+
+def _via_api(query: str, jurisdiction: str | None, token: str, limit: int) -> list[dict]:
+    params = {
+        "q": query,
+        "api_token": token,
+        "per_page": str(min(limit, 100)),
+    }
+    if jurisdiction:
+        params["jurisdiction_code"] = jurisdiction
+    url = f"{API_URL}?{urllib.parse.urlencode(params)}"
+    payload = get_json(url)
+    if not isinstance(payload, dict):
+        return []
+    results = payload.get("results", {}).get("companies", []) or []
+    return [r.get("company", {}) for r in results if isinstance(r, dict)]
+
+
+def _via_html(query: str, limit: int) -> list[dict]:
+    """Best-effort HTML fallback when no API token is available."""
+    params = {"q": query, "utf8": "✓"}
+    url = f"{HTML_URL}?{urllib.parse.urlencode(params)}"
+    body = get(url, user_agent="Mozilla/5.0 hermes-osint").decode("utf-8", errors="replace")
+    # Each result is in <li class="company"> ... </li> with name, url, status
+    pattern = re.compile(
+        r'<li[^>]*class="[^"]*company[^"]*"[^>]*>.*?'
+        r'<a[^>]+href="(?P<url>/companies/[^"]+)"[^>]*>(?P<name>[^<]+)</a>'
+        r'(?:.*?<span[^>]*class="[^"]*jurisdiction[^"]*"[^>]*>(?P<jur>[^<]+)</span>)?'
+        r"(?:.*?<dt[^>]*>(?:Company\s+Number|Number)</dt>\s*<dd[^>]*>(?P<num>[^<]+)</dd>)?",
+        re.DOTALL | re.IGNORECASE,
+    )
+    out = []
+    for m in pattern.finditer(body):
+        if len(out) >= limit:
+            break
+        url_path = m.group("url").strip()
+        out.append(
+            {
+                "name": (m.group("name") or "").strip(),
+                "opencorporates_url": f"https://opencorporates.com{url_path}",
+                "jurisdiction_code": (m.group("jur") or "").strip(),
+                "company_number": (m.group("num") or "").strip(),
+                "_via": "html",
+            }
+        )
+    return out
+
+
+def fetch(
+    query: str,
+    jurisdiction: str | None,
+    token: str | None,
+    limit: int,
+    out_path: str,
+) -> int:
+    if token:
+        try:
+            companies = _via_api(query, jurisdiction, token, limit)
+            source_tag = "api"
+        except Exception as e:  # noqa: BLE001
+            print(
+                f"OpenCorporates API call failed ({e}); falling back to HTML.",
+                file=sys.stderr,
+            )
+            companies = _via_html(query, limit)
+            source_tag = "html-fallback"
+    else:
+        print(
+            "OPENCORPORATES_API_TOKEN not set — using HTML fallback (limited fields). "
+            "Get a free token at https://opencorporates.com/api_accounts/new",
+            file=sys.stderr,
+        )
+        companies = _via_html(query, limit)
+        source_tag = "html"
+
+    rows: list[dict[str, str]] = []
+    for c in companies[:limit]:
+        if c.get("_via") == "html":
+            rows.append(
+                {
+                    "name": c.get("name", ""),
+                    "company_number": c.get("company_number", ""),
+                    "jurisdiction_code": c.get("jurisdiction_code", ""),
+                    "jurisdiction_name": "",
+                    "incorporation_date": "",
+                    "dissolution_date": "",
+                    "company_type": "",
+                    "status": "",
+                    "registered_address": "",
+                    "opencorporates_url": c.get("opencorporates_url", ""),
+                    "officers_count": "",
+                    "source": source_tag,
+                }
+            )
+            continue
+        addr = c.get("registered_address_in_full") or ""
+        rows.append(
+            {
+                "name": c.get("name", "") or "",
+                "company_number": c.get("company_number", "") or "",
+                "jurisdiction_code": c.get("jurisdiction_code", "") or "",
+                "jurisdiction_name": "",
+                "incorporation_date": c.get("incorporation_date", "") or "",
+                "dissolution_date": c.get("dissolution_date", "") or "",
+                "company_type": c.get("company_type", "") or "",
+                "status": c.get("current_status", "") or c.get("inactive", "") or "",
+                "registered_address": addr,
+                "opencorporates_url": c.get("opencorporates_url", "") or "",
+                "officers_count": str(c.get("officers", {}).get("total_count", "") if c.get("officers") else ""),
+                "source": source_tag,
+            }
+        )
+
+    Path(out_path).parent.mkdir(parents=True, exist_ok=True)
+    with open(out_path, "w", newline="", encoding="utf-8") as fh:
+        w = csv.DictWriter(fh, fieldnames=COLUMNS)
+        w.writeheader()
+        w.writerows(rows)
+    if not rows:
+        print(
+            f"OpenCorporates: 0 matches for query={query!r}"
+            f"{f' jurisdiction={jurisdiction!r}' if jurisdiction else ''}.",
+            file=sys.stderr,
+        )
+    return len(rows)
+
+
+def main() -> int:
+    p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("--query", required=True, help="Company name search")
+    p.add_argument(
+        "--jurisdiction",
+        help="Jurisdiction code, e.g. 'us_ny', 'us_de', 'gb', 'sg' (lowercased OpenCorporates style)",
+    )
+    p.add_argument("--limit", type=int, default=50)
+    p.add_argument("--token", default=os.environ.get("OPENCORPORATES_API_TOKEN"))
+    p.add_argument("--out", required=True)
+    a = p.parse_args()
+    n = fetch(
+        query=a.query,
+        jurisdiction=a.jurisdiction,
+        token=a.token,
+        limit=a.limit,
+        out_path=a.out,
+    )
+    print(f"Wrote {n} OpenCorporates rows to {a.out}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/.mindforge/skills/osint-investigation/scripts/fetch_sec_edgar.py

@@ -0,0 +1,184 @@
+#!/usr/bin/env python3
+"""Fetch SEC EDGAR filings index for a given CIK or company name.
+
+SEC requires a User-Agent header with contact info. Set SEC_USER_AGENT,
+e.g. SEC_USER_AGENT="Research example@example.com".
+
+Filings JSON is published at:
+    https://data.sec.gov/submissions/CIK<10-digit-padded>.json
+
+Company lookup uses:
+    https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&company=<name>&output=atom
+"""
+from __future__ import annotations
+
+import argparse
+import csv
+import os
+import re
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from _http import get, get_json  # noqa: E402
+
+SUBMISSIONS_URL = "https://data.sec.gov/submissions/CIK{cik}.json"
+COLUMNS = [
+    "cik",
+    "company_name",
+    "form_type",
+    "filing_date",
+    "accession_number",
+    "primary_document",
+    "filing_url",
+    "reporting_period",
+]
+
+
+def _ua() -> str:
+    ua = os.environ.get("SEC_USER_AGENT", "").strip()
+    if not ua:
+        raise SystemExit(
+            "SEC requires a User-Agent with contact info. "
+            "Set SEC_USER_AGENT='Your Name your@email'."
+        )
+    return ua
+
+
+def _resolve_cik(company: str) -> tuple[str, str]:
+    """Resolve a company name to a CIK via EDGAR's atom feed.
+
+    Returns (cik, resolved_company_name). The feed entries also reveal whether
+    the match is an individual filer (Form 3/4/5 only) — surfaced in the
+    return value so callers can warn.
+    """
+    url = "https://www.sec.gov/cgi-bin/browse-edgar"
+    params = {"action": "getcompany", "company": company, "output": "atom", "owner": "include"}
+    body = get(url, params=params, user_agent=_ua()).decode("utf-8", errors="replace")
+    m = re.search(r"CIK=(\d{10})", body)
+    if not m:
+        raise SystemExit(f"Could not resolve CIK for company={company!r}")
+    cik = m.group(1)
+    name_m = re.search(r"<title>([^<]+)\s*\((\d{10})\)</title>", body)
+    resolved = name_m.group(1).strip() if name_m else ""
+    return cik, resolved
+
+
+def fetch(
+    cik: str | None,
+    company: str | None,
+    types: list[str],
+    since: str | None,
+    out_path: str,
+) -> int:
+    resolved_name = ""
+    if not cik and company:
+        try:
+            cik, resolved_name = _resolve_cik(company)  # type: ignore[assignment]
+        except SystemExit as e:
+            # Write empty CSV with header so downstream tools still work,
+            # and tell the user clearly.
+            print(f"SEC EDGAR: {e}", file=sys.stderr)
+            Path(out_path).parent.mkdir(parents=True, exist_ok=True)
+            with open(out_path, "w", newline="", encoding="utf-8") as fh:
+                csv.DictWriter(fh, fieldnames=COLUMNS).writeheader()
+            return 0
+        if resolved_name:
+            print(
+                f"Resolved company={company!r} → CIK {cik} ({resolved_name})",
+                file=sys.stderr,
+            )
+    if not cik:
+        raise SystemExit("must supply --cik or --company")
+    cik = cik.zfill(10)
+    url = SUBMISSIONS_URL.format(cik=cik)
+    payload = get_json(url, user_agent=_ua())
+    if not isinstance(payload, dict):
+        raise SystemExit(f"Unexpected EDGAR response shape for CIK {cik}")
+    name = payload.get("name", "")
+    recent = (payload.get("filings", {}) or {}).get("recent", {}) or {}
+    form = recent.get("form", [])
+    date = recent.get("filingDate", [])
+    accession = recent.get("accessionNumber", [])
+    primary_doc = recent.get("primaryDocument", [])
+    period = recent.get("reportDate", [])
+
+    # Histogram of available filing types — useful for surfacing why a filter
+    # returned 0 (e.g. user asked for 10-K on an individual Form 4 filer).
+    type_hist: dict[str, int] = {}
+    for ftype in form:
+        type_hist[ftype] = type_hist.get(ftype, 0) + 1
+
+    type_set = {t.strip().upper() for t in types} if types else None
+    rows: list[dict[str, str]] = []
+    for i, ftype in enumerate(form):
+        if type_set and ftype.upper() not in type_set:
+            continue
+        fdate = date[i] if i < len(date) else ""
+        if since and fdate and fdate < since:
+            continue
+        acc = accession[i] if i < len(accession) else ""
+        pdoc = primary_doc[i] if i < len(primary_doc) else ""
+        acc_nodash = acc.replace("-", "")
+        filing_url = (
+            f"https://www.sec.gov/Archives/edgar/data/{int(cik)}/{acc_nodash}/{pdoc}"
+            if acc and pdoc
+            else ""
+        )
+        rows.append(
+            {
+                "cik": cik,
+                "company_name": name,
+                "form_type": ftype,
+                "filing_date": fdate,
+                "accession_number": acc,
+                "primary_document": pdoc,
+                "filing_url": filing_url,
+                "reporting_period": period[i] if i < len(period) else "",
+            }
+        )
+
+    Path(out_path).parent.mkdir(parents=True, exist_ok=True)
+    with open(out_path, "w", newline="", encoding="utf-8") as fh:
+        w = csv.DictWriter(fh, fieldnames=COLUMNS)
+        w.writeheader()
+        w.writerows(rows)
+
+    if not rows and type_hist:
+        top = sorted(type_hist.items(), key=lambda kv: -kv[1])[:8]
+        hist_str = ", ".join(f"{t}={n}" for t, n in top)
+        print(
+            f"Warning: SEC EDGAR CIK {cik} ({name}) has {sum(type_hist.values())} "
+            f"recent filings but NONE match types={types}. "
+            f"Available form types: {hist_str}.",
+            file=sys.stderr,
+        )
+        # Insider-filer heuristic: only Form 3/4/5 → individual person, not a company.
+        company_types = {"10-K", "10-Q", "8-K", "20-F", "DEF 14A", "S-1"}
+        if not (set(type_hist.keys()) & company_types):
+            print(
+                f"Note: CIK {cik} appears to be an INDIVIDUAL filer "
+                f"(insider Form 3/4/5 only), not a corporate registrant. "
+                f"The resolver may have matched an officer/director named "
+                f"{company!r} rather than a company.",
+                file=sys.stderr,
+            )
+    return len(rows)
+
+
+def main() -> int:
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument("--cik", help="Central Index Key (will be 10-digit zero-padded)")
+    p.add_argument("--company", help="Resolve to CIK by company name")
+    p.add_argument("--types", default="", help="Comma-separated form types (e.g. 10-K,10-Q,8-K)")
+    p.add_argument("--since", help="Skip filings before YYYY-MM-DD")
+    p.add_argument("--out", required=True)
+    a = p.parse_args()
+    types = [t for t in (a.types or "").split(",") if t.strip()]
+    n = fetch(cik=a.cik, company=a.company, types=types, since=a.since, out_path=a.out)
+    print(f"Wrote {n} EDGAR filing rows to {a.out}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/.mindforge/skills/osint-investigation/scripts/fetch_senate_ld.py

@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+"""Fetch Senate Lobbying Disclosure (LD-1 / LD-2) filings.
+
+Anonymous: 120 req/hour. Token (SENATE_LDA_TOKEN): 1200 req/hour.
+"""
+from __future__ import annotations
+
+import argparse
+import csv
+import os
+import sys
+import time
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from _http import get_json  # noqa: E402
+
+ENDPOINT = "https://lda.senate.gov/api/v1/filings/"
+COLUMNS = [
+    "filing_uuid",
+    "filing_type",
+    "filing_year",
+    "filing_period",
+    "registrant_name",
+    "registrant_id",
+    "client_name",
+    "client_id",
+    "client_general_description",
+    "income",
+    "expenses",
+    "lobbyists",
+    "issues",
+    "government_entities",
+    "filing_date",
+]
+
+
+def fetch(
+    client: str | None,
+    registrant: str | None,
+    year: int,
+    token: str | None,
+    out_path: str,
+    page_size: int = 100,
+    max_pages: int = 25,
+) -> int:
+    params: dict = {"filing_year": year, "page_size": page_size}
+    if client:
+        params["client_name"] = client
+    if registrant:
+        params["registrant_name"] = registrant
+
+    headers = {"Authorization": f"Token {token}"} if token else None
+    rows: list[dict[str, str]] = []
+    url = ENDPOINT
+    page = 0
+    while page < max_pages:
+        try:
+            payload = get_json(url, params=params if page == 0 else None, headers=headers)
+        except Exception as e:  # noqa: BLE001
+            print(f"Senate LDA error on page {page + 1}: {e}", file=sys.stderr)
+            break
+        if not isinstance(payload, dict):
+            break
+        results = payload.get("results", [])
+        for r in results:
+            client_obj = r.get("client") or {}
+            registrant_obj = r.get("registrant") or {}
+            lobbying_activities = r.get("lobbying_activities") or []
+            lobbyists = []
+            issues = []
+            entities = []
+            for la in lobbying_activities:
+                for lob in la.get("lobbyists") or []:
+                    lob_obj = lob.get("lobbyist") or {}
+                    name = " ".join(
+                        x for x in (lob_obj.get("first_name", ""), lob_obj.get("last_name", "")) if x
+                    )
+                    if name:
+                        lobbyists.append(name)
+                desc = la.get("description") or ""
+                if desc:
+                    issues.append(desc)
+                for ge in la.get("government_entities") or []:
+                    nm = ge.get("name") or ""
+                    if nm:
+                        entities.append(nm)
+            rows.append(
+                {
+                    "filing_uuid": r.get("filing_uuid", "") or "",
+                    "filing_type": r.get("filing_type", "") or "",
+                    "filing_year": str(r.get("filing_year", "") or year),
+                    "filing_period": r.get("filing_period", "") or "",
+                    "registrant_name": registrant_obj.get("name", "") or "",
+                    "registrant_id": str(registrant_obj.get("id", "") or ""),
+                    "client_name": client_obj.get("name", "") or "",
+                    "client_id": str(client_obj.get("id", "") or ""),
+                    "client_general_description": client_obj.get("general_description", "") or "",
+                    "income": str(r.get("income", "") or ""),
+                    "expenses": str(r.get("expenses", "") or ""),
+                    "lobbyists": "; ".join(sorted(set(lobbyists))),
+                    "issues": "; ".join(issues),
+                    "government_entities": "; ".join(sorted(set(entities))),
+                    "filing_date": (r.get("dt_posted") or "")[:10],
+                }
+            )
+        next_url = payload.get("next")
+        if not next_url:
+            break
+        url = next_url
+        page += 1
+        time.sleep(1.0 if not token else 0.3)
+
+    Path(out_path).parent.mkdir(parents=True, exist_ok=True)
+    with open(out_path, "w", newline="", encoding="utf-8") as fh:
+        w = csv.DictWriter(fh, fieldnames=COLUMNS)
+        w.writeheader()
+        w.writerows(rows)
+    return len(rows)
+
+
+def main() -> int:
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument("--client", help="Client name filter")
+    p.add_argument("--registrant", help="Registrant (lobbying firm) name filter")
+    p.add_argument("--year", type=int, default=2024)
+    p.add_argument("--token", default=os.environ.get("SENATE_LDA_TOKEN"))
+    p.add_argument("--max-pages", type=int, default=25)
+    p.add_argument("--out", required=True)
+    a = p.parse_args()
+    if not (a.client or a.registrant):
+        p.error("must supply at least one of --client / --registrant")
+    n = fetch(
+        client=a.client,
+        registrant=a.registrant,
+        year=a.year,
+        token=a.token,
+        out_path=a.out,
+        max_pages=a.max_pages,
+    )
+    print(f"Wrote {n} Senate LDA rows to {a.out}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())