Rail XML: Rename "format" attr to "validators"

Author: irgolic

guardrails/datatypes.py

@@ -16,7 +16,7 @@
 from guardrails.validator_base import Validator
 
 if TYPE_CHECKING:
-    from guardrails.schema import FormatAttr
+    from guardrails.schema import ValidatorsAttr
 
 logger = logging.getLogger(__name__)
 
@@ -64,20 +64,20 @@ class DataType:
     def __init__(
         self,
         children: Dict[str, Any],
-        format_attr: "FormatAttr",
+        validators_attr: "ValidatorsAttr",
         optional: bool,
         name: Optional[str],
         description: Optional[str],
     ) -> None:
         self._children = children
-        self.format_attr = format_attr
+        self.validators_attr = validators_attr
         self.name = name
         self.description = description
         self.optional = optional
 
     @property
     def validators(self) -> TypedList:
-        return self.format_attr.validators
+        return self.validators_attr.validators
 
     def __repr__(self) -> str:
         return f"{self.__class__.__name__}({self._children})"
@@ -120,12 +120,12 @@ def set_children_from_xml(self, element: ET._Element):
 
     @classmethod
     def from_xml(cls, element: ET._Element, strict: bool = False, **kwargs) -> Self:
-        from guardrails.schema import FormatAttr
+        from guardrails.schema import ValidatorsAttr
 
         # TODO: don't want to pass strict through to DataType,
-        # but need to pass it to FormatAttr.from_element
+        # but need to pass it to ValidatorsAttr.from_element
         # how to handle this?
-        format_attr = FormatAttr.from_element(element, cls.tag, strict)
+        validators_attr = ValidatorsAttr.from_element(element, cls.tag, strict)
 
         is_optional = element.attrib.get("required", "true") == "false"
 
@@ -137,7 +137,7 @@ def from_xml(cls, element: ET._Element, strict: bool = False, **kwargs) -> Self:
         if description is not None:
             description = cast_xml_to_string(description)
 
-        data_type = cls({}, format_attr, is_optional, name, description, **kwargs)
+        data_type = cls({}, validators_attr, is_optional, name, description, **kwargs)
         data_type.set_children_from_xml(element)
         return data_type
 
@@ -255,12 +255,12 @@ class Date(ScalarType):
     def __init__(
         self,
         children: Dict[str, Any],
-        format_attr: "FormatAttr",
+        validators_attr: "ValidatorsAttr",
         optional: bool,
         name: Optional[str],
         description: Optional[str],
     ) -> None:
-        super().__init__(children, format_attr, optional, name, description)
+        super().__init__(children, validators_attr, optional, name, description)
         self.date_format = None
 
     def from_str(self, s: str) -> Optional[datetime.date]:
@@ -294,13 +294,13 @@ class Time(ScalarType):
     def __init__(
         self,
         children: Dict[str, Any],
-        format_attr: "FormatAttr",
+        validators_attr: "ValidatorsAttr",
         optional: bool,
         name: Optional[str],
         description: Optional[str],
     ) -> None:
         self.time_format = "%H:%M:%S"
-        super().__init__(children, format_attr, optional, name, description)
+        super().__init__(children, validators_attr, optional, name, description)
 
     def from_str(self, s: str) -> Optional[datetime.time]:
         """Create a Time from a string."""
@@ -458,13 +458,13 @@ class Choice(NonScalarType):
     def __init__(
         self,
         children: Dict[str, Any],
-        format_attr: "FormatAttr",
+        validators_attr: "ValidatorsAttr",
         optional: bool,
         name: Optional[str],
         description: Optional[str],
         discriminator_key: str,
     ) -> None:
-        super().__init__(children, format_attr, optional, name, description)
+        super().__init__(children, validators_attr, optional, name, description)
         self.discriminator_key = discriminator_key
 
     @classmethod
@@ -520,12 +520,12 @@ class Case(NonScalarType):
     def __init__(
         self,
         children: Dict[str, Any],
-        format_attr: "FormatAttr",
+        validators_attr: "ValidatorsAttr",
         optional: bool,
         name: Optional[str],
         description: Optional[str],
     ) -> None:
