fix: resolve \$defs/\$ref in tool schemas for HuggingFace API

[Br1an67]

Related Issues

• fixes HuggingFace API does not support $defs field in tool parameter schema #9387

Proposed Changes:

The HuggingFace API does not support $defs and $ref in tool parameter schemas. When tools have complex/dataclass parameters (e.g. ChatMessage, Document), Pydantic's model_json_schema() generates schemas with $defs section and $ref references, which causes failures with the HF API.

Added _resolve_schema_refs() to hugging_face_api.py that:

1. Extracts $defs definitions from the schema
2. Recursively resolves all $ref pointers by inlining the definitions
3. Removes the $defs section from the final schema
4. Handles circular references by tracking resolution depth

This function is called in _convert_tools_to_hfapi_tools() before passing tool parameters to the HF API, following the same pattern used in the Google GenAI integration (PR haystack-core-integrations#1875).

No external dependencies are needed — the resolver is a pure Python implementation, avoiding the need to make jsonref a core dependency.

How did you test it?

Added 4 unit tests:

• test_resolve_schema_refs_no_defs — schema without $defs passes through unchanged
• test_resolve_schema_refs_expands_defs — basic $defs/$ref expansion
• test_resolve_schema_refs_nested_refs — nested $ref within $defs definitions
• test_convert_tools_to_hfapi_tools_resolves_defs — end-to-end test through the tool conversion pipeline

All 43 existing non-async tests continue to pass.

Notes for the reviewer

• The approach matches what was suggested in the issue by @sjrl and @vblagoje
• Unlike the Google GenAI integration which uses jsonref.replace_refs(), this uses an inline implementation to avoid adding jsonref as a core dependency (it's currently only an optional dep for OpenAPI components)

Checklist

• I have read the contributors guidelines and the code of conduct.
• I have updated the related issue with new insights and changes.
• I have added unit tests and updated the docstrings.
• I've used one of the conventional commit types for my PR title: fix:, feat:, build:, chore:, ci:, docs:, style:, refactor:, perf:, test: and added ! in case the PR includes breaking changes.
• I have documented my code.
• I have added a release note file, following the contributors guidelines.
• I have run pre-commit hooks and fixed any issue.

[vercel]

@Br1an67 is attempting to deploy a commit to the deepset Team on Vercel.

A member of the Team first needs to authorize it.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
haystack-docs	Ready	Preview, Comment	Mar 5, 2026 3:56pm

[bogdankostic]

Hi @Br1an67, this PR looks in principle good, but some checks are still failing. I recommend going through out contributing guidelines to fix them.