Python tool for aircraft Doppler audio geolocation using historical ADS-B flight data (Source-available)
Python acoustic-geolocationads-baircraft-trackingairplaneaudio-forensicsdoppler-effectdoppler-shiftgeolocationosintsignal-processing
Add read-only evidence-based next steps for saved jobs
Cinna Davisf34e4e08507f
diff --git a/docs/INCONCLUSIVE_GUIDANCE.md b/docs/INCONCLUSIVE_GUIDANCE.mdnew file mode 100644index 0000000..e1da3e6--- /dev/null+++ b/docs/INCONCLUSIVE_GUIDANCE.md@@ -0,0 +1,94 @@+# Evidence-based next steps++The local interface displays next steps below the coverage report for supported+terminal results. Each observation links to fields in that job's saved artifacts.+The job's status, reason, candidates, scores and uncertainty remain unchanged.++## Read an existing job++From an installed checkout, run:++```bash+PYTHONPATH=src python scripts/explain_job.py /path/to/job-directory+```++With the local service running, the same producer is available through:++```bash+curl http://127.0.0.1:8765/api/jobs/JOB_ID/guidance+```++Both operations only read `result.json` and optional `decision.json`. They do not+modify job files, resume checkpoints, search settings or decision thresholds.+The existing job-result contract and `/api/jobs/JOB_ID` response are unchanged.+Old saved jobs do not need migration. Recommendations are derived by the currently+installed guidance code, so their wording can change after a software update.++## Additive representation++The guidance response contains `schema_version: 1`, `job_id`, the saved `status`+and `reason_code` (or null), `ranked: false`, `items`, and `limitations`.+Each item contains `code`, `observation`, `suggestion`, `evidence`, and+`benefit: "unmeasured"`. Evidence references use an artifact name and a JSON+pointer, for example `result.json#/required_fields`. The browser downloads the+artifact; the pointer identifies the relevant field within it.++List order is presentation order, not estimated usefulness. No probability,+expected error reduction or guaranteed successful rerun is supplied. Empty items+mean that no supported suggestion was derived, not that a location is established.+An unreadable optional decision suppresses suggestions that need its diagnostics.+Decision-based guidance requires its status, reason and candidate list to match+the saved result. This prevents an older decision from supplying advice after a+different result was saved.++## Current scope++| Saved evidence | Guidance |+| --- | --- |+| Missing recording time and required `time_window` | Supply a defensible UTC window for the original recording start. |+| No discovered events for a missing-time/no-events result | More of the original recording may contain a usable event. |+| Too few matched acoustic groups | Explain the observed group count; a separate flyover may provide more evidence. |+| Possible harmonic or reused-ridge overlap | Explain that group independence is unestablished; do not assert aircraft identity. |+| Partial required data or explicit missing identifiers | Restore the identified flight or terrain data. |+| Unavailable data with a recorded acquisition/configuration limit | Inspect that limit before retrying; unavailability alone does not prove an archive gap. |+| Actual wall-time limit and incomplete search | Review runtime; resume only a compatible checkpoint, or rerun. |+| Incomplete search/model assessment | Inspect unfinished or unsupported assessments; extra runtime may not resolve them. |+| Reported competing-hypothesis separation | Preserve both alternatives and report separation and any recorded association difference. |++Coverage advice can coexist with another reason. The initial `unavailable` data+state before acquisition does not by itself trigger a missing-archive claim.+A failed data-access job can receive advice without changing `failed` to an+inconclusive scientific outcome. Other execution failures do not receive generic+retry advice.++This increment does not determine which narrower time window or extra event would+separate competing modes. It does not infer that weak or unmatched acoustic+proposals are confirmed aircraft. It does not perform counterfactuals, rank+suggestions, or recommend ground-truth coordinates or known flight IDs as inputs.++## Verification and remaining work++Use actual completed real-recording jobs when checking recommendations. Replay the+command above, inspect every cited JSON pointer, and compare the saved result+before and after the API/UI read. Check the browser at desktop and mobile widths.+Do not manufacture job outcomes to stand in for missing real evidence.++One local real reference MP3 job verifies the missing-clock case:+3,600.1845 decoded seconds, 18 ridge records, `needs_input` with+`recording_time_required`. Its unknown-clock result must have one `recording_time`+item and no missing-data item. A second completed real job has partial data and+an incomplete search. It produces both `missing_data` and+`incomplete_assessment`; the primary search reason does not hide the data limits.++Both cases passed API serialization, evidence-pointer resolution and actual+Chromium readback at desktop and mobile widths. Saved result bytes and artifact+downloads stayed unchanged. Delayed guidance responses did not overwrite a later+render of the same job. These checks did not publish the source jobs or modify+their original directories.++Issue [#63](https://github.com/1337isnot1337/DOPPLERGEIST/issues/63) remains open.+Its acceptance still requires completed real jobs for the remaining reasons and both+positive and negative controls for narrower clocks or additional independent+events. Those controls must preserve settings, the competitor population, work+limits, unsupported alternatives and before/after outcomes. No localization+accuracy or measured benefit follows from this software increment.diff --git a/docs/INTERFACES.md b/docs/INTERFACES.mdindex 33bea7e..04fa196 100644--- a/docs/INTERFACES.md+++ b/docs/INTERFACES.md@@ -140,6 +140,13 @@ hashes, configuration, time/altitude assumptions, searched/missing coverage andruntime. The service must independently enforce output-directory containment whenserving files, including symlink handling. Do not embed huge spectra in job JSON.+The optional read-only `GET /api/jobs/JOB_ID/guidance` endpoint derives next steps+from the saved result and matching decision artifacts. It has its own additive+envelope; it does not extend or rewrite `JobResult`. Recommendations include+artifact-relative evidence pointers and an explicit unmeasured-benefit label.+See [evidence-based next steps](INCONCLUSIVE_GUIDANCE.md) for the representation,+replay commands and unresolved verification requirements.+## Compatibility and ownershipThe existing `dopplergeist run CONFIG --output DIR` and `measure` commands keepdiff --git a/scripts/explain_job.py b/scripts/explain_job.pynew file mode 100644index 0000000..4524bbd--- /dev/null+++ b/scripts/explain_job.py@@ -0,0 +1,18 @@+#!/usr/bin/env python3+"""Print evidence-based next steps for an existing local job without changing it."""+import argparse+import json+from pathlib import Path++from dopplergeist.guidance import explain_job+++def main():+ parser = argparse.ArgumentParser(description=__doc__)+ parser.add_argument("job_dir", type=Path, help="directory containing result.json")+ args = parser.parse_args()+ print(json.dumps(explain_job(args.job_dir), indent=2, allow_nan=False))+++if __name__ == "__main__":+ main()diff --git a/src/dopplergeist/guidance.py b/src/dopplergeist/guidance.pynew file mode 100644index 0000000..cc57f4d--- /dev/null+++ b/src/dopplergeist/guidance.py@@ -0,0 +1,129 @@+"""Read-only next steps derived from a completed job's retained evidence.++Evidence references are artifact-relative JSON pointers. No recommendation changes+the decision or claims a measured benefit. Missing diagnostics suppress advice.+"""+import json+import math+from pathlib import Path++from .contracts import validate_result+++def guidance(result, decision=None):+ """Return unordered, conditional suggestions without modifying either input."""+ if result.get("status") not in {"needs_input", "inconclusive", "failed"}:+ return []+ reason = result.get("reason_code")+ # A saved decision from a different result (for example, before a resume)+ # must not supply the current result's observations.+ if (not isinstance(decision, dict)+ or decision.get("status") != result["status"]+ or decision.get("reason_code") != reason+ or not result.get("candidates")+ or decision.get("candidates") != result["candidates"]):+ decision = {}+ diagnostics = decision.get("diagnostics", {})+ if not isinstance(diagnostics, dict):+ diagnostics = {}+ coverage = result.get("coverage", {})+ items = []++ def add(code, observation, suggestion, evidence):+ items.append({"code": code, "observation": observation,+ "suggestion": suggestion, "evidence": evidence,+ "benefit": "unmeasured"})++ if reason == "recording_time_required" and "time_window" in result.get("required_fields", []):+ add("recording_time", "The recording start time is not established.",+ "Provide a defensible UTC window for the start of the original recording, then run the analysis again.",+ ["result.json#/reason_code", "result.json#/required_fields"])++ if reason in {"recording_time_required", "no_supported_events", "no_doppler_events"} and result.get("events") == []:+ add("no_events", "No supported Doppler events were found in this recording.",+ "If available, try more of the original recording. It may contain another usable event; this has not been assessed.",+ ["result.json#/reason_code", "result.json#/events"])++ if reason == "insufficient_independent_events":+ overlap = diagnostics.get("possible_harmonic_overlap")+ count = diagnostics.get("independent_event_groups")+ if (isinstance(overlap, dict) and overlap and count is None+ and "independent_event_groups" in diagnostics):+ add("event_independence", "The matched acoustic groups may share one flyover; their independence is not established.",+ "Inspect the overlapping ridges. More of the original recording may contain a separate flyover, but improvement is unmeasured.",+ ["result.json#/reason_code", "decision.json#/diagnostics/possible_harmonic_overlap",+ "decision.json#/diagnostics/independent_event_groups"])+ elif type(count) is int and count >= 0:+ add("more_events", f"The leading hypothesis has {count} matched acoustic group(s), below the decision's event requirement.",+ "If available, try more of the original recording containing a separate flyover. Another usable event is not guaranteed.",+ ["result.json#/reason_code", "decision.json#/diagnostics/independent_event_groups"])++ # Coverage and the primary reason can describe different simultaneous limits.+ # The initial unavailable state, before acquisition, is not an archive gap.+ missing = coverage.get("missing_data", [])+ data_problem = coverage.get("data_status") == "partial" or bool(missing)+ if data_problem and (coverage.get("limitations") or missing):+ evidence = ["result.json#/coverage/data_status"]+ if coverage.get("limitations"):+ evidence.append("result.json#/coverage/limitations")+ if missing:+ evidence.append("result.json#/coverage/missing_data")+ add("missing_data", "Required flight or terrain data are incomplete or unavailable; the coverage report identifies the limits.",+ "Ask the operator to restore the missing data before repeating the analysis. Downloaded archives do not guarantee receiver coverage.",+ evidence)+ elif (reason in {"missing_flight_data", "data_unavailable"}+ and coverage.get("data_status") == "unavailable" and coverage.get("limitations")):+ # The automatic producer also uses data_unavailable for acquisition+ # budgets and invalid provider settings. This is not proof of a gap.+ add("data_access_limit", "Required data could not be obtained or assessed; the coverage report records the limiting condition.",+ "Ask the operator to inspect the recorded data-access or configuration limit before repeating the analysis.",+ ["result.json#/reason_code", "result.json#/coverage/data_status", "result.json#/coverage/limitations"])++ if reason == "work_limit" and coverage.get("search_complete") is False:+ add("work_limit", "The configured wall-time limit ended the analysis before the search completed.",+ "Ask the operator to allow more time. A compatible saved checkpoint can be resumed; otherwise rerun. Completion is not guaranteed.",+ ["result.json#/reason_code", "result.json#/coverage/search_complete"])+ elif reason == "search_incomplete" and coverage.get("search_complete") is False:+ add("incomplete_assessment", "Search coverage or assessment of competing hypotheses is incomplete.",+ "Ask the operator to inspect unfinished work and unsupported model assessments. More runtime alone may not address these limits.",+ ["result.json#/reason_code", "result.json#/coverage/search_complete"])+ elif (reason == "finite_search_incomplete" and coverage.get("search_complete") is True+ and isinstance(diagnostics.get("finite_search"), dict)):+ # Completed tile coverage is distinct from assessment of every retained+ # or discarded competitor. The decision checks these separately.+ add("incomplete_assessment", "Assessment of competing hypotheses is incomplete, even though the requested search scope was processed.",+ "Ask the operator to inspect unassessed hypotheses and unsupported model assessments. More runtime alone may not address these limits.",+ ["result.json#/reason_code", "result.json#/coverage/search_complete",+ "decision.json#/diagnostics/finite_search"])++ if reason in {"ambiguous_locations", "ambiguous_flight_match"}:+ competitor = diagnostics.get("competing_hypothesis", {})+ if isinstance(competitor, dict):+ separation = competitor.get("separation_m")+ if type(separation) in (int, float) and math.isfinite(separation) and separation >= 0:+ observation = f"A competing hypothesis is about {separation:.0f} m from the leading one."+ evidence = ["result.json#/reason_code", "decision.json#/diagnostics/competing_hypothesis/separation_m"]+ if competitor.get("same_flight_association") is False:+ observation += " It assigns the acoustic events to different flight segments."+ evidence.append("decision.json#/diagnostics/competing_hypothesis/same_flight_association")+ add("competing_hypotheses", observation,+ "Inspect both alternatives. Whether a narrower recording-start window or more audio separates them has not been assessed.",+ evidence)+ return items+++def explain_job(job_dir):+ """Read an existing job; return an additive API envelope without writing it."""+ directory = Path(job_dir)+ result = validate_result(json.loads((directory / "result.json").read_text()))+ decision = None+ limitations = ["Suggestions are not ranked. Their benefit has not been measured; they do not change the job's decision."]+ try:+ decision = json.loads((directory / "decision.json").read_text())+ except FileNotFoundError:+ pass+ except (OSError, ValueError):+ limitations.append("The saved decision could not be read; suggestions requiring its diagnostics are omitted.")+ return {"schema_version": 1, "job_id": result["job_id"], "status": result["status"],+ "reason_code": result.get("reason_code"), "ranked": False,+ "items": guidance(result, decision), "limitations": limitations}diff --git a/src/dopplergeist/service.py b/src/dopplergeist/service.pyindex 59ab60e..4965a46 100644--- a/src/dopplergeist/service.py+++ b/src/dopplergeist/service.py@@ -66,6 +66,9 @@ class Handler(BaseHTTPRequestHandler):job_id = parts[2]if self.command == "GET" and len(parts) == 3:return self._reply(manager.get(job_id))+ if self.command == "GET" and parts[3:] == ["guidance"]:+ from .guidance import explain_job+ return self._reply(explain_job(manager.directory(job_id)))if self.command == "POST" and parts[3:] == ["cancel"]:return self._reply(manager.cancel(job_id))if self.command == "POST" and parts[3:] == ["resume"]:diff --git a/src/dopplergeist/web/app.js b/src/dopplergeist/web/app.jsindex f54affb..7330d47 100644--- a/src/dopplergeist/web/app.js+++ b/src/dopplergeist/web/app.js@@ -1,7 +1,7 @@'use strict';const $ = id => document.getElementById(id);const terminal = new Set(['needs_input', 'succeeded', 'inconclusive', 'failed', 'cancelled']);-let activeJob = null, timer = null, maxBytes = 100 * 1024 * 1024;+let activeJob = null, renderedJob = null, timer = null, maxBytes = 100 * 1024 * 1024;const node = (tag, text, cls) => { const n = document.createElement(tag); if (text !== undefined) n.textContent = text; if (cls) n.className = cls; return n; };async function api(path, options) {const response = await fetch(path, options);@@ -45,6 +45,7 @@ async function artifacts(id) {}}function render(value) {+ renderedJob = value;$('empty').hidden = true; $('job').hidden = false;$('job-id').textContent = `JOB ${value.job_id}`;$('status').textContent = value.status.replaceAll('_', ' ');@@ -55,6 +56,7 @@ function render(value) {$('message').textContent = value.message || 'Analysis is running. You can return to this job using its saved link.';$('required').hidden = !value.required_fields?.length;$('required').textContent = value.required_fields?.length ? `Required input: ${value.required_fields.join(', ')}. Add the evidence to a new analysis; this run is preserved.` : '';+ $('guidance').replaceChildren(); $('guidance').hidden = true;$('coverage').replaceChildren();if (value.coverage) {const coverage = value.coverage;@@ -98,17 +100,51 @@ function render(value) {$('events').replaceChildren();if (value.events?.length) {const groups = new Set(value.events.map(event => event.harmonic_group_id || event.event_id)).size;- $('events').append(node('h3', `${groups} independent acoustic proposals · ${value.events.length} ridge records`));+ $('events').append(node('h3', `${groups} acoustic proposal groups · ${value.events.length} ridge records`));for (const event of value.events) $('events').append(node('div', `${event.event_id} · ${event.start_s.toFixed(1)}–${event.end_s.toFixed(1)} s · ${event.band_hz.map(x => x.toFixed(0)).join('–')} Hz${event.harmonic_group_id ? ` · group ${event.harmonic_group_id}` : ''}`, 'event'));}}+async function readGuidance(value) {+ const id = value.job_id;+ try {+ const advice = await api(`/api/jobs/${id}/guidance`);+ if (id !== activeJob || renderedJob !== value || advice.status !== value.status || advice.reason_code !== (value.reason_code || null)) return;+ if (!advice.items?.length) return;+ const panel = $('guidance');+ panel.replaceChildren(node('h3', 'Next steps'));+ panel.append(node('p', 'These suggestions are not ranked. Their benefit has not been measured.', 'help'));+ for (const item of advice.items) {+ const card = node('div', undefined, 'candidate');+ card.append(node('p', item.observation), node('p', item.suggestion));+ const detail = node('details'); detail.append(node('summary', 'Evidence behind this suggestion'));+ const list = node('ul');+ for (const reference of item.evidence || []) {+ const li = node('li');+ const [artifact] = reference.split('#');+ // Only link the two local artifacts emitted by the guidance producer.+ if (artifact === 'result.json' || artifact === 'decision.json') {+ const link = node('a', reference);+ link.href = `/api/jobs/${id}/artifacts/${artifact}`; link.download = '';+ li.append(link);+ } else li.textContent = reference;+ list.append(li);+ }+ detail.append(list); card.append(detail); panel.append(card);+ }+ panel.hidden = false;+ } catch (_) {+ if (id !== activeJob || renderedJob !== value) return;+ $('guidance').replaceChildren(node('p', 'Next steps could not be read. The saved result and artifacts remain available.', 'help'));+ $('guidance').hidden = false;+ }+}async function poll(id) {clearTimeout(timer);try {const value = await api(`/api/jobs/${id}`);if (id !== activeJob) return;$('connection').textContent = ''; render(value);- if (terminal.has(value.status)) await artifacts(id);+ if (terminal.has(value.status)) await Promise.all([artifacts(id), readGuidance(value)]);else timer = setTimeout(() => poll(id), 1000);} catch (error) {if (id !== activeJob) return;diff --git a/src/dopplergeist/web/index.html b/src/dopplergeist/web/index.htmlindex 7cfba27..652c8c7 100644--- a/src/dopplergeist/web/index.html+++ b/src/dopplergeist/web/index.html@@ -27,7 +27,7 @@</fieldset><p id="limits" class="help"></p><button id="submit" type="submit">Upload & analyze <span aria-hidden="true">→</span></button><p id="upload-error" role="alert"></p></form></section>-<section class="panel results" aria-labelledby="results-heading"><div class="section-row"><h2 id="results-heading">Analysis</h2><button id="cancel" class="secondary" hidden>Stop job</button><button id="resume" class="secondary" hidden>Resume job</button></div><div id="empty"><div class="wave" aria-hidden="true">∿∿∿</div><h3>Your evidence will appear here</h3><p>Detected curves, location hypotheses, uncertainty, and downloadable artifacts stay attached to each job.</p></div><div id="job" hidden><p id="job-id" class="mono"></p><div class="section-row"><strong id="status" role="status" aria-live="polite"></strong><span id="stage" class="muted"></span></div><progress id="progress" max="1" value="0" aria-label="Analysis progress"></progress><p id="message"></p><p id="required" class="notice" hidden></p><div id="coverage"></div><div id="candidates"></div><div id="events"></div><div id="diagnostics"></div><details id="downloads"><summary>Download run artifacts</summary><ul id="artifacts"></ul></details><p id="connection" role="alert"></p></div></section>+<section class="panel results" aria-labelledby="results-heading"><div class="section-row"><h2 id="results-heading">Analysis</h2><button id="cancel" class="secondary" hidden>Stop job</button><button id="resume" class="secondary" hidden>Resume job</button></div><div id="empty"><div class="wave" aria-hidden="true">∿∿∿</div><h3>Your evidence will appear here</h3><p>Detected curves, location hypotheses, uncertainty, and downloadable artifacts stay attached to each job.</p></div><div id="job" hidden><p id="job-id" class="mono"></p><div class="section-row"><strong id="status" role="status" aria-live="polite"></strong><span id="stage" class="muted"></span></div><progress id="progress" max="1" value="0" aria-label="Analysis progress"></progress><p id="message"></p><p id="required" class="notice" hidden></p><div id="coverage"></div><section id="guidance" aria-label="Evidence-based next steps" hidden></section><div id="candidates"></div><div id="events"></div><div id="diagnostics"></div><details id="downloads"><summary>Download run artifacts</summary><ul id="artifacts"></ul></details><p id="connection" role="alert"></p></div></section></div><section id="recent-panel" class="recent" hidden><h2>Recent jobs on this browser</h2><ul id="recent"></ul></section><footer>Scores rank hypotheses; they are not probabilities. An inconclusive result can include alternatives without supporting a precise location.</footer>