feat: improve structured output tool circular reference handling

[afarntrog]

Description

This pull request improves the handling of circular references and optional fields in Pydantic model schema conversion. The main changes add error detection for circular references, update the logic for determining optional fields, and enhance test coverage for these scenarios.

Schema Conversion and Circular Reference Handling:

• Added explicit detection and error raising for circular references in the _flatten_schema function

Optional Field Logic:

• Updated the logic in _expand_nested_properties to use field.is_required() for determining if a field is optional, replacing the previous manual inspection of type annotations.

Test Coverage Enhancements:

• Added new tests in test_structured_output.py to verify that circular references (both required and optional) raise the appropriate errors, and that fields with default values are correctly marked as optional.
• Improved existing tests

Related Issues

#695

Type of Change

Bug fix

Testing

How have you tested the change? Verify that the changes do not break functionality or introduce warnings in consuming repositories: agents-docs, agents-tools, agents-cli

• I ran hatch run prepare

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[afarntrog]

Note: the test_structured_output_multi_modal_input integ test is failing for litellm v1.76.3. as Patrick mentioned in the chat. I tested against the local code and it works fine for v1.76.2 👍