Skip to content

docs(agentx): define the shared G2 contract for multi-replica AgentX [AISIM-1894] - #689

Closed
Harrilee wants to merge 2 commits into
harrli/aisim-1893-agentx-multi-replica-g2from
harrli/aisim-1894-agentx-shared-g2
Closed

Harrilee wants to merge 2 commits into
harrli/aisim-1893-agentx-multi-replica-g2from
harrli/aisim-1894-agentx-shared-g2

Conversation

@Harrilee

@Harrilee Harrilee commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Resolves AISIM-1894 (AISimulate side). Stacked on #688 (AISIM-1893). Retarget to main after that merges.

This PR documents the cluster_shared G2 contract under AgentX in docs/replay/engine/kv-cache.md:

  • Ownership and discovery: the deployment owns one pool, and capacity is counted once.
  • Visibility: a block is published as HostPinned to every subscribed rank when its D2H completes, and pool-wide LRU removals are published the same way.
  • Identity: conversations in a play share G2 prefixes; recycled snapshot/profile plays never share them.
  • Contention: concurrent restores split pool bandwidth max-min fairly and deterministically.
  • Stale entries: if residency is evicted before admission, the request falls back to recompute.
  • Membership: AgentX G2 requires static pools.
  • Disabling sharing: dp_rank_local reproduces private G2.

New public-API test: 2P2D on one shared pool reports a single 8-block domain. Switching the scope to dp_rank_local reproduces the private-G2 report exactly, even when shared-only bandwidth fields are left set.

The deterministic replica-level assertions (play-scoped sharing, recycled-play isolation, concurrent-consumer accounting, stale fallback) run through the Dynamo Router in ai-dynamo/dynamo#17879.

Validation

tests/test_agentx_g2.py: 38 passed. Ruff check/format clean.

Lift the one-aggregated-worker/1P1D limit on AgentX G2 in both the Python
sweeper gate and the native JSON entrypoint. Each worker publishes its G2
residency as native HostPinned KV events, so a KV-aware placement policy
(such as Dynamo's Router) follows a G2-resident prefix to its owner, and
snapshot/profile plays keep play-local token identities so hits never cross
a recycled play. vLLM, attention DP1 on every role, static pools, and no
speculation or G3 remain required; zero or non-integer worker counts are
still rejected.

Tests cover multi-replica aggregated and P/D runs through the public API
and native JSON payloads. Docs and CLI help describe the new boundary.

Signed-off-by: Harry Lee <harrli@nvidia.com>
…[AISIM-1894]

Document ownership, discovery, play-scoped identity, contention, stale-entry
fallback, membership, and disable semantics of a cluster-shared G2 pool under
AgentX. A public-API test runs 2P2D on one shared pool (capacity counted
once) and checks that switching to dp_rank_local reproduces the private-G2
report exactly, even with shared-only fields left set.

Signed-off-by: Harry Lee <harrli@nvidia.com>
@Harrilee
Harrilee requested review from a team as code owners November 2, 2026 23:54
@coderabbitai

coderabbitai Bot commented Nov 2, 2026

Copy link
Copy Markdown

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

🗂️ Base branches to auto review: 1
  • release/.*

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

Run configuration

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • Trigger review
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

CodeRabbit Verify

  • Run CodeRabbit Verify to test the changes in this pull request.

@Harrilee

Harrilee commented Nov 3, 2026

Copy link
Copy Markdown
Contributor Author

Folded into #688 per review: this PR only added docs and tests for the behavior #688 enables. #688 now resolves both AISIM-1893 and AISIM-1894.

@Harrilee Harrilee closed this Nov 3, 2026
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