stormlog.diagnose_report

Build the stormlog.report envelope for diagnose bundles.

The PyTorch, TensorFlow and JAX diagnose commands produce the same diagnostic_summary.json shape (risk_flags, suggestions and a few memory counters), so one builder turns that summary into findings with evidence pointers back into the bundle.

Functions

build_diagnose_report(*, tool_name, summary, ...)	Return the report dict for one diagnose bundle.
validate_output_directory(output)	Reject an --output that is, or sits under, an existing non-directory.
write_incomplete_bundle(artifact_dir, *, ...)	Best-effort fallback after a write failure inside run_diagnose.
write_verdict_report(artifact_dir, *, ...[, ...])	Build and write report.json for one diagnose bundle.

Exceptions

DiagnoseUsageError

The diagnose request cannot be served as asked.

exception stormlog.diagnose_report.DiagnoseUsageError

Bases: ValueError

The diagnose request cannot be served as asked.

Raised for an invalid option, a runtime that does not support the requested feature, or an output path that is not a directory. The CLIs map it to ExitCode.USAGE; any other exception from a diagnose run is an ERROR.

stormlog.diagnose_report.build_diagnose_report(*, tool_name, summary, exit_code, session_id, files, thresholds=None, tool_version=None, error=None)

Return the report dict for one diagnose bundle.

thresholds maps a risk flag to the threshold the command applied, so the finding can show the observed value next to it. error marks an incomplete bundle: the verdict summary names the failure and no findings are claimed, because the summary may never have been written.

Parameters:

• tool_name (str)

• summary (Mapping[str, Any])

• exit_code (int)

• session_id (str)

• files (Sequence[str])

• thresholds (Mapping[str, float] | None)

• tool_version (str | None)

• error (str | None)

Return type:

dict[str, Any]

stormlog.diagnose_report.validate_output_directory(output)

Reject an --output that is, or sits under, an existing non-directory.

Raises:

DiagnoseUsageError – when the nearest existing ancestor of output is not a directory.

Parameters:

output (str | None)

Return type:

None

stormlog.diagnose_report.write_incomplete_bundle(artifact_dir, *, tool_name, summary, session_id, files_written, error, thresholds, write_manifest)

Best-effort fallback after a write failure inside run_diagnose.

Rewrites report.json with an ERROR verdict so it never contradicts the exit code the process returns, then writes the manifest through write_manifest with the final file list. A stale report that cannot be rewritten is removed rather than left claiming a completed verdict.

Parameters:

• artifact_dir (Path)

• tool_name (str)

• summary (Mapping[str, Any])

• session_id (str)

• files_written (Sequence[str])

• error (str)

• thresholds (Mapping[str, float] | None)

• write_manifest (Callable[[list[str]], None])

Return type:

None

stormlog.diagnose_report.write_verdict_report(artifact_dir, *, tool_name, summary, exit_code, session_id, files, thresholds=None, error=None)

Build and write report.json for one diagnose bundle.

Parameters:

• artifact_dir (Path)

• tool_name (str)

• summary (Mapping[str, Any])

• exit_code (int)

• session_id (str)

• files (Sequence[str])

• thresholds (Mapping[str, float] | None)

• error (str | None)

Return type:

None