From 43014a508c789b6f1bced22476784961b375a7ed Mon Sep 17 00:00:00 2001 From: tn-pisama Date: Thu, 10 Sep 2026 11:39:26 -0700 Subject: [PATCH] docs: display hosted detector execution status without clean-run assumptions --- README.md | 13 +++++++++++- docs/plans/hosted-execution-docs.md | 33 +++++++++++++++++++++++++++++ 2 files changed, 45 insertions(+), 1 deletion(-) create mode 100644 docs/plans/hosted-execution-docs.md diff --git a/README.md b/README.md index 1375d82..b8d8d19 100644 --- a/README.md +++ b/README.md @@ -82,6 +82,10 @@ result = post("/diagnose/why-failed", { "content": json.dumps(trace), "format": "otel", "include_fixes": False, }, token) del token +execution = result.get("execution") +if not isinstance(execution, dict): + execution = {} +print("Detector execution:", execution.get("status", "unavailable")) print("Failure signals:", result.get("failure_count")) for finding in result.get("all_detections", []): print(json.dumps({name: finding.get(name) for name in ( @@ -91,7 +95,14 @@ for finding in result.get("all_detections", []): Ingestion accepts work asynchronously. The diagnosis request above analyzes the submitted content; it does not prove that background analysis of the stored run -has completed. Review the reported agent, spans, evidence and next action against +has completed. Execution metadata is not available on every deployment. Missing +metadata means coverage is unavailable, not complete. `partial`, `failed`, or +`unavailable` execution must not be interpreted as a clean diagnosis, even with +zero findings. Keep any partial findings for review. A `complete` execution +status describes reported detector operations, not universal detector coverage, +calibration validity, or task success. + +Review the reported agent, spans, evidence and next action against your run. Zero signals is not proof of success, and a suggested fix is not proof that the task will work after a change. `include_fixes=False` avoids requesting optional generated fixes; it does not promise that every hosted detector is free diff --git a/docs/plans/hosted-execution-docs.md b/docs/plans/hosted-execution-docs.md new file mode 100644 index 0000000..3cba923 --- /dev/null +++ b/docs/plans/hosted-execution-docs.md @@ -0,0 +1,33 @@ +# Hosted diagnosis execution reporting + +**Status:** Active +**As of:** 2026-09-10 +**Owner:** engineering +**Evidence scope:** documentation-only candidate + +The canonical hosted example currently prints findings without displaying +detector execution coverage. A separately tested backend candidate exposes a +sanitized execution summary, but it is not yet deployed. Display that summary +when present and explicitly report unavailable when absent. Explain incomplete +and partial results without claiming detector accuracy or a completed workflow. + +Do not change SDK runtime, dependencies, version, authentication, ingestion, +package publishing or deployment. Preserve the existing hosted example and +its warning that ingestion is asynchronous. This update is safe before the +backend change: absent metadata means unavailable, not an assumed clean run. + +Verify Markdown Python blocks compile and execute only the extracted reporting +statements against local complete/partial/failed/missing inputs; no network, +credential reads or customer files. Review the exact diff before publication. +DONE: reviewed docs and local example checks; no SDK/runtime score credit. + +## Local evidence + +All five Python documentation fragments compile with top-level await permitted +for the pre-existing async examples; the first ordinary-script compile attempt +failed on their top-level await and is not recorded as a pass. The hosted +example itself parses as ordinary Python. Executed only its three new reporting +statements against eight local inputs: missing, null, non-object and empty +metadata, then complete/partial/failed/unavailable. All eight passed. No network, +credential prompt, file ingestion or SDK method was executed. The example +reports server-supplied status; it is not an independent coverage verifier.