Skip to content

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

Add read-only evidence-based next steps for saved jobs

Cinna Davisf34e4e08507f
diff --git a/docs/INCONCLUSIVE_GUIDANCE.md b/docs/INCONCLUSIVE_GUIDANCE.md
new file mode 100644
index 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.md
index 33bea7e..04fa196 100644
--- a/docs/INTERFACES.md
+++ b/docs/INTERFACES.md
@@ -140,6 +140,13 @@ hashes, configuration, time/altitude assumptions, searched/missing coverage and
runtime. The service must independently enforce output-directory containment when
serving 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 ownership
The existing `dopplergeist run CONFIG --output DIR` and `measure` commands keep
diff --git a/scripts/explain_job.py b/scripts/explain_job.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
index 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.js
index 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.html
index 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 &amp; 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>