[feat]: dispatch trusted graph artifacts with native fallback

examples/inference/optimizations/README.md

@@ -52,3 +52,49 @@ Result files use `schema_version: 1` and record wall time, generation time,
 peak memory, environment identity, optional frames path, and failure reasons.
 `candidate` mode writes `candidate_result.json`, so it cannot overwrite a
 previously validated `optimized_result.json`.
+
+## Generic graph dispatch
+
+Once a kernel has been packaged as an artifact bundle, FastVideo can run it
+without any model-specific code. Point the runtime at a **trusted** directory
+of bundles:
+
+```bash
+FASTVIDEO_OPTIMIZATION_ARTIFACT_DIR=/path/to/artifacts \
+FASTVIDEO_OPTIMIZATION_ARTIFACT_MODEL_ID=Wan-AI/Wan2.1-T2V-1.3B-Diffusers \
+FASTVIDEO_OPTIMIZATION_ARTIFACT_DIAGNOSTICS=/tmp/dispatch.json \
+python examples/inference/optimizations/generation_launcher.py \
+  --workload /path/to/motionkernel/workloads/wan_t2v_1.3b_480p.yaml \
+  --mode candidate \
+  --output-dir /tmp/wan_candidate
+```
+
+Dispatch attaches to repeated block stacks -- children of an `nn.ModuleList`
+that share a class -- exactly as capture does, so no architecture is named
+anywhere. Per stack and per observed input signature it runs the first call
+natively (which is what reveals the output signature), recomputes the module's
+graph fingerprint with the capture tracer, and selects a bundle whose
+fingerprint, tensor signatures and declared environment all match. The chosen
+entry point is called as `candidate(module, *args, **kwargs)`.
+
+Everything is fail-safe. A missing match, an unloadable bundle, an untraceable
+module or an exception raised by the candidate falls back to native execution
+and records a structured reason; the candidate is not retried afterwards.
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `FASTVIDEO_OPTIMIZATION_ARTIFACT_DIR` | `""` | Trusted artifact root. **Unset means nothing is wrapped at all** and generation is byte-for-byte identical to a build without this feature. |
+| `FASTVIDEO_OPTIMIZATION_ARTIFACT_TRACER` | `symbolic` | Tracer used to recompute the fingerprint. `symbolic` does not re-execute the module with real inputs; `export` and `dynamo` do. |
+| `FASTVIDEO_OPTIMIZATION_ARTIFACT_MODEL_ID` | profile model id | Model identity matched against each bundle. |
+| `FASTVIDEO_OPTIMIZATION_ARTIFACT_MODEL_REVISION` | `*` | Revision matched against each bundle. |
+| `FASTVIDEO_OPTIMIZATION_ARTIFACT_DISTRIBUTED_MODE` | auto | Sharding mode. Auto-detection only resolves a single-rank run; a multi-rank run must declare its mode or no artifact is selected. |
+| `FASTVIDEO_OPTIMIZATION_ARTIFACT_MAX_SCOPES` | `64` | Upper bound on dispatched block stacks. |
+| `FASTVIDEO_OPTIMIZATION_ARTIFACT_MAX_SHAPES` | `8` | Upper bound on resolved input signatures per stack. |
+| `FASTVIDEO_OPTIMIZATION_ARTIFACT_DIAGNOSTICS` | `""` | Optional path for the structured dispatch/fallback report. |
+
+The diagnostics report is metadata only: it records each scope, shape key,
+decision reason, artifact id, rejection codes and call counts, plus the
+registry and runtime identity. It never contains tensor or prompt data.
+
+The bundle format, its packager and the matching rules are documented in
+MotionKernel's `docs/ARTIFACT_BUNDLE.md`.

fastvideo/envs.py

@@ -45,6 +45,14 @@
     FASTVIDEO_OPTIMIZATION_PROFILE_FX_TRACER: str = "auto"
     FASTVIDEO_OPTIMIZATION_PROFILE_FX_MAX_SCOPES: int = 64
     FASTVIDEO_OPTIMIZATION_PROFILE_FX_MAX_SHAPES: int = 8
