Metadata-Version: 2.1
Name: blackridge-whaco
Version: 1.2.0
Summary: Wind-Harvesting Adaptive Controller for Operations — resource-aware distributed autonomy governor
Author-email: Blackridge Autonomy LLC <contact@blackridgeautonomy.com>
License: Proprietary
Project-URL: Homepage, https://blackridgeautonomy.com
Project-URL: Documentation, https://github.com/morpheus18-glitch/whaco-rl
Project-URL: Repository, https://github.com/morpheus18-glitch/whaco-rl
Keywords: swarm,autonomy,governor,drone,uas,px4,throttle,multi-agent
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: numpy>=1.24
Provides-Extra: viz
Requires-Dist: matplotlib>=3.7; extra == "viz"
Provides-Extra: swarm
Requires-Dist: matplotlib>=3.7; extra == "swarm"
Requires-Dist: networkx>=3.0; extra == "swarm"
Provides-Extra: hil
Requires-Dist: matplotlib>=3.7; extra == "hil"
Requires-Dist: networkx>=3.0; extra == "hil"
Requires-Dist: pymavlink>=2.4.40; extra == "hil"
Provides-Extra: dev
Requires-Dist: matplotlib>=3.7; extra == "dev"
Requires-Dist: networkx>=3.0; extra == "dev"
Requires-Dist: pymavlink>=2.4.40; extra == "dev"
Requires-Dist: ruff>=0.3.0; extra == "dev"
Requires-Dist: coverage>=7.0; extra == "dev"
Provides-Extra: all
Requires-Dist: matplotlib>=3.7; extra == "all"
Requires-Dist: networkx>=3.0; extra == "all"
Requires-Dist: pymavlink>=2.4.40; extra == "all"
Requires-Dist: ruff>=0.3.0; extra == "all"
Requires-Dist: coverage>=7.0; extra == "all"

# WHACO — Wind-Harvesting Adaptive Controller for Operations

