Skip to content

Python tool for aircraft Doppler audio geolocation using historical ADS-B flight data (Source-available)

14.4 KB
Raw Blame

Agent swarm task plan

The goal is a real MP3-upload-to-location workflow with automatic Doppler-event discovery. Up to 1 km location error is acceptable; 100–500 m or better is preferred on supported, independently evaluated real recordings. Use every supported independent flyover, including three, four or more, under one shared clock/location; there is no default two- or three-event cap. Every issue includes a concrete objective, suggested file ownership, dependencies and acceptance checks.

Default agent communication: discussion board #39. Use threaded conversations for dependencies, design decisions, blockers and handoffs; read and respond at the checkpoints in AGENTS.md. Task index and completion tracking: issue #1. Workers are deployed by the user and claim work when launched. The primary and other workers must not launch subagents themselves; create concrete issues for new workstreams instead.

Historical flight data already used by the project: ADSB.lol globe_history_2026, with daily archives and a reusable all-aircraft cache described in DATA_AND_SCALE.md. Its observed tracks do not guarantee receiver completeness; it is not an independent source for an audit of the same ADSB.lol inputs. See data provenance for terms.

Launch order

  1. Start the integration lead on DG-01 and the evaluation agent on DG-02. Other agents can inspect code/data and reproduce relevant evidence immediately.
  2. Once the minimal contracts are settled, start DG-03, DG-05 and DG-11. The matching agent can start DG-07 once contracts and evaluation fixtures exist. The product agent can prepare the API skeleton using the shared contract.
  3. Continue audio work into DG-04, data work into DG-06, and matching work through integration with automatically detected events. Keep service integration moving as those interfaces become real.
  4. Complete DG-08 against the combined search/matching output. Finish DG-09 and DG-10 against the real backend, then DG-12 from a clean checkout.

Dependencies are integration gates, not an instruction to spend days idle. Work on fixtures, adapters, diagnostics and reproducible baseline checks while waiting. Do not close a task using mocked outputs or a proposed design alone.

Five swarm workers plus the primary integration agent

Agent role Task sequence Responsibility
Worker 1: Audio DG-03 / #4 → DG-04 / #5 Intake, automatic event discovery and harmonic grouping
Worker 2: Data and scale DG-05 / #6 → DG-06 / #7 Cached/indexed inputs and bounded-memory national search
Worker 3: Matching DG-07 / #8 Event-to-flight association and physical refinement
Worker 4: Evaluation and confidence DG-02 / #3 → DG-08 / #9 Independent benchmarks, ambiguity and abstention
Worker 5: Product DG-09 / #10 → DG-10 / #11 Actual orchestration/API and upload UI
Primary integration agent DG-01 / #2, DG-11 / #12, DG-12 / #13 Shared contracts, packaging/CI and final integration

The user is launching five workers. This allocation supersedes the earlier seven-role suggestion. Do not have several agents independently rewrite audio.py, search.py or pipeline.py.

Additional workstreams for user-deployed workers

Priority / role Task Boundary and deliverable
Highest: independent field-data acquisition #53 Obtain a documented multi-device/environment corpus with independent GPS and sample-zero UTC, plus a sealed holdout. Separate from W4's evaluator. Requires actual collection or an eligible independently documented source; tooling alone does not complete it.
High: end-to-end invariance verification #61 Replay evidence-preserving bitrate/rate/gain/channel/silence/chunk variants through the complete system. Predeclare consistency tolerances; retain all outcomes and flag accepted distant jumps. Separate from codec unit checks and destructive stress testing.
High: independent historical-track audit #62 Compare genuinely independent ADS-B archives, then source-swap frozen localization replays. Report time/position/altitude/gap discrepancies and the resulting error budget; separate from W2 ingestion.
Medium: actionable inconclusive guidance #63 Derive concise next steps from actual competing modes, clock, acoustic evidence, coverage and work limits. Coordinate additive product/decision contracts with W5/W4; guidance cannot change acceptance.
Atmospheric propagation audit #49 Frozen-model falsification with independent wind/temperature/refraction fixtures and a measured error budget. No production changes or reference-case tuning.
Recording robustness audit #54 Measure effects of phone processing, compression, microphone wind noise, reverberation, motion and rate changes. Report failure ranges before proposing correction models.

These are task assignments, not worker launches. The primary-launched atmospheric worker was stopped at the user's request; #49 is available for a user-deployed owner. Coordinate these workstreams on discussion board #39. Preserve every case and distinguish measured location error from model sensitivity and actual acceptance/abstention. Report outcomes at 100, 500 and 1,000 m.

Current integration priorities — 2026-11-03 UTC

