clarify reference solution/gold patch terminology and validation strategy

Author: sid-rl

src/runloop_api_client/sdk/async_scenario_builder.py

@@ -343,9 +343,10 @@ def with_metadata(self, metadata: Dict[str, str]) -> Self:
         return self
 
     def with_reference_output(self, output: str) -> Self:
-        """Set the reference output/solution for validation.
+        """Set the reference solution or gold patch for validation.
+        After application, the scorer is expected to return a score of 1.0.
 
-        :param output: Reference output (e.g., git diff)
+        :param output: Reference solution or gold patch (e.g., git diff)
         :type output: str
         :return: Self for method chaining
         :rtype: Self
@@ -376,7 +377,7 @@ def with_required_secrets(self, secrets: List[str]) -> Self:
         return self
 
     def with_validation_type(self, validation_type: Literal["UNSPECIFIED", "FORWARD", "REVERSE", "EVALUATION"]) -> Self:
-        """Set the validation strategy.
+        """Set the validation strategy to specify how the reference solution or gold patch is applied to the scenario.
 
         :param validation_type: Validation type
         :type validation_type: Literal["UNSPECIFIED", "FORWARD", "REVERSE", "EVALUATION"]

src/runloop_api_client/sdk/scenario_builder.py

@@ -343,9 +343,10 @@ def with_metadata(self, metadata: Dict[str, str]) -> Self:
         return self
 
     def with_reference_output(self, output: str) -> Self:
-        """Set the reference output/solution for validation.
+        """Set the reference solution or gold patch for validation.
+        After application, the scorer is expected to return a score of 1.0.
 
-        :param output: Reference output (e.g., git diff)
+        :param output: Reference solution or gold patch (e.g., git diff)
         :type output: str
         :return: Self for method chaining
         :rtype: Self
@@ -376,7 +377,7 @@ def with_required_secrets(self, secrets: List[str]) -> Self:
         return self
 
     def with_validation_type(self, validation_type: Literal["UNSPECIFIED", "FORWARD", "REVERSE", "EVALUATION"]) -> Self:
-        """Set the validation strategy.
+        """Set the validation strategy to specify how the reference solution or gold patch is applied to the scenario.
 
         :param validation_type: Validation type
         :type validation_type: Literal["UNSPECIFIED", "FORWARD", "REVERSE", "EVALUATION"]