Skip to content

feat(api): add semantic Task C ABI and C++ SDK - #1226

Draft
yifeif-nv wants to merge 8 commits into
NVIDIA:mainfrom
yifeif-nv:feat/shared-task-api
Draft

yifeif-nv wants to merge 8 commits into
NVIDIA:mainfrom
yifeif-nv:feat/shared-task-api

Conversation

@yifeif-nv

@yifeif-nv yifeif-nv commented Sep 9, 2026

Copy link
Copy Markdown
Collaborator

Background

Prepare the shared Task SDK so subsequent family migrations can stay inside
families/<name>/**, without editing Core, applications, website registration
or CI for an already-supported capability. This remains a draft while the
remaining migration rehearsals and performance-reference gaps are resolved.

Exit Criteria

  • All existing family capabilities have the required shared contracts and
    application paths, with family-only migration evidence.
  • C ABI ownership, configuration, lifecycle and installation checks pass;
    existing workloads, BYOK, examples and benchmark coverage remain available.
  • Applicable CI passes on the final PR head. Production family migrations and
    the actual merge are not part of this update.

Implementation

  • Families return typed bind<Interface>(*this, fields) records. Core snapshots
    the adjusted interface pointers and configuration metadata, then calls the
    internal interfaces directly. No additional adapter framework or family registry.
  • Shared configuration checks reject unknown/duplicate names and wrong types
    before execution. Families retain defaults, ranges and input-dependent policy.
    Missing values remain distinct from explicit zero, false or empty values.
  • Complete additional detection/structure contracts and shared CLI, benchmark,
    report and website paths. Preserve batch/session/callback ownership and error
    precedence. Unknown embedding-space identity is explicitly empty, not fabricated.
  • Correct Conan's SDK install directory so the wheel's C library and native
    runtime are colocated. Keep the existing full-family packaging checks.
  • Four existing checkpoint-policy tests move into their owning family test
    folders, retaining assertions and automatic CPU collection. No production
    builder/runtime migration is included.

Change categories

  • Model or runtime behavior
  • Public API
  • ABI
  • Bundle or artifact format
  • Dependencies
  • Documentation only
  • CI or developer tooling

SDK/wheel payloads change; bundle format 1 does not. Pandas remains optional.
No runner configuration, new exclusions, precision thresholds or passing
criteria are changed by this PR.

Validation

Commands and Results

Local evidence, not a claim that the updated remote head has passed CI:

  • python3 -m tools.community_ci unit: the current 126-family source snapshot passed
    946 Python tests (1 optional-dependency skip), built all native targets, and
    passed 198 CTests (6 existing no-GPU skips), including the latest embedding
    metadata change.
  • python3 -m tools.community_ci source-quality --base 714f1fc0d567213a7b79a488e9dcfdf405279c6a:
    passed legal, inventory, complexity and formatting checks plus 178 tests.
  • PYTHONPATH=core/builder:apps/benchmark:. python3 -m pytest apps/benchmark/trtmc_benchmark/tests/test_perf_matrix.py apps/benchmark/trtmc_benchmark/tests/test_timing_contracts.py -q:
    103 passed. Existing mainline release entries/exclusions are retained.
  • ctest --test-dir BUILD_DIR --output-on-failure -R '^test_features_(c|cpp)_api$':
    2 passed, including explicit unknown identity and result lifetime tests.
  • Retained pre-binding C/C++ client binaries run against the new library
    without recompilation. The existing single-device BYOK round trip passed.
  • npm --prefix website run build: passed, including 34 diagram checks.
  • Full wheel/archive and installed-SDK checks passed on the earlier 124-family
    snapshot; the newly added mainline families still need the final package refresh.

Hardware, Environment, and Revisions

Current development base: public main
714f1fc0d567213a7b79a488e9dcfdf405279c6a (126 families, 276 manifests).
Tested source is the content committed as
aa909bfd4207962dd2376bf29dd81abc63ff174d.
Local CPU validation uses the repository's existing isolated CPU image,
Linux/aarch64, GCC 13.3, CUDA 13.3 development tools and TensorRT 11.1.
Protocol fixtures are separate from trained-model numerical qualification.

Not Run / Remaining Gaps

  • Complete the remaining family-only rehearsals and matched performance
    references; no component timing or recorded output is presented as full inference.
  • Refresh the complete wheel and applicable checks for the final revision.
  • Final-head public CI, protected premerge and Nightly are not claimed here.
  • No multi-device execution. Earlier single-device model rehearsals do not
    establish qualification of every model or the final revision.

Contributor Self-Review

  • I have completed a self-review of this change.

Reviewed contracts, lifecycle/error handling, ownership and publication
boundaries, including independent code and confidentiality reviews.

Notes For Future Readers

Start with website/docs/api/cpp-api.md and the family migration checklist in
website/docs/extend/add-model-family.md, then the public headers and tests.
The SDK remains experimental until its first stable release. Core/backend/family
DSOs upgrade together; applications compile the convenience C++ header against
the public C ABI. Existing family execution paths remain during migration;
failed SDK calls never retry an older path.

Risk level

  • Low
  • Medium
  • High

This is a broad ABI/application change. CPU protocol coverage and isolated
rehearsals are necessary but do not replace real-model qualification.

@coderabbitai

coderabbitai Bot commented Sep 9, 2026

Copy link
Copy Markdown

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

  • Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

Comment @coderabbitai help to get the list of available commands.

@yifeif-nv yifeif-nv added the run-internal-ci Maintainer-approved dispatch to internal CI label Sep 12, 2026
@github-actions github-actions Bot removed the run-internal-ci Maintainer-approved dispatch to internal CI label Sep 12, 2026
Keep model behavior inside each family while giving applications a C binary
boundary and user-compiled C++ convenience wrappers. Add the shared typed
contracts, direct dispatch, family-owned configuration transport, ownership,
packaging and consumer paths needed for family-by-family migration.

Preserve existing application workloads during explicit primary-Task migration;
do not retry failures through old interfaces. Keep family policy tests in their
own directories without removing them from the CPU premerge invocation.

The SDK remains experimental pending its first stable release. Protocol and
host-pipeline tests do not establish model accuracy, GPU execution or full-wheel
qualification.

Signed-off-by: yifeif-nv <277870278+yifeif-nv@users.noreply.github.com>
Preserve the test-only replacement deallocation boundary under Release
optimization. GCC can otherwise inline free into callers and diagnose the
malloc-backed operator-new replacement as mismatched allocation/deallocation.

Keep all failure-injection assertions, optimization flags and strict warnings.
No runtime, ABI, CI gate or runner configuration changes.

Signed-off-by: yifeif-nv <277870278+yifeif-nv@users.noreply.github.com>
Replace repeated semantic Task discovery with family-owned typed bindings.
Validate declared configuration names and kinds before execution while keeping
defaults, ranges, state ownership and model behavior inside each family.

Extend shared image-only detection, molecular-structure and existing Task
consumer paths, preserve readable reports, and fix the SDK wheel install
layout. Keep unknown embedding-space identity explicit rather than inventing
an identifier or requiring new user configuration.

Production family migrations remain separate. This update does not claim
complete family migration or final performance qualification.

Signed-off-by: yifeif-nv <277870278+yifeif-nv@users.noreply.github.com>
Add head-score and deterministic-regression contracts without changing
existing public Task layouts. Preserve raw token inputs in CLI and
benchmark calls, and reject inputs that a selected contract cannot accept.

Let family-owned benchmark cases select an advertised secondary Task.
Keep bundle identity separate from call selection across native dispatch,
reference commands, cache checks, reports, and generated model recipes.

Production family migrations remain separate from these shared changes.

Signed-off-by: yifeif-nv <277870278+yifeif-nv@users.noreply.github.com>
Compose optional family-owned suites using the existing performance
format. Run declared family-local reference scripts through the existing
process boundary and validate their complete result protocol.

Add shape and representation contracts for head scores, geometry,
structures, refined poses, and offline speech. Preserve the existing
release entries, exclusions, timing policy, and family accuracy thresholds.

Keep explicit offline reference selection separate from bundle identity.
Real reference implementations and production migrations remain family-owned.

Signed-off-by: yifeif-nv <277870278+yifeif-nv@users.noreply.github.com>
Resolve structure preparation through the existing callable family hook,
without requiring the legacy structure_prediction task name. A family can
adopt the molecular-document Task without losing its preparation command
or adding another shared allowlist entry.

Keep the missing-hook error and all existing builder tests. Add coverage
for semantic-task dispatch, default cache forwarding, prepared output,
and absent or non-callable hooks.

Validation: all 83 builder tests pass; Ruff and git diff --check pass.
This change does not migrate production families or alter CI criteria.

Signed-off-by: yifeif-nv <277870278+yifeif-nv@users.noreply.github.com>
Add a distinct global-pooled image token role so a family's complete
feature matrix can retain its pooled prefix without calling it a CLS
token or removing that row. Keep the existing C layouts and task tables.

Carry the role through result validation, CLI JSON and benchmark
observations. Add C11 and header-only C++17 tests for complete values,
shape, metadata and result ownership, plus CLI and worker regressions.
Unknown token roles still fail without a partial result.

No production family migration or test threshold changes are included.

Signed-off-by: yifeif-nv <277870278+yifeif-nv@users.noreply.github.com>
Keep semantic benchmark parameter names and explicit Config values intact,
and separate SANA reference metadata from native per-call configuration.
Allow serial action queue/chunk calls with explicit reentry protection and
accept complete model-local classification scores without invented labels.

Retain measured audio, image, video and dialogue artifacts in readable
benchmark reports. Preserve unknown output identities and borrowed-buffer
lifetimes, reuse the segmentation session, and route structure preparation
through the existing family builder.

Keep production family migrations out of this shared-infrastructure update.
Validation includes 61 native core/SDK/application tests, 958 benchmark
Python tests with two optional skips, source checks, and the website build.
These results do not claim checkpoint, GPU, or final-head CI qualification.

Signed-off-by: yifeif-nv <277870278+yifeif-nv@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant