feat: add FPM self-service onboarding and validation

.github/codeowners/areas.yaml

@@ -10,6 +10,7 @@ areas:
     github_team: "@ai-dynamo/access-aisimulate-maintain"
     path_globs:
       - AGENTS.md
+      - CLAUDE.md
       - CODE_OF_CONDUCT.md
       - DEVELOPMENT.md
       - LICENSE
@@ -34,6 +35,7 @@ areas:
       - python/aisimulate/src/aisimulate/capacity.py
       - tests/test_aic.py
       - tests/test_fpm_profile_workflow.py
+      - tests/test_fpm_grouped_workflow.py
       - tests/test_fpm_query_evidence.py
   - label: sweeper
     github_team: "@ai-dynamo/aisimulate-sweeper-codeowners"
@@ -162,6 +164,8 @@ shared:
     owners: [forward-pass-engine, maintainers]
   - glob: tests/test_fpm_profile_workflow.py
     owners: [forward-pass-engine, maintainers]
+  - glob: tests/test_fpm_grouped_workflow.py
+    owners: [forward-pass-engine, maintainers]
   - glob: tests/test_fpm_query_evidence.py
     owners: [forward-pass-engine, replay, maintainers]
   - glob: python/aisimulate/src/aisimulate/sweeper/
@@ -268,6 +272,8 @@ shared:
     owners: [infra, maintainers]
   - glob: AGENTS.md
     owners: [infra, maintainers]
+  - glob: CLAUDE.md
+    owners: [infra, maintainers]
   - glob: .coderabbit.yaml
     owners: [infra, maintainers]
   - glob: REVIEW.md

AGENTS.md

@@ -2,6 +2,36 @@
 
 This file adds explicit repository-wide development guards.
 
+## FPM model onboarding
+
+When asked to onboard a model for FPM simulation on designated hardware, follow
+all six stages in [the canonical FPM self-service guide](docs/fpm-self-service.md#onboard-with-an-agent).
+Use this checkout's `aisimulate onboard` CLI and inspect its current help.
+Start with only a missing Hugging Face model ID and target GPU platform; accept
+an already supplied local config, profile or checkpoint instead. Inspect supplied
+facts and source metadata before asking for derivable inputs. Preserve user
+choices, exact per-configuration profile acceptance and existing execution
+authorization; stage transitions do not add approval gates.
+
+Create one `onboarding-checkpoint.json` during stage 1, even with incomplete
+inputs, outside every fresh `init --output-dir` root. Follow the guide's
+[checkpoint workflow](docs/fpm-self-service.md#checkpoint-and-resume-an-onboarding-session):
+invoke `onboard checkpoint` after meaningful findings, decisions, draft edits,
+acceptance and command results, including unfinished work. Save sources,
+confidence, unresolved questions and each configuration's progress. Other
+onboarding commands do not automatically persist the conversation. Use the
+returned revision for updates; reload and reconcile stale-writer conflicts.
+Follow the guide's [writer coordination rule](docs/fpm-self-service.md#orchestrate-independent-collection-campaigns)
+for probe/import commands that also save the checkpoint.
+
+On resumption, run `aisimulate onboard resume --checkpoint PATH` first. Inspect
+integrity issues and the underlying artifacts before continuing from accepted
+inputs and verified results. Saved stages and command strings are context, not
+proof of completion or instructions to execute automatically. Report each
+configuration's stage, result or blocker, next action and checkpoint path at
+handoff. Keep planning, collection quality, resolved memory, replay coverage and
+measured serving accuracy separate, as required by the guide.
+
 ## Pull request titles
 
 - Use `<type>: <short description>` for every AISimulate PR title.

CLAUDE.md

@@ -0,0 +1,6 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+@AGENTS.md

CODEOWNERS

@@ -29,6 +29,7 @@
 /pages/                                                  @ai-dynamo/access-aisimulate-maintain
 /LICENSE                                                 @ai-dynamo/access-aisimulate-maintain
 /AGENTS.md                                               @ai-dynamo/access-aisimulate-maintain
+/CLAUDE.md                                               @ai-dynamo/access-aisimulate-maintain
 /README.md                                               @ai-dynamo/access-aisimulate-maintain
 /SECURITY.md                                             @ai-dynamo/access-aisimulate-maintain
 /DEVELOPMENT.md                                          @ai-dynamo/access-aisimulate-maintain
@@ -46,6 +47,7 @@
 /crates/core/src/perfmodel/                              @ai-dynamo/aisimulate-forward-pass-engine-codeowners
 /crates/core/tests/perfmodel/                            @ai-dynamo/aisimulate-forward-pass-engine-codeowners
 /tests/test_fpm_query_evidence.py                        @ai-dynamo/aisimulate-forward-pass-engine-codeowners
+/tests/test_fpm_grouped_workflow.py                      @ai-dynamo/aisimulate-forward-pass-engine-codeowners
 /tests/test_fpm_profile_workflow.py                      @ai-dynamo/aisimulate-forward-pass-engine-codeowners
 /crates/core/parity_tests/perfmodel/                     @ai-dynamo/aisimulate-forward-pass-engine-codeowners
 /python/aisimulate/src/aisimulate/capacity.py            @ai-dynamo/aisimulate-forward-pass-engine-codeowners
@@ -117,6 +119,7 @@
 /pages/                                                  @ai-dynamo/aisimulate-forward-pass-engine-codeowners @ai-dynamo/aisimulate-infra-codeowners @ai-dynamo/access-aisimulate-maintain
 /scripts/                                                @ai-dynamo/aisimulate-infra-codeowners @ai-dynamo/access-aisimulate-maintain
 /AGENTS.md                                               @ai-dynamo/aisimulate-infra-codeowners @ai-dynamo/access-aisimulate-maintain
+/CLAUDE.md                                               @ai-dynamo/aisimulate-infra-codeowners @ai-dynamo/access-aisimulate-maintain
 /REVIEW.md                                               @ai-dynamo/aisimulate-infra-codeowners @ai-dynamo/access-aisimulate-maintain
 /deny.toml                                               @ai-dynamo/aisimulate-infra-codeowners @ai-dynamo/access-aisimulate-maintain
 /CODEOWNERS                                              @ai-dynamo/aisimulate-infra-codeowners @ai-dynamo/access-aisimulate-maintain
@@ -188,6 +191,7 @@
 /python/aisimulate/.coderabbit.yaml                      @ai-dynamo/aisimulate-infra-codeowners @ai-dynamo/access-aisimulate-maintain
 /python/aisimulate/eslint.config.js                      @ai-dynamo/aisimulate-infra-codeowners @ai-dynamo/access-aisimulate-maintain
 /tests/test_e2e_accuracy_nightly.py                      @ai-dynamo/aisimulate-forward-pass-engine-codeowners @ai-dynamo/aisimulate-replay-codeowners @ai-dynamo/aisimulate-infra-codeowners @ai-dynamo/access-aisimulate-maintain
+/tests/test_fpm_grouped_workflow.py                      @ai-dynamo/aisimulate-forward-pass-engine-codeowners @ai-dynamo/access-aisimulate-maintain
 /tests/test_fpm_profile_workflow.py                      @ai-dynamo/aisimulate-forward-pass-engine-codeowners @ai-dynamo/access-aisimulate-maintain
 /tests/test_resource_supervision.py                      @ai-dynamo/aisimulate-replay-codeowners @ai-dynamo/aisimulate-sweeper-codeowners @ai-dynamo/access-aisimulate-maintain
 /crates/core/parity_tests/perfmodel/                     @ai-dynamo/aisimulate-forward-pass-engine-codeowners @ai-dynamo/access-aisimulate-maintain

README.md

@@ -266,7 +266,7 @@ APIs:
 - [Estimator/FPE Python and Rust SDK](docs/core-api.md)
 - [FPM self-service: onboard a model on target hardware](docs/fpm-self-service.md)
 - [AIC-compatible modeled-power contract (semantics only)](docs/power-model.md)
-- [Self-benchmarking and FPM onboarding guide](python/aisimulate/docs/fpm/self-benchmarking-and-onboarding.md)
+- [FPM self-benchmarking and onboarding guide](python/aisimulate/docs/fpm/self-benchmarking-and-onboarding.md)
 - [Replay SDK and artifact contract](crates/core/src/replay/README.md)
 - [Sweeper SDK](docs/sweeper/overview.md)
 - [Legacy CLI reference](docs/cli/legacy-aic-user-guide.md)

THIRD_PARTY_NOTICES.md

@@ -157,6 +157,29 @@ https://gitlab-master.nvidia.com/dl/sglang/sglang/-/blob/02c5a855aceb968c310e6fb
 
 ## vLLM
 
+The grouped-cache config derivation and metadata regression tests in
+`src/aisimulate/support/config_profile.py`,
+`tests/unit/test_support_config_profile.py`, and
+`tests/unit/test_support_topology.py` are adapted and modified from vLLM's
+Inkling cache layout, decoder state construction, and configuration defaults at
+commit `98dff2a81d747d1dba01a47f939f48c3526d4206`:
+
+- [`vllm/models/inkling/nvidia/sconv_swa_attn.py`](https://github.com/vllm-project/vllm/blob/98dff2a81d747d1dba01a47f939f48c3526d4206/vllm/models/inkling/nvidia/sconv_swa_attn.py)
+- [`vllm/models/inkling/nvidia/model.py`](https://github.com/vllm-project/vllm/blob/98dff2a81d747d1dba01a47f939f48c3526d4206/vllm/models/inkling/nvidia/model.py)
+- [`vllm/models/inkling/configs.py`](https://github.com/vllm-project/vllm/blob/98dff2a81d747d1dba01a47f939f48c3526d4206/vllm/models/inkling/configs.py)
+
+Copyright contributors to the vLLM project.
+
+This material is licensed under Apache-2.0; the upstream license at the
+identified revision is available at:
+https://github.com/vllm-project/vllm/blob/98dff2a81d747d1dba01a47f939f48c3526d4206/LICENSE
+
+AISimulate modifies these contracts for metadata-only rank-local aggregate
+cache sizing and validation, without constructing runtime tensors or a model.
+The derived tests use original synthetic geometries and do not copy a
+checkpoint fixture. The derived files retain the upstream copyright and
+identify the modified source material.
+
 The repository-root files `crates/core/src/engine/scheduler/vllm/core.rs`,
 `crates/core/src/engine/kv_manager/{state_cache_manager,vllm_backend}.rs`,
 `crates/core/src/engine/cache/vllm_block_pool.rs`,

crates/core/src/engine/common/protocols.rs

@@ -209,6 +209,10 @@ pub(crate) struct MockEngineArgs {
     pub kv_transfer_bytes_per_token: Option<usize>,
     #[builder(default = "None")]
     pub kv_cache_bytes_per_token: Option<usize>,
+    #[builder(default)]
+    pub kv_cache_groups: Vec<crate::perfmodel::FpmCacheGroup>,
+    #[builder(default = "None")]
+    pub kv_cache_capacity_bytes: Option<u64>,
     #[builder(default = "None")]
     pub native_host_offload: Option<NativeHostOffloadConfig>,
     #[builder(default = "None")]

crates/core/src/engine/config.rs

@@ -11,6 +11,7 @@ use serde::{Deserialize, Deserializer, Serialize};
 use crate::engine::common::speculative::normalize_conditional_accept_rates;
 use crate::engine::handoff::TransferTimingMode;
 use crate::engine::timing::{TimingModel, TimingModelConfig, built_in_timing_model};
+use crate::perfmodel::FpmCacheGroup;
 
 const DEFAULT_MAX_PREFILL_TOKENS: usize = 16_384;
 const DEFAULT_CHUNKED_PREFILL_SIZE: usize = 8_192;
@@ -371,7 +372,8 @@ pub struct EngineConfig {
     /// Use [`Self::for_backend`] instead of changing this field on
     /// [`Self::default`] when backend-dependent defaults are desired.
     pub backend: Backend,
-    /// Physical G1 capacity in blocks.
+    /// Physical G1 capacity in blocks for a linear cache. Retained as a
+    /// positive compatibility field and ignored when `kv_cache_groups` is set.
     #[serde(default = "default_num_gpu_blocks")]
     pub num_gpu_blocks: usize,
     /// KV block size in tokens.
@@ -429,6 +431,12 @@ pub struct EngineConfig {
     /// Physical KV-cache bytes occupied by one token for host offload.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub kv_cache_bytes_per_token: Option<usize>,
+    /// Rank-local cache group geometry. An empty list retains the linear pool.
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub kv_cache_groups: Vec<FpmCacheGroup>,
+    /// Shared physical budget for `kv_cache_groups`, including page padding.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub kv_cache_capacity_bytes: Option<u64>,
     /// Optional framework-native host-offload simulation.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub native_host_offload: Option<NativeHostOffloadConfig>,
@@ -502,6 +510,10 @@ struct EngineConfigWire {
     kv_transfer_bytes_per_token: Option<usize>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
     kv_cache_bytes_per_token: Option<usize>,
+    #[serde(default)]
+    kv_cache_groups: Vec<FpmCacheGroup>,
+    #[serde(default)]
+    kv_cache_capacity_bytes: Option<u64>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
     native_host_offload: Option<NativeHostOffloadConfig>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
@@ -563,6 +575,8 @@ impl<'de> Deserialize<'de> for EngineConfig {
             emit_kv_token_ids: wire.emit_kv_token_ids,
             kv_transfer_bytes_per_token: wire.kv_transfer_bytes_per_token,
             kv_cache_bytes_per_token: wire.kv_cache_bytes_per_token,
+            kv_cache_groups: wire.kv_cache_groups,
+            kv_cache_capacity_bytes: wire.kv_cache_capacity_bytes,
             native_host_offload: wire.native_host_offload,
             g3_offload: wire.g3_offload,
             state_cache: wire.state_cache,
@@ -604,6 +618,8 @@ impl Default for EngineConfig {
             emit_kv_token_ids: false,
             kv_transfer_bytes_per_token: None,
             kv_cache_bytes_per_token: None,
+            kv_cache_groups: Vec::new(),
+            kv_cache_capacity_bytes: None,
             native_host_offload: None,
             g3_offload: None,
             state_cache: None,
@@ -761,6 +777,49 @@ impl EngineConfig {
             self.kv_cache_bytes_per_token.is_none_or(|bytes| bytes > 0),
             "kv_cache_bytes_per_token must be positive"
         );
+        if self.kv_cache_groups.is_empty() {
+            ensure!(
+                self.kv_cache_capacity_bytes.is_none(),
+                "kv_cache_capacity_bytes requires kv_cache_groups"
+            );
+        } else {
+            ensure!(
+                self.backend == Backend::Vllm && self.worker_type == WorkerType::Aggregated,
+                "kv_cache_groups currently require backend=vllm and worker_type=aggregated"
+            );
+            ensure!(
+                !self.enable_prefix_caching,
+                "kv_cache_groups currently require enable_prefix_caching=false"
+            );
+            ensure!(
+                self.native_host_offload.is_none() && self.g3_offload.is_none(),
+                "kv_cache_groups currently support only HBM without host or G3 offload"
+            );
+            ensure!(
+                self.aic_nextn.is_none(),
+                "kv_cache_groups currently do not support speculative decoding"
+            );
+            ensure!(
+                !self.emit_kv_events && !self.emit_kv_token_ids,
+                "kv_cache_groups currently do not support KV event or token-ID emission"
+            );
+            ensure!(
+                self.kv_cache_bytes_per_token.is_none()
+                    && self.kv_transfer_bytes_per_token.is_none()
+                    && self.kv_transfer_bandwidth.is_none(),
+                "kv_cache_groups cannot use linear cache or KV transfer byte geometry"
+            );
+            ensure!(
+                self.kv_cache_capacity_bytes
+                    .is_some_and(|bytes| bytes > 0 && bytes <= (1u64 << 53)),
+                "kv_cache_groups require positive kv_cache_capacity_bytes at most 2^53"
+            );
+            let mut names = std::collections::HashSet::new();
+            for group in &self.kv_cache_groups {
+                group.validate()?;
+                ensure!(names.insert(&group.name), "duplicate KV cache group name");
+            }
+        }
         if let Some(g3) = &self.g3_offload {
             g3.validate()?;
             anyhow::ensure!(
@@ -1184,6 +1243,63 @@ mod tests {
         assert!(error.to_string().contains("unknown field"));
     }
 
+    #[test]
+    fn grouped_cache_round_trips_and_rejects_unsupported_runtime_modes() {
+        let wire = serde_json::json!({
+            "backend": "vllm",
+            "enable_prefix_caching": false,
+            "kv_cache_capacity_bytes": 1024,
+            "kv_cache_groups": [{
+                "name": "window", "kind": "attention", "num_layers": 4,
+                "block_size_tokens": 4, "page_size_bytes": 64, "sliding_window": 8
+            }]
+        });
+        let config: EngineConfig = serde_json::from_value(wire.clone()).unwrap();
+        config.validate().unwrap();
+        let reloaded: EngineConfig =
+            serde_json::from_value(serde_json::to_value(&config).unwrap()).unwrap();
+        assert_eq!(config, reloaded);
+        for (key, value, expected) in [
+            ("backend", serde_json::json!("sglang"), "backend=vllm"),
+            (
+                "worker_type",
+                serde_json::json!("decode"),
+                "worker_type=aggregated",
+            ),
+            (
+                "enable_prefix_caching",
+                serde_json::json!(true),
+                "enable_prefix_caching=false",
+            ),
+            ("aic_nextn", serde_json::json!(1), "speculative"),
+            ("emit_kv_events", serde_json::json!(true), "KV event"),
+            (
+                "kv_cache_bytes_per_token",
+                serde_json::json!(64),
+                "linear cache",
+            ),
+            (
+                "kv_cache_capacity_bytes",
+                serde_json::json!(0),
+                "positive kv_cache_capacity_bytes",
+            ),
+            (
+                "native_host_offload",
+                serde_json::json!({"num_host_blocks": 1}),
+                "only HBM",
+            ),
+        ] {
+            let mut unsupported = wire.clone();
+            unsupported[key] = value;
+            let config: EngineConfig = serde_json::from_value(unsupported).unwrap();
+            let error = config.validate().unwrap_err();
+            assert!(error.to_string().contains(expected), "{key}: {error}");
+        }
+        let linear = serde_json::to_value(EngineConfig::default()).unwrap();
+        assert!(linear.get("kv_cache_groups").is_none());
+        assert!(linear.get("kv_cache_capacity_bytes").is_none());
+    }
+
     #[test]
     fn native_host_offload_deserializes_with_default_bandwidths() {
         assert_eq!(DEFAULT_HOST_OFFLOAD_BANDWIDTH_GBPS, 32.0);

crates/core/src/engine/kv_manager/g1_manager.rs

@@ -18,7 +18,7 @@ use super::vllm_backend::{
     StoreSourceSnapshot as VllmStoreSourceSnapshot, VllmAcquire, VllmKvManager,
 };
 pub(crate) use super::vllm_backend::{NativeAllocation, SourceReuseDependency};
-use super::{AllocationRequirement, DestinationReservationMode, G1Acquire};
+use super::{AllocationRequirement, DestinationReservationMode, G1Acquire, GroupedKvPool};
 
 fn into_g1_acquire<T>(outcome: VllmAcquire<T>) -> G1Acquire<T> {
     match outcome {
@@ -70,6 +70,14 @@ pub(crate) struct G1Manager {
 }
 
 impl G1Manager {
+    pub(crate) fn set_grouped_cache(&mut self, groups: GroupedKvPool) {
+        self.inner.set_grouped_cache(groups);
+    }
+
+    pub(crate) fn grouped(&self) -> Option<&GroupedKvPool> {
+        self.inner.grouped()
+    }
+
     pub(crate) fn set_belady_oracle(&mut self, oracle: BeladyOracle) {
         self.inner.set_belady_oracle(oracle);
     }