[CORE] Add TypeConverter system for runtime type validation/conversion

[junrushao]

Summary

• Add a TypeConverter system to the Cython FFI module that takes a TypeSchema and returns a tvm_ffi.Function wrapping a C++ conversion function (Any) -> Any
• The converter validates/converts input values to match the target type, with fast-path (zero-copy) for containers when elements already match and slow-path (element-by-element conversion) otherwise
• Detailed TypeError messages are provided on type mismatch (e.g., "expected int, got float", "expected list[int], but element at index 2 has type float")

New Files

• python/tvm_ffi/cython/tvm_ffi_type_converter.h — C++ header implementing TVMFFIPyTypeConverterNode tree with CheckStrict (zero-copy eligibility) and Convert methods for all supported kinds
• python/tvm_ffi/cython/type_converter.pxi — Cython bridge mapping TypeSchema origins to C++ converter nodes, exposes create_type_converter(schema)
• tests/python/test_type_converter.py — 34 comprehensive tests covering POD types, strings/bytes, special types, Optional, Union, container fast/slow paths, tuples, nested containers, object hierarchy, and error messages

Supported Type Kinds

Kind	CheckStrict	Convert (also accepts)
int	kTVMFFIInt	+ bool (coerce)
float	kTVMFFIFloat	+ int, bool (coerce)
bool	kTVMFFIBool	strict only
str	kTVMFFIStr/SmallStr	same
bytes	kTVMFFIBytes/SmallBytes	same
Tensor	kTVMFFITensor	+ DLTensorPtr
Object	type hierarchy check	same
Optional	None or child	same
Union	any child strict	try each child
list	Array + all elems strict	slow-path: new Array
dict	Map + all k/v strict	slow-path: new Map
tuple	Array + size + per-elem	slow-path: new Array

Test plan

• uv run pytest tests/python/test_type_converter.py -v — 34/34 pass
• uv run pytest tests/python/ -v — 425 passed, 0 failures (no regressions)

🤖 Generated with Claude Code

[gemini-code-assist]

Summary of Changes

Hello @junrushao, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the TVM FFI system by introducing robust runtime type checking and dynamic type conversion capabilities. It provides a TypeSchema to define FFI types programmatically and a TypeChecker to efficiently validate and convert values against these schemas. This new functionality allows for more flexible and dynamic interactions with the FFI, aligning runtime behavior with existing compile-time type mechanisms and supporting a comprehensive set of data types and container structures.

Highlights

• Runtime Type Schema: Introduced a TypeSchema struct for describing FFI types at runtime using a recursive {origin, args} structure, with JSON parsing and human-readable representation capabilities.
• Dynamic Type Checker: Added a TypeChecker class that provides efficient, pre-compiled runtime type checking and conversion, serving as the dynamic equivalent of compile-time TypeTraits.
• Comprehensive Type Support: Enabled support for a wide range of FFI types, including POD (int, float, bool, None), String, Bytes, DataType, Device, Object hierarchy, Optional, Array, List, Map, Variant, Tuple, and Callable.
• Optimized Container Conversion: Implemented container conversion logic that utilizes both fast-path (zero-copy for strict matches) and slow-path (element-by-element conversion) mechanisms, similar to compile-time TypeTraits.
• Small String/Bytes Handling: Ensured transparent handling of small string and bytes optimizations during Object type checks for accurate type resolution.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

• CMakeLists.txt
  • Added src/ffi/extra/type_checker.cc to the _tvm_ffi_extra_objs_sources list for compilation.
• include/tvm/ffi/extra/type_checker.h
  • Defined TypeSchema struct for runtime FFI type representation, including FromJSON, FromJSONStr, and Repr methods.
  • Defined TypeChecker class for pre-compiled type checking and conversion, with TryCast, Cast, and CheckStrict methods.
  • Included an internal Kind enum for efficient type dispatch.
• src/ffi/extra/type_checker.cc
  • Implemented the TypeSchema methods for JSON parsing and human-readable representation.
  • Implemented the TypeChecker's constructor, ResolveKind static method, CheckStrict, TryCast, and Cast methods, covering all supported FFI types and conversion logic.
  • Included helper function IsObjectInstanceRuntime for object hierarchy checks.
• tests/cpp/extra/test_type_checker.cc
  • Added extensive unit tests for TypeSchema JSON parsing and Repr functionality.
  • Included comprehensive tests for TypeChecker's CheckStrict and TryCast methods across POD types, String, Bytes, Optional, Array (typed, untyped, conversion, failure), Map, Variant, Object hierarchy, Callable, Tuple, and nested types.
  • Verified Cast method's throwing behavior on type mismatch and success on valid conversion.

Activity

• All 319 existing tests passed.
• 40 new tests were added for TypeChecker and TypeSchema, covering various FFI types and conversion scenarios.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a powerful and well-designed TypeSchema and TypeChecker for runtime type checking and conversion in the FFI layer. The approach of pre-compiling schemas into an efficient representation with a Kind enum is a great optimization. The implementation is comprehensive, covering a wide range of FFI types and their conversion semantics, including container conversions with fast-paths. The test suite is also extensive, providing good coverage for the new functionality. I have a couple of suggestions to improve robustness and code clarity, but overall this is a solid contribution.

[junrushao]

Addressed Gemini's review comments:

1. Arity validation in constructor (high): Added argument count validation in the TypeChecker constructor for generic kinds:

   • Optional: requires exactly 1 type argument
   • Array/List: requires 0 or 1 type arguments
   • Map: requires 0 or 2 type arguments

   Malformed schemas now fail early with a clear error message via TVM_FFI_ICHECK.

2. Simplified DLTensorPtr logic (medium): Removed the redundant inner if (ti == TypeIndex::kTVMFFITensor) branch since both paths returned Any(src). The simplified code just checks src.try_cast<DLTensor*>() and returns Any(src) on success.