feat(M88): Framework-Level Inference Hooks

docs/iterations/current.md

@@ -51,4 +51,5 @@ shell for exploratory comparison of two endpoints.
 | M83 | 2026-04-06 | Divergence Heatmap by Token Position | ✅ merged | Both approved |
 | M84 | 2026-04-06 | Endpoint Response Time Regression Detection | ✅ merged | Both approved |
 | M85 | 2026-04-06 | Offline Mode — File-Based Comparison | ✅ merged | Both approved |
-| M87 | 2026-04-06 | Automatic KV Cache Export from vLLM | ⏳ pending review | — |
+| M87 | 2026-04-06 | Automatic KV Cache Export from vLLM | ✅ merged | Both approved |
+| M88 | 2026-04-06 | Framework-Level Inference Hooks | ⏳ pending review | — |

src/xpyd_acc/cli/__init__.py

@@ -23,6 +23,7 @@
     handle_heatmap,
     handle_root_cause,
     handle_token_diff,
+    handle_trace,
 )
 from .batch import _run_batch_compare
 from .benchmark import (
@@ -129,6 +130,7 @@ def main(argv: list[str] | None = None) -> None:
         "token-diff": lambda: handle_token_diff(args),
         "heatmap": lambda: handle_heatmap(args),
         "capture-kv": lambda: handle_capture_kv(args),
+        "trace": lambda: handle_trace(args),
         "filter": lambda: _run_filter(args),
         "serve": lambda: _run_serve(args),
         "grafana-dashboard": lambda: _run_grafana_dashboard(args),

src/xpyd_acc/cli/analysis.py

@@ -416,3 +416,58 @@ def handle_capture_kv(args: argparse.Namespace) -> None:
         with open(args.json, "w") as f:
             _json.dump(result.to_dict(), f, indent=2)
         print(f"  Metadata exported to {args.json}")
+
+
+def handle_trace(args: argparse.Namespace) -> None:
+    """Handle the trace CLI subcommand."""
+    import json as _json
+
+    from xpyd_acc.inference_hooks import (
+        HookPoint,
+        MockInferenceHook,
+        format_trace,
+        run_trace,
+    )
+
+    hooks = [HookPoint(h.strip()) for h in args.hooks.split(",")]
+
+    if args.mock:
+        baseline_hook = MockInferenceHook(
+            num_layers=args.num_layers,
+            noise_scale=0.0,
+            seed=42,
+        )
+        target_hook = MockInferenceHook(
+            num_layers=args.num_layers,
+            noise_scale=args.noise_scale,
+            seed=42,
+        )
+    else:
+        print(
+            "Live inference tracing requires framework-specific hooks.\n"
+            "Use --mock for testing, or see docs for vLLM/SGLang integration.",
+            file=sys.stderr,
+        )
+        raise SystemExit(1)
+
+    result = run_trace(
+        baseline_hook=baseline_hook,
+        target_hook=target_hook,
+        prompt=args.prompt,
+        baseline_url=args.baseline,
+        target_url=args.target,
+        hooks=hooks,
+        num_layers=args.num_layers,
+        decode_steps=args.decode_steps,
+        threshold=args.threshold,
+    )
+
+    print(format_trace(result))
+
+    if getattr(args, "json", None):
+        with open(args.json, "w") as f:
+            _json.dump(result.to_dict(), f, indent=2)
+        print(f"Trace exported to {args.json}")
+
+    if result.overall_diverged:
+        raise SystemExit(1)

src/xpyd_acc/cli/parsers.py

@@ -54,6 +54,7 @@ def register_all(sub: argparse._SubParsersAction) -> None:
     _register_heatmap(sub)
     _register_capture_kv(sub)
     _register_file_compare(sub)
+    _register_trace(sub)
 def _register_compare(sub):
     lp = sub.add_parser("compare-logprobs", help="Compare logprobs between two endpoints")
     lp.add_argument("--baseline", required=True, help="Baseline endpoint URL")
@@ -695,3 +696,39 @@ def _register_file_compare(sub):
         "--numeric-tolerance", type=float, default=None,
         help="Numeric tolerance for matching",
     )
+
+
+def _register_trace(sub):
+    tr = sub.add_parser(
+        "trace",
+        help="Trace intermediate inference states between baseline and target",
+    )
+    tr.add_argument("--baseline", required=True, help="Baseline endpoint URL")
+    tr.add_argument("--target", required=True, help="Target endpoint URL")
+    tr.add_argument("--prompt", required=True, help="Prompt text")
+    tr.add_argument(
+        "--hooks",
+        default="prefill,kv_transfer,decode_step",
+        help="Comma-separated hooks: prefill,kv_transfer,decode_step",
+    )
+    tr.add_argument(
+        "--num-layers", type=int, default=4,
+        help="Number of layers to trace (default: 4)",
+    )
+    tr.add_argument(
+        "--decode-steps", type=int, default=1,
+        help="Number of decode steps to trace (default: 1)",
+    )
+    tr.add_argument(
+        "--threshold", type=float, default=1e-5,
+        help="Divergence threshold (default: 1e-5)",
+    )
+    tr.add_argument(
+        "--mock", action="store_true", default=False,
+        help="Use mock hooks for testing",
+    )
+    tr.add_argument(
+        "--noise-scale", type=float, default=0.0,
+        help="Noise scale for mock target hook (default: 0.0)",
+    )
+    tr.add_argument("--json", default=None, help="Export trace result as JSON")