docs: separate FPM metadata from optional analytical integration

[Arsene12358]

Superseded by #248. The commits from this PR are included in d03a09f8ee6f762422aa26088621f5ff1abe6299 on feat/fpm-config-onboarding. Its refreshed model-integration guide now describes the available class-independent direct-FPM workflow and optional registered-model/SOL integration using current APIs. Continue review in #248, which remains a draft.

The original proposal and its historical evidence are retained below.

---

Why and what changed

FPM onboarding needs pinned model/deployment metadata, correct resource accounting, and matching whole-forward timing data. The guide separates those shared requirements from the optional procedure for reusing or implementing a registered analytical model. It documents the currently available registered-model/SOL route and the class-independent route planned in a separate decoupling PR, without making an op-level class a universal onboarding prerequisite.

The registered-model procedure covers operation construction, memory/cache accounting, the native FPM analytical contract, and installing a reviewed integration. Its runnable Qwen3-0.6B CPU example distinguishes SOL_FULL diagnostics from FPM interpolation and needs no model weights, GPU, or matching timing pair. Per-operation GPU timing collection is not required. Entry links from the model and FPM workflow guides identify the route choice explicitly.

The planned class-independent route uses validated metadata and direct measured-time interpolation with wider two-sided KV brackets; 2D interpolation remains experimental. Inkling on GB200 with TP, DEP, and TEP is the planned pilot. This documentation introduces no class-independent API or Inkling implementation, and it states that the separate guided foundation currently generates pure-TP configurations only.

Review map

• Risk: low; documentation only.
• Start with python/aisimulate/docs/fpm/model-integration.md, especially the current/planned route distinction and the conditional registered-model transfer-path tests.
• Public or serialized contract changed: no. Every existing code block is unchanged.
• The PR is based on main and can merge independently of the CLI foundation and decoupling implementation.

Evidence

Updated head: d338ebc37f2c6e4abc496975bce9e05c33e8a55a.

• Reran the documented CPU example with source-scoped imports and the existing native wheel: retained graphs, expected geometry and per-rank weight/KV accounting, native memory sizing, and finite analytical diagnostics pass.
• Documentation checks pass for 64 Markdown files; seven link tests and whitespace checks pass. All documented code blocks match the prior guide.
• Historical baseline caca6d0f304dc660cce5a12c88cd58ecf6c09270: Python FPM/OpSpec/single-oracle contracts passed 37 tests; native FPM SOL passed 16 and native FPM forward passed 17. Independent reviews, Fast CI, and Full CI passed on that baseline. Those results are historical, not hosted evidence for the documentation update.
• Hosted checks and applicable human CODEOWNER approval must cover the updated head. The PR remains draft.

Modeling and data provenance

No performance data or model implementation is added. Examples use bundled Qwen metadata, the H200 catalog, and CPU analytical checks. The values are analytical estimates rather than measured latency or peak serving memory. Existing contract tests use synthetic fixtures. No GPU collection, Inkling readiness, or predictive accuracy is claimed.

Tracking

Refs AIC-1963 onboarding guidance and AIC-1964 model/resource metadata. Related foundation: #196. The separate decoupling PR implements AIC-1964, AIC-1990, and AIC-1991; this guide does not complete those implementation issues.

The decoupling PR will validate actual CLI predict, recommend, and exported replay against existing MiniMax-M2.7 H200 TP4 and GLM-5.2-NVFP4 B200 DEP8/TEP8 FPM data, including explicit GLM FP8 FMHA identity and classless resource metadata.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Enterprise

Run ID: 05343f14-4a4a-4748-853c-b601f0b82b8d

📥 Commits

Reviewing files that changed from the base of the PR and between 1c4ff5e and caca6d0.

📒 Files selected for processing (3)

• python/aisimulate/docs/add_a_new_model.md
• python/aisimulate/docs/fpm/end-to-end-workflow.md
• python/aisimulate/docs/fpm/model-integration.md

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

• ai-dynamo/dynamo (manual)
• ai-dynamo/aiconfigurator (manual)

Included review availability: Your plan provides up to 12 included reviews per hour; 11 remain after this review.

📜 Recent review details

🧰 Additional context used

📓 Path-based instructions (2)

Read REVIEW.md before commenting.

⚙️ CodeRabbit configuration file

Files:

• python/aisimulate/docs/add_a_new_model.md
• python/aisimulate/docs/fpm/end-to-end-workflow.md
• python/aisimulate/docs/fpm/model-integration.md

