ONNX Doctor — Development Skills

Package Structure

• •Package: onnx_doctor at src/onnx_doctor/
• •Core modules: _rule.py, _rule_registry.py, _loader.py, _checker.py, _cli.py, _formatter.py, _message.py, _diagnostics.py
• •Providers: diagnostics_providers/ — each provider is a subpackage or module
• •Tests: src/onnx_doctor/tests/
• •Docs: docs/ (Sphinx + MyST markdown, furo theme)

Rule Numbering Convention

• •Spec rules that apply to both protobuf and IR use ONNX001–ONNX099.
• •IR-only rules (e.g., duplicate Value object identity) use ONNX101+.
• •Protobuf-only rules (impossible in IR by construction) use PB prefix.
• •Simplification rules (unused functions/nodes/opsets) use SIM prefix.

Adding a New Rule

1. •

   Define in YAML (spec.yaml or provider-specific YAML):

   yaml

   - code: ONNX036
     name: kebab-case-name
     category: spec
     severity: error
     message: Short description of the issue.
     suggestion: How to fix it.
     explanation: |
       ## Details
       Extended markdown explanation.
   

2. •

   Implement check in the provider (e.g., onnx_spec/__init__.py):

   python

   # ONNX036: kebab-case-name
   if condition:
       yield _emit(_rule("ONNX036"), "node", node, message=f"...")
   

3. •

   Add a test in tests/test_onnx_spec_provider.py:

   python

   def test_kebab_case_name(self):
       model = _make_model(...)
       messages = _diagnose(model)
       self.assertIn("ONNX036", _codes(messages))
   

Build & Test

pip install -e .                              # Editable install
pip install -r requirements-dev.txt           # Dev dependencies
python -m pytest src/onnx_doctor/tests/       # Run tests
ruff check src/                               # Lint
ruff format src/                              # Format
onnx-doctor check model.onnx                  # CLI

Code Style

• •Every .py file must start with from __future__ import annotations.
• •Google-style docstrings. Target Python 3.9.
• •Ruff enforced (see pyproject.toml for full config).
• •Private modules prefixed with _ (e.g., _rule.py, _checker.py).

Key Dependencies

• •onnx_ir: The linter operates on IR objects (ir.Model, ir.Graph, etc.), not protobuf directly.
• •onnx: Used for op schema lookups (onnx.defs.get_schema).
• •pyyaml: Rule definitions loaded from YAML files.
• •rich: CLI output formatting.

Architecture Notes

• •_checker.py walks the IR tree and dispatches to providers. It threads a _location string through the traversal for human-readable paths (e.g., graph:node/3(MatMul)).
• •_loader.py has a lazy singleton get_default_registry() that loads all YAML rule files on first access.
• •Providers yield DiagnosticsMessage objects via generator functions (check_model, check_graph, check_node, check_value, check_tensor, check_function).

Autofix Architecture

• •Fix = Callable[[], None] — a no-arg callable that mutates the IR in place. Stored on DiagnosticsMessage.fix.
• •Rules marked fixable: true in YAML should attach a fix callable via the _emit() helper.
• •CLI --fix applies all fixes, saves the model, then re-diagnoses to show remaining issues.
• •CLI --diff shows a unified diff of what --fix would change, without writing.
• •Fix deduplication: _apply_fixes() deduplicates by callable identity (id(fix)) to avoid running the same pass multiple times.

Available IR Passes for Fixes

From onnx_ir.passes.common (all take model: ir.Model, return PassResult):

Adding a Fixable Rule

1. •

   Mark fixable: true in YAML.

2. •

   In the provider, pass fix= to _emit():

   python

   yield _emit(
       _rule("ONNX004"), "graph", graph,
       fix=graph.sort,
   )
   

3. •

   For model-level passes, use the module-level helper functions:

   python

   yield _emit(
       _rule("ONNX003"), "graph", graph,
       fix=lambda: _apply_name_fix(self._model),
   )
   

Provider Structure