icdev 0.0.3__py3-none-any.whl

tools/govcon/sam_scanner.py

@@ -0,0 +1,754 @@
+# CUI // SP-CTI
+# ICDEV GovCon SAM.gov Scanner — Phase 59 (D366)
+# Scans SAM.gov Opportunities API v2 for solicitations and award notices.
+
+"""
+SAM.gov Scanner — populates competitive intelligence from federal procurement data.
+
+Scans:
+    - Active solicitations → sam_gov_opportunities
+    - Award notices → govcon_awards + auto-discovers competitors → creative_competitors
+
+Usage:
+    SAM_GOV_API_KEY=<key> python tools/govcon/sam_scanner.py --scan --json
+    SAM_GOV_API_KEY=<key> python tools/govcon/sam_scanner.py --awards --json
+    python tools/govcon/sam_scanner.py --competitors --json
+    python tools/govcon/sam_scanner.py --stats --json
+"""
+
+import argparse
+import hashlib
+import json
+import os
+import sqlite3
+import sys
+import time
+import uuid
+import urllib.error
+import urllib.parse
+import urllib.request
+from datetime import datetime, timezone, timedelta
+from pathlib import Path
+from tools.db.storage import get_connection
+DB_PATH = None  # Storage layer handles path resolution (D-DB-20)
+
+_ROOT = Path(__file__).resolve().parent.parent.parent
+_DB_PATH = Path(os.environ.get("ICDEV_DB_PATH", str(_ROOT / "data" / "icdev.db")))
+_CONFIG_PATH = _ROOT / "args" / "govcon_config.yaml"
+
+_SAM_API_BASE = "https://api.sam.gov/opportunities/v2/search"
+_USASPENDING_API = "https://api.usaspending.gov/api/v2/search/spending_by_award/"
+_DEFAULT_NAICS = ["541512", "541519", "541715"]
+_DEFAULT_DAYS_BACK_OPPS = 30
+_DEFAULT_DAYS_BACK_AWARDS = 90
+_RATE_LIMIT_DELAY = 0.15
+_PAGE_SIZE = 100
+_MAX_RECORDS = 5000
+
+
+# ── helpers ───────────────────────────────────────────────────────────
+
+def _get_db():
+    conn = sqlite3.connect(str(_DB_PATH))
+    conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA journal_mode=WAL")
+    return conn
+
+
+def _now():
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _content_hash(text):
+    return hashlib.sha256(text.encode()).hexdigest()[:16]
+
+
+def _audit(conn, action, details="", actor="sam_scanner"):
+    try:
+        conn.execute(
+            "INSERT INTO audit_trail (id, timestamp, event_type, actor, action, details, session_id) "
+            "VALUES (?, ?, ?, ?, ?, ?, ?)",
+            (str(uuid.uuid4()), _now(), "govcon.sam_scanner", actor, action, details, "govcon"),
+        )
+    except Exception:
+        pass
+
+
+def _load_config():
+    """Load govcon config with graceful fallback."""
+    defaults = {
+        "naics_codes": _DEFAULT_NAICS,
+        "endpoint": _SAM_API_BASE,
+        "rate_limit_delay": _RATE_LIMIT_DELAY,
+        "page_size": _PAGE_SIZE,
+        "max_records": _MAX_RECORDS,
+        "opportunities_days_back": _DEFAULT_DAYS_BACK_OPPS,
+        "awards_days_back": _DEFAULT_DAYS_BACK_AWARDS,
+        "notice_types_opportunities": "o,p,r,s,k",
+        "notice_types_awards": "a",
+        "competitor_discovery_enabled": True,
+        "top_competitors_limit": 20,
+        "recent_awards_limit": 50,
+    }
+    try:
+        import yaml
+        if _CONFIG_PATH.exists():
+            with open(_CONFIG_PATH) as f:
+                raw = yaml.safe_load(f) or {}
+            gc = raw.get("govcon", {})
+            defaults["naics_codes"] = gc.get("naics_codes", defaults["naics_codes"])
+            sam = gc.get("sam_api", {})
+            defaults["endpoint"] = sam.get("endpoint", defaults["endpoint"])
+            defaults["rate_limit_delay"] = sam.get("rate_limit_delay_seconds", defaults["rate_limit_delay"])
+            defaults["page_size"] = sam.get("page_size", defaults["page_size"])
+            defaults["max_records"] = sam.get("max_records_per_scan", defaults["max_records"])
+            scan = gc.get("scan", {})
+            defaults["opportunities_days_back"] = scan.get("opportunities_days_back", defaults["opportunities_days_back"])
+            defaults["awards_days_back"] = scan.get("awards_days_back", defaults["awards_days_back"])
+            defaults["notice_types_opportunities"] = scan.get("notice_types_opportunities", defaults["notice_types_opportunities"])
+            defaults["notice_types_awards"] = scan.get("notice_types_awards", defaults["notice_types_awards"])
+            cd = gc.get("competitor_discovery", {})
+            defaults["competitor_discovery_enabled"] = cd.get("enabled", True)
+            dash = gc.get("dashboard", {})
+            defaults["top_competitors_limit"] = dash.get("top_competitors_limit", 20)
+            defaults["recent_awards_limit"] = dash.get("recent_awards_limit", 50)
+    except (ImportError, Exception):
+        pass
+    return defaults
+
+
+def _get_api_key():
+    """Read SAM.gov API key from environment."""
+    return os.environ.get("SAM_GOV_API_KEY", "")
+
+
+# ── SAM.gov API ───────────────────────────────────────────────────────
+
+def _build_url(endpoint, api_key, naics_codes, posted_from, posted_to,
+               notice_types, limit, offset):
+    """Build SAM.gov search URL."""
+    params = {
+        "api_key": api_key,
+        "postedFrom": posted_from,
+        "postedTo": posted_to,
+        "limit": str(limit),
+        "offset": str(offset),
+    }
+    if naics_codes:
+        params["ncode"] = ",".join(naics_codes)
+    if notice_types:
+        params["ptype"] = notice_types
+    return f"{endpoint}?{urllib.parse.urlencode(params)}"
+
+
+def _fetch_page(url):
+    """Fetch a single page from SAM.gov API."""
+    try:
+        req = urllib.request.Request(url, headers={"Accept": "application/json"})
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            data = json.loads(resp.read().decode("utf-8"))
+        time.sleep(_RATE_LIMIT_DELAY)
+        return {"status": "ok", "data": data}
+    except urllib.error.HTTPError as e:
+        if e.code == 429:
+            print("Rate limited, waiting 60s...", file=sys.stderr)
+            time.sleep(60)
+            try:
+                req = urllib.request.Request(url, headers={"Accept": "application/json"})
+                with urllib.request.urlopen(req, timeout=30) as resp:
+                    data = json.loads(resp.read().decode("utf-8"))
+                return {"status": "ok", "data": data}
+            except Exception as e2:
+                return {"status": "error", "message": f"Retry failed: {e2}"}
+        return {"status": "error", "message": f"HTTP {e.code}: {e.reason}"}
+    except urllib.error.URLError as e:
+        return {"status": "error", "message": f"Network error: {e.reason}"}
+    except Exception as e:
+        return {"status": "error", "message": str(e)}
+
+
+def _paginate(endpoint, api_key, naics_codes, posted_from, posted_to,
+              notice_types, page_size, max_records):
+    """Paginate through SAM.gov results, yielding opportunity dicts."""
+    offset = 0
+    total_yielded = 0
+    while total_yielded < max_records:
+        url = _build_url(endpoint, api_key, naics_codes, posted_from, posted_to,
+                         notice_types, page_size, offset)
+        result = _fetch_page(url)
+        if result["status"] != "ok":
+            print(f"Fetch error at offset {offset}: {result['message']}", file=sys.stderr)
+            break
+
+        data = result["data"]
+        opps = data.get("opportunitiesData", [])
+        if not opps:
+            break
+
+        for opp in opps:
+            yield opp
+            total_yielded += 1
+            if total_yielded >= max_records:
+                break
+
+        total_records = data.get("totalRecords", 0)
+        offset += page_size
+        if offset >= total_records:
+            break
+
+    print(f"Paginated: {total_yielded} records fetched", file=sys.stderr)
+
+
+def _format_date_for_api(dt):
+    """Format date as MM/dd/yyyy for SAM.gov API."""
+    return dt.strftime("%m/%d/%Y")
+
+
+# ── Opportunity scanner ───────────────────────────────────────────────
+
+def scan_opportunities(naics_codes=None, days_back=None):
+    """Scan SAM.gov for active solicitations."""
+    api_key = _get_api_key()
+    if not api_key:
+        return {"status": "error", "message": "SAM_GOV_API_KEY environment variable not set"}
+
+    config = _load_config()
+    naics = naics_codes or config["naics_codes"]
+    days = days_back or config["opportunities_days_back"]
+
+    now = datetime.now(timezone.utc)
+    posted_from = _format_date_for_api(now - timedelta(days=days))
+    posted_to = _format_date_for_api(now)
+
+    conn = _get_db()
+    new_count = 0
+    updated_count = 0
+    total = 0
+
+    try:
+        for opp in _paginate(
+            config["endpoint"], api_key, naics, posted_from, posted_to,
+            config["notice_types_opportunities"], config["page_size"], config["max_records"]
+        ):
+            total += 1
+            sol_num = opp.get("solicitationNumber", "")
+            title = opp.get("title", "")
+            chash = _content_hash(f"{sol_num}|{title}")
+
+            existing = conn.execute(
+                "SELECT id FROM sam_gov_opportunities WHERE content_hash = ?", (chash,)
+            ).fetchone()
+
+            agency_hierarchy = opp.get("fullParentPathName", "")
+            agency = agency_hierarchy.split(".")[0].strip() if agency_hierarchy else opp.get("department", "")
+
+            if existing:
+                conn.execute(
+                    "UPDATE sam_gov_opportunities SET last_synced = ?, active = ? WHERE content_hash = ?",
+                    (_now(), "true", chash),
+                )
+                updated_count += 1
+            else:
+                opp_id = str(uuid.uuid4())
+                conn.execute(
+                    "INSERT INTO sam_gov_opportunities "
+                    "(id, solicitation_number, title, agency, agency_hierarchy, naics_code, "
+                    "classification_code, notice_type, posted_date, response_deadline, "
+                    "description, point_of_contact, set_aside_type, place_of_performance, "
+                    "content_hash, first_seen, last_synced, classification) "
+                    "VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)",
+                    (
+                        opp_id,
+                        sol_num,
+                        title,
+                        agency,
+                        agency_hierarchy,
+                        opp.get("naicsCode", ""),
+                        opp.get("classificationCode", ""),
+                        opp.get("type", ""),
+                        opp.get("postedDate", ""),
+                        opp.get("responseDeadLine", ""),
+                        opp.get("description", ""),
+                        json.dumps(opp.get("pointOfContact", [])),
+                        opp.get("typeOfSetAsideDescription", ""),
+                        json.dumps(opp.get("placeOfPerformance", {})),
+                        chash,
+                        _now(),
+                        _now(),
+                        "CUI",
+                    ),
+                )
+                new_count += 1
+
+        _audit(conn, "scan_opportunities",
+               f"Scanned {total} opportunities: {new_count} new, {updated_count} updated. NAICS={naics}")
+        conn.commit()
+    except Exception as e:
+        conn.rollback()
+        return {"status": "error", "message": str(e)}
+    finally:
+        conn.close()
+
+    return {
+        "status": "ok",
+        "opportunities_scanned": total,
+        "new": new_count,
+        "updated": updated_count,
+        "naics_codes": naics,
+        "days_back": days,
+        "classification": "CUI // SP-CTI",
+    }
+
+
+# ── Award scanner + competitor discovery ──────────────────────────────
+
+def _find_or_create_competitor(conn, awardee_name, awardee_uei="", naics_code=""):
+    """Find existing competitor or auto-discover new one. Returns competitor_id."""
+    row = conn.execute(
+        "SELECT id FROM creative_competitors WHERE LOWER(name) = LOWER(?)",
+        (awardee_name,),
+    ).fetchone()
+    if row:
+        return row["id"]
+
+    comp_id = str(uuid.uuid4())
+    conn.execute(
+        "INSERT INTO creative_competitors "
+        "(id, name, domain, source, status, metadata, discovered_at, classification) "
+        "VALUES (?,?,?,?,?,?,?,?)",
+        (
+            comp_id,
+            awardee_name,
+            "govcon",
+            "manual",  # within CHECK constraint; actual source in metadata
+            "discovered",
+            json.dumps({
+                "actual_source": "sam.gov",
+                "uei": awardee_uei,
+                "naics_codes": [naics_code] if naics_code else [],
+            }),
+            _now(),
+            "CUI",
+        ),
+    )
+    return comp_id
+
+
+def scan_awards(naics_codes=None, days_back=None):
+    """Scan SAM.gov for award notices and populate competitive intelligence."""
+    api_key = _get_api_key()
+    if not api_key:
+        return {"status": "error", "message": "SAM_GOV_API_KEY environment variable not set"}
+
+    config = _load_config()
+    naics = naics_codes or config["naics_codes"]
+    days = days_back or config["awards_days_back"]
+
+    now = datetime.now(timezone.utc)
+    posted_from = _format_date_for_api(now - timedelta(days=days))
+    posted_to = _format_date_for_api(now)
+
+    conn = _get_db()
+    new_awards = 0
+    new_competitors = 0
+    skipped = 0
+    total = 0
+
+    try:
+        for opp in _paginate(
+            config["endpoint"], api_key, naics, posted_from, posted_to,
+            config["notice_types_awards"], config["page_size"], config["max_records"]
+        ):
+            total += 1
+            award = opp.get("award", {})
+            if not award:
+                skipped += 1
+                continue
+
+            awardee = award.get("awardee", {})
+            awardee_name = awardee.get("name", "")
+            if not awardee_name:
+                skipped += 1
+                continue
+
+            sol_num = opp.get("solicitationNumber", "")
+            award_number = award.get("number", "")
+            chash = _content_hash(f"{sol_num}|{award_number}|{awardee_name}")
+
+            existing = conn.execute(
+                "SELECT id FROM govcon_awards WHERE content_hash = ?", (chash,)
+            ).fetchone()
+            if existing:
+                skipped += 1
+                continue
+
+            # Link to sam_gov_opportunities if we have it
+            sam_opp_row = conn.execute(
+                "SELECT id FROM sam_gov_opportunities WHERE solicitation_number = ? LIMIT 1",
+                (sol_num,),
+            ).fetchone() if sol_num else None
+            sam_opp_id = sam_opp_row["id"] if sam_opp_row else None
+
+            # Auto-discover competitor
+            naics_code = opp.get("naicsCode", "")
+            awardee_uei = awardee.get("ueiSAM", "") or awardee.get("uei", "")
+
+            # Check if competitor is truly new
+            existing_comp = conn.execute(
+                "SELECT id FROM creative_competitors WHERE LOWER(name) = LOWER(?)",
+                (awardee_name,),
+            ).fetchone()
+            is_new_competitor = existing_comp is None
+
+            competitor_id = _find_or_create_competitor(
+                conn, awardee_name, awardee_uei, naics_code
+            )
+            if is_new_competitor:
+                new_competitors += 1
+
+            agency_hierarchy = opp.get("fullParentPathName", "")
+            agency = agency_hierarchy.split(".")[0].strip() if agency_hierarchy else opp.get("department", "")
+
+            award_amount = None
+            try:
+                award_amount = float(award.get("amount", 0))
+            except (ValueError, TypeError):
+                award_amount = 0.0
+
+            conn.execute(
+                "INSERT INTO govcon_awards "
+                "(id, sam_opportunity_id, solicitation_number, title, agency, naics_code, "
+                "awardee_name, awardee_duns, awardee_uei, contract_number, award_amount, "
+                "award_date, set_aside_type, competitor_id, content_hash, discovered_at, classification) "
+                "VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)",
+                (
+                    str(uuid.uuid4()),
+                    sam_opp_id,
+                    sol_num,
+                    opp.get("title", ""),
+                    agency,
+                    naics_code,
+                    awardee_name,
+                    "",  # DUNS deprecated
+                    awardee_uei,
+                    award_number,
+                    award_amount,
+                    award.get("date", ""),
+                    opp.get("typeOfSetAsideDescription", ""),
+                    competitor_id,
+                    chash,
+                    _now(),
+                    "CUI",
+                ),
+            )
+            new_awards += 1
+
+        _audit(conn, "scan_awards",
+               f"Scanned {total} award notices: {new_awards} new awards, "
+               f"{new_competitors} new competitors, {skipped} skipped. NAICS={naics}")
+        conn.commit()
+    except Exception as e:
+        conn.rollback()
+        return {"status": "error", "message": str(e)}
+    finally:
+        conn.close()
+
+    return {
+        "status": "ok",
+        "award_notices_scanned": total,
+        "new_awards": new_awards,
+        "new_competitors": new_competitors,
+        "skipped": skipped,
+        "naics_codes": naics,
+        "days_back": days,
+        "classification": "CUI // SP-CTI",
+    }
+
+
+# ── Queries ───────────────────────────────────────────────────────────
+
+def list_competitors():
+    """List discovered competitors with award metrics."""
+    conn = _get_db()
+    try:
+        rows = conn.execute("""
+            SELECT c.id, c.name, c.status, c.discovered_at, c.metadata,
+                   COUNT(a.id) as award_count,
+                   COALESCE(SUM(a.award_amount), 0) as total_value,
+                   GROUP_CONCAT(DISTINCT a.naics_code) as naics_codes
+            FROM creative_competitors c
+            LEFT JOIN govcon_awards a ON a.competitor_id = c.id
+            GROUP BY c.id
+            ORDER BY total_value DESC
+        """).fetchall()
+        return {
+            "status": "ok",
+            "total": len(rows),
+            "competitors": [dict(r) for r in rows],
+            "classification": "CUI // SP-CTI",
+        }
+    finally:
+        conn.close()
+
+
+def get_stats():
+    """Aggregate statistics across SAM.gov data."""
+    conn = _get_db()
+    try:
+        total_opps = conn.execute("SELECT COUNT(*) FROM sam_gov_opportunities").fetchone()[0]
+        total_awards = conn.execute("SELECT COUNT(*) FROM govcon_awards").fetchone()[0]
+        unique_competitors = conn.execute(
+            "SELECT COUNT(DISTINCT awardee_name) FROM govcon_awards"
+        ).fetchone()[0]
+        total_value = conn.execute(
+            "SELECT COALESCE(SUM(award_amount), 0) FROM govcon_awards"
+        ).fetchone()[0]
+
+        # Top 10 by value
+        top_competitors = conn.execute("""
+            SELECT awardee_name, COUNT(*) as awards, COALESCE(SUM(award_amount), 0) as total_value
+            FROM govcon_awards
+            GROUP BY awardee_name
+            ORDER BY total_value DESC
+            LIMIT 10
+        """).fetchall()
+
+        # NAICS distribution
+        naics_dist = conn.execute("""
+            SELECT naics_code, COUNT(*) as count, COALESCE(SUM(award_amount), 0) as total_value
+            FROM govcon_awards
+            WHERE naics_code IS NOT NULL AND naics_code != ''
+            GROUP BY naics_code
+            ORDER BY count DESC
+            LIMIT 10
+        """).fetchall()
+
+        # By notice type
+        opp_types = conn.execute("""
+            SELECT notice_type, COUNT(*) as count
+            FROM sam_gov_opportunities
+            GROUP BY notice_type
+            ORDER BY count DESC
+        """).fetchall()
+
+        return {
+            "status": "ok",
+            "total_opportunities": total_opps,
+            "total_awards": total_awards,
+            "unique_competitors": unique_competitors,
+            "total_award_value": total_value,
+            "top_competitors": [dict(r) for r in top_competitors],
+            "naics_distribution": [dict(r) for r in naics_dist],
+            "opportunity_types": [dict(r) for r in opp_types],
+            "classification": "CUI // SP-CTI",
+        }
+    finally:
+        conn.close()
+
+
+# ── FPDS / USASpending.gov ────────────────────────────────────────────
+
+def _ensure_fpds_table(conn):
+    """Create fpds_contract_wins table if it doesn't exist."""
+    conn.execute("""
+        CREATE TABLE IF NOT EXISTS fpds_contract_wins (
+            id TEXT PRIMARY KEY,
+            internal_id INTEGER,
+            award_id TEXT NOT NULL,
+            recipient_name TEXT NOT NULL,
+            award_amount REAL DEFAULT 0,
+            awarding_agency TEXT,
+            start_date TEXT,
+            naics_code TEXT,
+            description TEXT,
+            content_hash TEXT NOT NULL UNIQUE,
+            competitor_id TEXT REFERENCES creative_competitors(id),
+            fetched_at TEXT NOT NULL,
+            classification TEXT DEFAULT 'CUI'
+        )
+    """)
+    conn.execute("""
+        CREATE INDEX IF NOT EXISTS idx_fpds_recipient
+        ON fpds_contract_wins(recipient_name)
+    """)
+
+
+def scan_fpds(naics_codes=None, days_back=None):
+    """Scan USASpending.gov for FPDS contract wins by known competitors."""
+    import ssl
+
+    config = _load_config()
+    naics = naics_codes or config["naics_codes"]
+    days = days_back or config.get("awards_days_back", 90)
+
+    now = datetime.now(timezone.utc)
+    start_date = (now - timedelta(days=days)).strftime("%Y-%m-%d")
+    end_date = now.strftime("%Y-%m-%d")
+
+    ctx = ssl.create_default_context()
+    ctx.check_hostname = False
+    ctx.verify_mode = ssl.CERT_NONE
+
+    conn = _get_db()
+    _ensure_fpds_table(conn)
+    new_wins = 0
+    new_competitors = 0
+    total = 0
+
+    try:
+        for naics_code in naics:
+            page = 1
+            while True:
+                payload = json.dumps({
+                    "filters": {
+                        "time_period": [{"start_date": start_date, "end_date": end_date}],
+                        "award_type_codes": ["A", "B", "C", "D"],
+                        "naics_codes": {"require": [naics_code]},
+                    },
+                    "fields": [
+                        "Award ID", "Recipient Name", "Award Amount",
+                        "Awarding Agency", "Start Date", "NAICS Code", "Description",
+                    ],
+                    "limit": 100,
+                    "page": page,
+                    "sort": "Award Amount",
+                    "order": "desc",
+                }).encode()
+
+                req = urllib.request.Request(
+                    _USASPENDING_API,
+                    data=payload,
+                    headers={"Content-Type": "application/json"},
+                )
+                try:
+                    resp = urllib.request.urlopen(req, timeout=30, context=ctx)
+                    data = json.loads(resp.read().decode())
+                except Exception as e:
+                    print(f"FPDS fetch error page {page}: {e}", file=sys.stderr)
+                    break
+
+                results = data.get("results", [])
+                if not results:
+                    break
+
+                for r in results:
+                    total += 1
+                    recipient = r.get("Recipient Name", "")
+                    award_id = r.get("Award ID", "")
+                    if not recipient or not award_id:
+                        continue
+
+                    chash = _content_hash(f"fpds|{award_id}|{recipient}")
+                    existing = conn.execute(
+                        "SELECT id FROM fpds_contract_wins WHERE content_hash = ?",
+                        (chash,),
+                    ).fetchone()
+                    if existing:
+                        continue
+
+                    # Link to competitor
+                    comp_row = conn.execute(
+                        "SELECT id FROM creative_competitors WHERE LOWER(name) = LOWER(?)",
+                        (recipient,),
+                    ).fetchone()
+                    if comp_row:
+                        competitor_id = comp_row["id"]
+                    else:
+                        competitor_id = _find_or_create_competitor(
+                            conn, recipient, "", naics_code
+                        )
+                        new_competitors += 1
+
+                    try:
+                        amount = float(r.get("Award Amount", 0) or 0)
+                    except (ValueError, TypeError):
+                        amount = 0.0
+
+                    conn.execute(
+                        "INSERT INTO fpds_contract_wins "
+                        "(id, internal_id, award_id, recipient_name, award_amount, "
+                        "awarding_agency, start_date, naics_code, description, "
+                        "content_hash, competitor_id, fetched_at, classification) "
+                        "VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?)",
+                        (
+                            str(uuid.uuid4()),
+                            r.get("internal_id"),
+                            award_id,
+                            recipient,
+                            amount,
+                            r.get("Awarding Agency", ""),
+                            r.get("Start Date", ""),
+                            r.get("NAICS Code", naics_code),
+                            (r.get("Description", "") or "")[:500],
+                            chash,
+                            competitor_id,
+                            _now(),
+                            "CUI",
+                        ),
+                    )
+                    new_wins += 1
+
+                time.sleep(0.5)  # USASpending rate courtesy
+                if len(results) < 100:
+                    break
+                page += 1
+                if page > 10:  # Cap at 1000 per NAICS
+                    break
+
+        _audit(conn, "scan_fpds",
+               f"FPDS scan: {total} checked, {new_wins} new wins, "
+               f"{new_competitors} new competitors. NAICS={naics}")
+        conn.commit()
+    except Exception as e:
+        conn.rollback()
+        return {"status": "error", "message": str(e)}
+    finally:
+        conn.close()
+
+    return {
+        "status": "ok",
+        "fpds_records_checked": total,
+        "new_wins": new_wins,
+        "new_competitors": new_competitors,
+        "naics_codes": naics,
+        "days_back": days,
+        "classification": "CUI // SP-CTI",
+    }
+
+
+# ── CLI ───────────────────────────────────────────────────────────────
+
+def main():
+    parser = argparse.ArgumentParser(description="ICDEV SAM.gov Scanner (D366)")
+    group = parser.add_mutually_exclusive_group(required=True)
+    group.add_argument("--scan", action="store_true", help="Scan SAM.gov opportunities")
+    group.add_argument("--awards", action="store_true", help="Scan SAM.gov award notices")
+    group.add_argument("--fpds", action="store_true", help="Scan FPDS via USASpending.gov")
+    group.add_argument("--competitors", action="store_true", help="List discovered competitors")
+    group.add_argument("--stats", action="store_true", help="Summary statistics")
+
+    parser.add_argument("--naics", help="Comma-separated NAICS codes (override config)")
+    parser.add_argument("--days-back", type=int, help="Days to look back")
+    parser.add_argument("--json", action="store_true", help="JSON output")
+    parser.add_argument("--human", action="store_true", help="Human-readable output")
+
+    args = parser.parse_args()
+
+    naics = args.naics.split(",") if args.naics else None
+
+    if args.scan:
+        result = scan_opportunities(naics_codes=naics, days_back=args.days_back)
+    elif args.awards:
+        result = scan_awards(naics_codes=naics, days_back=args.days_back)
+    elif args.fpds:
+        result = scan_fpds(naics_codes=naics, days_back=args.days_back)
+    elif args.competitors:
+        result = list_competitors()
+    elif args.stats:
+        result = get_stats()
+
+    print(json.dumps(result, indent=2, default=str))
+
+
+if __name__ == "__main__":
+    main()