Before making any change under: `python/aisimulate/src/aiconfigurator/generator/**` MUST read: `python/aisimulate/.claude/rules/generator-development.md` Before making any change under `python/aisimulate/collector/**` MUST read: `python/ais...

📄 CodeRabbit inference engine (AGENTS.md)

Files:

• python/aisimulate/docs/add_a_new_model.md
• python/aisimulate/docs/fpm/end-to-end-workflow.md
• python/aisimulate/docs/fpm/model-integration.md

🔀 Multi-repo context ai-dynamo/aiconfigurator, ai-dynamo/dynamo

Linked repositories findings

ai-dynamo/aiconfigurator

• The FPM analytical contract requires exact model-path matching plus a 15-field execution identity, including quantization, parallelism, backend, and feature flags. [::ai-dynamo/aiconfigurator::] (aic-core/src/aiconfigurator_core/sdk/operations/fpm_forward.py:35-61)
• Whole-model FPM construction requires the original phase sol_ops; Python sol_fn callbacks are retired and rejected. [::ai-dynamo/aiconfigurator::] (aic-core/src/aiconfigurator_core/sdk/operations/fpm_forward.py:91-121)
• The collector case plan explicitly includes Qwen/Qwen3-0.6B under Qwen3ForCausalLM. [::ai-dynamo/aiconfigurator::] (collector/cases/models/Qwen3ForCausalLM_cases.yaml:5-13,26-36)
• The FPM collector requires a model path, architecture, or model-cases input, and collects fpm_forward as an isolated campaign rather than mixing it with ordinary operation entries. [::ai-dynamo/aiconfigurator::] (collector/collect.py:5904-5908)

ai-dynamo/dynamo

• Dynamo currently pins aisimulate==0.12.0.dev2 for Python 3.11–3.13 and registers AISimulate sweep providers, replay runners, and config adapters through entry points. [::ai-dynamo/dynamo::] (pyproject.toml:15-18,116-125)
• Dynamo’s Rust mocker uses AISimulate’s compiled engine and replay APIs, with external timing models used for interpolated/Aiconfigurator performance models. [::ai-dynamo/dynamo::] (lib/mocker/src/engine_adapter.rs:8-13,88-108)
• Dynamo also has a separate versioned ForwardPassMetrics wire-format contract with positional field ordering; the new analytical FPM onboarding docs should not imply that this runtime telemetry schema is being changed. [::ai-dynamo/dynamo::] (components/src/dynamo/sglang/tests/test_fpm_contract.py:4-10,64-79)

---

📝 Summary

Risk: Medium. Human attention should focus on the FPM analytical contract, Qwen3-0.6B example correctness, and installation/review gates before timing collection.

Changed behavior and contracts

• Adds a new FPM model-integration procedure.
• Requires model integrations to validate operation construction, CPU memory accounting, FPM support, analytical diagnostics, installation, and review before collection.
• Adds a runnable Qwen3-0.6B CPU example.
• Separates SOL_FULL diagnostics from the exact FPM interpolation path.
• States that whole-forward FPM collection does not require per-operation GPU timing.
• Updates the model-addition and FPM end-to-end workflow guides to reference the new procedure.
• No public API, CLI behavior, performance data, model implementation, or serialized contract changes are identified.

Evidence supplied

• The changes are documentation-only.
• The new guide documents deployment metadata, model reuse or implementation, operation and memory contracts, centralized FPM wrapping, CPU validation, FPM execution-contract testing, installation, review, and collection handoff.
• The supplied objectives report passing Python, native FPM, documentation-link, and contract tests, including negative cases.

Evidence still missing

• The raw change summary does not include test commands, logs, or independent verification of the reported test results.
• No current review findings or severity counts are supplied.
• Technical correctness of the documented Qwen3-0.6B example and FPM contract remains dependent on the reported tests and human review.
• Merge readiness cannot be confirmed from the supplied evidence alone.

Walkthrough

The PR adds a complete FPM model-integration guide, a CPU validation example, FPM contract and transfer-test requirements, and collection handoff guidance. Related onboarding documents now require this procedure before GPU collection planning.

Changes

FPM model integration

Layer / File(s)	Summary
Integration procedure python/aisimulate/docs/fpm/model-integration.md	Defines deployment metadata, model-family integration, analytical operations, memory curves, Rust evaluator support, and centralized FPMForwardOp wrapping.
CPU and FPM contract validation python/aisimulate/docs/fpm/model-integration.md	Adds a Qwen3-0.6B CPU validation script, expected validation values, Python and Rust contract suites, and model-specific FPM transfer regression requirements.
Collection handoff python/aisimulate/docs/fpm/model-integration.md, python/aisimulate/docs/fpm/end-to-end-workflow.md, python/aisimulate/docs/add_a_new_model.md	Adds review, installation, verification, evidence, collection, and onboarding requirements before GPU collection.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~15 minutes

Merge Risk: ⚪ Minimal · up to caca6

The documented validation artifacts retain the FPM identity needed to reproduce collection and prediction inputs, so no actionable merge-blocking risk remains.

🚥 Pre-merge checks | ✅ 8

✅ Passed checks (8 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Cross-Layer Contract	✅ Passed	The reviewed range changes only three Markdown files: two edits and one new guide. It changes no Rust, Python, CLI, schema, serialization, or test consumer, so no public input/output contract requires…
Modeling And Data Evidence	✅ Passed	PASS. The reviewed range changes documentation only; it adds no model/performance-data or predicted-output artifact. The new procedure gives reproducible provenance: Qwen3-0.6B metadata, H200 catalog,…
Compatibility Boundaries	✅ Passed	PASS. The authoritative PR range changes only three Markdown files; it changes no Python/Rust source, schema, binding, manifest, version, or dependency file. The added FPM procedure references existin…
Review Evidence	✅ Passed	The PR description reports the local CPU example and named Python/Rust/documentation test results, with pass counts. It includes boundary failures for an unknown architecture and for a Qwen FPM query …
Title check	✅ Passed	The title precisely describes the main documentation change: separating shared FPM metadata requirements from the optional analytical integration procedure.
Description check	✅ Passed	The description is mostly complete and covers the problem, scope, review map, contract impact, evidence, provenance, and related work. It clearly identifies the documentation-only scope and distinguis…

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

---

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