-        super().__init__(children, format_attr, optional, name, description)
+        super().__init__(children, validators_attr, optional, name, description)
 
     def collect_validation(
         self,

guardrails/schema.py

@@ -49,10 +49,11 @@
 logger = logging.getLogger(__name__)
 
 
-class FormatAttr(pydantic.BaseModel):
-    """Class for parsing and manipulating the `format` attribute of an element.
+class ValidatorsAttr(pydantic.BaseModel):
+    """Class for parsing and manipulating the `validators` attribute of an
+    element.
 
-    The format attribute is a string that contains semi-colon separated
+    The validators attribute is a string that contains semi-colon separated
     validators e.g. "valid-url; is-reachable". Each validator is itself either:
     - the name of an parameter-less validator, e.g. "valid-url"
     - the name of a validator with parameters, separated by a colon with a
@@ -68,8 +69,8 @@ class FormatAttr(pydantic.BaseModel):
     class Config:
         arbitrary_types_allowed = True
 
-    # The format attribute string.
-    format: Optional[str]
+    # The validators attribute string.
+    validators_spec: Optional[str]
 
     # The on-fail handlers.
     on_fail_handlers: Dict[str, str]
@@ -85,32 +86,40 @@ class Config:
 
     @property
     def empty(self) -> bool:
-        """Return True if the format attribute is empty, False otherwise."""
-        return self.format is None
+        """Return True if the validators attribute is empty, False
+        otherwise."""
+        return self.validators_spec is None
 
     @classmethod
     def from_element(
         cls, element: ET._Element, tag: str, strict: bool = False
-    ) -> "FormatAttr":
-        """Create a FormatAttr object from an XML element.
+    ) -> "ValidatorsAttr":
+        """Create a ValidatorsAttr object from an XML element.
 
         Args:
             element (ET._Element): The XML element.
 
         Returns:
-            A FormatAttr object.
+            A ValidatorsAttr object.
         """
+        validators_str = element.get("validators")
         format_str = element.get("format")
-        if format_str is None:
+        if format_str is not None:
+            warnings.warn(
+                "Attribute `format` is deprecated. Use `validators` instead.",
+                DeprecationWarning,
+            )
+            validators_str = format_str
+        if validators_str is None:
             return cls(
-                format=None,
+                validators_spec=None,
                 on_fail_handlers={},
                 validator_args={},
                 validators=[],
                 unregistered_validators=[],
             )
 
-        validator_args = cls.parse(format_str)
+        validator_args = cls.parse(validators_str)
 
         on_fail_handlers = {}
         for key, value in element.attrib.items():
@@ -128,7 +137,7 @@ def from_element(
         )
 
         return cls(
-            format=format_str,
+            validators_spec=validators_str,
             on_fail_handlers=on_fail_handlers,
             validator_args=validator_args,
             validators=validators,
@@ -196,7 +205,7 @@ def parse(format_string: str) -> Dict[str, List[Any]]:
         validators = {}
         for token in tokens:
             # Parse the token into a validator name and a list of parameters.
-            validator_name, args = FormatAttr.parse_token(token)
+            validator_name, args = ValidatorsAttr.parse_token(token)
             validators[validator_name] = args
 
         return validators
@@ -268,7 +277,7 @@ def to_prompt(self, with_keywords: bool = True) -> str:
         {1 + 2}" will be converted to "valid-url other-validator:
         arg1=1.0 arg2=3".
         """
-        if self.format is None:
+        if self.validators_spec is None:
             return ""
         # Use the validators' to_prompt method to convert the format string to
         # another string representation.
@@ -953,11 +962,11 @@ def transpile(self, method: str = "default") -> str:
                 "Here's a description of what I want you to generate: "
                 f"{obj.description}"
             )
-        if not obj.format_attr.empty:
+        if not obj.validators_attr.empty:
             schema += (
                 "\n\nYour generated response should satisfy the following properties:"
             )
-            for validator in obj.format_attr.validators:
+            for validator in obj.validators_attr.validators:
                 schema += f"\n- {validator.to_prompt()}"
 
         schema += "\n\nDon't talk; just go."
