Source code for ase2sprkkr.outputs.project_results

"""Rehydrate SPR-KKR results from project run records."""

from __future__ import annotations

import os

from ..common.module_registry import RegistryEntryNotFound
from kkrunner.files import ArtifactAvailabilityState, FileState
from kkrunner.runs import FailurePhase, HistoricalFileMismatchError
from kkrunner import RunState
from ..input_parameters.input_parameters import InputParameters
from ..input_parameters.task_definition import TaskMismatchError
from .reader_registry import reader_registry


[docs] class ProjectResultUnavailableError(RuntimeError): """A stored run cannot be reconstructed as its historical TaskResult.""" def __init__(self, record, message): self.record = record super().__init__(f"Run {record.id}: {message}")
[docs] class UnrecoverableProjectResultError(ProjectResultUnavailableError): """The persisted metadata is insufficient to reconstruct this result."""
[docs] def _record(manager, run): return manager.store.get(run) if isinstance(run, str) else manager.store.get(run.id)
[docs] def application_metadata(record): """Validate and read the immutable SPR-KKR namespace of a generic record.""" metadata = record.metadata.get("ase2sprkkr") if not isinstance(metadata, dict) or not isinstance(metadata.get("task"), str): raise UnrecoverableProjectResultError(record, "missing SPR-KKR task metadata") return metadata
[docs] def _task_definition_for_record(record): try: return InputParameters.task_registry[application_metadata(record)["task"]] except RegistryEntryNotFound: raise UnrecoverableProjectResultError( record, f"unknown persisted task {application_metadata(record)['task']!r}" ) from None
[docs] def _input_parameters_for_record(manager, record, task_definition): result_files = record.files input_file = None if result_files is None else result_files.input_file current_input = (manager.input_file_is_current(record) if manager is not None else any(str(v.path) == input_file and v.is_current() for v in result_files.input_versions)) if input_file is None or not current_input: return None if application_metadata(record).get("input_definition") is None: return None input_registry = InputParameters.input_parameters_registry try: definition = input_registry[application_metadata(record).get("input_definition")] except RegistryEntryNotFound: raise UnrecoverableProjectResultError( record, f"unknown persisted input definition {application_metadata(record).get('input_definition')!r}", ) from None try: return input_registry.read_for_task( task_definition, input_file, input_definition=definition, ) except TaskMismatchError as exc: raise UnrecoverableProjectResultError( record, "persisted task does not match historical input " f"({application_metadata(record)['task']!r} != {exc.task_name!r})", ) from exc
[docs] def _reader_for_record(manager, record): """Create the task-owned output reader declared by the persisted task.""" task_definition = _task_definition_for_record(record) parameters = _input_parameters_for_record(manager, record, task_definition) reader_class = reader_registry.class_for_task(task_definition) return reader_class( parameters, None, record.execution.directory.local, task_name=application_metadata(record)["task"], )
[docs] def _result_processor_for_record(manager, record): """Build the generic execution→TaskResult boundary in the outputs layer.""" reader = _reader_for_record(manager, record) def process_result(outcome): return reader.read_from_file( outcome.output_file, outcome.error_file, return_code=(0 if outcome.return_code is None else outcome.return_code), input_file=outcome.input_file, directory=record.execution.directory.local, ) return process_result
[docs] def attach_project_run( manager, run, *, executor=None, callback=None, output_listener=None, ): """Reconnect an active run and resume its client-side lifecycle.""" record = _record(manager, run) retry_download = ( record.state == RunState.FAILED and record.failure_phase == FailurePhase.DOWNLOAD and record.return_code == 0 ) if not retry_download and record.state in ( RunState.FINISHED, RunState.FAILED, RunState.CANCELLED ): raise ProjectResultUnavailableError( record, f"run is already terminal ({record.state.value})" ) # An attach attempt does not own a running processor's lock, so reader # reconstruction failures must not finalize its processing state. process_result = _result_processor_for_record(manager, record) if retry_download: # Resolve the reader first: a construction error must not turn a # historically failed transfer into an orphan active run. record = manager.resume_download(record) def completed(result): from .task_result import TaskResult if isinstance(result, TaskResult): result.run_record = manager.store.get(record.id) if callback is not None: callback(result) return manager.attach( record, process_result=process_result, client=executor, callback=completed, output_listener=output_listener, )
[docs] def retry_project_postprocessing(manager, run): """Explicitly parse preserved result files again without executing the task.""" record = _record(manager, run) # Reader construction is outside the transition: programming errors and # missing definitions must leave the original failure record unchanged. processor = _result_processor_for_record(manager, record) result = manager.retry_postprocessing(record, processor) # TaskResult provenance belongs to the outputs layer, not the generic project manager. # Generic processors may return immutable or scalar values. Only task # results carry the optional project provenance attribute. from .task_result import TaskResult if isinstance(result, TaskResult): result.run_record = manager.store.get(record.id) return result
[docs] def load_project_result(manager, run): """Reconstruct the historical TaskResult of one terminal project run.""" record = _record(manager, run) if record.state not in (RunState.FINISHED, RunState.FAILED, RunState.CANCELLED): raise ProjectResultUnavailableError( record, f"run is still active ({record.state.value})" ) # Restore every available file independently. Missing auxiliary files do # not invalidate a historical result whose primary output is intact. try: record = manager.retrieve_result_files(record) except HistoricalFileMismatchError as exc: # Older KKRunner versions raise the digest mismatch directly, rather # than returning a per-file failure. Preserve the same public error # and store the primary result's unavailability in either case. output_file = None if record.files is None else record.files.output_file if output_file is not None: record = manager.update_artifact_availability( record, output_file, ArtifactAvailabilityState.FAILED, str(exc), ) raise ProjectResultUnavailableError(record, str(exc)) from exc result_files = record.files if result_files is not None and result_files.captured_at is None: raise ProjectResultUnavailableError( record, "historical output is unavailable: no authoritative file snapshot" ) if result_files is None or result_files.output_file is None: raise ProjectResultUnavailableError( record, "no persisted output result file" ) output_file = result_files.output_file output_available = manager.output_file_is_current(record) if not output_available: # Distinguish a changed historical file from a missing file: both must # prevent parsing, but the user needs the actual reason for recovery. output_error = ( result_files.stdout.availability_message if result_files.stdout is not None else None ) version = next(( item for item in result_files.output_versions if os.path.abspath(os.fspath(item.path)) == os.path.abspath(os.fspath(output_file)) ), None) if version is not None and version.state() == FileState.OVERWRITTEN: output_error = f"historical output was overwritten: {output_file}" raise ProjectResultUnavailableError( record, output_error or "output result file is unavailable" ) reader = _reader_for_record(manager, record) return_code = record.return_code if return_code is None: return_code = 0 if record.state == RunState.FINISHED else 1 input_file = None if manager.input_file_is_current(record) and ( getattr(reader, "input_parameters", None) is not None ): input_file = result_files.input_file result = reader.read_from_file( output_file, return_code=return_code, input_file=input_file, directory=record.execution.directory.local, ) result.run_record = record return result