feat(function_schema): add enforce_type_annotations flag for stricter schema validation with type enforcement, clearer errors, and updated docstrings

[mshsheikh]

Problem:
Previously, the function_schema function silently defaulted unannotated parameters to Any, leading to:

• Ambiguous JSON schemas ("type": "any")
• Potential runtime errors due to invalid inputs
• Reduced reliability of LLM tool calls This made it harder to ensure type safety without manual validation.

Solution:

This PR introduces the enforce_type_annotations flag to function_schema, allowing developers to:

1. Enforce type annotations by setting enforce_type_annotations=True, which raises a ValueError for unannotated parameters.
2. Maintain backward compatibility by defaulting to Any when enforce_type_annotations=False (default).

Example error message:

raise ValueError(
    f"Parameter '{name}' must be type-annotated. Example: def func({name}: str)"
)

Changes Made

1. New Parameter:

   def function_schema(
       func: Callable[..., Any],
       enforce_type_annotations: bool = False,  # New parameter
       ...
   ):

2. Validation Logic:

• If enforce_type_annotations=True, unannotated parameters now raise a ValueError with a clear example.
• Falls back to Any if disabled (default behavior preserved).

3. Docstring Updates:

• Added detailed documentation for enforce_type_annotations:

     Args:
         enforce_type_annotations: If True, raises a ValueError for any unannotated parameters.
             If False (default), unannotated parameters are assumed to be of type `Any`.

4. Error Message Improvements:

• Clear guidance for developers: Example: def func(x: str)

Backward Compatibility:

• Preserved: Existing code continues to work as-is (default enforce_type_annotations=False).
• Opt-in: Type annotation enforcement is optional, allowing gradual adoption.

Testing Guidance:
To verify the change:

def test_enforce_type_annotations():
    def func(x): ...
    with pytest.raises(ValueError):
        function_schema(func, enforce_type_annotations=True)
    # Should not raise
    function_schema(func, enforce_type_annotations=False)

Impact:

• Type Safety: Prevents ambiguous schemas and improves LLM tool reliability.
• Developer Experience: Clear error messages guide users to fix missing annotations.
• Flexibility: Maintains backward compatibility while enabling stricter validation.

Example Usage:

# Strict mode: raises error for unannotated params
schema = function_schema(my_func, enforce_type_annotations=True)

# Default mode: works as before
schema = function_schema(my_func)  # silently defaults to Any

[seratch]

having unit tests would be appreciated too

[seratch]

adding this option may be a good one, but adding here (=2nd arg) is a breaking change. new arguments must be added as the last one when a method accepts both args and keyword args.