@@ -991,8 +1000,8 @@ def datatypes_to_xml(
         if dt.description:
             el.attrib["description"] = dt.description
 
-        if dt.format_attr:
-            format_prompt = dt.format_attr.to_prompt()
+        if dt.validators_attr:
+            format_prompt = dt.validators_attr.to_prompt()
             if format_prompt:
                 el.attrib["format"] = format_prompt
 

guardrails/utils/pydantic_utils.py

@@ -195,7 +195,7 @@ def add_validators_to_xml_element(
     # construct a valid-choices validator for Literal types
     if typing.get_origin(field_info.annotation) is typing.Literal:
         valid_choices = typing.get_args(field_info.annotation)
-        element.set("format", "valid-choices")
+        element.set("validators", "valid-choices")
         element.set("valid-choices", ",".join(valid_choices))
 
     return element
@@ -249,7 +249,7 @@ def attach_validators_to_element(
 
     if len(format_prompt) > 0:
         format_prompt = "; ".join(format_prompt)
-        element.set("format", format_prompt)
+        element.set("validators", format_prompt)
         for rail_alias, on_fail in on_fails.items():
             element.set("on-fail-" + rail_alias, on_fail)
 

tests/integration_tests/test_async.py

@@ -231,7 +231,7 @@ def string_rail_spec():
 <rail version="0.1">
 <output
   type="string"
-  format="two-words"
+  validators="two-words"
   on-fail-two-words="fix"
 />
 <prompt>

tests/integration_tests/test_cli.py

@@ -11,7 +11,7 @@
 <output>
     <object name="patient_info">
         <string name="gender" description="Patient's gender" />
-        <integer name="age" format="valid-range: 0 100" />
+        <integer name="age" validators="valid-range: 0 100" />
         <string name="symptoms" description="Symptoms that the patient is currently experiencing" />
     </object>
 </output>

tests/integration_tests/test_data_validation.py

@@ -33,11 +33,11 @@ def test_choice_validation(llm_output, raises):
 <output>
     <choice name="choice" on-fail-choice="exception" discriminator="action">
         <case name="fight">
-            <string name="fight_move" format="valid-choices: {['punch','kick','headbutt']}" on-fail-valid-choices="exception" />
+            <string name="fight_move" validators="valid-choices: {['punch','kick','headbutt']}" on-fail-valid-choices="exception" />
         </case>
         <case name="flight">
-            <string name="flight_direction" format="valid-choices: {['north','south','east','west']}" on-fail-valid-choices="exception" />
-            <integer name="flight_speed" format="valid-choices: {[1,2,3,4]}" on-fail-valid-choices="exception" />
+            <string name="flight_direction" validators="valid-choices: {['north','south','east','west']}" on-fail-valid-choices="exception" />
+            <integer name="flight_speed" validators="valid-choices: {[1,2,3,4]}" on-fail-valid-choices="exception" />
         </case>
     </choice>
 </output>

tests/integration_tests/test_schema_to_prompt.py

@@ -13,20 +13,20 @@ def test_choice_schema():
         <case name="fight">
             <string
                 name="fight_move"
-                format="valid-choices: {['punch','kick','headbutt']}"
+                validators="valid-choices: {['punch','kick','headbutt']}"
                 on-fail-valid-choices="exception"
             />
         </case>
         <case name="flight">
             <object name="flight">
                 <string
                     name="flight_direction"
-                    format="valid-choices: {['north','south','east','west']}"
+                    validators="valid-choices: {['north','south','east','west']}"
                     on-fail-valid-choices="exception"
                 />
                 <integer
                     name="flight_speed"
-                    format="valid-choices: {[1,2,3,4]}"
+                    validators="valid-choices: {[1,2,3,4]}"
                     on-fail-valid-choices="exception"
                 />
             </object>

tests/integration_tests/test_validators.py

@@ -42,7 +42,7 @@ def embed_function(text: str):
     # Check types remain intact
     output_schema: StringSchema = guard.rail.output_schema
     data_type: DataType = output_schema.root_datatype
-    validators = data_type.format_attr.validators
+    validators = data_type.validators_attr.validators
     validator: SimilarToList = validators[0]
 
     assert isinstance(validator._standard_deviations, int)

tests/unit_tests/test_datatypes.py

@@ -2,7 +2,7 @@
 from lxml.builder import E
 
 import guardrails.datatypes as datatypes
-from guardrails.schema import FormatAttr
+from guardrails.schema import ValidatorsAttr
 
 
 @pytest.mark.parametrize(
@@ -26,7 +26,7 @@
     ],
 )
 def test_get_args(input_string, expected):
-    _, args = FormatAttr.parse_token(input_string)
+    _, args = ValidatorsAttr.parse_token(input_string)
     assert args == expected
 
 

tests/unit_tests/test_guard.py

@@ -31,7 +31,7 @@ def validate(self, value, metadata):
             """
 <rail version="0.1">
 <output>
-    <string name="string_name" format="myrequiringvalidator" />
+    <string name="string_name" validators="myrequiringvalidator" />
 </output>
 </rail>
         """,
@@ -42,10 +42,10 @@ def validate(self, value, metadata):
 <rail version="0.1">
 <output>
     <object name="temp_name">
-        <string name="string_name" format="myrequiringvalidator" />
+        <string name="string_name" validators="myrequiringvalidator" />
     </object>
     <list name="list_name">
-        <string name="string_name" format="myrequiringvalidator2" />
+        <string name="string_name" validators="myrequiringvalidator2" />
     </list>
 </output>
 </rail>
@@ -63,7 +63,7 @@ def validate(self, value, metadata):
         <string name="string_name" />
     </case>
     <case name="hiya">
-        <string name="string_name" format="myrequiringvalidator" />
+        <string name="string_name" validators="myrequiringvalidator" />
     </case>
     </choice>
     </list>