fix(signatures): raise clear error for field names that shadow SignatureMeta properties

Declaring a Signature field whose name collides with a SignatureMeta
property (e.g. `instructions`, which is a class-level property on the
metaclass for reading/writing the docstring) crashed signature class
construction with an opaque internal error:

    class MySig(dspy.Signature):
        instructions: str = dspy.InputField()
        answer: str = dspy.OutputField()
    # TypeError: 'NoneType' object is not subscriptable

Pydantic detects the name collision (it emits its own "shadows an
attribute in parent" UserWarning) and, for that field only, produces a
plain FieldInfo with json_schema_extra=None instead of preserving the
InputField()/OutputField() instance from the class body. SignatureMeta
already has validation for exactly this shape of problem -
_validate_fields() raises a clear TypeError when a field's
json_schema_extra doesn't carry the expected __dspy_field_type key -
but it ran too late: SignatureMeta.__new__ computes default
instructions first when no docstring is given, via
_default_instructions(cls) -> cls.input_fields ->
_get_fields_with_type(), which indexes json_schema_extra directly and
crashes before _validate_fields() ever gets a chance to run.

Move the existing _validate_fields() call to run immediately after
Pydantic builds the class, before anything reads json_schema_extra.
No new validation logic - just correct ordering of what was already
there.

Fixes #1710.

Author: STiFLeR7

dspy/signatures/signature.py

@@ -184,6 +184,14 @@ def __new__(mcs, signature_name, bases, namespace, **kwargs):
         # Let Pydantic do its thing
         cls = super().__new__(mcs, signature_name, bases, namespace, **kwargs)
 
+        # Ensure all fields are declared with InputField or OutputField. This must run before
+        # any code below that reads `field.json_schema_extra` (e.g. via input_fields/output_fields),
+        # since a field whose name collides with a SignatureMeta property (e.g. `instructions`)
+        # gets a plain pydantic FieldInfo with json_schema_extra=None instead of the one from
+        # InputField()/OutputField() - which would otherwise surface as an opaque internal
+        # TypeError instead of this validation's clear message.
+        cls._validate_fields()
+
         # If we don't have instructions, it might be because we are a derived generic type.
         # In that case, we should inherit the instructions from the base class.
         if cls.__doc__ is None:
@@ -198,9 +206,6 @@ def __new__(mcs, signature_name, bases, namespace, **kwargs):
         if cls.__doc__ is None:
             cls.__doc__ = _default_instructions(cls)
 
-        # Ensure all fields are declared with InputField or OutputField
-        cls._validate_fields()
-
         # Ensure all fields have a prefix
         for name, field in cls.model_fields.items():
             if "prefix" not in field.json_schema_extra:

tests/signatures/test_signature.py

@@ -41,6 +41,21 @@ class TestSignature(Signature):
             input1: str = pydantic.Field()
 
 
+def test_field_name_shadowing_signaturemeta_property_raises_clear_error():
+    """
+    Regression test for https://github.com/stanfordnlp/dspy/issues/1710
+
+    A field name that collides with a SignatureMeta property (e.g. `instructions`) must raise
+    the existing `_validate_fields` TypeError, not crash with an opaque internal TypeError from
+    `_get_fields_with_type` deep inside `input_fields`/`output_fields`.
+    """
+    with pytest.raises(TypeError, match="must be declared with InputField or OutputField"):
+
+        class TestSignature(Signature):
+            instructions: str = InputField()
+            answer: str = OutputField()
+
+
 def test_all_fields_have_prefix():
     class TestSignature(Signature):
         input = InputField(prefix="Modified:")