segrails.result
===============

.. py:module:: segrails.result

.. autoapi-nested-parse::

   Segrails result dataclasses.

   Defines the structured output returned by the Segrails inference pipeline.



Classes
-------

.. autoapisummary::

   segrails.result.SegrailsError
   segrails.result.ModelInfo
   segrails.result.SegrailsPrediction
   segrails.result.SegrailsResult


Module Contents
---------------

.. py:class:: SegrailsError

   Error descriptor returned when a pipeline step fails.

   .. attribute:: code

      HTTP-style error code (e.g. 500 for an internal error).

   .. attribute:: message

      Human-readable description of the error.


   .. py:attribute:: code
      :type:  int


   .. py:attribute:: message
      :type:  str


.. py:class:: ModelInfo

   Metadata about the model used during inference.

   .. attribute:: name

      Registered model name.

   .. attribute:: version

      Registered model version.

   .. attribute:: model_path

      Local path to the model checkpoint file.


   .. py:attribute:: name
      :type:  str


   .. py:attribute:: version
      :type:  str


   .. py:attribute:: model_path
      :type:  str


.. py:class:: SegrailsPrediction

   Detection results produced by the postprocessing step.

   .. attribute:: inference_time

      Duration of the UNet inference in seconds.

   .. attribute:: n_tracks

      Total number of track segments detected.

   .. attribute:: valid_tracks

      Number of tracks classified as valid rail tracks.

   .. attribute:: crossings

      Number of segments classified as rail crossings.

   .. attribute:: total_low_detections

      Total count of detections with IoU below threshold.

   .. attribute:: total_missed_detections

      Total count of track segments with no detection.

   .. attribute:: tracks

      List of track dictionaries. Each entry contains id, classification,
      and a list of point dicts with coordinates, direction, IoU score and status.


   .. py:attribute:: inference_time
      :type:  float
      :value: 0.0



   .. py:attribute:: n_tracks
      :type:  int
      :value: 0



   .. py:attribute:: valid_tracks
      :type:  int
      :value: 0



   .. py:attribute:: crossings
      :type:  int
      :value: 0



   .. py:attribute:: total_low_detections
      :type:  int
      :value: 0



   .. py:attribute:: total_missed_detections
      :type:  int
      :value: 0



   .. py:attribute:: tracks
      :type:  List[Dict[str, Any]]
      :value: []



.. py:class:: SegrailsResult

   Top-level result returned by the Segrails pipeline.

   .. attribute:: status

      Pipeline status. Either ``"success"`` or ``"failure"``.

   .. attribute:: timestamp

      ISO 8601 UTC timestamp of when the pipeline ran.

   .. attribute:: model

      Metadata about the model used. None if loading failed.

   .. attribute:: input

      Optional dict describing the pipeline inputs (paths, center, …).

   .. attribute:: predictions

      Detection results. None if inference or postprocessing failed.

   .. attribute:: error

      Error descriptor. None when status is ``"success"``.

   .. rubric:: Example

   >>> result = SegrailsResult(status="success", timestamp="2026-01-01T00:00:00Z")
   >>> result.dump()
   {'status': 'success', 'timestamp': '2026-01-01T00:00:00Z', ...}


   .. py:attribute:: status
      :type:  Literal['success', 'failure']


   .. py:attribute:: timestamp
      :type:  str


   .. py:attribute:: model
      :type:  Optional[ModelInfo]
      :value: None



   .. py:attribute:: input
      :type:  Optional[Dict[str, Any]]
      :value: None



   .. py:attribute:: predictions
      :type:  Optional[SegrailsPrediction]
      :value: None



   .. py:attribute:: error
      :type:  Optional[SegrailsError]
      :value: None



   .. py:method:: dump() -> Dict[str, Any]

      Serialize the result to a plain dictionary.

      :returns: Fully serialized result, suitable for JSON export.
      :rtype: Dict[str, Any]