+    FASTVIDEO_OPTIMIZATION_ARTIFACT_DIR: str = ""
+    FASTVIDEO_OPTIMIZATION_ARTIFACT_TRACER: str = "symbolic"
+    FASTVIDEO_OPTIMIZATION_ARTIFACT_MAX_SCOPES: int = 64
+    FASTVIDEO_OPTIMIZATION_ARTIFACT_MAX_SHAPES: int = 8
+    FASTVIDEO_OPTIMIZATION_ARTIFACT_MODEL_ID: str = ""
+    FASTVIDEO_OPTIMIZATION_ARTIFACT_MODEL_REVISION: str = "*"
+    FASTVIDEO_OPTIMIZATION_ARTIFACT_DISTRIBUTED_MODE: str = ""
+    FASTVIDEO_OPTIMIZATION_ARTIFACT_DIAGNOSTICS: str = ""
     FASTVIDEO_TRACE_ACTIVATIONS: bool = False
     FASTVIDEO_TRACE_LAYERS: str = ""
     FASTVIDEO_TRACE_STATS: str = "abs_mean,sum"
@@ -305,6 +313,39 @@ def maybe_convert_int(value: str | None) -> int | None:
     "FASTVIDEO_OPTIMIZATION_PROFILE_FX_MAX_SHAPES":
     lambda: int(os.getenv("FASTVIDEO_OPTIMIZATION_PROFILE_FX_MAX_SHAPES", "8")),
 
+    # Trusted directory holding packaged optimization artifacts. Executable
+    # candidate code is loaded only from here, and only after every declared
+    # file matches the hash recorded in its manifest. Leaving this unset
+    # disables graph dispatch entirely: no forward is wrapped and generation
+    # behaves exactly as it does without the feature.
+    "FASTVIDEO_OPTIMIZATION_ARTIFACT_DIR":
+    lambda: os.getenv("FASTVIDEO_OPTIMIZATION_ARTIFACT_DIR", ""),
+    # Tracer used to recompute a module's graph fingerprint at dispatch time.
+    # ``symbolic`` is the default because, unlike ``export`` and ``dynamo``, it
+    # does not re-execute the module with real inputs.
+    "FASTVIDEO_OPTIMIZATION_ARTIFACT_TRACER":
+    lambda: os.getenv("FASTVIDEO_OPTIMIZATION_ARTIFACT_TRACER", "symbolic"),
+    # Upper bound on dispatched block stacks.
+    "FASTVIDEO_OPTIMIZATION_ARTIFACT_MAX_SCOPES":
+    lambda: int(os.getenv("FASTVIDEO_OPTIMIZATION_ARTIFACT_MAX_SCOPES", "64")),
+    # Upper bound on distinct input signatures resolved per stack.
+    "FASTVIDEO_OPTIMIZATION_ARTIFACT_MAX_SHAPES":
+    lambda: int(os.getenv("FASTVIDEO_OPTIMIZATION_ARTIFACT_MAX_SHAPES", "8")),
+    # Model identity matched against each artifact's declared compatibility.
+    # Falls back to the optimization profile's model id when unset.
+    "FASTVIDEO_OPTIMIZATION_ARTIFACT_MODEL_ID":
+    lambda: os.getenv("FASTVIDEO_OPTIMIZATION_ARTIFACT_MODEL_ID", ""),
+    "FASTVIDEO_OPTIMIZATION_ARTIFACT_MODEL_REVISION":
+    lambda: os.getenv("FASTVIDEO_OPTIMIZATION_ARTIFACT_MODEL_REVISION", "*"),
+    # Sharding mode declared to the matcher. Empty means auto-detect, which
+    # only resolves a single-rank run; a multi-rank run must declare its mode
+    # explicitly or no artifact is selected.
+    "FASTVIDEO_OPTIMIZATION_ARTIFACT_DISTRIBUTED_MODE":
+    lambda: os.getenv("FASTVIDEO_OPTIMIZATION_ARTIFACT_DISTRIBUTED_MODE", ""),
+    # Optional path for the structured dispatch/fallback report.
+    "FASTVIDEO_OPTIMIZATION_ARTIFACT_DIAGNOSTICS":
+    lambda: os.getenv("FASTVIDEO_OPTIMIZATION_ARTIFACT_DIAGNOSTICS", ""),
+
     # Enable activation trace hooks if set.
     "FASTVIDEO_TRACE_ACTIVATIONS":
     lambda: bool(os.getenv("FASTVIDEO_TRACE_ACTIVATIONS", "0") != "0"),

fastvideo/optimization/__init__.py

@@ -1,6 +1,11 @@
 # SPDX-License-Identifier: Apache-2.0
-"""Model-independent optimization discovery helpers."""
+"""Model-independent optimization discovery and dispatch helpers."""
 
+from fastvideo.optimization.dispatch import (attach_graph_dispatch, detach_graph_dispatch)
 from fastvideo.optimization.profiler import optimization_profile
 
-__all__ = ["optimization_profile"]
+__all__ = [
+    "attach_graph_dispatch",
+    "detach_graph_dispatch",
+    "optimization_profile",
+]