Add online predictive KV tiering experiments

README.md

@@ -72,6 +72,7 @@ arrival_time,prompt_tokens,output_tokens
 - P/D transfer latency / transfer volume / role utilization
 - heuristic bottleneck diagnoses with explicit simulator provenance
 - cross-turn KV hit rate, recomputed history tokens, routing locality, HBM/host GB-seconds, TTL/pressure evictions, and explicit host-tier transfer latency for stateful sessions
+- online tool-gap prediction MAE, oracle-action agreement, and pre/post-shift adaptation diagnostics
 
 ## Interactive experiments
 
@@ -109,7 +110,7 @@ Run a bounded live sweep across scheduler, batch size, prefix caching, and P/D w
 
 Model stateful multi-turn programs rather than isolated requests. Each program has ordered LLM turns separated by tool-call gaps. The simulator tracks cross-turn KV residency on multiple replicas, routing locality, TTL expiry, pressure eviction, recomputation after cache loss, and memory-time residency.
 
-Six live experiments are included:
+Eight live experiments are included:
 
 1. **Session run:** inspect one retention/routing policy on a generated program trace.
 2. **Session Policy Arena:** replay the exact same program trace through simple stateless/retention baselines.
@@ -117,9 +118,20 @@ Six live experiments are included:
 4. **Agent Memory Lab:** compare HBM retention, bounded affinity, host-memory offload, and an explicitly labeled oracle gap-aware tiering upper bound.
 5. **Finite-HBM budget stress:** derive per-replica KV budgets from the trace's unconstrained working set and rerun tiering policies under deliberate memory pressure.
 6. **Affinity Frontier:** sweep the queue-delay slack that bounded-affinity routing is willing to pay for cache locality.
+7. **Predictive Tiering Lab:** replace the clairvoyant gap-aware policy with online global/per-tool EWMA predictors that learn only from completed tool calls, then compare them on a non-stationary program trace.
+8. **Adaptation-rate sweep:** vary the EWMA update rate on the exact same shifted trace to expose the stability-versus-reactivity trade-off.
 
 Agent mode intentionally uses a serial service station per replica. The existing Serving Lab models batching; Agent Sessions isolates program dependencies, cache locality, tool gaps, and state-management decisions so those effects are interpretable rather than conflated.
 
+### Predictive tiering without future leakage
+
+The adaptive KV policy does **not** read the sampled future tool duration when it decides whether to retain state in HBM or offload it. Retained adaptive state is also bounded by the configured KV safety TTL, so a bad short-gap prediction cannot pin HBM indefinitely. Each completed tool call emits a later observation event; only then is its duration added to the online predictor. Two transparent predictors are available:
+
+- a global EWMA over all completed tools;
+- a per-tool EWMA that falls back to the global estimate during warm-up.
+
+The Predictive Tiering Lab deliberately changes the duration distribution of slower external tools partway through one shared trace. It compares fixed TTL, unconditional host offload, global prediction, per-tool prediction, and an explicitly labeled oracle upper bound. Prediction error and serving outcomes are shown together so a lower forecasting error is not automatically treated as a better systems policy.
+
 ### Research Studies
 
 This is the statistical/research layer rather than another configuration dashboard.
@@ -169,7 +181,7 @@ This makes profile uncertainty visible rather than allowing one uncalibrated pro
 |                  |                                          |     |
 |                  +-----------------------+------------------+     |
 |                                          v                        |
