docs: Add documentation for Assertions in dspy/ass

docs/primitives/assertions.md

@@ -0,0 +1,81 @@
+
+## Suggest
+The `Suggest` class is a type of `Constraint` that represents a suggestion in the DSPy framework. It takes a boolean result and an optional message as parameters. If the result is `False`, it raises a `DSPySuggestionError` unless `bypass_suggest` is set in the settings.
+
+Example usage:
+```python
+suggestion = Suggest(result=True, msg="This is a test suggestion")
+```
+
+## Constraint
+The `Constraint` class is a base class for `Assert` and `Suggest`. It takes a boolean result and an optional message as parameters.
+
+Example usage:
+```python
+constraint = Constraint(result=True, msg="This is a test constraint")
+```
+
+## noop_handler
+The `noop_handler` function is an assertion handler that bypasses both assertions and suggestions. It takes a function as a parameter and returns a wrapper function that bypasses assertions and suggestions when called.
+
+Example usage:
+```python
+@noop_handler
+def test_function():
+    pass
+```
+
+## bypass_suggest_handler
+The `bypass_suggest_handler` function is an assertion handler that bypasses suggestions only. It takes a function as a parameter and returns a wrapper function that bypasses suggestions when called.
+
+Example usage:
+```python
+@bypass_suggest_handler
+def test_function():
+    pass
+```
+
+## bypass_assert_handler
+The `bypass_assert_handler` function is an assertion handler that bypasses assertions only. It takes a function as a parameter and returns a wrapper function that bypasses assertions when called.
+
+Example usage:
+```python
+@bypass_assert_handler
+def test_function():
+    pass
+```
+
+## assert_no_except_handler
+The `assert_no_except_handler` function is an assertion handler that ignores assertion failures and returns `None`. It takes a function as a parameter and returns a wrapper function that ignores assertion failures when called.
+
+Example usage:
+```python
+@assert_no_except_handler
+def test_function():
+    pass
+```
+
+## suggest_backtrack_handler
+The `suggest_backtrack_handler` function is an assertion handler for backtracking suggestions. It takes a function, a boolean `bypass_suggest`, and an integer `max_backtracks` as parameters. It returns a wrapper function that re-runs the latest predictor up to `max_backtracks` times, with updated signature if a suggestion fails.
+
+Example usage:
+```python
+@suggest_backtrack_handler(bypass_suggest=True, max_backtracks=2)
+def test_function():
+    pass
+```
+
+## handle_assert_forward
+The `handle_assert_forward` function is used to handle assertions. It wraps the `forward` method of a module with an assertion handler. It takes an assertion handler and handler arguments as parameters.
+
+Example usage:
+```python
+forward = handle_assert_forward(assertion_handler, **handler_args)
+```
+
+## assert_transform_module
+The `assert_transform_module` function is used to transform a module to handle assertions. It replaces the `forward` method of the module with a version that handles assertions. It takes a module, an assertion handler, and handler arguments as parameters.
+
+Example usage:
+```python
+module = assert_transform_module(module, assertion_handler=default_assertion_handler, **handler_args)