ddimunzio/bot-detector

Contest Log Bot Detector

Streamlit app to detect automated bots in amateur radio contest logs (Cabrillo format).

Features

• —Upload and compare multiple Cabrillo .log files side-by-side
• —9 detection modules: S&P Burst, Frequency Entropy, RBN Trap, QRP Feasibility, Typo Decoupling, ISFE (band/frequency feasibility), Fatigue/Decay, 2BSIQ Cognitive Load, Clock-Phase Detector
• —Bayesian adjudication output: posterior P(bot), P(suspicious), P(human)
• —Color-highlighted comparison table (🔴 bot-level / 🟡 suspicious / 🟢 human)
• —SO2R/SO3R aware scoring (multi-transmitter thresholds)

Methodology (Current)

• —Hybrid adjudication: heuristic score + Bayesian posterior.
• —Final Likely BOT decision is Bayesian-gated. Heuristic output can raise a case to Suspicious, but cannot force Likely BOT on its own.
• —Bayesian evidence is aggregated in 5 active blocks (timing, rate, frequency, physical/cognitive, fatigue/clock-phase), each with clamped log-likelihood contribution.
• —RBN contributes to Bayesian adjudication only through a confidence-gated statistical-window model (delay buckets + ambiguity/sample guards); when confidence is low it is automatically suppressed.
• —Multi-operator and multi-transmitter contexts apply block suppression in Bayesian space to reduce false positives on legitimate high-performance team logs.

Calibration (How It Works)

• —Runtime overrides are loaded automatically from calibration.json when bot_detector_engine.py is imported.
• —Tunable families include priors, mode log-LR offsets, block weights, verdict thresholds, heuristic offsets, and optional metric PDFs.
• —calibrate.py performs:
• —One-time metric extraction for all selected logs.
• —Random search over parameter bounds.
• —Phase-2 refinement strategy (de by default, nelder optional, none to skip).
• —Optional profile overlay calibration (--profile-split multi-op) when sample size is sufficient.
• —The objective combines hard verdict penalties and smooth softplus penalties, with support for:
• —HUMAN labeled logs (strong false-positive control),
• —BOT labeled logs (false-negative control),
• —UNLABELED logs (soft-label weighting by mode prior).

App Runtime Modes

• —Local runtime: both Detection and Calibration tabs are available.
• —Deployment runtime: only Detection is shown; the UI displays a DEPLOYMENT MODE DETECTED badge and hides calibration controls.
• —Optional overrides:
• —BOT_DETECTOR_ENABLE_CALIBRATION_UI=1 forces calibration tab visible.
• —BOT_DETECTOR_DISABLE_CALIBRATION_UI=1 forces calibration tab hidden.

Example calibration run:

python calibrate.py --contest all --sample 400 --n-random 5000 --phase2 de --de-maxiter 60 --de-popsize 8 --output-json calibration.json

Usage

Upload one or more Cabrillo log files using the sidebar, then switch between Single Log and Compare Logs views.

Documentation

• —Detection architecture and full indicator reference: docs/DETECTION_SYSTEM_GUIDE.md
• —Version en espanol: docs/DETECTION_SYSTEM_GUIDE_ES.md