-|                  metrics / search / research / agent sessions       |
+|                  metrics / search / research / agent sessions / online prediction       |
 +------------------------------------------------------------------+
 ```
 

app.js

@@ -16,6 +16,8 @@ let lastAgentTtl = null;
 let lastAgentMemory = null;
 let lastAgentBudget = null;
 let lastAgentAffinity = null;
+let lastPredictiveStudy = null;
+let lastPredictiveAlpha = null;
 let traceRequests = [];
 
 const COLORS = {
@@ -39,7 +41,7 @@ worker.addEventListener("message", (event) => {
   if (data.type === "ready") {
     runtimePill.classList.add("ready");
     runtimeText.textContent = "Python runtime ready";
-    ["runBtn", "arenaBtn", "capacityBtn", "topologyBtn", "designBtn", "pairedStudyBtn", "robustStudyBtn", "agentRunBtn", "agentCompareBtn", "agentTtlBtn", "agentMemoryCompareBtn", "agentBudgetBtn", "agentAffinityBtn"].forEach((id) => { $(id).disabled = false; });
+    ["runBtn", "arenaBtn", "capacityBtn", "topologyBtn", "designBtn", "pairedStudyBtn", "robustStudyBtn", "agentRunBtn", "agentCompareBtn", "agentTtlBtn", "agentMemoryCompareBtn", "agentBudgetBtn", "agentAffinityBtn", "predictiveCompareBtn", "predictiveAlphaBtn"].forEach((id) => { $(id).disabled = false; });
     syncConditionalControls();
     window.setTimeout(() => document.body.classList.add("runtime-ready"), 650);
     return;
@@ -780,6 +782,9 @@ function agentConfigFromUI(overrides = {}) {
     host_memory_gb: num("agentHostMemory"),
     host_bandwidth_gbps: num("agentHostBandwidth"),
     host_transfer_base_ms: num("agentHostBase"),
+    adaptive_predictor_scope: $("agentPredictorScope").value,
+    adaptive_alpha: num("agentPredictorAlpha"),
+    adaptive_min_observations: num("agentPredictorMin"),
     slo_turn_ttft_ms: num("agentTtftSlo"),
     slo_session_e2e_ms: num("agentSessionSlo"),
     ...overrides,
@@ -984,12 +989,119 @@ $("agentAffinityBtn").addEventListener("click", async () => {
 $("agentAffinityCopy").addEventListener("click", () => { if (lastAgentAffinity) copyText(tableText(agentAffinityHeaders, agentAffinityTableRows(lastAgentAffinity)), "Affinity sweep copied"); });
 $("agentAffinityCsv").addEventListener("click", () => { if (lastAgentAffinity) downloadCsv(`inferscale_agent-affinity-frontier_${stamp()}.csv`, agentAffinityHeaders, agentAffinityTableRows(lastAgentAffinity)); });
 
+
+const predictiveHeaders = ["Policy", "p95 turn TTFT", "p95 session E2E", "Session SLO", "Reuse", "Mean HBM", "Mean host", "Prediction MAE", "Oracle agreement", "Post-shift MAE", "Recomputed"];
+function predictiveTableRows(result) {
+  return result.rows.map((r) => [
+    r.label,
+    `${fmt(r.p95_turn_ttft_ms)} ms`,
+    `${fmt(r.p95_session_e2e_ms)} ms`,
+    pct(r.session_slo_attainment),
+    pct(r.cache_hit_rate),
+    `${fmt(r.mean_hbm_gb, 4)} GB`,
+    `${fmt(r.mean_host_gb, 4)} GB`,
+    r.prediction_count ? `${fmt(r.prediction_mae_s, 3)} s` : "N/A",
+    r.prediction_count ? pct(r.oracle_action_agreement) : "N/A",
+    r.prediction_count ? `${fmt(r.post_shift_mae_s, 3)} s` : "N/A",
+    `${fmt(r.recomputed_history_tokens, 0)} tok`,
+  ]);
+}
+function renderPredictiveStudy(result) {
+  lastPredictiveStudy = result;
+  $("predictiveEmpty").classList.add("hidden");
+  $("predictiveContent").classList.remove("hidden");
+  $("predictiveCompareBlock").classList.remove("hidden");
+  ["predictiveCopy", "predictiveCsv"].forEach((id) => { $(id).disabled = false; });
+  const nonOracle = result.rows.filter((r) => r.retention !== "gap_aware");
+  const best = [...nonOracle].sort((a, b) => a.p95_turn_ttft_ms - b.p95_turn_ttft_ms)[0];
+  const tool = result.rows.find((r) => r.label === "Adaptive per-tool EWMA");
+  $("predictiveBestTtft").textContent = best ? `${fmt(best.p95_turn_ttft_ms)} ms` : "N/A";
+  $("predictiveAgreement").textContent = tool ? pct(tool.oracle_action_agreement) : "N/A";
+  $("predictivePostMae").textContent = tool ? `${fmt(tool.post_shift_mae_s, 3)} s` : "N/A";
+  $("predictiveShiftValue").textContent = `${fmt(result.shift_fraction * 100, 0)}% / ${fmt(result.shift_multiplier, 2)}x`;
+  $("predictiveRows").innerHTML = result.rows.map((r) => `<tr><td>${escapeHtml(r.label)}</td><td>${fmt(r.p95_turn_ttft_ms)} ms</td><td>${fmt(r.p95_session_e2e_ms)} ms</td><td>${pct(r.session_slo_attainment)}</td><td>${pct(r.cache_hit_rate)}</td><td>${fmt(r.mean_hbm_gb, 4)} GB</td><td>${fmt(r.mean_host_gb, 4)} GB</td><td>${r.prediction_count ? `${fmt(r.prediction_mae_s, 3)} s` : "N/A"}</td><td>${r.prediction_count ? pct(r.oracle_action_agreement) : "N/A"}</td><td>${r.prediction_count ? `${fmt(r.post_shift_mae_s, 3)} s` : "N/A"}</td><td>${fmt(r.recomputed_history_tokens, 0)} tok</td></tr>`).join("");
+
+  const palette = [COLORS.amber, COLORS.steel, COLORS.purple, COLORS.blue, COLORS.green];
+  destroyChart("predictivePolicy");
+  charts.predictivePolicy = new Chart($("predictivePolicyChart"), {
+    type: "scatter",
+    data: { datasets: result.rows.map((r, i) => ({ label: r.label, data: [{ x: r.mean_hbm_gb, y: r.p95_turn_ttft_ms }], backgroundColor: palette[i], borderColor: palette[i], pointRadius: 7, pointHoverRadius: 9 })) },
+    options: { ...commonChartOptions(), parsing: false, scales: { x: { type: "linear", beginAtZero: true, title: { display: true, text: "Mean HBM KV (GB)" } }, y: { beginAtZero: true, title: { display: true, text: "p95 turn TTFT (ms)" } } } },
+  });
+
+  const globalCurve = result.learning_curves.global || [];
+  const toolCurve = result.learning_curves.per_tool || [];
+  const maxMae = Math.max(0.1, ...globalCurve.map((r) => r.rolling_mae_s), ...toolCurve.map((r) => r.rolling_mae_s));
+  const shiftX = result.shift_observation || 0;
+  const learningDatasets = [
+    { label: "Global EWMA rolling MAE", data: globalCurve.map((r) => ({ x: r.observation, y: r.rolling_mae_s })), borderColor: COLORS.steel, backgroundColor: COLORS.steel, pointRadius: 0, tension: .16, fill: false },
+    { label: "Per-tool EWMA rolling MAE", data: toolCurve.map((r) => ({ x: r.observation, y: r.rolling_mae_s })), borderColor: COLORS.blue, backgroundColor: COLORS.blue, pointRadius: 0, tension: .16, fill: false },
+  ];
+  if (shiftX > 0) learningDatasets.push({ label: "Regime shift", data: [{ x: shiftX, y: 0 }, { x: shiftX, y: maxMae }], borderColor: COLORS.amber, backgroundColor: COLORS.amber, pointRadius: 0, borderDash: [6, 5], fill: false });
+  destroyChart("predictiveLearning");
+  charts.predictiveLearning = new Chart($("predictiveLearningChart"), {
+    type: "line",
+    data: { datasets: learningDatasets },
+    options: { ...commonChartOptions(), parsing: false, plugins: { legend: lineLegend() }, scales: { x: { type: "linear", beginAtZero: true, title: { display: true, text: "Completed tool observations" } }, y: { beginAtZero: true, title: { display: true, text: "Rolling absolute error (s)" } } } },
+  });
+}
+function predictivePayload() {
+  return {
+    config: agentConfigFromUI({ routing_policy: "bounded_affinity" }),
+    horizon_s: num("predictiveHorizon"),
+    shift_fraction: num("predictiveShift"),
+    shift_multiplier: num("predictiveMultiplier"),
+    alpha: num("predictiveAlpha"),
+  };
+}
+$("predictiveCompareBtn").addEventListener("click", async () => {
+  const button = $("predictiveCompareBtn"); button.disabled = true; button.textContent = "Running predictive study...";
+  try { renderPredictiveStudy(await callPython("agent_predictive_tiering", predictivePayload())); }
+  catch (error) { alert(`Predictive tiering study failed: ${error.message}`); }
+  finally { button.disabled = false; button.textContent = "Compare predictive policies"; }
+});
+$("predictiveCopy").addEventListener("click", () => { if (lastPredictiveStudy) copyText(tableText(predictiveHeaders, predictiveTableRows(lastPredictiveStudy)), "Predictive-tiering table copied"); });
+$("predictiveCsv").addEventListener("click", () => { if (lastPredictiveStudy) downloadCsv(`inferscale_predictive-tiering_${stamp()}.csv`, predictiveHeaders, predictiveTableRows(lastPredictiveStudy)); });
+
+const predictiveAlphaHeaders = ["Alpha", "Pre-shift MAE", "Post-shift MAE", "Oracle agreement", "p95 TTFT", "p95 session E2E", "Session SLO", "Mean HBM", "Mean host"];
+function predictiveAlphaTableRows(result) {
+  return result.rows.map((r) => [fmt(r.alpha, 2), `${fmt(r.pre_shift_mae_s, 3)} s`, `${fmt(r.post_shift_mae_s, 3)} s`, pct(r.oracle_action_agreement), `${fmt(r.p95_turn_ttft_ms)} ms`, `${fmt(r.p95_session_e2e_ms)} ms`, pct(r.session_slo_attainment), `${fmt(r.mean_hbm_gb, 4)} GB`, `${fmt(r.mean_host_gb, 4)} GB`]);
+}
+function renderPredictiveAlpha(result) {
+  lastPredictiveAlpha = result;
+  $("predictiveEmpty").classList.add("hidden");
+  $("predictiveContent").classList.remove("hidden");
+  $("predictiveAlphaBlock").classList.remove("hidden");
+  ["predictiveAlphaCopy", "predictiveAlphaCsv"].forEach((id) => { $(id).disabled = false; });
+  $("predictiveAlphaCaption").textContent = `Adaptation-rate sweep (best post-shift alpha ${fmt(result.best_post_shift_alpha, 2)})`;
+  $("predictiveAlphaRows").innerHTML = result.rows.map((r) => `<tr><td>${fmt(r.alpha, 2)}</td><td>${fmt(r.pre_shift_mae_s, 3)} s</td><td>${fmt(r.post_shift_mae_s, 3)} s</td><td>${pct(r.oracle_action_agreement)}</td><td>${fmt(r.p95_turn_ttft_ms)} ms</td><td>${fmt(r.p95_session_e2e_ms)} ms</td><td>${pct(r.session_slo_attainment)}</td><td>${fmt(r.mean_hbm_gb, 4)} GB</td><td>${fmt(r.mean_host_gb, 4)} GB</td></tr>`).join("");
+  destroyChart("predictiveAlpha");
+  charts.predictiveAlpha = new Chart($("predictiveAlphaChart"), {
+    type: "line",
+    data: { datasets: [
+      { label: "Pre-shift MAE", data: result.rows.map((r) => ({ x: r.alpha, y: r.pre_shift_mae_s })), borderColor: COLORS.steel, backgroundColor: COLORS.steel, pointRadius: 4, tension: .12, fill: false },
+      { label: "Post-shift MAE", data: result.rows.map((r) => ({ x: r.alpha, y: r.post_shift_mae_s })), borderColor: COLORS.blue, backgroundColor: COLORS.blue, pointRadius: 4, tension: .12, fill: false },
+    ] },
+    options: { ...commonChartOptions(), parsing: false, plugins: { legend: lineLegend() }, scales: { x: { type: "linear", min: 0, max: 1, title: { display: true, text: "EWMA alpha" } }, y: { beginAtZero: true, title: { display: true, text: "Mean absolute error (s)" } } } },
+  });
+}
+$("predictiveAlphaBtn").addEventListener("click", async () => {
+  const button = $("predictiveAlphaBtn"); button.disabled = true; button.textContent = "Sweeping adaptation rate...";
+  const payload = predictivePayload();
+  try { renderPredictiveAlpha(await callPython("agent_adaptive_alpha_sweep", payload)); }
+  catch (error) { alert(`Adaptation-rate sweep failed: ${error.message}`); }
+  finally { button.disabled = false; button.textContent = "Sweep adaptation rate"; }
+});
+$("predictiveAlphaCopy").addEventListener("click", () => { if (lastPredictiveAlpha) copyText(tableText(predictiveAlphaHeaders, predictiveAlphaTableRows(lastPredictiveAlpha)), "Adaptation-rate table copied"); });
+$("predictiveAlphaCsv").addEventListener("click", () => { if (lastPredictiveAlpha) downloadCsv(`inferscale_adaptation-rate-sweep_${stamp()}.csv`, predictiveAlphaHeaders, predictiveAlphaTableRows(lastPredictiveAlpha)); });
+
 function syncAgentControls() {
   const retention = $("agentRetention").value;
   const routing = $("agentRouting").value;
-  const ttl = retention === "ttl";
-  const hostTier = retention === "offload" || retention === "gap_aware";
-  const gapAware = retention === "gap_aware";
+  const ttl = retention === "ttl" || adaptive;
+  const adaptive = retention === "adaptive";
+  const hostTier = retention === "offload" || retention === "gap_aware" || adaptive;
+  const gapAware = retention === "gap_aware" || adaptive;
   const bounded = routing === "bounded_affinity";
   $("agentTtl").disabled = !ttl;
   $("agentTtlLabel").classList.toggle("field-disabled", !ttl);
@@ -999,6 +1111,8 @@ function syncAgentControls() {
   $("agentGapThresholdLabel").classList.toggle("field-disabled", !gapAware);
   ["agentHostMemory", "agentHostBandwidth", "agentHostBase"].forEach((id) => { $(id).disabled = !hostTier; });
   ["agentHostMemoryLabel", "agentHostBandwidthLabel", "agentHostBaseLabel"].forEach((id) => { $(id).classList.toggle("field-disabled", !hostTier); });
+  ["agentPredictorScope", "agentPredictorAlpha", "agentPredictorMin"].forEach((id) => { $(id).disabled = !adaptive; });
+  ["agentPredictorScopeLabel", "agentPredictorAlphaLabel", "agentPredictorMinLabel"].forEach((id) => { $(id).classList.toggle("field-disabled", !adaptive); });
 }
 $("agentRetention").addEventListener("change", syncAgentControls);
 $("agentRouting").addEventListener("change", syncAgentControls);

docs/methodology.md

@@ -183,3 +183,45 @@ The estimator is intentionally simple and labeled as such. The Affinity Frontier
 The memory-budget experiment first runs a full-retention reference trace and records the unconstrained peak per-replica KV working set. It then expresses stress budgets as multiples of that trace-specific peak rather than arbitrary fractions of total accelerator VRAM. This makes the experiment meaningful even for small models whose default VRAM headroom would otherwise be far larger than the generated KV working set.
 
 Failed turns and incomplete sessions count against SLO attainment; latency percentiles remain conditional on turns/sessions that actually complete and are accompanied by failure counts in the experiment table.
+
+## Adaptive tool-gap prediction
+
+Agent traces attach a `tool_kind` to each non-final LLM turn. Reference tool families have different duration scales (`filesystem`, `search`, `database`, and `remote_api`) so a tool-aware predictor has an identifiable structure to learn. Tool identity is synthetic metadata used only by the agent-session simulator.
+
+The adaptive policy uses an online exponentially weighted moving average (EWMA). Two scopes are supported:
+
+- `global_ema`: one duration estimate shared by all tool families;
+- `per_tool_ema`: one estimate per tool family, with the global estimate used until the per-tool warm-up count is reached.
+
+No future tool duration is visible when the retention decision is made. When an LLM turn completes, the adaptive policy predicts the upcoming gap and chooses HBM retention or host offload using the same threshold as the oracle gap-aware baseline. The actual tool duration is added to predictor history only when the simulated tool call completes through a separate `tool_observed` event. A predicted HBM-retain decision is still capped by `kv_ttl_s`; this safety TTL prevents a severe under-prediction from pinning HBM indefinitely.
+
+This sequencing is important: directly updating the predictor at LLM-turn completion would leak the already-sampled future gap into the policy and make the adaptive result clairvoyant.
+
+## Non-stationary predictive-tiering study
+
+The Predictive Tiering Lab generates one common program trace and replays it across fixed and adaptive policies. At a configured fraction of the arrival horizon, the duration scale of slower external tools (`database` and `remote_api`) is multiplied by a user-selected factor. Faster local-style tools remain unchanged.
+
+The study compares:
+
+1. fixed TTL;
+2. unconditional host offload;
+3. adaptive global EWMA;
+4. adaptive per-tool EWMA;
+5. oracle gap-aware tiering.
+
+The oracle is not a deployable contender. It reads the realized future tool gap and exists only to expose an upper bound for the threshold-based decision rule.
+
+For adaptive candidates InferScale reports:
+
+- mean absolute tool-gap prediction error;
+- pre-shift and post-shift MAE;
+- agreement with the oracle retain/offload action;
+- serving p95 TTFT and session E2E;
+- SLO attainment;
+- HBM/host residency and recomputation.
+
+Prediction accuracy is intentionally not treated as the sole objective. Two predictors can have similar MAE while producing different queueing and memory behavior because only errors near the retention threshold change the tiering action.
+
+## Adaptation-rate sweep
+
+The EWMA alpha sweep replays the exact same shifted trace for every candidate alpha. Small alpha values smooth noise but react slowly after distribution shift; large values react quickly but can overfit individual long-tailed tool calls. InferScale therefore reports both pre-shift and post-shift error alongside system-level latency and memory metrics rather than presenting one global optimum.

docs/research.md

@@ -122,3 +122,27 @@ SMetric reports that aggressively routing agent turns to replicas that already c
 InferScale's **bounded-affinity** policy is a deliberately simple baseline: it follows the cached replica only while its estimated queue penalty remains within a configurable slack. The Affinity Frontier then sweeps that slack on one common trace.
 
 Source: https://arxiv.org/abs/2607.08565
+
+## Continuum / adaptive TTL for tool calls (May 2026)
+
+Continuum treats tool-call duration as a first-class signal for KV retention. It records historical tool-call information, estimates whether a program is likely to return within a candidate TTL, and balances the benefit of avoiding reload/prefill and queueing delay against the opportunity cost of pinning GPU memory. The paper also emphasizes robustness to highly variable tool durations rather than assuming clairvoyant tool completion times.
+
+InferScale inspiration: the new adaptive policy learns tool-duration estimates only from completed tool calls, keeps its oracle policy visibly separate, and exposes an explicit non-stationary shift experiment. InferScale's EWMA predictor is deliberately simpler than Continuum's cost/TTL model.
+
+Source: https://arxiv.org/abs/2511.02230
+
+## Predictive multi-tier KV memory (April/August 2026)
+
+Recent predictive KV-memory work combines a multi-tier memory hierarchy with online reuse prediction instead of relying only on reactive eviction. One 2026 design uses a Bayesian reuse predictor with per-class priors to guide eviction and prefetching across a much richer storage hierarchy than InferScale models.
+
+InferScale inspiration: measure prediction quality and systems outcomes together, and keep HBM/host placement decisions explicit. InferScale currently models only HBM plus host DRAM and uses transparent EWMA duration prediction; it does not reproduce the paper's six-tier hierarchy or Bayesian predictor.
+
+Source: https://arxiv.org/abs/2604.26968
+
+## CacheScout / learning agent execution online (July 2026)
+
+CacheScout argues that future KV reuse in multi-agent systems is governed by execution semantics rather than recency alone. It learns agent execution transitions online without requiring predefined workflow graphs or offline training, then uses the learned model for eviction and proactive prefetching.
+
+InferScale inspiration: move beyond an oracle or fixed TTL toward a policy that actually learns from runtime history. The current Predictive Tiering Lab learns tool-duration statistics, not workflow-transition graphs or prefetch decisions, so CacheScout remains a direction for deeper future work rather than a claimed reproduction.
+
+Source: https://arxiv.org/abs/2608.14624

index.html

@@ -363,15 +363,18 @@
           <hr />
           <div class="section-kicker">State policy</div>
           <div class="field-grid two">
-            <label>KV retention<select id="agentRetention"><option value="evict">Evict after every turn</option><option value="ttl" selected>TTL retention</option><option value="retain">Retain until session ends</option><option value="offload">Offload idle KV to host</option><option value="gap_aware">Oracle gap-aware HBM / host tiering</option></select></label>
+            <label>KV retention<select id="agentRetention"><option value="evict">Evict after every turn</option><option value="ttl" selected>TTL retention</option><option value="retain">Retain until session ends</option><option value="offload">Offload idle KV to host</option><option value="gap_aware">Oracle gap-aware HBM / host tiering</option><option value="adaptive">Adaptive tool-gap predictor</option></select></label>
             <label>Routing<select id="agentRouting"><option value="least_load">Least-load</option><option value="session_affinity" selected>Strict session affinity</option><option value="bounded_affinity">Bounded affinity</option></select></label>
-            <label id="agentTtlLabel">KV TTL<input id="agentTtl" type="number" min="0" step="0.25" value="3" /><span class="unit">s</span></label>
+            <label id="agentTtlLabel">KV / adaptive safety TTL<input id="agentTtl" type="number" min="0" step="0.25" value="3" /><span class="unit">s</span></label>
             <label>KV memory fraction<input id="agentKvFraction" type="number" min="0.01" max="0.98" step="0.05" value="0.85" /><span class="unit">fraction</span></label>
             <label id="agentAffinitySlackLabel">Affinity slack<input id="agentAffinitySlack" type="number" min="0" step="25" value="150" /><span class="unit">ms</span></label>
             <label id="agentGapThresholdLabel">Gap-aware HBM threshold<input id="agentGapThreshold" type="number" min="0" step="0.25" value="1.5" /><span class="unit">s</span></label>
             <label id="agentHostMemoryLabel">Host KV capacity<input id="agentHostMemory" type="number" min="0" step="4" value="32" /><span class="unit">GB</span></label>
             <label id="agentHostBandwidthLabel">Host transfer bandwidth<input id="agentHostBandwidth" type="number" min="0.1" step="1" value="32" /><span class="unit">GB/s</span></label>
             <label id="agentHostBaseLabel">Transfer base latency<input id="agentHostBase" type="number" min="0" step="0.05" value="0.15" /><span class="unit">ms</span></label>
+            <label id="agentPredictorScopeLabel">Adaptive predictor<select id="agentPredictorScope"><option value="per_tool_ema" selected>Per-tool EWMA</option><option value="global_ema">Global EWMA</option></select></label>
+            <label id="agentPredictorAlphaLabel">EWMA alpha<input id="agentPredictorAlpha" type="number" min="0.01" max="1" step="0.05" value="0.30" /><span class="unit">fraction</span></label>
+            <label id="agentPredictorMinLabel">Warm-up observations<input id="agentPredictorMin" type="number" min="1" max="20" step="1" value="2" /></label>
           </div>
           <div class="field-grid two">
             <label>Turn TTFT SLO<input id="agentTtftSlo" type="number" min="1" value="500" /><span class="unit">ms</span></label>
@@ -470,6 +473,48 @@
             </div>
           </section>
 
+          <section class="panel research-panel">
+            <div class="panel-title-row"><div><div class="section-kicker">Online prediction under workload shift</div><h2>Predictive Tiering Lab</h2><p class="muted">Replace the oracle tool-gap policy with online estimates learned only from completed tool calls. The study changes slow-tool latency partway through one common program trace, then measures whether global and per-tool predictors adapt without future-duration leakage.</p></div></div>
+            <div class="predictive-controls field-grid four">
+              <label>Study horizon<input id="predictiveHorizon" type="number" min="30" max="600" step="30" value="120" /><span class="unit">sim s</span></label>
+              <label>Shift point<input id="predictiveShift" type="number" min="0.1" max="0.9" step="0.05" value="0.55" /><span class="unit">fraction</span></label>
+              <label>Slow-tool multiplier<input id="predictiveMultiplier" type="number" min="1" max="6" step="0.25" value="2.5" /><span class="unit">x</span></label>
+              <label>Adaptive alpha<input id="predictiveAlpha" type="number" min="0.01" max="1" step="0.05" value="0.30" /><span class="unit">fraction</span></label>
+            </div>
+            <div class="stacked-actions horizontal-actions"><button id="predictiveCompareBtn" class="primary compact" disabled>Compare predictive policies</button><button id="predictiveAlphaBtn" class="primary compact" disabled>Sweep adaptation rate</button></div>
+            <div id="predictiveEmpty" class="empty-state small"><h3>No predictive-tiering experiment yet</h3><p>The adaptive policies use exponentially weighted tool-duration history. The oracle candidate is retained only as an upper bound; it can see the realized future gap while adaptive candidates cannot.</p></div>
+            <div id="predictiveContent" class="hidden">
+              <div id="predictiveCompareBlock" class="hidden">
+                <div class="metric-grid four">
+                  <div class="metric emphasis"><span>Best non-oracle p95 TTFT</span><strong id="predictiveBestTtft">N/A</strong></div>
+                  <div class="metric"><span>Per-tool oracle agreement</span><strong id="predictiveAgreement">N/A</strong></div>
+                  <div class="metric"><span>Post-shift MAE</span><strong id="predictivePostMae">N/A</strong></div>
+                  <div class="metric"><span>Shift point</span><strong id="predictiveShiftValue">N/A</strong></div>
+                </div>
+                <div class="chart-grid">
+                  <div class="chart-card" data-chart-card data-chart-name="agent-predictive-policy-tradeoff">
+                    <div class="chart-head"><div class="chart-title">Mean HBM residency vs p95 turn TTFT</div><div class="chart-actions"><button class="chart-download" type="button">Download PNG</button><button class="chart-expand" type="button">Expand</button></div></div>
+                    <div class="chart-body research-chart"><canvas id="predictivePolicyChart"></canvas></div>
+                  </div>
+                  <div class="chart-card" data-chart-card data-chart-name="agent-tool-gap-learning-curve">
+                    <div class="chart-head"><div class="chart-title">Online tool-gap prediction error</div><div class="chart-actions"><button class="chart-download" type="button">Download PNG</button><button class="chart-expand" type="button">Expand</button></div></div>
+                    <div class="chart-body research-chart"><canvas id="predictiveLearningChart"></canvas></div>
+                  </div>
+                </div>
+                <div class="table-toolbar"><span>Common shifted-trace policy results</span><div><button id="predictiveCopy" class="mini-button" disabled>Copy table</button><button id="predictiveCsv" class="mini-button" disabled>Download CSV</button></div></div>
+                <div class="table-wrap"><table><thead><tr><th>Policy</th><th>p95 turn TTFT</th><th>p95 session E2E</th><th>Session SLO</th><th>Reuse</th><th>Mean HBM</th><th>Mean host</th><th>Prediction MAE</th><th>Oracle agreement</th><th>Post-shift MAE</th><th>Recomputed</th></tr></thead><tbody id="predictiveRows"></tbody></table></div>
+              </div>
+              <div id="predictiveAlphaBlock" class="hidden experiment-subsection">
+                <div class="chart-card full" data-chart-card data-chart-name="agent-adaptation-rate-sweep">
+                  <div class="chart-head"><div class="chart-title">EWMA alpha vs prediction error before and after shift</div><div class="chart-actions"><button class="chart-download" type="button">Download PNG</button><button class="chart-expand" type="button">Expand</button></div></div>
+                  <div class="chart-body research-chart"><canvas id="predictiveAlphaChart"></canvas></div>
+                </div>
+                <div class="table-toolbar"><span id="predictiveAlphaCaption">Adaptation-rate sweep</span><div><button id="predictiveAlphaCopy" class="mini-button" disabled>Copy table</button><button id="predictiveAlphaCsv" class="mini-button" disabled>Download CSV</button></div></div>
+                <div class="table-wrap"><table><thead><tr><th>Alpha</th><th>Pre-shift MAE</th><th>Post-shift MAE</th><th>Oracle agreement</th><th>p95 TTFT</th><th>p95 session E2E</th><th>Session SLO</th><th>Mean HBM</th><th>Mean host</th></tr></thead><tbody id="predictiveAlphaRows"></tbody></table></div>
+              </div>
+            </div>
+          </section>
+
         </div>
       </div>
     </section>
@@ -480,10 +525,11 @@
         <article class="panel prose"><div class="section-kicker">Prefix reuse</div><h2>Cache without pretending to implement a radix tree</h2><p>The simulator models a single shared prompt prefix with configurable length and reuse fraction. Cache hits avoid redundant prefill work and share one persistent KV allocation. It is deliberately a controlled what-if abstraction, not a claim to reproduce SGLang's full RadixAttention policy.</p></article>
         <article class="panel prose"><div class="section-kicker">P/D disaggregation</div><h2>Role-specific resources and transfer cost</h2><p>Prefill and decode have separate accelerator profiles and worker counts. Prompt KV state crosses a modeled interconnect before decode admission. The simulator reports role utilization, transfer latency, and transfer pressure so the benefit of isolation can be weighed against data-movement overhead.</p></article>
         <article class="panel prose"><div class="section-kicker">Stateful agent sessions</div><h2>Tool gaps turn KV into a residency and routing decision</h2><p>Agent Sessions preserves program identity and turn order, materializes tool-induced gaps, and tracks HBM retention, TTL expiry, host-memory offload/restore, recomputation, and pressure eviction. Strict affinity, least-load, and bounded-affinity routing expose the tension between cache locality and hot-replica queueing. The per-replica service model remains intentionally serial so state-management effects are not confounded with dynamic batching.</p></article>
+        <article class="panel prose"><div class="section-kicker">Online adaptive tiering</div><h2>Prediction without future-gap leakage</h2><p>Adaptive tiering learns an exponentially weighted estimate from tool calls only after they complete. Global and per-tool predictors can be evaluated on the same non-stationary program trace, while an oracle policy that sees the realized future gap is kept separate as an upper bound. A shift experiment changes slower external-tool durations mid-trace to expose the stability-versus-adaptation trade-off.</p></article>
         <article class="panel prose"><div class="section-kicker">Design search</div><h2>Pareto, not one magic configuration</h2><p>The Design Explorer reports both a raw-performance frontier and a resource-normalized frontier using goodput per accelerator. That prevents a multi-GPU P/D layout from looking unconditionally better merely because it uses more simulated hardware.</p></article>
         <article class="panel prose"><div class="section-kicker">Trace methodology</div><h2>Generated load or exact replay</h2><p>Poisson, constant, and bursty workloads are open-loop: arrivals are scheduled independently of response completion, so queueing delay is not hidden by client backpressure. Exact CSV/JSON traces can be replayed with their original arrival times and token lengths.</p></article>
         <article class="panel prose"><div class="section-kicker">Research protocol</div><h2>Paired conclusions, not one lucky seed</h2><p>Research Studies use common random numbers: baseline and treatment receive identical seeds, reducing workload variance in the paired difference. A bootstrap interval summarizes the repeated effect, while a separate sensitivity study perturbs analytical latency scales to reveal conclusions that depend too strongly on one reference profile.</p></article>
-        <article class="panel prose wide-method"><div class="section-kicker">Research lineage</div><h2>Research lineage and scope</h2><p>Vidur established the value of simulation for avoiding expensive deployment sweeps. Recent systems have pushed toward heterogeneous and disaggregated serving, communication-aware modeling, stateful workloads, trace replay, and SLA-dependent design-space exploration. InferScale-Sim remains intentionally smaller and inspectable, with paired experiments and sensitivity analysis built into the workflow.</p><div class="paper-grid"><div><strong>Vidur / 2024</strong><span>Predictive profiling, workload-aware serving simulation, configuration search.</span></div><div><strong>TokenSim / 2025</strong><span>Extensible scheduling and memory-management simulation.</span></div><div><strong>Revati / 2026</strong><span>GPU-free time-warp emulation of serving control logic.</span></div><div><strong>LLMServingSim 2.0 / 2026</strong><span>Heterogeneous and disaggregated infrastructure, memory and communication.</span></div><div><strong>Frontier / May 2026</strong><span>P/D disaggregation, runtime optimizations, stateful workloads, Pareto exploration.</span></div><div><strong>HeteroPanacea / Aug 2026</strong><span>Heterogeneous stage specialization motivates resource-aware P/D comparison.</span></div><div><strong>Vanguard / Jun 2026</strong><span>Open-loop replay avoids coordinated omission when studying latency under load.</span></div><div><strong>AgentServeSim / Jun 2026</strong><span>Stateful multi-turn serving motivates session-aware workload modeling.</span></div><div><strong>IdleKV / Jun 2026</strong><span>Tool-call idle windows motivate explicit HBM-to-host KV offload experiments.</span></div><div><strong>SMetric / Jul 2026</strong><span>Cache-local routing can overload hot replicas, motivating bounded affinity.</span></div><div><strong>SGLang / RadixAttention</strong><span>Automatic shared-prefix KV reuse motivates the controlled cache scenario.</span></div></div></article>
+        <article class="panel prose wide-method"><div class="section-kicker">Research lineage</div><h2>Research lineage and scope</h2><p>Vidur established the value of simulation for avoiding expensive deployment sweeps. Recent systems have pushed toward heterogeneous and disaggregated serving, communication-aware modeling, stateful workloads, trace replay, and SLA-dependent design-space exploration. InferScale-Sim remains intentionally smaller and inspectable, with paired experiments and sensitivity analysis built into the workflow.</p><div class="paper-grid"><div><strong>Vidur / 2024</strong><span>Predictive profiling, workload-aware serving simulation, configuration search.</span></div><div><strong>TokenSim / 2025</strong><span>Extensible scheduling and memory-management simulation.</span></div><div><strong>Revati / 2026</strong><span>GPU-free time-warp emulation of serving control logic.</span></div><div><strong>LLMServingSim 2.0 / 2026</strong><span>Heterogeneous and disaggregated infrastructure, memory and communication.</span></div><div><strong>Frontier / May 2026</strong><span>P/D disaggregation, runtime optimizations, stateful workloads, Pareto exploration.</span></div><div><strong>HeteroPanacea / Aug 2026</strong><span>Heterogeneous stage specialization motivates resource-aware P/D comparison.</span></div><div><strong>Vanguard / Jun 2026</strong><span>Open-loop replay avoids coordinated omission when studying latency under load.</span></div><div><strong>AgentServeSim / Jun 2026</strong><span>Stateful multi-turn serving motivates session-aware workload modeling.</span></div><div><strong>IdleKV / Jun 2026</strong><span>Tool-call idle windows motivate explicit HBM-to-host KV offload experiments.</span></div><div><strong>SMetric / Jul 2026</strong><span>Cache-local routing can overload hot replicas, motivating bounded affinity.</span></div><div><strong>Continuum / May 2026</strong><span>Per-tool duration history and bounded TTL motivate adaptive retention without clairvoyance.</span></div><div><strong>CacheScout / Jul 2026</strong><span>Online learning of agent execution semantics motivates predictive rather than purely reactive KV management.</span></div><div><strong>Predictive KV Memory / Aug 2026 rev.</strong><span>Bayesian reuse prediction and multi-tier placement motivate explicit prediction-quality experiments.</span></div><div><strong>SGLang / RadixAttention</strong><span>Automatic shared-prefix KV reuse motivates the controlled cache scenario.</span></div></div></article>
       </div>
     </section>
   </main>

py/inferscale/__init__.py

@@ -1,4 +1,6 @@
 from .agentic import (
+    adaptive_alpha_sweep,
+    adaptive_tiering_study,
     agent_affinity_sweep,
     agent_memory_budget_sweep,
     compare_agent_memory_policies,
@@ -15,6 +17,8 @@ from .validation import validate_cases
 
 __all__ = [
     "SimulationConfig",
+    "adaptive_alpha_sweep",
+    "adaptive_tiering_study",
     "agent_affinity_sweep",
     "agent_memory_budget_sweep",
     "compare_agent_memory_policies",
@@ -35,4 +39,4 @@ __all__ = [
 
 # Internal package metadata only; the public project intentionally avoids
 # release/version branding in the interface and documentation.
-__version__ = "0.6.0"
+__version__ = "0.7.0"

py/inferscale/agentic.py

@@ -9,11 +9,20 @@ from typing import Any
 
 from .latency import AnalyticalLatencyModel
 from .metrics import percentile
+from .prediction import OnlineToolGapPredictor, PREDICTOR_SCOPES
 from .profiles import get_accelerator, get_model
 
 
 ROUTING_POLICIES = {"least_load", "session_affinity", "bounded_affinity"}
-RETENTION_POLICIES = {"evict", "retain", "ttl", "offload", "gap_aware"}
+RETENTION_POLICIES = {"evict", "retain", "ttl", "offload", "gap_aware", "adaptive"}
+
+TOOL_GAP_MULTIPLIERS = {
+    "filesystem": 0.45,
+    "search": 0.80,
+    "database": 1.25,
+    "remote_api": 2.20,
+}
+TOOL_WEIGHTS = (0.28, 0.32, 0.22, 0.18)
 
 
 @dataclass
@@ -44,6 +53,11 @@ class AgentSessionConfig:
     host_transfer_base_ms: float = 0.15
     affinity_slack_ms: float = 150.0
     gap_aware_threshold_s: float = 1.5
+    adaptive_predictor_scope: str = "per_tool_ema"
+    adaptive_alpha: float = 0.30
+    adaptive_min_observations: int = 2
+    tool_regime_shift_fraction: float = 0.0
+    tool_regime_shift_multiplier: float = 1.0
     slo_turn_ttft_ms: float = 500.0
     slo_session_e2e_ms: float = 30000.0
     timeline_points: int = 240
@@ -67,6 +81,12 @@ class AgentSessionConfig:
         cfg.host_transfer_base_ms = max(float(cfg.host_transfer_base_ms), 0.0)
         cfg.affinity_slack_ms = max(float(cfg.affinity_slack_ms), 0.0)
         cfg.gap_aware_threshold_s = max(float(cfg.gap_aware_threshold_s), 0.0)
+        if cfg.adaptive_predictor_scope not in PREDICTOR_SCOPES:
+            raise ValueError(f"Unsupported adaptive predictor scope: {cfg.adaptive_predictor_scope}")
+        cfg.adaptive_alpha = min(max(float(cfg.adaptive_alpha), 0.01), 1.0)
+        cfg.adaptive_min_observations = max(1, int(cfg.adaptive_min_observations))
+        cfg.tool_regime_shift_fraction = min(max(float(cfg.tool_regime_shift_fraction), 0.0), 0.95)
+        cfg.tool_regime_shift_multiplier = max(float(cfg.tool_regime_shift_multiplier), 0.1)
         return cfg
 
     def to_dict(self) -> dict[str, Any]:
@@ -80,6 +100,8 @@ class TurnSpec:
     append_tokens: int
     output_tokens: int
     tool_gap_after_s: float
+    tool_kind: str = "generic"
+    shifted_regime: bool = False
 
 
 @dataclass
@@ -161,13 +183,23 @@ def generate_agent_sessions(cfg: AgentSessionConfig) -> list[SessionSpec]:
         turns = max(2, _sample_int(rng, cfg.turns_mean, cfg.turns_cv, 2))
         initial = _sample_int(rng, cfg.initial_prompt_tokens_mean, cfg.token_cv, 32)
         specs = []
+        tool_names = tuple(TOOL_GAP_MULTIPLIERS)
+        shifted = cfg.tool_regime_shift_fraction > 0.0 and now >= cfg.duration_s * cfg.tool_regime_shift_fraction
         for turn_idx in range(turns):
             append = 0 if turn_idx == 0 else _sample_int(rng, cfg.append_tokens_mean, cfg.token_cv, 8)
             output = _sample_int(rng, cfg.output_tokens_mean, cfg.output_tokens_cv, 1)
-            gap = 0.0 if turn_idx == turns - 1 else _sample_positive_lognormal(
-                rng, cfg.tool_gap_mean_s, cfg.tool_gap_cv, 0.0
-            )
-            specs.append(TurnSpec(sid, turn_idx, append, output, gap))
+            tool_kind = rng.choices(tool_names, weights=TOOL_WEIGHTS, k=1)[0]
+            if turn_idx == turns - 1:
+                gap = 0.0
+            else:
+                mean_gap = cfg.tool_gap_mean_s * TOOL_GAP_MULTIPLIERS[tool_kind]
+                # The optional shift deliberately changes only the slower external
+                # tools. This creates a non-stationary workload where a global
+                # duration average is less informative than tool-aware history.
+                if shifted and tool_kind in {"database", "remote_api"}:
+                    mean_gap *= cfg.tool_regime_shift_multiplier
+                gap = _sample_positive_lognormal(rng, mean_gap, cfg.tool_gap_cv, 0.0)
+            specs.append(TurnSpec(sid, turn_idx, append, output, gap, tool_kind, shifted))
         sessions.append(SessionSpec(sid, now, initial, specs))
         sid += 1
     return sessions
@@ -224,6 +256,13 @@ class AgentSessionSimulator:
         self.route_opportunities = 0
         self.failed_turns = 0
         self.tool_gap_total_s = 0.0
+        self.tool_gap_predictor = OnlineToolGapPredictor(
+            initial_mean_s=cfg.tool_gap_mean_s,
+            alpha=cfg.adaptive_alpha,
+            min_observations=cfg.adaptive_min_observations,
+            scope=cfg.adaptive_predictor_scope,
+        )
+        self.prediction_rows: list[dict[str, Any]] = []
         for session in specs:
             if session.turns:
                 self._push(session.arrival_time, "turn_ready", session.session_id, 0)
@@ -406,7 +445,7 @@ class AgentSessionSimulator:
         previous = replica.cache.get(session_id)
         generation = (previous.generation + 1) if previous else 1
         expiry: float | None = None
-        if keep and self.cfg.retention_policy == "ttl":
+        if keep and self.cfg.retention_policy in {"ttl", "adaptive"}:
             expiry = self.now + self.cfg.kv_ttl_s
         replica.cache[session_id] = CacheEntry(session_id, tokens, size_gb, self.now, expiry, generation)
         self.peak_kv_gb = max(self.peak_kv_gb, self._used_gb())
@@ -542,6 +581,31 @@ class AgentSessionSimulator:
                 state_action = "offload_host_long_gap"
             else:
                 state_action = "evict_host_full"
+        elif self.cfg.retention_policy == "adaptive":
+            predicted_gap_s, prediction_source, history_count = self.tool_gap_predictor.predict(turn.tool_kind)
+            predicted_retain = predicted_gap_s <= self.cfg.gap_aware_threshold_s
+            oracle_retain = turn.tool_gap_after_s <= self.cfg.gap_aware_threshold_s
+            if predicted_retain:
+                self._put_cache(replica, session_id, projected_tokens, keep=True)
+                state_action = "adaptive_retain_hbm"
+            elif self._offload_cache(replica, session_id, projected_tokens):
+                state_action = "adaptive_offload_host"
+            else:
+                state_action = "adaptive_evict_host_full"
+            self.prediction_rows.append({
+                "session_id": session_id,
+                "turn_index": turn_index + 1,
+                "tool_kind": turn.tool_kind,
+                "shifted_regime": turn.shifted_regime,
+                "predicted_gap_s": predicted_gap_s,
+                "actual_gap_s": turn.tool_gap_after_s,
+                "absolute_error_s": abs(predicted_gap_s - turn.tool_gap_after_s),
+                "prediction_source": prediction_source,
+                "history_count": history_count,
+                "predicted_action": "retain" if predicted_retain else "offload",
+                "oracle_action": "retain" if oracle_retain else "offload",
+                "action_match": predicted_retain == oracle_retain,
+            })
 
         e2e_ms = (self.now - ready_time) * 1000.0
         self.turn_rows.append(
@@ -555,6 +619,9 @@ class AgentSessionSimulator:
                 "cache_source": cache_source,
                 "restore_ms": restore_s * 1000.0,
                 "state_action": state_action,
+                "tool_kind": turn.tool_kind,
+                "tool_gap_after_s": turn.tool_gap_after_s,
+                "shifted_regime": turn.shifted_regime,
                 "prefill_tokens": prefill_tokens,
                 "context_tokens_after": projected_tokens,
                 "output_tokens": turn.output_tokens,
@@ -568,7 +635,9 @@ class AgentSessionSimulator:
             runtime.completion_time = self.now
         else:
             self.tool_gap_total_s += turn.tool_gap_after_s
-            self._push(self.now + turn.tool_gap_after_s, "turn_ready", session_id, turn_index + 1)
+            observed_at = self.now + turn.tool_gap_after_s
+            self._push(observed_at, "tool_observed", turn.tool_kind, turn.tool_gap_after_s)
+            self._push(observed_at, "turn_ready", session_id, turn_index + 1)
         self._start_next(replica)
 
     def run(self) -> dict[str, Any]:
@@ -577,7 +646,9 @@ class AgentSessionSimulator:
             event_time, _, kind, payload = heapq.heappop(self.events)
             self._integrate_memory(event_time)
             self.now = event_time
-            if kind == "turn_ready":
+            if kind == "tool_observed":
+                self.tool_gap_predictor.observe(str(payload[0]), float(payload[1]))
+            elif kind == "turn_ready":
                 session_id, turn_index = int(payload[0]), int(payload[1])
                 turn = self.sessions[session_id].spec.turns[turn_index]
                 replica = self._route(session_id)
@@ -641,6 +712,8 @@ class AgentSessionSimulator:
         }
         host_restore_p95_ms = percentile(self.host_transfer_latencies_ms, 0.95)
         total_reuse_hits = self.cache_hits + self.host_cache_hits
+        prediction_errors = [float(row["absolute_error_s"]) for row in self.prediction_rows]
+        prediction_matches = [bool(row["action_match"]) for row in self.prediction_rows]
         resource = {
             "replicas": self.cfg.replicas,
             "kv_capacity_gb_per_replica": self.kv_capacity_gb,
@@ -667,6 +740,13 @@ class AgentSessionSimulator:
             "restored_gb": self.restore_bytes / 1e9,
             "p95_host_transfer_ms": host_restore_p95_ms,
             "tool_gap_total_s": self.tool_gap_total_s,
+            "adaptive_prediction_count": len(self.prediction_rows),
+            "adaptive_prediction_mae_s": mean(prediction_errors) if prediction_errors else 0.0,
+            "adaptive_prediction_p95_abs_error_s": percentile(prediction_errors, 0.95),
+            "adaptive_oracle_action_agreement": (
+                sum(1 for match in prediction_matches if match) / len(prediction_matches)
+                if prediction_matches else 0.0
+            ),
         }
         return {
             "config": self.cfg.to_dict(),
@@ -677,12 +757,19 @@ class AgentSessionSimulator:
                 "agent_service_model": "serial-per-replica-reference",
                 "host_tier_model": "serialized-reference-transfer",
                 "gap_aware_policy": "oracle-upper-bound" if self.cfg.retention_policy == "gap_aware" else "not-active",
+                "adaptive_policy": (
+                    "online-tool-gap-ewma-no-lookahead" if self.cfg.retention_policy == "adaptive" else "not-active"
+                ),
                 "warning": "Agent-session mode isolates routing/KV-retention effects and does not model dynamic batching within each replica.",
             },
             "summary": summary,
             "latency": latency,
             "resource": resource,
             "turns": successful_turns[:3000],
+            "prediction": {
+                "rows": self.prediction_rows[:3000],
+                "predictor": self.tool_gap_predictor.snapshot(),
+            },
             "sessions": [
                 {
                     "session_id": s.spec.session_id,
@@ -957,3 +1044,192 @@ def agent_affinity_sweep(config: dict[str, Any], slack_values_ms: list[float] |
         "study": "bounded-affinity-routing-frontier",
         "rows": rows,
     }
+
+
+def _prediction_phase_metrics(result: dict[str, Any]) -> dict[str, float]:
+    rows = result.get("prediction", {}).get("rows", [])
+    before = [row for row in rows if not row.get("shifted_regime")]
+    after = [row for row in rows if row.get("shifted_regime")]
+
+    def phase(items: list[dict[str, Any]]) -> tuple[float, float]:
+        if not items:
+            return 0.0, 0.0
+        mae = mean(float(row["absolute_error_s"]) for row in items)
+        agreement = sum(1 for row in items if row.get("action_match")) / len(items)
+        return mae, agreement
+
+    pre_mae, pre_agreement = phase(before)
+    post_mae, post_agreement = phase(after)
+    return {
+        "pre_shift_mae_s": pre_mae,
+        "post_shift_mae_s": post_mae,
+        "pre_shift_action_agreement": pre_agreement,
+        "post_shift_action_agreement": post_agreement,
+    }
+
+
+def _rolling_prediction_curve(result: dict[str, Any], window: int = 16) -> list[dict[str, Any]]:
+    rows = result.get("prediction", {}).get("rows", [])
+    if not rows:
+        return []
+    points: list[dict[str, Any]] = []
+    width = max(4, min(int(window), 64))
+    for idx in range(len(rows)):
+        start = max(0, idx - width + 1)
+        chunk = rows[start : idx + 1]
+        points.append(
+            {
+                "observation": idx + 1,
+                "rolling_mae_s": mean(float(row["absolute_error_s"]) for row in chunk),
+                "rolling_action_agreement": sum(1 for row in chunk if row.get("action_match")) / len(chunk),
+                "tool_kind": rows[idx].get("tool_kind", "generic"),
+                "shifted_regime": bool(rows[idx].get("shifted_regime")),
+            }
+        )
+    return points
+
+
+def adaptive_tiering_study(
+    config: dict[str, Any],
+    *,
+    horizon_s: float = 120.0,
+    shift_fraction: float = 0.55,
+    shift_multiplier: float = 2.5,
+    alpha: float = 0.30,
+) -> dict[str, Any]:
+    """Compare fixed, adaptive, and oracle KV tiering on one non-stationary trace.
+
+    The adaptive candidates never inspect the realized future tool duration at
+    decision time. They learn an EWMA online from completed tool calls. The
+    oracle candidate intentionally sees the realized gap and serves only as an
+    upper bound.
+    """
+    base = AgentSessionConfig.from_dict(config)
+    base.duration_s = max(float(horizon_s), 30.0)
+    base.tool_regime_shift_fraction = min(max(float(shift_fraction), 0.05), 0.95)
+    base.tool_regime_shift_multiplier = max(float(shift_multiplier), 1.0)
+    base.adaptive_alpha = min(max(float(alpha), 0.01), 1.0)
+    base.routing_policy = "bounded_affinity"
+    trace = generate_agent_sessions(base)
+
+    candidates = [
+        ("Fixed TTL", "ttl", "per_tool_ema"),
+        ("Always host offload", "offload", "per_tool_ema"),
+        ("Adaptive global EWMA", "adaptive", "global_ema"),
+        ("Adaptive per-tool EWMA", "adaptive", "per_tool_ema"),
+        ("Oracle gap-aware", "gap_aware", "per_tool_ema"),
+    ]
+    rows: list[dict[str, Any]] = []
+    results: dict[str, dict[str, Any]] = {}
+    for label, retention, scope in candidates:
+        cfg = AgentSessionConfig.from_dict(base.to_dict())
+        cfg.retention_policy = retention
+        cfg.adaptive_predictor_scope = scope
+        result = run_agent_session_simulation(cfg.to_dict(), trace)
+        results[label] = result
+        phase = _prediction_phase_metrics(result)
+        rows.append(
+            {
+                "label": label,
+                "retention": retention,
+                "predictor_scope": scope if retention == "adaptive" else "not-active",
+                "p95_turn_ttft_ms": result["latency"]["turn_ttft_ms"]["p95"],
+                "p95_session_e2e_ms": result["latency"]["session_e2e_ms"]["p95"],
+                "session_slo_attainment": result["summary"]["session_slo_attainment"],
+                "cache_hit_rate": result["resource"]["cross_turn_cache_hit_rate"],
+                "mean_hbm_gb": result["resource"]["mean_kv_gb"],
+                "mean_host_gb": result["resource"]["mean_host_kv_gb"],
+                "recomputed_history_tokens": result["resource"]["recomputed_history_tokens"],
+                "prediction_count": result["resource"].get("adaptive_prediction_count", 0),
+                "prediction_mae_s": result["resource"].get("adaptive_prediction_mae_s", 0.0),
+                "oracle_action_agreement": result["resource"].get("adaptive_oracle_action_agreement", 0.0),
+                **phase,
+            }
+        )
+
+    global_result = results["Adaptive global EWMA"]
+    tool_result = results["Adaptive per-tool EWMA"]
+    shift_observation = next(
+        (
+            idx + 1
+            for idx, row in enumerate(tool_result.get("prediction", {}).get("rows", []))
+            if row.get("shifted_regime")
+        ),
+        0,
+    )
+    return {
+        "protocol": "common-nonstationary-agent-program-trace",
+        "study": "online-predictive-kv-tiering",
+        "horizon_s": base.duration_s,
+        "shift_fraction": base.tool_regime_shift_fraction,
+        "shift_multiplier": base.tool_regime_shift_multiplier,
+        "shift_time_s": base.duration_s * base.tool_regime_shift_fraction,
+        "shift_observation": shift_observation,
+        "threshold_s": base.gap_aware_threshold_s,
+        "alpha": base.adaptive_alpha,
+        "rows": rows,
+        "learning_curves": {
+            "global": _rolling_prediction_curve(global_result),
+            "per_tool": _rolling_prediction_curve(tool_result),
+        },
+        "tool_profiles": TOOL_GAP_MULTIPLIERS,
+        "note": (
+            "The oracle gap-aware candidate sees realized future tool gaps and is an upper bound. "
+            "Adaptive candidates learn only from tool calls that have already completed."
+        ),
+    }
+
+
+def adaptive_alpha_sweep(
+    config: dict[str, Any],
+    alpha_values: list[float] | None = None,
+    *,
+    horizon_s: float = 120.0,
+    shift_fraction: float = 0.55,
+    shift_multiplier: float = 2.5,
+) -> dict[str, Any]:
+    """Sweep EWMA adaptation speed on one shifted trace.
+
+    Lower alpha values are stable but adapt slowly; high values react quickly but
+    are noisier. The study reports both pre- and post-shift prediction error and
+    the resulting serving metrics.
+    """
+    base = AgentSessionConfig.from_dict(config)
+    base.duration_s = max(float(horizon_s), 30.0)
+    base.tool_regime_shift_fraction = min(max(float(shift_fraction), 0.05), 0.95)
+    base.tool_regime_shift_multiplier = max(float(shift_multiplier), 1.0)
+    base.retention_policy = "adaptive"
+    base.routing_policy = "bounded_affinity"
+    base.adaptive_predictor_scope = "per_tool_ema"
+    trace = generate_agent_sessions(base)
+    values = alpha_values or [0.05, 0.10, 0.20, 0.30, 0.50, 0.75, 1.00]
+    cleaned = sorted({min(max(float(value), 0.01), 1.0) for value in values})
+    rows: list[dict[str, Any]] = []
+    for alpha in cleaned:
+        cfg = AgentSessionConfig.from_dict(base.to_dict())
+        cfg.adaptive_alpha = alpha
+        result = run_agent_session_simulation(cfg.to_dict(), trace)
+        phase = _prediction_phase_metrics(result)
+        rows.append(
+            {
+                "alpha": alpha,
+                "prediction_mae_s": result["resource"]["adaptive_prediction_mae_s"],
+                "oracle_action_agreement": result["resource"]["adaptive_oracle_action_agreement"],
+                "p95_turn_ttft_ms": result["latency"]["turn_ttft_ms"]["p95"],
+                "p95_session_e2e_ms": result["latency"]["session_e2e_ms"]["p95"],
+                "session_slo_attainment": result["summary"]["session_slo_attainment"],
+                "mean_hbm_gb": result["resource"]["mean_kv_gb"],
+                "mean_host_gb": result["resource"]["mean_host_kv_gb"],
+                **phase,
+            }
+        )
+    best_post = min(rows, key=lambda row: (row["post_shift_mae_s"], row["p95_turn_ttft_ms"])) if rows else None
+    return {
+        "protocol": "common-nonstationary-agent-program-trace",
+        "study": "adaptive-ewma-rate-sweep",
+        "shift_fraction": base.tool_regime_shift_fraction,
+        "shift_multiplier": base.tool_regime_shift_multiplier,
+        "rows": rows,
+        "best_post_shift_alpha": best_post["alpha"] if best_post else None,
+        "note": "Alpha controls adaptation speed; this is an online heuristic study, not a learned model benchmark.",
+    }

py/inferscale/api.py

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
 from .agentic import (
+    adaptive_alpha_sweep,
+    adaptive_tiering_study,
     agent_affinity_sweep,
     agent_memory_budget_sweep,
     compare_agent_memory_policies,
@@ -25,6 +27,7 @@ def metadata() -> dict:
         "agentic_modes": [
             "session_simulation", "policy_compare", "ttl_sweep",
             "memory_policy_compare", "memory_budget_sweep", "affinity_sweep",
+            "predictive_tiering", "adaptive_alpha_sweep",
         ],
     }
 
@@ -71,6 +74,22 @@ def execute(action: str, payload: dict) -> dict:
         return agent_memory_budget_sweep(payload.get("config", payload), payload.get("budget_multipliers"))
     if action == "agent_affinity_sweep":
         return agent_affinity_sweep(payload.get("config", payload), payload.get("slack_values_ms"))
+    if action == "agent_predictive_tiering":
+        return adaptive_tiering_study(
+            payload.get("config", payload),
+            horizon_s=float(payload.get("horizon_s", 120.0)),
+            shift_fraction=float(payload.get("shift_fraction", 0.55)),
+            shift_multiplier=float(payload.get("shift_multiplier", 2.5)),
+            alpha=float(payload.get("alpha", 0.30)),
+        )
+    if action == "agent_adaptive_alpha_sweep":
+        return adaptive_alpha_sweep(
+            payload.get("config", payload),
+            payload.get("alpha_values"),
+            horizon_s=float(payload.get("horizon_s", 120.0)),
+            shift_fraction=float(payload.get("shift_fraction", 0.55)),
+            shift_multiplier=float(payload.get("shift_multiplier", 2.5)),
+        )
     if action == "robustness_study":
         config = payload.get("config", payload)
         return robustness_study(

py/inferscale/prediction.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+PREDICTOR_SCOPES = {"global_ema", "per_tool_ema"}
+
+
+@dataclass
+class _Estimate:
+    mean_s: float
+    count: int = 0
+
+
+class OnlineToolGapPredictor:
+    """Tiny online tool-duration predictor used by adaptive KV tiering.
+
+    The predictor deliberately stays transparent: it keeps an exponentially
+    weighted moving average (EWMA) of observed tool-call durations. In
+    ``per_tool_ema`` mode each tool family gets its own estimate, backed by a
+    global EWMA until enough observations have arrived. No future tool duration
+    is visible at decision time.
+    """
+
+    def __init__(
+        self,
+        *,
+        initial_mean_s: float,
+        alpha: float = 0.30,
+        min_observations: int = 2,
+        scope: str = "per_tool_ema",
+    ) -> None:
+        if scope not in PREDICTOR_SCOPES:
+            raise ValueError(f"Unsupported predictor scope: {scope}")
+        self.scope = scope
+        self.alpha = min(max(float(alpha), 0.01), 1.0)
+        self.min_observations = max(int(min_observations), 1)
+        self.global_estimate = _Estimate(max(float(initial_mean_s), 0.0), 0)
+        self.per_tool: dict[str, _Estimate] = {}
+
+    @staticmethod
+    def _update(estimate: _Estimate, value_s: float, alpha: float) -> None:
+        value_s = max(float(value_s), 0.0)
+        if estimate.count == 0:
+            estimate.mean_s = value_s
+        else:
+            estimate.mean_s = alpha * value_s + (1.0 - alpha) * estimate.mean_s
+        estimate.count += 1
+
+    def predict(self, tool_kind: str) -> tuple[float, str, int]:
+        if self.scope == "per_tool_ema":
+            estimate = self.per_tool.get(tool_kind)
+            if estimate is not None and estimate.count >= self.min_observations:
+                return estimate.mean_s, "tool", estimate.count
+        return self.global_estimate.mean_s, "global", self.global_estimate.count
+
+    def observe(self, tool_kind: str, duration_s: float) -> None:
+        self._update(self.global_estimate, duration_s, self.alpha)
+        estimate = self.per_tool.setdefault(tool_kind, _Estimate(self.global_estimate.mean_s, 0))
+        self._update(estimate, duration_s, self.alpha)
+
+    def snapshot(self) -> dict:
+        return {
+            "scope": self.scope,
+            "alpha": self.alpha,
+            "min_observations": self.min_observations,
+            "global": {"mean_s": self.global_estimate.mean_s, "count": self.global_estimate.count},
+            "per_tool": {
+                key: {"mean_s": value.mean_s, "count": value.count}
+                for key, value in sorted(self.per_tool.items())
+            },
+        }

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "inferscale-sim"
-version = "0.6.0"
+version = "0.7.0"
 description = "Interactive LLM serving simulator and SLO capacity planner"
 readme = "README.md"
 requires-python = ">=3.10"

scripts/release_check.py

@@ -14,6 +14,8 @@ inferscale = importlib.import_module("inferscale")
 internal_version = inferscale.__version__
 design_space_search = inferscale.design_space_search
 compare_agent_policies = inferscale.compare_agent_policies
+adaptive_tiering_study = inferscale.adaptive_tiering_study
+adaptive_alpha_sweep = inferscale.adaptive_alpha_sweep
 compare_agent_memory_policies = inferscale.compare_agent_memory_policies
 agent_memory_budget_sweep = inferscale.agent_memory_budget_sweep
 agent_affinity_sweep = inferscale.agent_affinity_sweep
@@ -37,8 +39,8 @@ else:
 
 if "sdk: static" not in README:
     errors.append("README metadata must use sdk: static")
-if internal_version != "0.6.0":
-    errors.append(f"internal package version is {internal_version}; expected 0.6.0")
+if internal_version != "0.7.0":
+    errors.append(f"internal package version is {internal_version}; expected 0.7.0")
 
 # Public-facing release/version branding is intentionally absent. Model names
 # such as Mistral-7B-v0.3 are allowed; project headings/badges are not.
@@ -77,7 +79,7 @@ if "Download PNG" not in index or ".chart-download" not in app:
     errors.append("chart PNG export controls are missing")
 if "Worst repetition" not in index or "Target" not in index:
     errors.append("capacity evidence columns are missing")
-for expected in ["Trace replay", "Research Studies", "Run paired study", "Stress-test selected hypothesis", "Agent Sessions", "Session Policy Arena", "TTL frontier", "Agent Memory Lab", "Affinity Frontier", "Stress HBM budget"]:
+for expected in ["Trace replay", "Research Studies", "Run paired study", "Stress-test selected hypothesis", "Agent Sessions", "Session Policy Arena", "TTL frontier", "Agent Memory Lab", "Affinity Frontier", "Stress HBM budget", "Predictive Tiering Lab", "Compare predictive policies", "Sweep adaptation rate"]:
     if expected not in index:
         errors.append(f"UI is missing research/trace feature: {expected}")
 
@@ -197,6 +199,27 @@ try:
     agent_affinity = agent_affinity_sweep(agent_cfg, [0, 150, 600])
     if len(agent_affinity.get("rows", [])) != 3:
         errors.append("bounded-affinity sweep is incomplete")
+    adaptive = run_agent_session_simulation(agent_cfg | {
+        "retention_policy": "adaptive",
+        "routing_policy": "bounded_affinity",
+        "adaptive_predictor_scope": "per_tool_ema",
+    })
+    if adaptive["provenance"].get("adaptive_policy") != "online-tool-gap-ewma-no-lookahead":
+        errors.append("adaptive policy provenance guard is missing")
+    if adaptive["resource"].get("adaptive_prediction_count", 0) <= 0:
+        errors.append("adaptive policy produced no tool-gap predictions")
+    predictive = adaptive_tiering_study(
+        agent_cfg | {"host_memory_gb": 4, "routing_policy": "bounded_affinity"},
+        horizon_s=40, shift_fraction=0.5, shift_multiplier=2.0, alpha=0.3,
+    )
+    if len(predictive.get("rows", [])) != 5 or predictive.get("shift_observation", 0) <= 0:
+        errors.append("predictive tiering study is incomplete")
+    alpha_sweep = adaptive_alpha_sweep(
+        agent_cfg | {"host_memory_gb": 4, "routing_policy": "bounded_affinity"},
+        [0.1, 0.3, 0.8], horizon_s=40, shift_fraction=0.5, shift_multiplier=2.0,
+    )
+    if len(alpha_sweep.get("rows", [])) != 3:
+        errors.append("adaptation-rate sweep is incomplete")
 except Exception as exc:  # pragma: no cover
     errors.append(f"agent-session smoke test raised: {exc}")
 
@@ -232,5 +255,8 @@ print(f"Agent TTL candidates: {len(agent_ttl['rows'])}")
 print(f"Agent memory policies: {agent_memory['candidate_count']}")
 print(f"HBM budget study rows: {len(agent_budget['rows'])}")
 print(f"Affinity sweep points: {len(agent_affinity['rows'])}")
+print(f"Adaptive predictions: {adaptive['resource']['adaptive_prediction_count']}")
+print(f"Predictive-tiering candidates: {len(predictive['rows'])}")
+print(f"Adaptation-rate points: {len(alpha_sweep['rows'])}")
 print(f"Validation observations: {validation['observation_count']}")
 print(f"Profile provenance: {smoke['provenance']['latency_profile_type']}")

src/inferscale/__init__.py

@@ -1,4 +1,6 @@
 from .agentic import (
+    adaptive_alpha_sweep,
+    adaptive_tiering_study,
     agent_affinity_sweep,
     agent_memory_budget_sweep,
     compare_agent_memory_policies,
@@ -15,6 +17,8 @@ from .validation import validate_cases
 
 __all__ = [
     "SimulationConfig",
+    "adaptive_alpha_sweep",
+    "adaptive_tiering_study",
     "agent_affinity_sweep",
     "agent_memory_budget_sweep",
     "compare_agent_memory_policies",
@@ -35,4 +39,4 @@ __all__ = [
 
 # Internal package metadata only; the public project intentionally avoids
 # release/version branding in the interface and documentation.
-__version__ = "0.6.0"
+__version__ = "0.7.0"

src/inferscale/agentic.py

@@ -9,11 +9,20 @@ from typing import Any
 
 from .latency import AnalyticalLatencyModel
 from .metrics import percentile
+from .prediction import OnlineToolGapPredictor, PREDICTOR_SCOPES
 from .profiles import get_accelerator, get_model
 
 
 ROUTING_POLICIES = {"least_load", "session_affinity", "bounded_affinity"}
-RETENTION_POLICIES = {"evict", "retain", "ttl", "offload", "gap_aware"}
+RETENTION_POLICIES = {"evict", "retain", "ttl", "offload", "gap_aware", "adaptive"}
+
+TOOL_GAP_MULTIPLIERS = {
+    "filesystem": 0.45,
+    "search": 0.80,
+    "database": 1.25,
+    "remote_api": 2.20,
+}
+TOOL_WEIGHTS = (0.28, 0.32, 0.22, 0.18)
 
 
 @dataclass
@@ -44,6 +53,11 @@ class AgentSessionConfig:
     host_transfer_base_ms: float = 0.15
     affinity_slack_ms: float = 150.0
     gap_aware_threshold_s: float = 1.5
+    adaptive_predictor_scope: str = "per_tool_ema"
+    adaptive_alpha: float = 0.30
+    adaptive_min_observations: int = 2
+    tool_regime_shift_fraction: float = 0.0
+    tool_regime_shift_multiplier: float = 1.0
     slo_turn_ttft_ms: float = 500.0
     slo_session_e2e_ms: float = 30000.0
     timeline_points: int = 240
@@ -67,6 +81,12 @@ class AgentSessionConfig:
         cfg.host_transfer_base_ms = max(float(cfg.host_transfer_base_ms), 0.0)
         cfg.affinity_slack_ms = max(float(cfg.affinity_slack_ms), 0.0)
         cfg.gap_aware_threshold_s = max(float(cfg.gap_aware_threshold_s), 0.0)
+        if cfg.adaptive_predictor_scope not in PREDICTOR_SCOPES:
+            raise ValueError(f"Unsupported adaptive predictor scope: {cfg.adaptive_predictor_scope}")
+        cfg.adaptive_alpha = min(max(float(cfg.adaptive_alpha), 0.01), 1.0)
+        cfg.adaptive_min_observations = max(1, int(cfg.adaptive_min_observations))
+        cfg.tool_regime_shift_fraction = min(max(float(cfg.tool_regime_shift_fraction), 0.0), 0.95)
+        cfg.tool_regime_shift_multiplier = max(float(cfg.tool_regime_shift_multiplier), 0.1)
         return cfg
 
     def to_dict(self) -> dict[str, Any]:
@@ -80,6 +100,8 @@ class TurnSpec:
     append_tokens: int
     output_tokens: int
     tool_gap_after_s: float
+    tool_kind: str = "generic"
+    shifted_regime: bool = False
 
 
 @dataclass
@@ -161,13 +183,23 @@ def generate_agent_sessions(cfg: AgentSessionConfig) -> list[SessionSpec]:
         turns = max(2, _sample_int(rng, cfg.turns_mean, cfg.turns_cv, 2))
         initial = _sample_int(rng, cfg.initial_prompt_tokens_mean, cfg.token_cv, 32)
         specs = []
+        tool_names = tuple(TOOL_GAP_MULTIPLIERS)
+        shifted = cfg.tool_regime_shift_fraction > 0.0 and now >= cfg.duration_s * cfg.tool_regime_shift_fraction
         for turn_idx in range(turns):
             append = 0 if turn_idx == 0 else _sample_int(rng, cfg.append_tokens_mean, cfg.token_cv, 8)
             output = _sample_int(rng, cfg.output_tokens_mean, cfg.output_tokens_cv, 1)
-            gap = 0.0 if turn_idx == turns - 1 else _sample_positive_lognormal(
-                rng, cfg.tool_gap_mean_s, cfg.tool_gap_cv, 0.0
-            )
-            specs.append(TurnSpec(sid, turn_idx, append, output, gap))
+            tool_kind = rng.choices(tool_names, weights=TOOL_WEIGHTS, k=1)[0]
+            if turn_idx == turns - 1:
+                gap = 0.0
+            else:
+                mean_gap = cfg.tool_gap_mean_s * TOOL_GAP_MULTIPLIERS[tool_kind]
+                # The optional shift deliberately changes only the slower external
+                # tools. This creates a non-stationary workload where a global
+                # duration average is less informative than tool-aware history.
+                if shifted and tool_kind in {"database", "remote_api"}:
+                    mean_gap *= cfg.tool_regime_shift_multiplier
+                gap = _sample_positive_lognormal(rng, mean_gap, cfg.tool_gap_cv, 0.0)
+            specs.append(TurnSpec(sid, turn_idx, append, output, gap, tool_kind, shifted))
         sessions.append(SessionSpec(sid, now, initial, specs))
         sid += 1
     return sessions
@@ -224,6 +256,13 @@ class AgentSessionSimulator:
         self.route_opportunities = 0
         self.failed_turns = 0
         self.tool_gap_total_s = 0.0
+        self.tool_gap_predictor = OnlineToolGapPredictor(
+            initial_mean_s=cfg.tool_gap_mean_s,
+            alpha=cfg.adaptive_alpha,
+            min_observations=cfg.adaptive_min_observations,
+            scope=cfg.adaptive_predictor_scope,
+        )
+        self.prediction_rows: list[dict[str, Any]] = []
         for session in specs:
             if session.turns:
                 self._push(session.arrival_time, "turn_ready", session.session_id, 0)
@@ -406,7 +445,7 @@ class AgentSessionSimulator:
         previous = replica.cache.get(session_id)
         generation = (previous.generation + 1) if previous else 1
         expiry: float | None = None
-        if keep and self.cfg.retention_policy == "ttl":
+        if keep and self.cfg.retention_policy in {"ttl", "adaptive"}:
             expiry = self.now + self.cfg.kv_ttl_s
         replica.cache[session_id] = CacheEntry(session_id, tokens, size_gb, self.now, expiry, generation)
         self.peak_kv_gb = max(self.peak_kv_gb, self._used_gb())
@@ -542,6 +581,31 @@ class AgentSessionSimulator:
                 state_action = "offload_host_long_gap"
             else:
                 state_action = "evict_host_full"
+        elif self.cfg.retention_policy == "adaptive":
+            predicted_gap_s, prediction_source, history_count = self.tool_gap_predictor.predict(turn.tool_kind)
+            predicted_retain = predicted_gap_s <= self.cfg.gap_aware_threshold_s
+            oracle_retain = turn.tool_gap_after_s <= self.cfg.gap_aware_threshold_s
+            if predicted_retain:
+                self._put_cache(replica, session_id, projected_tokens, keep=True)
+                state_action = "adaptive_retain_hbm"
+            elif self._offload_cache(replica, session_id, projected_tokens):
+                state_action = "adaptive_offload_host"
+            else:
+                state_action = "adaptive_evict_host_full"
+            self.prediction_rows.append({
+                "session_id": session_id,
+                "turn_index": turn_index + 1,
+                "tool_kind": turn.tool_kind,
+                "shifted_regime": turn.shifted_regime,
+                "predicted_gap_s": predicted_gap_s,
+                "actual_gap_s": turn.tool_gap_after_s,
+                "absolute_error_s": abs(predicted_gap_s - turn.tool_gap_after_s),
+                "prediction_source": prediction_source,
+                "history_count": history_count,
+                "predicted_action": "retain" if predicted_retain else "offload",
+                "oracle_action": "retain" if oracle_retain else "offload",
+                "action_match": predicted_retain == oracle_retain,
+            })
 
         e2e_ms = (self.now - ready_time) * 1000.0
         self.turn_rows.append(
@@ -555,6 +619,9 @@ class AgentSessionSimulator:
                 "cache_source": cache_source,
                 "restore_ms": restore_s * 1000.0,
                 "state_action": state_action,
+                "tool_kind": turn.tool_kind,
+                "tool_gap_after_s": turn.tool_gap_after_s,
+                "shifted_regime": turn.shifted_regime,
                 "prefill_tokens": prefill_tokens,
                 "context_tokens_after": projected_tokens,
                 "output_tokens": turn.output_tokens,
@@ -568,7 +635,9 @@ class AgentSessionSimulator:
             runtime.completion_time = self.now
         else:
             self.tool_gap_total_s += turn.tool_gap_after_s
-            self._push(self.now + turn.tool_gap_after_s, "turn_ready", session_id, turn_index + 1)
+            observed_at = self.now + turn.tool_gap_after_s
+            self._push(observed_at, "tool_observed", turn.tool_kind, turn.tool_gap_after_s)
+            self._push(observed_at, "turn_ready", session_id, turn_index + 1)
         self._start_next(replica)
 
     def run(self) -> dict[str, Any]:
@@ -577,7 +646,9 @@ class AgentSessionSimulator:
             event_time, _, kind, payload = heapq.heappop(self.events)
             self._integrate_memory(event_time)
             self.now = event_time
-            if kind == "turn_ready":
+            if kind == "tool_observed":
+                self.tool_gap_predictor.observe(str(payload[0]), float(payload[1]))
+            elif kind == "turn_ready":
                 session_id, turn_index = int(payload[0]), int(payload[1])
                 turn = self.sessions[session_id].spec.turns[turn_index]
                 replica = self._route(session_id)
@@ -641,6 +712,8 @@ class AgentSessionSimulator:
         }
         host_restore_p95_ms = percentile(self.host_transfer_latencies_ms, 0.95)
         total_reuse_hits = self.cache_hits + self.host_cache_hits
+        prediction_errors = [float(row["absolute_error_s"]) for row in self.prediction_rows]
+        prediction_matches = [bool(row["action_match"]) for row in self.prediction_rows]
         resource = {
             "replicas": self.cfg.replicas,
             "kv_capacity_gb_per_replica": self.kv_capacity_gb,
@@ -667,6 +740,13 @@ class AgentSessionSimulator:
             "restored_gb": self.restore_bytes / 1e9,
             "p95_host_transfer_ms": host_restore_p95_ms,
             "tool_gap_total_s": self.tool_gap_total_s,
+            "adaptive_prediction_count": len(self.prediction_rows),
+            "adaptive_prediction_mae_s": mean(prediction_errors) if prediction_errors else 0.0,
+            "adaptive_prediction_p95_abs_error_s": percentile(prediction_errors, 0.95),
+            "adaptive_oracle_action_agreement": (
+                sum(1 for match in prediction_matches if match) / len(prediction_matches)
+                if prediction_matches else 0.0
+            ),
         }
         return {
             "config": self.cfg.to_dict(),
@@ -677,12 +757,19 @@ class AgentSessionSimulator:
                 "agent_service_model": "serial-per-replica-reference",
                 "host_tier_model": "serialized-reference-transfer",
                 "gap_aware_policy": "oracle-upper-bound" if self.cfg.retention_policy == "gap_aware" else "not-active",
+                "adaptive_policy": (
+                    "online-tool-gap-ewma-no-lookahead" if self.cfg.retention_policy == "adaptive" else "not-active"
+                ),
                 "warning": "Agent-session mode isolates routing/KV-retention effects and does not model dynamic batching within each replica.",
             },
             "summary": summary,
             "latency": latency,
             "resource": resource,
             "turns": successful_turns[:3000],
+            "prediction": {
+                "rows": self.prediction_rows[:3000],
+                "predictor": self.tool_gap_predictor.snapshot(),
+            },
             "sessions": [
                 {
                     "session_id": s.spec.session_id,
@@ -957,3 +1044,192 @@ def agent_affinity_sweep(config: dict[str, Any], slack_values_ms: list[float] |
         "study": "bounded-affinity-routing-frontier",
         "rows": rows,
     }
+
+
+def _prediction_phase_metrics(result: dict[str, Any]) -> dict[str, float]:
+    rows = result.get("prediction", {}).get("rows", [])
+    before = [row for row in rows if not row.get("shifted_regime")]
+    after = [row for row in rows if row.get("shifted_regime")]
+
+    def phase(items: list[dict[str, Any]]) -> tuple[float, float]:
+        if not items:
+            return 0.0, 0.0
+        mae = mean(float(row["absolute_error_s"]) for row in items)
+        agreement = sum(1 for row in items if row.get("action_match")) / len(items)
+        return mae, agreement
+
+    pre_mae, pre_agreement = phase(before)
+    post_mae, post_agreement = phase(after)
+    return {
+        "pre_shift_mae_s": pre_mae,
+        "post_shift_mae_s": post_mae,
+        "pre_shift_action_agreement": pre_agreement,
+        "post_shift_action_agreement": post_agreement,
+    }
+
+
+def _rolling_prediction_curve(result: dict[str, Any], window: int = 16) -> list[dict[str, Any]]:
+    rows = result.get("prediction", {}).get("rows", [])
+    if not rows:
+        return []
+    points: list[dict[str, Any]] = []
+    width = max(4, min(int(window), 64))
+    for idx in range(len(rows)):
+        start = max(0, idx - width + 1)
+        chunk = rows[start : idx + 1]
+        points.append(
+            {
+                "observation": idx + 1,
+                "rolling_mae_s": mean(float(row["absolute_error_s"]) for row in chunk),
+                "rolling_action_agreement": sum(1 for row in chunk if row.get("action_match")) / len(chunk),
+                "tool_kind": rows[idx].get("tool_kind", "generic"),
+                "shifted_regime": bool(rows[idx].get("shifted_regime")),
+            }
+        )
+    return points
+
+
+def adaptive_tiering_study(
+    config: dict[str, Any],
+    *,
+    horizon_s: float = 120.0,
+    shift_fraction: float = 0.55,
+    shift_multiplier: float = 2.5,
+    alpha: float = 0.30,
+) -> dict[str, Any]:
+    """Compare fixed, adaptive, and oracle KV tiering on one non-stationary trace.
+
+    The adaptive candidates never inspect the realized future tool duration at
+    decision time. They learn an EWMA online from completed tool calls. The
+    oracle candidate intentionally sees the realized gap and serves only as an
+    upper bound.
+    """
+    base = AgentSessionConfig.from_dict(config)
+    base.duration_s = max(float(horizon_s), 30.0)
+    base.tool_regime_shift_fraction = min(max(float(shift_fraction), 0.05), 0.95)
+    base.tool_regime_shift_multiplier = max(float(shift_multiplier), 1.0)
+    base.adaptive_alpha = min(max(float(alpha), 0.01), 1.0)
+    base.routing_policy = "bounded_affinity"
+    trace = generate_agent_sessions(base)
+
+    candidates = [
+        ("Fixed TTL", "ttl", "per_tool_ema"),
+        ("Always host offload", "offload", "per_tool_ema"),
+        ("Adaptive global EWMA", "adaptive", "global_ema"),
+        ("Adaptive per-tool EWMA", "adaptive", "per_tool_ema"),
+        ("Oracle gap-aware", "gap_aware", "per_tool_ema"),
+    ]
+    rows: list[dict[str, Any]] = []
+    results: dict[str, dict[str, Any]] = {}
+    for label, retention, scope in candidates:
+        cfg = AgentSessionConfig.from_dict(base.to_dict())
+        cfg.retention_policy = retention
+        cfg.adaptive_predictor_scope = scope
+        result = run_agent_session_simulation(cfg.to_dict(), trace)
+        results[label] = result
+        phase = _prediction_phase_metrics(result)
+        rows.append(
+            {
+                "label": label,
+                "retention": retention,
+                "predictor_scope": scope if retention == "adaptive" else "not-active",
+                "p95_turn_ttft_ms": result["latency"]["turn_ttft_ms"]["p95"],
+                "p95_session_e2e_ms": result["latency"]["session_e2e_ms"]["p95"],
+                "session_slo_attainment": result["summary"]["session_slo_attainment"],
+                "cache_hit_rate": result["resource"]["cross_turn_cache_hit_rate"],
+                "mean_hbm_gb": result["resource"]["mean_kv_gb"],
+                "mean_host_gb": result["resource"]["mean_host_kv_gb"],
+                "recomputed_history_tokens": result["resource"]["recomputed_history_tokens"],
+                "prediction_count": result["resource"].get("adaptive_prediction_count", 0),
+                "prediction_mae_s": result["resource"].get("adaptive_prediction_mae_s", 0.0),
+                "oracle_action_agreement": result["resource"].get("adaptive_oracle_action_agreement", 0.0),
+                **phase,
+            }
+        )
+
+    global_result = results["Adaptive global EWMA"]
+    tool_result = results["Adaptive per-tool EWMA"]
+    shift_observation = next(
+        (
+            idx + 1
+            for idx, row in enumerate(tool_result.get("prediction", {}).get("rows", []))
+            if row.get("shifted_regime")
+        ),
+        0,
+    )
+    return {
+        "protocol": "common-nonstationary-agent-program-trace",
+        "study": "online-predictive-kv-tiering",
+        "horizon_s": base.duration_s,
+        "shift_fraction": base.tool_regime_shift_fraction,
+        "shift_multiplier": base.tool_regime_shift_multiplier,
+        "shift_time_s": base.duration_s * base.tool_regime_shift_fraction,
+        "shift_observation": shift_observation,
+        "threshold_s": base.gap_aware_threshold_s,
+        "alpha": base.adaptive_alpha,
+        "rows": rows,
+        "learning_curves": {
+            "global": _rolling_prediction_curve(global_result),
+            "per_tool": _rolling_prediction_curve(tool_result),
+        },
+        "tool_profiles": TOOL_GAP_MULTIPLIERS,
+        "note": (
+            "The oracle gap-aware candidate sees realized future tool gaps and is an upper bound. "
+            "Adaptive candidates learn only from tool calls that have already completed."
+        ),
+    }
+
+
+def adaptive_alpha_sweep(
+    config: dict[str, Any],
+    alpha_values: list[float] | None = None,
+    *,
+    horizon_s: float = 120.0,
+    shift_fraction: float = 0.55,
+    shift_multiplier: float = 2.5,
+) -> dict[str, Any]:
+    """Sweep EWMA adaptation speed on one shifted trace.
+
+    Lower alpha values are stable but adapt slowly; high values react quickly but
+    are noisier. The study reports both pre- and post-shift prediction error and
+    the resulting serving metrics.
+    """
+    base = AgentSessionConfig.from_dict(config)
+    base.duration_s = max(float(horizon_s), 30.0)
+    base.tool_regime_shift_fraction = min(max(float(shift_fraction), 0.05), 0.95)
+    base.tool_regime_shift_multiplier = max(float(shift_multiplier), 1.0)
+    base.retention_policy = "adaptive"
+    base.routing_policy = "bounded_affinity"
+    base.adaptive_predictor_scope = "per_tool_ema"
+    trace = generate_agent_sessions(base)
+    values = alpha_values or [0.05, 0.10, 0.20, 0.30, 0.50, 0.75, 1.00]
+    cleaned = sorted({min(max(float(value), 0.01), 1.0) for value in values})
+    rows: list[dict[str, Any]] = []
+    for alpha in cleaned:
+        cfg = AgentSessionConfig.from_dict(base.to_dict())
+        cfg.adaptive_alpha = alpha
+        result = run_agent_session_simulation(cfg.to_dict(), trace)
+        phase = _prediction_phase_metrics(result)
+        rows.append(
+            {
+                "alpha": alpha,
+                "prediction_mae_s": result["resource"]["adaptive_prediction_mae_s"],
+                "oracle_action_agreement": result["resource"]["adaptive_oracle_action_agreement"],
+                "p95_turn_ttft_ms": result["latency"]["turn_ttft_ms"]["p95"],
+                "p95_session_e2e_ms": result["latency"]["session_e2e_ms"]["p95"],
+                "session_slo_attainment": result["summary"]["session_slo_attainment"],
+                "mean_hbm_gb": result["resource"]["mean_kv_gb"],
+                "mean_host_gb": result["resource"]["mean_host_kv_gb"],
+                **phase,
+            }
+        )
+    best_post = min(rows, key=lambda row: (row["post_shift_mae_s"], row["p95_turn_ttft_ms"])) if rows else None
+    return {
+        "protocol": "common-nonstationary-agent-program-trace",
+        "study": "adaptive-ewma-rate-sweep",
+        "shift_fraction": base.tool_regime_shift_fraction,
+        "shift_multiplier": base.tool_regime_shift_multiplier,
+        "rows": rows,
+        "best_post_shift_alpha": best_post["alpha"] if best_post else None,
+        "note": "Alpha controls adaptation speed; this is an online heuristic study, not a learned model benchmark.",
+    }

src/inferscale/api.py

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
 from .agentic import (
+    adaptive_alpha_sweep,
+    adaptive_tiering_study,
     agent_affinity_sweep,
     agent_memory_budget_sweep,
     compare_agent_memory_policies,
@@ -25,6 +27,7 @@ def metadata() -> dict:
         "agentic_modes": [
             "session_simulation", "policy_compare", "ttl_sweep",
             "memory_policy_compare", "memory_budget_sweep", "affinity_sweep",
+            "predictive_tiering", "adaptive_alpha_sweep",
         ],
     }
 
@@ -71,6 +74,22 @@ def execute(action: str, payload: dict) -> dict:
         return agent_memory_budget_sweep(payload.get("config", payload), payload.get("budget_multipliers"))
     if action == "agent_affinity_sweep":
         return agent_affinity_sweep(payload.get("config", payload), payload.get("slack_values_ms"))
+    if action == "agent_predictive_tiering":
+        return adaptive_tiering_study(
+            payload.get("config", payload),
+            horizon_s=float(payload.get("horizon_s", 120.0)),
+            shift_fraction=float(payload.get("shift_fraction", 0.55)),
+            shift_multiplier=float(payload.get("shift_multiplier", 2.5)),
+            alpha=float(payload.get("alpha", 0.30)),
+        )
+    if action == "agent_adaptive_alpha_sweep":
+        return adaptive_alpha_sweep(
+            payload.get("config", payload),
+            payload.get("alpha_values"),
+            horizon_s=float(payload.get("horizon_s", 120.0)),
+            shift_fraction=float(payload.get("shift_fraction", 0.55)),
+            shift_multiplier=float(payload.get("shift_multiplier", 2.5)),
+        )
     if action == "robustness_study":
         config = payload.get("config", payload)
         return robustness_study(

src/inferscale/prediction.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+PREDICTOR_SCOPES = {"global_ema", "per_tool_ema"}
+
+
+@dataclass
+class _Estimate:
+    mean_s: float
+    count: int = 0
+
+
+class OnlineToolGapPredictor:
+    """Tiny online tool-duration predictor used by adaptive KV tiering.
+
+    The predictor deliberately stays transparent: it keeps an exponentially
+    weighted moving average (EWMA) of observed tool-call durations. In
+    ``per_tool_ema`` mode each tool family gets its own estimate, backed by a
+    global EWMA until enough observations have arrived. No future tool duration
+    is visible at decision time.
+    """
+
+    def __init__(
+        self,
+        *,
+        initial_mean_s: float,
+        alpha: float = 0.30,
+        min_observations: int = 2,
+        scope: str = "per_tool_ema",
+    ) -> None:
+        if scope not in PREDICTOR_SCOPES:
+            raise ValueError(f"Unsupported predictor scope: {scope}")
+        self.scope = scope
+        self.alpha = min(max(float(alpha), 0.01), 1.0)
+        self.min_observations = max(int(min_observations), 1)
+        self.global_estimate = _Estimate(max(float(initial_mean_s), 0.0), 0)
+        self.per_tool: dict[str, _Estimate] = {}
+
+    @staticmethod
+    def _update(estimate: _Estimate, value_s: float, alpha: float) -> None:
+        value_s = max(float(value_s), 0.0)
+        if estimate.count == 0:
+            estimate.mean_s = value_s
+        else:
+            estimate.mean_s = alpha * value_s + (1.0 - alpha) * estimate.mean_s
+        estimate.count += 1
+
+    def predict(self, tool_kind: str) -> tuple[float, str, int]:
+        if self.scope == "per_tool_ema":
+            estimate = self.per_tool.get(tool_kind)
+            if estimate is not None and estimate.count >= self.min_observations:
+                return estimate.mean_s, "tool", estimate.count
+        return self.global_estimate.mean_s, "global", self.global_estimate.count
+
+    def observe(self, tool_kind: str, duration_s: float) -> None:
+        self._update(self.global_estimate, duration_s, self.alpha)
+        estimate = self.per_tool.setdefault(tool_kind, _Estimate(self.global_estimate.mean_s, 0))
+        self._update(estimate, duration_s, self.alpha)
+
+    def snapshot(self) -> dict:
+        return {
+            "scope": self.scope,
+            "alpha": self.alpha,
+            "min_observations": self.min_observations,
+            "global": {"mean_s": self.global_estimate.mean_s, "count": self.global_estimate.count},
+            "per_tool": {
+                key: {"mean_s": value.mean_s, "count": value.count}
+                for key, value in sorted(self.per_tool.items())
+            },
+        }

styles.css

@@ -170,6 +170,7 @@ select:focus, input[type="number"]:focus { border-color: #5475a8; box-shadow: 0
 .unit { position: absolute; right: 9px; bottom: 12px; color: #697687; font-size: 10.5px; pointer-events: none; }
 .field-grid { display: grid; gap: 10px; margin-bottom: 10px; }
 .field-grid.two { grid-template-columns: 1fr 1fr; }
+.field-grid.four { grid-template-columns: repeat(4, minmax(0, 1fr)); }
 .subcontrols { margin: 12px 0 4px; padding: 12px; border: 1px solid var(--line-soft); background: #0a0f15; }
 .subcontrols .section-kicker { margin-bottom: 10px; }
 hr { border: 0; border-top: 1px solid var(--line-soft); margin: 17px 0; }
@@ -325,6 +326,9 @@ input[type="file"]::file-selector-button {
 .metric-grid.eight-agent { grid-template-columns: repeat(4, minmax(0, 1fr)); }
 .stacked-actions { display: flex; gap: 8px; flex-wrap: wrap; justify-content: flex-end; }
 .stacked-actions .compact { min-width: 168px; }
+.horizontal-actions { margin: 10px 0 14px; justify-content: flex-start; }
+.predictive-controls { margin-top: 12px; }
 @media (max-width: 1250px) { .metric-grid.eight-agent { grid-template-columns: repeat(2, 1fr); } }
-@media (max-width: 720px) { .metric-grid.eight-agent { grid-template-columns: 1fr 1fr; } .stacked-actions { width: 100%; } .stacked-actions .compact { width: 100% !important; } }
+@media (max-width: 960px) { .field-grid.four { grid-template-columns: 1fr 1fr; } }
+@media (max-width: 720px) { .metric-grid.eight-agent { grid-template-columns: 1fr 1fr; } .field-grid.four { grid-template-columns: 1fr; } .stacked-actions { width: 100%; } .stacked-actions .compact { width: 100% !important; } }
 .experiment-subsection { margin-top: 18px; padding-top: 18px; border-top: 1px solid var(--line); }

tests/test_prediction.py

@@ -0,0 +1,73 @@
+from inferscale.agentic import adaptive_alpha_sweep, adaptive_tiering_study, run_agent_session_simulation
+from inferscale.prediction import OnlineToolGapPredictor
+
+
+def _agent_cfg():
+    return {
+        "model": "Qwen2.5-3B",
+        "accelerator": "L4",
+        "quantization": "int8",
+        "duration_s": 24,
+        "session_rate_rps": 0.3,
+        "replicas": 2,
+        "seed": 7,
+        "retention_policy": "adaptive",
+        "routing_policy": "bounded_affinity",
+        "host_memory_gb": 4,
+        "gap_aware_threshold_s": 1.5,
+    }
+
+
+def test_online_predictor_uses_completed_history_only():
+    predictor = OnlineToolGapPredictor(initial_mean_s=1.5, alpha=0.5, min_observations=2, scope="per_tool_ema")
+    first, source, count = predictor.predict("search")
+    assert first == 1.5
+    assert source == "global"
+    assert count == 0
+
+    predictor.observe("search", 0.4)
+    second, source, count = predictor.predict("search")
+    assert source == "global"  # tool estimate is still warming up
+    assert count == 1
+
+    predictor.observe("search", 0.6)
+    third, source, count = predictor.predict("search")
+    assert source == "tool"
+    assert count == 2
+    assert 0.4 <= third <= 0.6
+
+
+def test_adaptive_agent_run_reports_prediction_provenance():
+    result = run_agent_session_simulation(_agent_cfg())
+    assert result["provenance"]["adaptive_policy"] == "online-tool-gap-ewma-no-lookahead"
+    assert result["resource"]["adaptive_prediction_count"] > 0
+    assert result["resource"]["adaptive_prediction_mae_s"] >= 0
+    assert 0 <= result["resource"]["adaptive_oracle_action_agreement"] <= 1
+    assert result["prediction"]["rows"]
+
+
+def test_predictive_tiering_study_has_common_shifted_trace():
+    result = adaptive_tiering_study(
+        _agent_cfg(), horizon_s=60, shift_fraction=0.5, shift_multiplier=2.0, alpha=0.3
+    )
+    assert result["protocol"] == "common-nonstationary-agent-program-trace"
+    assert len(result["rows"]) == 5
+    assert result["shift_observation"] > 0
+    labels = {row["label"] for row in result["rows"]}
+    assert "Adaptive per-tool EWMA" in labels
+    assert "Oracle gap-aware" in labels
+    adaptive = next(row for row in result["rows"] if row["label"] == "Adaptive per-tool EWMA")
+    assert adaptive["prediction_count"] > 0
+    assert result["learning_curves"]["per_tool"]
+
+
+def test_adaptation_rate_sweep_uses_same_trace():
+    result = adaptive_alpha_sweep(
+        _agent_cfg(), [0.1, 0.3, 0.8], horizon_s=60, shift_fraction=0.5, shift_multiplier=2.0
+    )
+    assert len(result["rows"]) == 3
+    assert result["best_post_shift_alpha"] in {0.1, 0.3, 0.8}
+    for row in result["rows"]:
+        assert row["pre_shift_mae_s"] >= 0
+        assert row["post_shift_mae_s"] >= 0
+        assert 0 <= row["oracle_action_agreement"] <= 1

worker.mjs

@@ -11,6 +11,7 @@ const MODULES = [
   "metrics.py",
   "models.py",
   "optimizer.py",
+  "prediction.py",
   "profiles.py",
   "research.py",
   "simulator.py",