RatingManager
=============

Rating management for segmentation review.

Provides a rating system with CSV export for tracking review decisions
on trial segmentations.

Classes
-------

.. py:class:: Rating
   :bases: IntEnum

   Segmentation quality rating (Likert scale).
   
   Based on SegmentationReview extension's approach:
   https://github.com/zapaishchykova/SegmentationReview

   **Methods:**

   .. py:method:: label()

      Human-readable label.

   .. py:method:: from_string()

      Create Rating from string label.


.. py:class:: ReviewRecord

   Record of a single review decision.

   **Methods:**

   .. py:method:: to_dict()

      Convert to dictionary for serialization.

   .. py:method:: from_dict()

      Create from dictionary.


.. py:class:: RatingManager

   Manage review ratings with persistence.
   
   Tracks ratings for trial segmentations and exports to CSV/JSON
   for analysis and audit.

   **Methods:**

   .. py:method:: __init__()

      Initialize rating manager.

   .. py:method:: set_reviewer()

      Set the current reviewer name.

   .. py:method:: start_session()

      Start a new review session.

   .. py:method:: rate_trial()

      Record a rating for a trial.

   .. py:method:: get_rating()

      Get existing rating for a trial.

   .. py:method:: get_all_ratings()

      Get all ratings, optionally filtered by run.

   .. py:method:: export_csv()

      Export ratings to CSV file.

   .. py:method:: export_json()

      Export ratings to JSON file.

   .. py:method:: get_summary()

      Get summary of current session ratings.

   .. py:method:: clear_session()

      Clear current session records.


Functions
---------

.. py:function:: label()

   Human-readable label.

.. py:function:: from_string()

   Create Rating from string label.

.. py:function:: to_dict()

   Convert to dictionary for serialization.

.. py:function:: from_dict()

   Create from dictionary.

.. py:function:: set_reviewer()

   Set the current reviewer name.
   
   Args:
       name: Reviewer name/ID for attribution.

.. py:function:: start_session()

   Start a new review session.
   
   Args:
       run_name: Name of the optimization run being reviewed.
   
   Returns:
       Path to session file.

.. py:function:: rate_trial()

   Record a rating for a trial.
   
   Args:
       trial_id: Trial identifier (e.g., "trial_079").
       run_name: Name of the optimization run.
       rating: Quality rating.
       notes: Optional reviewer notes.
       metrics: Optional metrics to store with the rating.
   
   Returns:
       The created ReviewRecord.

.. py:function:: get_rating()

   Get existing rating for a trial.
   
   Args:
       trial_id: Trial identifier.
       run_name: Run name.
   
   Returns:
       ReviewRecord if found, None otherwise.

.. py:function:: get_all_ratings()

   Get all ratings, optionally filtered by run.
   
   Args:
       run_name: Optional run name to filter by.
   
   Returns:
       List of ReviewRecords.

.. py:function:: export_csv()

   Export ratings to CSV file.
   
   Args:
       output_path: Path for CSV file.
   
   Returns:
       Path to created CSV.

.. py:function:: export_json()

   Export ratings to JSON file.
   
   Args:
       output_path: Path for JSON file.
   
   Returns:
       Path to created JSON.

.. py:function:: get_summary()

   Get summary of current session ratings.

.. py:function:: clear_session()

   Clear current session records.