From 568e73984d522237ccd2cd1d26eb529c407c9340 Mon Sep 17 00:00:00 2001 From: "sweep-ai[bot]" <128439645+sweep-ai[bot]@users.noreply.github.com> Date: Fri, 22 Dec 2023 06:18:06 +0000 Subject: [PATCH] feat: Updated dspy/primitives/assertions.py --- dspy/primitives/assertions.py | 121 ++++++++++++++++++++++++---------- 1 file changed, 87 insertions(+), 34 deletions(-) diff --git a/dspy/primitives/assertions.py b/dspy/primitives/assertions.py index 1bb42429b..b1f40a743 100644 --- a/dspy/primitives/assertions.py +++ b/dspy/primitives/assertions.py @@ -45,16 +45,26 @@ def _build_error_msg(feedback_msgs): class DSPyAssertionError(AssertionError): - """Custom exception raised when a DSPy `Assert` fails.""" + """An exception raised specifically by DSPy when an assertion fails. + + This exception is raised when a condition checked by an `Assert` object is determined to be false and + bypassing assertions has not been enabled in the DSPy settings. + + Attributes: + id (str): The unique identifier of the failed assertion. + msg (str): A message that describes the reason for the assertion failure. + state (Any): The state of the system at the time of the assertion failure. + + """ def __init__(self, id: str, msg: str, state: Any = None) -> None: """ - Initialize a new instance of the DSPyAssertionError class. + Create a new instance of the DSPyAssertionError exception. Args: - id (str): The ID of the assertion. - msg (str): The error message. - state (Any): The state of the assertion. + id (str): The ID of the failed assertion. + msg (str): The error message describing the assertion failure. + state (Any, optional): The state of the system when the assertion failed. Defaults to None. """ super().__init__(msg) self.id = id @@ -63,19 +73,30 @@ def __init__(self, id: str, msg: str, state: Any = None) -> None: class DSPySuggestionError(AssertionError): - """Custom exception raised when a DSPy `Suggest` fails.""" + """An exception raised specifically by DSPy when a suggestion outcome is rejected. + + This exception is thrown when a condition checked by a `Suggest` object does not meet the desired criteria and + the suggestion is not being bypassed in the DSPy settings. + + Attributes: + id (str): The unique identifier of the failed suggestion. + msg (str): A message that describes the reason for the suggestion rejection. + target_module (Any): The module associated with the suggestion. + state (Any): The state of the system at the time of the suggestion evaluation. + + """ def __init__( self, id: str, msg: str, target_module: Any = None, state: Any = None ) -> None: """ - Initialize a new instance of the DSPySuggestionError class. + Create a new instance of the DSPySuggestionError exception. Args: - id (str): The ID of the suggestion. - msg (str): The error message. - target_module (Any): The target module of the suggestion. - state (Any): The state of the suggestion. + id (str): The ID of the rejected suggestion. + msg (str): The error message describing the cause for the suggestion rejection. + target_module (Any, optional): The module associated with the suggestion. Defaults to None. + state (Any, optional): The state of the system at the suggestion evaluation time. Defaults to None. """ super().__init__(msg) self.id = id @@ -88,7 +109,30 @@ def __init__( class Constraint: + """Represents a constraint that can be asserted or suggested within the DSPy framework. + + A Constraint is a condition that is intended to be checked during the execution of DSPy workflows. It can + be used to assert conditions (with `Assert`) or make suggestions (with `Suggest`) of how a workflow or + module should behave. + + Attributes: + id (str): A unique identifier for the constraint. + result (bool): The result of evaluating the constraint condition (True or False). + msg (str, optional): An optional message providing details about the condition being checked. Defaults to an empty string. + target_module (Any, optional): An optional reference to the module associated with the constraint. Defaults to None. + + """ + def __init__(self, result: bool, msg: str = "", target_module=None): + """ + Initializes a new Constraint object. + + Args: + result (bool): The outcome of the constraint check (True if the condition is met, False otherwise). + msg (str, optional): A descriptive message about the constraint condition. Defaults to an empty string. + target_module (Any, optional): The module that this constraint is associated with, if applicable. Defaults to None. + + """ self.id = str(uuid.uuid4()) self.result = result self.msg = msg @@ -98,21 +142,26 @@ def __init__(self, result: bool, msg: str = "", target_module=None): class Assert(Constraint): - """DSPy Assertion""" + """Implements an assert mechanism within the DSPy framework. + + An `Assert` is a type of `Constraint` used to enforce certain conditions that must be met during the DSPy workflows. + If the condition is not met and assertions are not being bypassed, this will raise an `DSPyAssertionError`. + + """ def __call__(self) -> bool: """ - Call the Assert instance. + Evaluates the assertion and determines if the condition is met. - If the result is True, return True. If the result is False and bypass_assert is set in the settings, log an error and return True. - If the result is False and bypass_assert is not set in the settings, log an error and raise a DSPyAssertionError. + If the result of the constraint is True, it means the assertion condition is met. If the result is False, depends on the DSPy settings, + it may either log an error and return True (if assertions are being bypassed) or raise a `DSPyAssertionError` (if assertions are not bypassed). Raises: - ValueError: If the result is not a boolean. - DSPyAssertionError: If the result is False and bypass_assert is not set in the settings. + ValueError: If the result of the constraint is not a boolean value. + DSPyAssertionError: If the result is False and assertions are supposed to be enforced according to the settings. Returns: - bool: The result of the assertion. + bool: True if the assertion condition is met, False if it is not met but assertions are being bypassed. """ if isinstance(self.result, bool): if self.result: @@ -130,24 +179,28 @@ def __call__(self) -> bool: class Suggest(Constraint): - """DSPy Suggestion""" + """Implements a suggestion mechanism within the DSPy framework. + + A `Suggest` is a type of `Constraint` used to propose preferable conditions which are not strictly mandatory within the DSPy workflows. + If the condition is not met, depending on DSPy settings, it may either log the failure and return True (if suggestions are being bypassed), or + raise a `DSPySuggestionError` if suggestions are enforced and not followed. + + """ def __call__(self) -> Any: - if isinstance(self.result, bool): - if self.result: - return True - elif dspy.settings.bypass_suggest: - logger.error(f"SuggestionFailed: {self.msg}") - return True - else: - logger.error(f"SuggestionFailed: {self.msg}") - raise DSPySuggestionError( - id=self.id, - msg=self.msg, - target_module=self.target_module, - state=dsp.settings.trace, - ) - else: + """ + Evaluates the suggestion and determines if the preferable condition is met. + + If the result of the constraint is True, it means the suggestion condition is met. If it is False, depends on the DSPy settings, + it may either log an error and return True (if suggestions are being bypassed) or raise a `DSPySuggestionError` (if suggestions are intended to be enforced). + + Raises: + ValueError: If the result of the constraint is not a boolean value. + DSPySuggestionError: If the result is False and suggestions are not meant to be bypassed. + + Returns: + Any: True if the suggestion condition is met, False if it is not met but suggestions are being bypassed. + """ raise ValueError("Suggestion function should always return [bool]")