[![CI](https://github.com/morpheus18-glitch/whaco-rl/actions/workflows/ci.yml/badge.svg)](https://github.com/morpheus18-glitch/whaco-rl/actions/workflows/ci.yml)

**Bolt-on throttle governor that turns fuel waste into mission survival.** Energy-constrained drone swarms lose 15-20% of missions to fuel exhaustion despite having sufficient reserves. WHACO creates fuel reserves during nominal operation and redistributes them after agent loss — delivering +9.8pp mission success with zero firmware changes.

Blackridge Autonomy LLC | v1.1.0 | February 2026 | [blackridgeautonomy.com](https://blackridgeautonomy.com)

---

## The Problem

Multi-agent autonomous systems operating under hard energy constraints face a compounding failure mode: when agents are lost to attrition, comms degradation, or environmental stress, the remaining agents inherit expanded mission objectives but have no additional fuel budget. Fixed-throttle controllers cannot adapt — they run out of fuel and fail.

## The Solution

WHACO is an 11-mode throttle governor that shapes burn rate in real time based on fuel pressure, wind state, and swarm connectivity. It runs as a companion-computer overlay on standard autopilots (PX4 via MAVLink OFFBOARD) — **zero changes to firmware, zero changes to airframe, 15 microsecond compute overhead**.

---

## Validated Claims

Every claim has a traceable path: **Claim → Test Script → Data Artifact → Quantitative Verdict**.

| # | Claim | Evidence | Effect Size |
|---|-------|----------|-------------|
| 1 | +9.8pp mission success over fixed-throttle (1,000 OOD environments) | [TEST_REPORT.md](TEST_REPORT.md#claim-1) | d=1.30 |
| 2 | Mechanism is burn-rate shaping, not corridor exploitation | [TEST_REPORT.md](TEST_REPORT.md#claim-2) | Ablation + counterfactual |
| 3 | Generalizes across 1,000 out-of-distribution environments | [TEST_REPORT.md](TEST_REPORT.md#claim-3) | p<0.001 |
| 4 | Scale-emergent multi-agent advantage at N>=50-75 | [TEST_REPORT.md](TEST_REPORT.md#claim-4) | Crossover at N~75 |
| 5 | PX4 SITL closed-loop validation: 7/7 scenarios pass | [TEST_REPORT.md](TEST_REPORT.md#claim-5) | 7/7 PASS |
| 6 | 15.1 us/call compute cost (1.8% of 50 Hz budget) | [TEST_REPORT.md](TEST_REPORT.md#claim-6) | 1.8% overhead |
| 7 | Robust to +/-20% threshold perturbation | [TEST_REPORT.md](TEST_REPORT.md#claim-7) | No qualitative change |
| 8 | Robust to dropout timing (early/mid/late/burst) | [TEST_REPORT.md](TEST_REPORT.md#claim-8) | Burst amplifies advantage |
| 9 | EW modes (CLOAK/GHOST/SCUTTLE) with 6/6 RCS validation | [VERSION.md](VERSION.md#ew-mode-thresholds) | 6.2 us/agent |

See [CLAIM_BOUNDARY.md](CLAIM_BOUNDARY.md) for what does **NOT** hold — regime boundaries, explicit limitations, and honest failure modes.

---

## Quick Start

### Install

```bash
git clone https://github.com/morpheus18-glitch/whaco-rl.git
cd whaco-rl
pip install -e ".[all]"
```

### Run Tests

```bash
make test-quick          # SDK + PX4 dry-run (~30s) → 2/2 PASS
make test-full           # Full 9-battery suite (~30 min)
make baqr-fast           # BAQR qualification (~3 min)
```

### Use the SDK

```python
from blackridge_governor import Governor

gov = Governor(fuel_budget=4.0)
thrust, mode_id, mode_name = gov.step(
    wind_x=-3.0, wind_y=0.5,
    fuel_remaining=2.8, dist_to_goal=45.0,
    groundspeed=6.2, throttle_pct=0.55,
)
print(f"Mode: {mode_name}, Thrust: {thrust}")
# Mode: CRUISE, Thrust: 0.55
```

---

## Architecture

```
blackridge_governor/           SDK package
  governor.py                  11-mode throttle controller (15 us/call)
  ew_governor.py               EW swarm coordinator (formations, roles, 6.2 us/agent)
  demo.py                      SDK smoke test + reproduction runner

hil/                           PX4 SITL hardware-in-loop
  px4_sitl_harness.py          MAVLink companion controller (50 Hz)
  test_px4_harness_dryrun.py   128-check offline validation
  pegasus/                     Gazebo + UE5 4K visual simulation

results/                       Frozen publication data (immutable)
  pubA_200t/                   2,400 trials (PYTHONHASHSEED=42)
  baqr/v1.0/                   BAQR qualification artifacts

docs/                          Technical documentation
  baqr/                        BAQR scoring rubric, DARPA appendix
  FLIGHT_TEST_DESIGN.md        Phase II flight test protocol (98K)
  PATENT_STRATEGY.md           IP prosecution plan
  PROCUREMENT_PATHWAY.md       DoD procurement roadmap
  COST_MODEL.md                Operational economics

whaco_*.py                     43 test/benchmark scripts
reproduce_all.py               Single-command full reproduction
```

---

## Test & Qualification Infrastructure

| Suite | Script | What It Validates | Runtime |
|-------|--------|-------------------|---------|
| **Stress (1-3)** | `whaco_stress_test.py` | Structure index, compute, worst-case | ~2 min |
| **OOD (4-6)** | `whaco_ood_ablation_regret.py` | 1000-world generalization, ablation, regret | ~5 min |
| **Reviewers (7-9)** | `whaco_reviewer_killers.py` | Calibration, counterfactual, significance | ~3 min |
| **Verifier** | `whaco_verifier.py` | 30 checks across 7 dimensions | ~5 min |
| **CTF Benchmark** | `whaco_ctf_tests.py` | Multi-scale contested (2km/10km, 2D/3D) | ~10 min |
| **BAQR v1.0** | `whaco_baqr.py` | 6-tier formal qualification, 100-pt rubric | ~8 min |
| **Scale Sweep** | `whaco_scale_sweep.py` | N=10-100 crossover analysis | ~5 min |
| **Kill Tests** | `whaco_kill_tests.py` | Structural kill conditions (N=20, N=50) | ~8 min |
| **3D Benchmark** | `whaco_3d_benchmark.py` | Altitude shear, climb penalty | ~5 min |
| **PX4 SITL** | `reproduce_all.py --with-sitl` | 7 closed-loop MAVLink scenarios | ~10 min |

All tests produce machine-readable JSON artifacts and publication-quality PNG plots. Full reproduction: `PYTHONHASHSEED=42 python3 reproduce_all.py`

---

## BAQR v1.0 — Autonomy Qualification

BAQR (Blackridge Autonomy Qualification Range) is a formal benchmark suite for swarm autonomy evaluation.

```bash
python3 whaco_baqr.py --fast --all    # Quick (3 trials)
python3 whaco_baqr.py --all           # Full (15 trials)
python3 whaco_baqr.py --critique      # DARPA critique appendix
```

**Tiers:** T0 Regression → T1 Benign → T2 Contested → T3 Operational (LOW/MED/HIGH turbulence)

**Awards:** Gold (all tiers) | Silver (through T3-LOW) | Bronze (through T2) | Certified (T0+T1)

See [docs/baqr/SCORING_RUBRIC.md](docs/baqr/SCORING_RUBRIC.md) for the 100-point rubric.

---

## Documentation Map

| Document | Audience | Purpose |
|----------|----------|---------|
| [TEST_REPORT.md](TEST_REPORT.md) | Technical reviewer | Formal evidence chain for all 9 claims |
| [VALIDATION_PACKET.md](VALIDATION_PACKET.md) | Program manager | 6-tier CTF results with effect sizes |
| [SBIR_TECHNICAL_VOLUME.md](SBIR_TECHNICAL_VOLUME.md) | Government | SBIR-formatted technical narrative |
| [COMMERCIAL_READINESS.md](COMMERCIAL_READINESS.md) | Investor | ICP analysis, pricing, GTM funnel |
| [QUAD_CHART.md](QUAD_CHART.md) | Executive | 1-page program office summary |
| [CLAIM_BOUNDARY.md](CLAIM_BOUNDARY.md) | Skeptic | Regime map + explicit limitations |
| [INVENTION_DISCLOSURE.md](INVENTION_DISCLOSURE.md) | Legal | Patent novelty + prior art |
| [VERSION.md](VERSION.md) | Developer | Canonical v1.1.0 spec |
| [paper.md](paper.md) | Academic | Full technical paper (13 sections) |
| [CHANGELOG.md](CHANGELOG.md) | All | Version history |

---

## PX4 SITL Reproduction

Requires PX4 v1.14.3 + jMAVSim running in Docker:

```bash
# Terminal 1: Start PX4
bash hil/px4_sitl_setup.sh

# Terminal 2: Run validation
python3 reproduce_all.py --with-sitl
```

Expected: **7/7 scenarios PASS** with telemetry in `hil/telemetry/`.

---

## Docker

```bash
make docker-build          # Build image with smoke test
make docker-test           # Run quick tests in container
```

---

## License

Copyright (c) 2026 Blackridge Autonomy LLC. All rights reserved. See [LICENSE](LICENSE).

Third-party acknowledgments in [NOTICE](NOTICE).

---

## Citation

```
Blackridge Autonomy LLC. "WHACO: Wind-Harvesting Adaptive Controller for Operations —
Resource-Aware Distributed Control Governor with Scale-Emergent Attrition Resilience."
Technical Report TR-WHACO-2026-001, v1.1.0, February 2026.
```

---

## Contact

Blackridge Autonomy LLC
[blackridgeautonomy.com](https://blackridgeautonomy.com)
contact@blackridgeautonomy.com
