type: clean mypy in optracing, quant, serve, session, sysinfo, telemetry, utils and enforce in CI (#916)

@
## Summary

Brings seven more `winml.modelkit` packages to **zero mypy errors**
under the strict `[tool.mypy]` config and wires them into the required
CI type-check gate (16 → 23 packages). Continues the incremental cleanup
from #896.

Cleaned: **optracing, quant, serve, session, sysinfo, telemetry, utils**
(sysinfo was already clean). Fixes follow the repos typing playbook —
fix at the source first; `cast()` only at genuine untyped third-party
boundaries; `Any` only for true dynamic pass-throughs.

## Real bugs surfaced (not just typing)

- **`utils/hub_utils.py` version import** — `from ..version import
__version__` referenced a non-existent module; guarded by `try/except`,
so the export version was silently always `"unknown"`. Fixed to `from ..
import __version__`. (The containing helper `inject_hub_metadata` is
dead code — tracked in #913.)
- **`utils/hub_utils.py`** — `model_info.modelId` → `model_info.id`
(huggingface_hub renamed the attribute).

## Notable fixes

- **session** — bound a non-None local after auto-compile so narrowing
survives into the lambda/comprehension; explicit guards for `resolved_ep
is None` and single-mode `model_path`; widened PDH counter containers to
`float`; class-level `_initialized` annotation; distinct ctypes struct
locals.
- **telemetry** — annotated the `LoggerProvider`/`Logger` instance
attributes (were inferred as `None`, cascading into
unreachable/attr-defined); OTel/JSON boundary casts; typed the
`@contextmanager`/`@asynccontextmanager` generators.
- **serve** — `cast()` at `json.loads`/`app.state` boundaries; `import
binascii` to use `binascii.Error` (typeshed doesnt expose
`base64.binascii`); explicit single-mode `model_path` guard.
- **utils** — removed stale `# type: ignore`s; `DataclassInstance` cast
for generic-`TypeVar` dataclass reflection; `EPAlias` key cast for the
alias lookup; loop-variable rename to fix
`InputTensorSpec`/`OutputTensorSpec` shadowing.

## Config changes (`pyproject.toml`)

- **`qairt.*`** → `ignore_missing_imports` (external Qualcomm AI Runtime
SDK; imported only inside `compile_qairt_bin.py`, which runs in a
separate `venv-winml` subprocess — absent from the CI env).
- **`windowsml`** → `follow_untyped_imports = true` (installed but ships
no `py.typed`; analyzing its source is clean and keeps its inline
annotations instead of collapsing to `Any`).

## Verification

- Combined required-gate invocation (all 23 packages): `Success: no
issues found in 300 source files`.
- ruff clean; unit tests green for the touched packages (2 pre-existing
OpenVINO-EP-unavailable failures in this env, confirmed unrelated).
- Branch-vs-main diff is content-only (line endings normalized to LF to
match main).
@

---------

Co-authored-by: Hualiang Xie <hualxie@microsoft.com>

Author: xieofxie

.github/workflows/lint.yml

@@ -13,7 +13,7 @@ concurrency:
 jobs:
   lint:
     runs-on: windows-latest
-    # Bumped from 5: combined mypy on 16 packages cold-starts at ~3-4 min on
+    # Bumped from 5: combined mypy on 23 packages cold-starts at ~3-4 min on
     # Windows runners; the original 5-min ceiling cancelled mid-run.
     timeout-minutes: 10
 
@@ -64,3 +64,10 @@ jobs:
           -p winml.modelkit.loader
           -p winml.modelkit.onnx
           -p winml.modelkit.optim
+          -p winml.modelkit.optracing
+          -p winml.modelkit.quant
+          -p winml.modelkit.serve
+          -p winml.modelkit.session
+          -p winml.modelkit.sysinfo
+          -p winml.modelkit.telemetry
+          -p winml.modelkit.utils

pyproject.toml

@@ -506,9 +506,21 @@ module = [
   "sklearn.*",       # used in eval/metrics; no community stubs
   "evaluate",        # HF evaluate, used in eval/; no community stubs
   "evaluate.*",
+  # QAIRT (Qualcomm AI Runtime) SDK — imported only inside compile_qairt_bin.py,
+  # which runs in a separate venv-winml subprocess where the SDK is installed.
+  # Not a dependency of the main/CI environment, so it has no stubs here.
+  "qairt",
+  "qairt.*",
 ]
 ignore_missing_imports = true
 
+# windowsml ships no py.typed marker, but its source is installed and usable —
+# analyze it directly (PEP 561 opt-in) so its inline annotations are honored
+# instead of collapsing every symbol to Any.
+[[tool.mypy.overrides]]
+module = [ "windowsml", "windowsml.*" ]
+follow_untyped_imports = true
+
 # Relaxed modules: tests and WIP code
 
 [[tool.mypy.overrides]]

src/winml/modelkit/optracing/qnn/profiler.py

@@ -19,7 +19,7 @@
 import logging
 import os
 from pathlib import Path
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 import numpy as np
 
@@ -29,6 +29,10 @@
 from .viewer import find_qnn_sdk, run_qhas_viewer
 
 
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+
 logger = logging.getLogger(__name__)
 
 
@@ -53,7 +57,7 @@ def _resolve_shape(shape: list, default_dim: int = 1) -> list[int]:
 
 
 @contextlib.contextmanager
-def _working_directory(path: Path):
+def _working_directory(path: Path) -> Iterator[None]:
     """Temporarily change CWD and restore on exit.
 
     QNN EP writes ``*_schematic.bin`` into the process CWD, so we

src/winml/modelkit/optracing/qnn/qhas_parser.py

@@ -110,4 +110,4 @@ def _vtcm_ratio(op: dict) -> float | None:
     total = vtcm_read + dram_read
     if total == 0:
         return None
-    return vtcm_read / total
+    return float(vtcm_read / total)

src/winml/modelkit/quant/__init__.py

@@ -16,6 +16,8 @@
     result = quantize_onnx("model.onnx", WinMLQuantizationConfig(samples=100))
 """
 
+from typing import Any
+
 from .config import QuantizeResult, WinMLQuantizationConfig
 
 
@@ -31,7 +33,7 @@
 }
 
 
-def __getattr__(name: str):
+def __getattr__(name: str) -> Any:
     """Lazy-load quantizer (imports onnxruntime.quantization)."""
     if name in _LAZY_IMPORTS:
         module_path, attr_name = _LAZY_IMPORTS[name]

src/winml/modelkit/serve/app.py

@@ -23,14 +23,15 @@
 
 import asyncio
 import base64
+import binascii
 import importlib.resources
 import json
 import logging
 import time
 from collections import deque
 from contextlib import asynccontextmanager
 from pathlib import Path
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, cast
 
 from fastapi import FastAPI, File, Form, HTTPException, UploadFile
 from fastapi.middleware.cors import CORSMiddleware
@@ -57,6 +58,8 @@
 
 
 if TYPE_CHECKING:
+    from collections.abc import AsyncIterator
+
     from ..utils.constants import EPNameOrAlias
 
 logger = logging.getLogger(__name__)
@@ -166,7 +169,7 @@ def create_app(
     """
 
     @asynccontextmanager
-    async def lifespan(app: FastAPI):
+    async def lifespan(app: FastAPI) -> AsyncIterator[None]:
         app.state.start_time = time.time()
         # Raise the modelkit logger to INFO so the ring handler receives
         # operational records during `winml serve`. Tests that build the app
@@ -187,6 +190,8 @@ async def lifespan(app: FastAPI):
                 logger.info("Multi-model server started (empty — load via POST /v1/models)")
             app.state.manager = mgr
         else:
+            if model_path is None:
+                raise ValueError("single-model mode requires a model_path")
             engine = InferenceEngine()
             engine.load(model_path, task=task, device=device, ep=ep)
             app.state.manager = SingleModelManager(engine, idle_timeout_sec=idle_timeout_sec)
@@ -240,7 +245,7 @@ def _get_mgr() -> SingleModelManager | ModelSlotManager:
         mgr = getattr(app.state, "manager", None)
         if mgr is None:
             raise HTTPException(status_code=503, detail="Model not loaded yet")
-        return mgr
+        return cast("SingleModelManager | ModelSlotManager", mgr)
 
     def _get_start_time() -> float:
         return getattr(app.state, "start_time", time.time())
@@ -733,13 +738,13 @@ async def cli_command(command: str, request: CliRequest) -> CliResponse:
 # ---------------------------------------------------------------------------
 
 
-def _manifest_from_engine(engine: InferenceEngine) -> dict:
+def _manifest_from_engine(engine: InferenceEngine) -> dict[str, Any]:
     """Build manifest dict from engine, trying build_manifest.json first."""
     if engine.model_path:
         manifest_file = Path(engine.model_path) / "build_manifest.json"
         if manifest_file.exists():
             try:
-                return json.loads(manifest_file.read_text())
+                return cast("dict[str, Any]", json.loads(manifest_file.read_text()))
             except (json.JSONDecodeError, OSError) as e:
                 logger.warning("Failed to load manifest: %s", e)
 
@@ -753,7 +758,7 @@ def _manifest_from_engine(engine: InferenceEngine) -> dict:
 
 
 def _build_model_schema(
-    manifest: dict,
+    manifest: dict[str, Any],
     engine: InferenceEngine | None = None,
     task_override: str | None = None,
 ) -> dict[str, Any]:
@@ -828,7 +833,7 @@ def _decode_rest_inputs(
         if field and field.type in BINARY_TYPES and isinstance(value, str):
             try:
                 result[name] = base64.b64decode(value)
-            except (ValueError, base64.binascii.Error) as exc:
+            except (ValueError, binascii.Error) as exc:
                 raise ValueError(f"Invalid base64 for input '{name}': {exc}") from exc
     return result
 

src/winml/modelkit/serve/cli_api.py

@@ -27,7 +27,7 @@
 import tempfile
 import time
 from pathlib import Path
-from typing import Any
+from typing import Any, cast
 
 from fastapi import FastAPI, HTTPException
 from fastapi.middleware.cors import CORSMiddleware
@@ -212,7 +212,12 @@ def _extract_json_from_stdout(stdout: str) -> dict[str, Any] | list[Any] | None:
                 if start == -1:
                     break
                 try:
-                    return json.loads(stdout[start : end + 1])
+                    # Reached only after matching a {...} / [...] pair, so the
+                    # parse yields a dict or list — never None.
+                    return cast(
+                        "dict[str, Any] | list[Any]",
+                        json.loads(stdout[start : end + 1]),
+                    )
                 except json.JSONDecodeError:
                     continue
             pos = end  # try next (earlier) end_char

src/winml/modelkit/session/ep_registry.py

@@ -228,6 +228,10 @@ class WinMLEPRegistry:
         available = registry.get_available_eps()
     """
 
+    # Set in __new__ before __init__ runs; declared here so mypy can resolve its
+    # type at the __init__ read site.
+    _initialized: bool
+
     def __new__(cls) -> WinMLEPRegistry:
         """Singleton pattern."""
         global _winml_ep_registry
@@ -269,7 +273,8 @@ def _load_ep_catalog(self) -> None:
         """Load EP catalog from WinML."""
         from windowsml import EpCatalog
 
-        checked_eps: set[EPName] = set()
+        # Dedup of raw windowsml provider-name strings (pre-validation).
+        checked_eps: set[str] = set()
         with EpCatalog() as catalog:
             for provider in catalog.find_all_providers():
                 if provider.name in checked_eps:
@@ -402,4 +407,4 @@ def get_ort_available_providers(use_winml: bool = True) -> list[str]:
         except Exception as e:
             logger.debug("WinML discovery skipped: %s", e)
 
-    return ort.get_available_providers()
+    return cast("list[str]", ort.get_available_providers())

src/winml/modelkit/session/monitor/_pdh.py

@@ -178,22 +178,24 @@ def _collect_once(self) -> dict[str, float | int | None]:
                 continue
 
             if entry.fmt == _PDH_FMT_DOUBLE:
-                val = _PdhFmtDouble()
+                dval = _PdhFmtDouble()
                 s = _pdh.PdhGetFormattedCounterValue(
                     entry.handle,
                     _PDH_FMT_DOUBLE | _PDH_FMT_NOCAP100,
                     ctypes.byref(ct),
-                    ctypes.byref(val),
+                    ctypes.byref(dval),
                 )
                 values[entry.name] = (
-                    val.doubleValue if _pdh_ok(s) and _pdh_ok(val.CStatus) else None
+                    dval.doubleValue if _pdh_ok(s) and _pdh_ok(dval.CStatus) else None
                 )
             else:
-                val = _PdhFmtLarge()
+                lval = _PdhFmtLarge()
                 s = _pdh.PdhGetFormattedCounterValue(
-                    entry.handle, _PDH_FMT_LARGE, ctypes.byref(ct), ctypes.byref(val)
+                    entry.handle, _PDH_FMT_LARGE, ctypes.byref(ct), ctypes.byref(lval)
+                )
+                values[entry.name] = (
+                    lval.largeValue if _pdh_ok(s) and _pdh_ok(lval.CStatus) else None
                 )
-                values[entry.name] = val.largeValue if _pdh_ok(s) and _pdh_ok(val.CStatus) else None
 
         return values
 
@@ -403,14 +405,17 @@ def __init__(
         self._stop_event = threading.Event()
         self._lock = threading.Lock()
         self._util_samples: list[float] = []
-        self._memory_local_bytes: list[int] = []
-        self._memory_shared_bytes: list[int] = []
+        # PDH counters arrive as float|int (double vs large format), so store as float.
+        self._memory_local_bytes: list[float] = []
+        self._memory_shared_bytes: list[float] = []
         self._cpu_samples: list[float] = []
-        self._ram_used_bytes: list[int] = []
+        self._ram_used_bytes: list[float] = []
         # Per-engtype snapshots of the monotonic Running Time counter. Stored
         # as dicts because an adapter exposes multiple engines (e.g. several
         # Compute_* on an NPU; 3D + Compute_* on a GPU) and the total adapter
         # time is the sum of per-engine deltas.
+        # Running-time counters are 64-bit ns integers; ns-since-epoch (~1.7e18)
+        # exceeds float64's exact range (2**53), so keep them int.
         self._running_time_start_ns: dict[str, int] = {}
         self._running_time_end_ns: dict[str, int] = {}
 
@@ -479,7 +484,7 @@ def start(self) -> None:
 
             initial = self._query.collect(interval=0.05)
             self._running_time_start_ns = {
-                k: v
+                k: int(v)
                 for k, v in initial.items()
                 if k.startswith("running_time_") and v is not None
             }
@@ -509,7 +514,7 @@ def stop(self) -> None:
             try:
                 final = self._query._collect_once()
                 self._running_time_end_ns = {
-                    k: v
+                    k: int(v)
                     for k, v in final.items()
                     if k.startswith("running_time_") and v is not None
                 }
@@ -532,8 +537,11 @@ def _poll_loop(self) -> None:
         # normalize so cpu_pct stays 0..100 across machines.
         cpu_divisor = float(os.cpu_count() or 1)
         while not self._stop_event.is_set():
+            query = self._query
+            if query is None:
+                break
             try:
-                values = self._query._collect_once()
+                values = query._collect_once()
                 # util_* counters are per-engine ratios over the same sample
                 # window, so max reports the most-loaded engine on the adapter.
                 # Don't sum — that would exceed 100% and duplicate what the

src/winml/modelkit/session/monitor/_xrt_smi.py

@@ -21,7 +21,7 @@
 import tempfile
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any
+from typing import Any, cast
 
 
 logger = logging.getLogger(__name__)
@@ -109,7 +109,7 @@ def snapshot(self) -> dict[str, Any]:
                 return {}
 
             with Path(tmp_path).open(encoding="utf-8") as f:
-                return json.load(f)
+                return cast("dict[str, Any]", json.load(f))
 
         except (subprocess.TimeoutExpired, json.JSONDecodeError, OSError) as exc:
             logger.debug("xrt-smi snapshot failed: %s", exc)