1  import json
  2  from functools import cached_property
  3  
  4  from mlflow.entities._mlflow_object import _MlflowObject
  5  from mlflow.protos.service_pb2 import Scorer as ProtoScorer
  6  
  7  
  8  class ScorerVersion(_MlflowObject):
  9      """
 10      A versioned scorer entity that represents a specific version of a scorer within an MLflow
 11      experiment.
 12  
 13      Each ScorerVersion instance is uniquely identified by the combination of:
 14      - experiment_id: The experiment containing the scorer
 15      - scorer_name: The name of the scorer
 16      - scorer_version: The version number of the scorer
 17  
 18      The class provides access to both the metadata (name, version, creation time) and the actual
 19      scorer implementation through the serialized_scorer property, which deserializes the stored
 20      scorer data into a usable SerializedScorer object.
 21  
 22      Args:
 23          experiment_id (str): The ID of the experiment this scorer belongs to.
 24          scorer_name (str): The name identifier for the scorer.
 25          scorer_version (int): The version number of this scorer instance.
 26          serialized_scorer (str): JSON-serialized string containing the scorer's metadata and code.
 27          creation_time (int): Unix timestamp (in milliseconds) when this version was created.
 28          scorer_id (str, optional): The unique identifier for the scorer.
 29  
 30      Example:
 31          .. code-block:: python
 32  
 33              from mlflow.entities.scorer import ScorerVersion
 34  
 35              # Create a ScorerVersion instance
 36              scorer_version = ScorerVersion(
 37                  experiment_id="123",
 38                  scorer_name="accuracy_scorer",
 39                  scorer_version=2,
 40                  serialized_scorer='{"name": "accuracy_scorer", "call_source": "..."}',
 41                  creation_time=1640995200000,
 42              )
 43  
 44              # Access scorer metadata
 45              print(f"Scorer: {scorer_version.scorer_name} v{scorer_version.scorer_version}")
 46              print(f"Created: {scorer_version.creation_time}")
 47      """
 48  
 49      def __init__(
 50          self,
 51          experiment_id: str,
 52          scorer_name: str,
 53          scorer_version: int,
 54          serialized_scorer: str,
 55          creation_time: int,
 56          scorer_id: str | None = None,
 57      ):
 58          self._experiment_id = experiment_id
 59          self._scorer_name = scorer_name
 60          self._scorer_version = scorer_version
 61          self._serialized_scorer = serialized_scorer
 62          self._creation_time = creation_time
 63          self._scorer_id = scorer_id
 64  
 65      @property
 66      def experiment_id(self):
 67          """
 68          The ID of the experiment this scorer belongs to.
 69  
 70          Returns:
 71              str: The id of the experiment that this scorer version belongs to.
 72          """
 73          return self._experiment_id
 74  
 75      @property
 76      def scorer_name(self):
 77          """
 78          The name identifier for the scorer.
 79  
 80          Returns:
 81              str: The human-readable name used to identify and reference this scorer.
 82          """
 83          return self._scorer_name
 84  
 85      @property
 86      def scorer_version(self):
 87          """
 88          The version number of this scorer instance.
 89  
 90          Returns:
 91              int: The sequential version number, starting from 1. Higher versions represent
 92                   newer saved scorers with the same name.
 93          """
 94          return self._scorer_version
 95  
 96      @cached_property
 97      def serialized_scorer(self):
 98          """
 99          The deserialized scorer object containing metadata and function code.
100  
101          This property automatically deserializes the stored JSON string into a
102          SerializedScorer object that contains all the information needed to
103          reconstruct and execute the scorer function.
104  
105          The result is cached to avoid repeated deserialization
106          when the same ScorerVersion instance is accessed multiple times.
107  
108          Returns:
109              SerializedScorer: A `SerializedScorer` object with metadata, function code,
110                                and configuration information.
111  
112          Note:
113              The `SerializedScorer` object construction is lazy,
114              it only happens when this property is first accessed.
115          """
116          from mlflow.genai.scorers.base import SerializedScorer
117  
118          return SerializedScorer(**json.loads(self._serialized_scorer))
119  
120      @property
121      def creation_time(self):
122          """
123          The timestamp when this scorer version was created.
124  
125          Returns:
126              int: Unix timestamp in milliseconds representing when this specific
127                   version of the scorer was registered in MLflow.
128          """
129          return self._creation_time
130  
131      @property
132      def scorer_id(self):
133          """
134          The unique identifier for the scorer.
135  
136          Returns:
137              str: The unique identifier (UUID) for the scorer, or None if not available.
138          """
139          return self._scorer_id
140  
141      @classmethod
142      def from_proto(cls, proto):
143          """
144          Create a ScorerVersion instance from a protobuf message.
145  
146          This class method is used internally by MLflow to reconstruct ScorerVersion
147          objects from serialized protobuf data, typically when retrieving scorers
148          from remote tracking servers or deserializing stored data.
149  
150          Args:
151              proto: A protobuf message containing scorer version data.
152  
153          Returns:
154              ScorerVersion: A new ScorerVersion instance populated with data from the protobuf.
155  
156          Note:
157              This method is primarily used internally by MLflow's tracking infrastructure
158              and should not typically be called directly by users.
159          """
160          return cls(
161              experiment_id=proto.experiment_id,
162              scorer_name=proto.scorer_name,
163              scorer_version=proto.scorer_version,
164              serialized_scorer=proto.serialized_scorer,
165              creation_time=proto.creation_time,
166              scorer_id=proto.scorer_id if proto.HasField("scorer_id") else None,
167          )
168  
169      def to_proto(self):
170          """
171          Convert this ScorerVersion instance to a protobuf message.
172  
173          This method serializes the ScorerVersion data into a protobuf format
174          for transmission over the network or storage in binary format. It's
175          primarily used internally by MLflow's tracking infrastructure.
176  
177          Returns:
178              ProtoScorer: A protobuf message containing the serialized scorer version data.
179  
180          Note:
181              This method is primarily used internally by MLflow's tracking infrastructure
182              and should not typically be called directly by users.
183          """
184          proto = ProtoScorer()
185          proto.experiment_id = int(self.experiment_id)
186          proto.scorer_name = self.scorer_name
187          proto.scorer_version = self.scorer_version
188          proto.serialized_scorer = self._serialized_scorer
189          proto.creation_time = self.creation_time
190          if self.scorer_id is not None:
191              proto.scorer_id = self.scorer_id
192          return proto
193  
194      def __repr__(self):
195          """
196          Return a string representation of the ScorerVersion instance.
197  
198          Returns:
199              str: A human-readable string showing the key identifying information
200                   of this scorer version (experiment_id, scorer_name, and scorer_version).
201          """
202          return (
203              f"<ScorerVersion(experiment_id={self.experiment_id}, "
204              f"scorer_name='{self.scorer_name}', "
205              f"scorer_version={self.scorer_version})>"
206          )