Complete the correctness gates #52 and #64, integrate the all-event driver/local application, and obtain the independent field corpus #53 before expanding major features. National null/look-elsewhere calibration and leave-one-flyover-out prediction are focused additions to existing #9/#3 confidence/evaluation ownership; their frozen protocols are in #9. They do not create another worker role. Keep unsupported tracks, omitted coverage and failed profiles explicit. Prioritize repeatable local loopback operation; hosted-service development is outside this phase. Existing CI remains verification.

Ready-to-copy assignment prompt

Replace the task/role placeholders with one row above:

Work in https://github.com/1337isnot1337/DOPPLERGEIST as the <ROLE> agent.
Implement <TASK ISSUE URL>, followed by its next task only when dependencies allow.
Read AGENTS.md, docs/AGENT_TASKS.md, docs/HANDOFF.md and the issue before editing.
Claim the issue with your agent identity, branch/worktree and owned files.
Use a separate branch/worktree and preserve existing changes and frozen evidence.
Do not launch subagents; record additional tasks as issues for user deployment.
Use discussion board #39 as the default way to communicate with other workers.
Read it at least every 10 minutes; reply to questions directed to your role.
Discuss shared interfaces and conflicting ownership before changing them.
Post findings, failures, dependencies and blockers promptly; link relevant issues/PRs.
Implement the task, run meaningful verification, and open a focused linked PR.
Report exact commands, commit, artifacts, measured results and unresolved limits.
The product must discover Doppler events automatically from uploaded audio.
A defensible recording date/time window may be supplied; manual event windows,
frequency bands, known flight IDs and ground-truth locations are not normal inputs.
Up to 1 km error is acceptable; aim for 100–500 m or better and report all three
thresholds (100/500/1,000 m). Use all supported independent flyovers, including
3, 4 or more; harmonics/fragments count once and false proposals can stay unmatched.
Bound computational work explicitly instead of silently limiting matched events.
Do not claim national real-audio accuracy from regional-only, synthetic-only,
mocked, selected, or ground-truth-assisted evidence.
Do not upload the YouTube MP4. Do not overwrite historical experiment outputs.

Issue index

Work package Integration prerequisites
DG-01: Define pipeline contracts and compatibility rules Ready now
DG-02: Build a truth-separated benchmark corpus and evaluation runner Ready now
DG-03: Implement whole-recording audio intake and trustworthy time metadata DG-01
DG-04: Discover and trace Doppler events automatically across an entire recording DG-01, DG-03
DG-05: Automate historical flight and terrain acquisition with reusable indexes DG-01
DG-06: Add bounded-memory national search and deterministic candidate merging DG-01, DG-05
DG-07: Improve event-to-flight association and uncertainty-aware localization DG-01, DG-02
DG-08: Add ambiguity, uncertainty and explicit inconclusive outcomes DG-02, DG-06, DG-07
DG-09: Connect automatic detection, data retrieval and search through CLI and job API DG-01, DG-03, DG-04, DG-05, DG-06, DG-07, DG-08
DG-10: Build the MP3 upload interface and inspectable results DG-01, DG-09
DG-11: Provide reproducible installation, lightweight CI and artifact restoration DG-01
DG-12: Integrate the swarm and prove the complete upload-to-location workflow DG-01, DG-02, DG-03, DG-04, DG-05, DG-06, DG-07, DG-08, DG-09, DG-10, DG-11

Shared interfaces and ownership

DG-01 publishes the request/event/result contracts before other agents finalize them. Times must distinguish absolute UTC from audio-relative seconds, and all distances, speeds and frequencies must carry explicit units. Evaluation-only truth stays outside search inputs.

DG-04 owns event discovery; DG-07 owns scoring/association internals; DG-06 owns the outer national-search driver; DG-09 owns orchestration and the API; DG-10 consumes the API. DG-11 coordinates shared dependency and CI changes. The issue bodies specify where existing files overlap and require coordination.

Each PR must include its issue, changed behavior, meaningful validation, exact artifact paths and unresolved failures. A failed experiment is useful evidence; preserve it with a clear label. Use new output directories and record code/input hashes. Existing results live in Git under evidence/ and in the checkpoint release; do not quietly regenerate them in place.

Completion evidence

The final report must exercise an actual MP3 upload through the real automatic pipeline and show detection, acquisition, association, search, decision and result display. Evaluate held-out real cases and the declared national coverage, with ground truth inaccessible to search. Report every case, including misses and inconclusive outcomes, reference-coordinate/time uncertainty, runtime and memory.

The existing 43.86 m regional reference result is a useful baseline. It does not complete automatic discovery or nationwide validation. The faint-event result is 357.47 m off and remains an explicit development failure. See PROGRESS.md for all qualifications.