2.3.0

2.3.0

Starting with onnx2tf v2.4.0, tf_converter will be deprecated and the default backend will be switched to flatbuffer_direct.

1. Content and background

This PR introduces a complete SavedModel path for the direct LiteRT backend and aligns the CLI/runtime behavior with a no-fallback flatbuffer_direct policy.

Historically, SavedModel export behavior in direct-mode workflows depended on fallback/legacy conversion behavior. This branch makes SavedModel generation explicit and deterministic by using a dedicated ModelIR -> SavedModel exporter and by adding a TFLite -> ModelIR importer for direct TFLite input use cases.

The branch also adds machine-readable validation/reporting and a bulk verification runner to support large-scale model sweeps.

2. Summary of corrections

A. flatbuffer_direct SavedModel export

• Added a new exporter subsystem: onnx2tf/tflite_builder/saved_model_exporter.py.
• Exporter architecture:
  • tf.Module + @tf.function serving signature generation.
  • TensorSpec generation from shape_signature (-1 -> None) and TensorIR dtype mapping.
  • Graph execution via op-kernel dispatch over ModelIR operators.
  • Subgraph-aware execution and control-flow support (including WHILE).
• Added strict support gating:
  • Fail-fast on unsupported op types.
  • Explicit fail-fast on CUSTOM ops with detailed per-node diagnostics.
• Integrated into direct writer path in onnx2tf/tflite_builder/__init__.py and return payload now includes saved_model_path when generated.

B. Remove fallback behavior from direct backend

• Removed --flatbuffer_direct_fallback_to_tf_converter usage from CLI/runtime path.
• Direct path now fails explicitly on unsupported patterns instead of silently switching to TF converter.
• Updated docs and migration guidance to reflect explicit no-fallback operation.

C. New direct TFLite input mode (.tflite -> SavedModel only)

• Added input_tflite_file_path parameter to convert() and new CLI option:
  • -it, --input_tflite_file_path
• Added a new importer: onnx2tf/tflite_builder/tflite_importer.py:
  • Reconstructs ModelIR from TFLite FlatBuffer (main graph + subgraphs).
  • Restores tensor metadata (dtype, shape, shape_signature, is_variable, quant fields, constant data).
  • Restores operator metadata (op_type, version, builtin options normalization, CUSTOM metadata preservation).
  • Handles tensor naming normalization for empty/duplicate names.
  • Prefers serving_default SignatureDef boundary names when available.
• Added early tflite-mode branching/validation in onnx2tf/onnx2tf.py:
  • input_onnx_file_path, input_tflite_file_path, and onnx_graph are mutually exclusive.
  • ONNX-dependent options are rejected in TFLite direct mode.
  • disable_model_save=True is rejected in TFLite direct mode.
  • tflite_backend must be flatbuffer_direct for this mode.

D. SavedModel validation/reporting improvements (-cotof behavior)

• Added SavedModel-vs-TFLite validation path with structured JSON output:
  • <model_name>_saved_model_validation_report.json
  • Includes inference status, comparison pass/fail, matched/total outputs, max abs error, unmatched outputs, and overall pass.
• In TFLite direct mode, -cotof now runs SavedModel inference + comparison against input TFLite.
• In direct ONNX flow, SavedModel validation reporting is integrated so strict checks can be automated.

E. Bulk verification utility for large-scale sweeps

• Added onnx2tf/utils/tflite2sm_bulk_runner.py with CLI entrypoint behavior.
• Implements ordered list execution for model-list files, with:
  • Resume support (bulk_status.json state).
  • Per-model run directories + command/stdout/stderr capture.
  • Classification and strict-pass evaluation using machine-readable SavedModel validation reports.
  • Summary artifacts: bulk_summary.json and bulk_summary.md.
• Includes policy hooks currently used in this branch workflow:
  • model-skip policy for deformable_detr_one_input_simple
  • accepted-mismatch policy for mosaic-9

F. Accuracy evaluator improvement for seeded input generation

• Updated seeded random input distribution heuristic in accuracy_evaluator.py:
  • NCHW-like image tensors default to normal distribution.
  • NHWC-like image tensors keep non-negative uniform default.
• Added/updated tests for distribution behavior and non-finite metric stability.

G. Documentation and version updates

• README updates:
  • Added --flatbuffer_direct_output_saved_model / -fdosm descriptions in CLI and script-option sections.
  • Added --input_tflite_file_path / -it usage and examples.
  • Documented no-fallback behavior and constraints.
  • Added bulk-runner usage and SavedModel validation report details.
• Updated FLATBUFFER_DIRECT_MIGRATION_GUIDE.md for no-fallback migration guidance.
• Version bump to 2.3.0 (onnx2tf/__init__.py, pyproject.toml, uv.lock).

H. Tests

Added/updated test coverage across:

• tests/test_tflite2sm_phase1.py
• tests/test_tflite2sm_bulk_runner.py
• tests/test_accuracy_evaluator_seeded_input.py

Validated in this branch with:

• pytest -q tests/test_tflite2sm_phase1.py tests/test_tflite2sm_bulk_runner.py tests/test_accuracy_evaluator_seeded_input.py
• Result: 37 passed

I. Follow-up improvements in flatbuffer_direct

• Preserved direct-path error semantics in convert() by re-raising NotImplementedError from the flatbuffer_direct fast path (instead of always wrapping as generic RuntimeError).
• Expanded generic 2-input Einsum builtin handling so rank-2 equations that are not pure matmul-style can still lower via builtin ops.
• Kept the optimized matmul-style rank-2 path unchanged/preferred for ij,jk->ik-style equations.
• Confirmed builtin lowering for transposed-output rank-2 Einsum ij,jk->kj (no ONNX_EINSUM custom op).
• Added/updated tests:
  • direct-path test for builtin transposed-output rank-2 Einsum
  • custom-candidate fixtures switched to repeated-label unsupported equation ii,jk->kj
  • op-coverage snapshot extension for the new builtin dispatch case
• Additional validation run:
  • pytest -q tests -k flatbuffer_direct
  • Result: 564 passed, 108 deselected, 1 warning

3. Before/After (If there is an operating log that can be used as a reference)

Before

• Direct backend could depend on fallback behavior for certain flows.
• No dedicated .tflite direct-input mode for SavedModel generation.
• No standardized machine-readable SavedModel-vs-TFLite validation artifact for strict gating.

After

• Direct backend has explicit no-fallback semantics.
• SavedModel can be produced from:
  1. direct ModelIR in flatbuffer_direct flow (-fdosm), and
  2. direct .tflite input mode (-it).
• -cotof can produce strict SavedModel-vs-TFLite validation reports.
• Bulk sweep automation is available with resume + strict classification output.

4. Issue number (only if there is a related issue)

N/A

What's Changed

• feat: add direct SavedModel paths for flatbuffer_direct and TFLite input by @PINTO0309 in #900

Full Changelog: 2.2.2...2.3.0