A simpler contribution model: one family, one directory

[yifeif-nv]

Quick note from maintainers

Hey all,

You've probably seen me being pretty quiet over the last few days because we are working on this important re-architecture and cutover to support better community development and reducing conflicts. Now the change is finally in, and I want to let everyone know what we've done and what is expected.

A simpler contribution model: one family, one directory

With PR #1093, we have completed a repository-wide architecture cutover in TensorRT-Model-Connect. All 98 current model families now follow the same ownership model. The goal is simple: each family should be independently understandable, testable, and changeable.

What changed

Each model family is now a complete vertical slice under:

families/<family>/

That directory owns the family’s:

• model and task detection in support.py;
• plain build(request, writer) entry point in model.py—builder inheritance is not allowed;
• TensorRT graph construction, weight mapping, precision, parallelism, and bundle contents;
• native runtime pipeline implementing an abstract Task interface;
• optional Python dependencies in requirements.txt;
• manifests, references, correctness thresholds, fixtures, and tests.

The shared core is intentionally narrow. It owns model-agnostic discovery and loading, bounded bundle I/O, abstract Build/Task/Engine contracts, stable TensorRT primitives, and the existing BYOK bridge. It does not own model policy or concrete family implementations.

Families must not import, include, or link sibling families. Similar code may be duplicated when that preserves ownership and fault isolation.

Benchmarks, examples, the CLI, and BYOK examples remain one-way consumers of public ModelConnect APIs. Core and model families do not depend back on application code.

This is an atomic breaking cutover. The retired registries, shared model paths, and compatibility shims are gone; existing serialized bundles must be rebuilt against the new contracts.

Direction for future PRs

For a normal model-family contribution, the expected diff should be limited to:

families/<family>/**

Adding or updating a model should not require edits to a central registry, a central CMake source list, shared model helpers, unrelated families, or compatibility layers.

A typical family PR may update:

families/<family>/support.py
families/<family>/model.py
families/<family>/requirements.txt        # only when this family needs it
families/<family>/runtime/**
families/<family>/tests/**

Please keep these principles in mind:

1. Keep model-specific behavior in the owning family.
2. Use a plain model.py::build(request, writer) function; do not introduce a base builder hierarchy.
3. Implement user behavior through the appropriate abstract Task interface.
4. Declare extra packages in the family’s own requirements.txt.
5. Keep manifests, references, thresholds, and native tests with the family.
6. Do not depend on another family. Copying a small implementation is preferable to coupling owners prematurely.
7. Do not add fallback, migration, compatibility, or configuration layers without a current concrete requirement.

Shared changes are still possible, but they should represent a small, proven, model-independent contract that multiple independent families genuinely need. A new public user behavior may justify a new Task contract; visual similarity between two model implementations does not.

The practical review question for future model PRs is now:

Can this model be added, changed, or reverted by touching only its owning family directory?

In the normal case, the answer should be yes.

For more detail, see the architecture guide and contributing guide.

Thank you

Thank you to everyone who has contributed code, opened pull requests or issues, reviewed changes, or shared feedback with the project:

@27av03 @AbishekCoder1 @Darshan3690 @dhruvdavest07 @EvanGruhlkey @ftadros @husizhtu @JiaxinD @jkzhang7 @kanhaiya-dct @lukiod @Moviw @munnmajithia @neuregex @roma5087 @ruiling-smartbear @sbirchfield @shariqueahmad108-ship-it @sparkleholic @sylvesterkaczmarek @T4t4KAU

This change is intended to make your next contribution smaller, clearer, and easier to review. We look forward to building the next model families with you.

[yifeif-nv]

Please note if you currently have a PR, please ask your agent to rebase it onto the latest top of tree to adapt to the new formats. Sorry for the inconvenience, but this is a hard decision we have to make now, rather than later, to make this project sustainable so it can keep evolving with the community.

[kanhaiya-dct]

Thank you so much for the detailed write-up, @yifeif-nv , and for the shout-out — it means a lot!

This architecture makes a huge amount of sense. The "one family, one directory" model removes the mental overhead of tracing ownership across central registries, and the fault isolation guarantee — that a defect in one family can't silently affect another — is exactly what a project at this scale needs to stay sustainable.

A couple of questions as I align my current work with the new model:

Shared serialization utilities (like BundleReader) — my open PR (#974) adds a BundleReader to complement the existing BundleWriter. Since bundle I/O is model-agnostic and used by all families at load time, I've kept it in the shared python/tensorrt_model_connect/ package. Does that still fit the intended scope of core/, or should each family that needs custom deserialization own its own reader logic?

Test placement — I learned from CI today that shared utility tests belong under tools/tests/ rather than tests/python/. I've already moved test_bundle_reader.py accordingly. Is that the right long-term home for shared-layer unit tests, or is there a preferred location post-cutover?

Happy to rebase and adapt the PR to whatever shape fits best. The new structure is genuinely cleaner — looking forward to contributing more family PRs under it!

[Darshan3690]

hi @yifeif-nv sir .

Thanks for the clear update! The new architecture makes model-family contributions much more straightforward. I’ll review the new structure and look for a contribution that fits it. Looking forward to contributing! 🚀

[chaofengw-nv]

📣 Recommended: self-review your PR before submission

Hi all,
Before opening a PR—or marking a draft as ready—we strongly recommend running the repo-local Codex skill:

$review-trtmc-pr Review my current branch against main.

For an existing PR:

$review-trtmc-pr Review PR .

The review audits the current TRTMC architecture and contribution rules, including:

• post-refactor: isolate model families end to end #1093 model-family ownership and isolation
• cross-family coupling
• shared-core neutrality
• dependency and runtime boundaries
• validation strength and repository compliance

The skill is read-only and does not replace maintainer review or CI. Its purpose is to catch architecture and
validation issues earlier, while they are still easy to fix.

If the self-review reports that the change is ready, confirm the Contributor Self-Review checkbox in the PR
description.