feat(v4/spec): VBSpec Stage E — verify_and_estimate + suggest_adapters + GUI workflow

Adds cppmega_v4.spec.api — the GUI-facing public surface that wires
Stages A-D into the three operations the visual builder cares about
(VisualBuilderSpec.md §3.5, §6 E).

  - suggest_dim_env(preset_name=None) → dict[str,int]
    Sensible production-scale named-dim env per preset (B=1, S=4096,
    H=4096, nh=32, nkv=4, head_dim=128, num_experts=8, top_k=2, plus
    MLA LoRA / sliding / SSM / coarse-attn extras when needed). With
    preset_name=None, returns the generic base env.

  - verify_and_estimate(graph, dim_env, *, preset_name, device_hbm_bytes,
    headroom, training, optimizer, dtype_bytes, kv_cache_dtype_bytes,
    available_side_channels, strict) → VerificationResult
    One-shot: resolve_shapes → plan_fusion_regions → estimate_memory.
    Carries resolved graph, fusion plan, memory report, elapsed_ms, and
    optional fits_on_device gate. .summary() returns a JSON-friendly
    dict the GUI can render directly.

  - suggest_adapters(resolved, producer, consumer, *, max_steps) →
    AdapterProposal. Looks up the resolved edge and asks the Stage C
    adapter library for a chain that closes the mismatch.

Tests (tests/v4/test_vbspec_stage_e.py, 38 cases):
  - suggest_dim_env: independent-copy invariant, base-key coverage,
    per-preset coverage (12), unknown-preset error, MLA extras included
  - verify_and_estimate: well-formed result; explicit env overrides
    preset; device gate populates fits_on_device; default no-device =
    None; summary dict shape; strict mode re-raises
  - suggest_adapters: unknown-edge KeyError; matched edge = empty chain
    + "no adapter needed" reason; synthetic mismatch → chain proposed,
    accept-and-splice removes the original mismatched edge
  - PERF GATE: every preset (12) completes verify_and_estimate in
    <100 ms warm (soft cap; target 50 ms — current runs ~3 ms)
  - SYSTEM: full GUI workflow integration (drop brick with mismatch →
    red edge → suggest → accept → re-verify → original edge gone)

Full v4 regression: 769 passed / 5 skipped / 0 failed.

Closes VBSpec roadmap (Stages A-E from VisualBuilderSpec.md).

Author: apstenku123

cppmega_v4/spec/__init__.py

@@ -16,6 +16,13 @@
     insert_adapter_chain,
     suggest_adapter_chain,
 )
+from cppmega_v4.spec.api import (
+    AdapterProposal,
+    VerificationResult,
+    suggest_adapters,
+    suggest_dim_env,
+    verify_and_estimate,
+)
 from cppmega_v4.spec.memory_report import (
     BrickMemoryRow,
     MemoryReport,
@@ -40,9 +47,11 @@
 
 __all__ = [
     "ADAPTER_RULES",
+    "AdapterProposal",
     "AdapterRule",
     "AdapterSuggestion",
     "BrickMemoryRow",
+    "VerificationResult",
     "BrickShapeContract",
     "DiagnosticSeverity",
     "MemoryReport",
@@ -59,4 +68,7 @@
     "registered_kinds",
     "resolve_shapes",
     "suggest_adapter_chain",
+    "suggest_adapters",
+    "suggest_dim_env",
+    "verify_and_estimate",
 ]

cppmega_v4/spec/api.py

@@ -0,0 +1,270 @@
+"""GUI-facing public API: verify + estimate in one call, adapter
+suggestion lookup, ergonomic dim_env builders.
+
+This module is what the visual-builder front-end actually imports. It
+wires together Stages A-D into the three operations the GUI cares about:
+
+  - :func:`verify_and_estimate` — on every graph mutation, return both
+    the diagnostics list (red/yellow/green per edge) and the memory
+    report (bar at the top: ``18.2 / 80 GB``).
+  - :func:`suggest_adapters` — when the user hovers a red edge, propose
+    the adapter chain that would close it.
+  - :func:`suggest_dim_env` — sensible default named-dim env for a given
+    preset name, so the GUI doesn't have to ship a full editor before
+    the first verify lands.
+
+Designed to run in <50 ms per call for any of the 12 architecture
+presets at production-scale dim envs (B=1, S=4096, H=4096) — the
+GUI workflow test in tests/v4/test_vbspec_stage_e.py enforces this.
+"""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from typing import Any
+
+from cppmega_v4.fusion import FusionRegionPlan, plan_fusion_regions
+from cppmega_v4.fusion.brick_graph import BrickGraph, BrickNode
+from cppmega_v4.spec.adapters import (
+    AdapterSuggestion,
+    suggest_adapter_chain,
+)
+from cppmega_v4.spec.memory_report import (
+    MemoryReport,
+    estimate_memory,
+)
+from cppmega_v4.spec.resolver import (
+    ResolvedBrickGraph,
+    resolve_shapes,
+)
+
+
+# ---------------------------------------------------------------------------
+# Default named-dim envs per preset
+# ---------------------------------------------------------------------------
+
+
+# Production-scale defaults. The GUI ships these so a fresh-open model
+# already has a sensible env without the user touching dim sliders.
+# Override by passing your own ``dim_env`` to verify_and_estimate.
+_PROD_BASE: Mapping[str, int] = {
+    "B": 1, "S": 4096, "H": 4096,
+    "nh": 32, "nkv": 4, "head_dim": 128,
+    "num_experts": 8, "top_k": 2,
+}
+
+
+_PROD_MLA_EXTRAS: Mapping[str, int] = {
+    "q_lora_rank": 1536, "kv_lora_rank": 512,
+    "qk_rope_head_dim": 64, "qk_nope_head_dim": 128, "v_head_dim": 128,
+}
+
+
+_PROD_GEMMA_EXTRAS = {"sliding_window_size": 1024}
+_PROD_NEMOTRON_EXTRAS = {"d_state": 64}
+_PROD_ZAYA_EXTRAS = {"fine_window": 256, "coarse_block_size": 16}
+
+
+_PRESET_DIM_ENVS: Mapping[str, Mapping[str, int]] = {
+    "qwen3_next":        dict(_PROD_BASE),
+    "kimi_linear":       {**_PROD_BASE, **_PROD_MLA_EXTRAS},
+    "kimi_k2":           {**_PROD_BASE, **_PROD_MLA_EXTRAS},
+    "deepseek_v3":       {**_PROD_BASE, **_PROD_MLA_EXTRAS},
+    "deepseek_v4_flash": dict(_PROD_BASE),
+    "gemma4":            {**_PROD_BASE, **_PROD_GEMMA_EXTRAS},
+    "mistral4":          {**_PROD_BASE, **_PROD_MLA_EXTRAS},
+    "ling26":            {**_PROD_BASE, **_PROD_MLA_EXTRAS},
+    "longcat":           {**_PROD_BASE, **_PROD_MLA_EXTRAS},
+    "nemotron3":         {**_PROD_BASE, **_PROD_NEMOTRON_EXTRAS},
+    "zaya1":             {**_PROD_BASE, **_PROD_ZAYA_EXTRAS},
+    "arcee_trinity":     {**_PROD_BASE, **_PROD_GEMMA_EXTRAS},
+}
+
+
+def suggest_dim_env(preset_name: str | None = None) -> dict[str, int]:
+    """Return a sensible default named-dim env.
+
+    With ``preset_name=None``, returns the generic production-scale
+    base env (B=1, S=4096, H=4096, nh=32, nkv=4, head_dim=128,
+    num_experts=8, top_k=2). With a preset name, returns the env that
+    includes any preset-specific extra dims (MLA LoRA ranks, sliding
+    window size, etc.).
+    """
+    if preset_name is None:
+        return dict(_PROD_BASE)
+    if preset_name not in _PRESET_DIM_ENVS:
+        raise KeyError(
+            f"unknown preset {preset_name!r}; "
+            f"available: {sorted(_PRESET_DIM_ENVS)}"
+        )
+    return dict(_PRESET_DIM_ENVS[preset_name])
+
+
+# ---------------------------------------------------------------------------
+# verify_and_estimate
+# ---------------------------------------------------------------------------
+
+
+_DEFAULT_SIDE_CHANNELS = frozenset({"doc_ids", "token_ids"})
+
+
+@dataclass(frozen=True)
+class VerificationResult:
+    """One-shot result of :func:`verify_and_estimate`."""
+
+    resolved: ResolvedBrickGraph
+    fusion_plan: tuple[FusionRegionPlan, ...]
+    memory: MemoryReport
+    elapsed_ms: float
+    fits_on_device: bool | None = None
+
+    @property
+    def has_errors(self) -> bool:
+        return self.resolved.has_errors
+
+    def summary(self) -> dict[str, Any]:
+        """Compact dict the GUI can render directly."""
+        return {
+            "errors":    len(self.resolved.errors),
+            "warnings":  len(self.resolved.warnings),
+            "regions":   len(self.fusion_plan),
+            "memory":    self.memory.summary(),
+            "elapsed_ms": round(self.elapsed_ms, 2),
+            "fits_on_device": self.fits_on_device,
+        }
+
+
+def verify_and_estimate(
+    graph: BrickGraph,
+    dim_env: Mapping[str, int] | None = None,
+    *,
+    preset_name: str | None = None,
+    device_hbm_bytes: int | None = None,
+    headroom: float = 0.9,
+    training: bool = True,
+    optimizer: str = "adamw",
+    dtype_bytes: int = 2,
+    kv_cache_dtype_bytes: int = 1,
+    available_side_channels: frozenset[str] = _DEFAULT_SIDE_CHANNELS,
+    strict: bool = False,
+) -> VerificationResult:
+    """Resolve shapes, plan fusion regions, estimate memory — one shot.
+
+    Args:
+      graph: the BrickGraph to verify.
+      dim_env: concrete int values per named dim. If None, falls back
+        to :func:`suggest_dim_env(preset_name)`.
+      preset_name: lookup key for the default dim_env if dim_env=None.
+      device_hbm_bytes: when supplied, the result includes
+        ``fits_on_device`` (Memory.fits_on(device, headroom)).
+      headroom: HBM headroom fraction for fits_on (default 0.9).
+      training: forwarded to estimate_memory.
+      optimizer, dtype_bytes, kv_cache_dtype_bytes: forwarded.
+      available_side_channels: forwarded to resolve_shapes; defaults to
+        ``{"doc_ids", "token_ids"}`` (the most common case for our bricks).
+      strict: when True, resolver raises on first ERROR instead of
+        collecting diagnostics.
+    """
+    if dim_env is None:
+        dim_env = suggest_dim_env(preset_name)
+
+    t0 = time.perf_counter()
+    resolved = resolve_shapes(
+        graph, dim_env,
+        strict=strict,
+        available_side_channels=available_side_channels,
+    )
+    plans = tuple(plan_fusion_regions(graph))
+    memory = estimate_memory(
+        resolved,
+        fusion_plan=plans,
+        training=training,
+        optimizer=optimizer,
+        dtype_bytes=dtype_bytes,
+        kv_cache_dtype_bytes=kv_cache_dtype_bytes,
+    )
+    elapsed_ms = (time.perf_counter() - t0) * 1000.0
+
+    fits = (
+        memory.fits_on(device_hbm_bytes, headroom=headroom)
+        if device_hbm_bytes is not None else None
+    )
+    return VerificationResult(
+        resolved=resolved,
+        fusion_plan=plans,
+        memory=memory,
+        elapsed_ms=elapsed_ms,
+        fits_on_device=fits,
+    )
+
+
+# ---------------------------------------------------------------------------
+# suggest_adapters
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class AdapterProposal:
+    """Bundle returned by :func:`suggest_adapters`.
+
+    Fields:
+      producer / consumer: the names of the edge endpoints.
+      producer_shape / consumer_shape: resolved shapes on the edge.
+      chain: ordered list of AdapterSuggestion steps; empty when shapes
+        already match; None when no chain ≤ max_steps exists.
+      reason: human-readable explanation for the GUI tooltip.
+    """
+
+    producer: str
+    consumer: str
+    producer_shape: tuple[int, ...]
+    consumer_shape: tuple[int, ...]
+    chain: list[AdapterSuggestion] | None
+    reason: str
+
+
+def suggest_adapters(
+    resolved: ResolvedBrickGraph,
+    producer: str,
+    consumer: str,
+    *,
+    max_steps: int = 4,
+) -> AdapterProposal:
+    """Look up the resolved edge ``producer -> consumer`` and produce
+    an :class:`AdapterProposal`. Raises KeyError if no such edge."""
+    edge = resolved.edge(producer, consumer)
+    chain = suggest_adapter_chain(
+        edge.producer_shape, edge.consumer_shape, max_steps=max_steps,
+    )
+    if edge.matched:
+        reason = "shapes already match — no adapter needed"
+    elif chain is None:
+        reason = (
+            f"no adapter chain (≤ {max_steps} hops) bridges "
+            f"{edge.producer_shape} -> {edge.consumer_shape}"
+        )
+    elif not chain:
+        reason = "shapes match by value but resolver disagreed — no adapter needed"
+    else:
+        reason = f"chain of {len(chain)} adapter step(s): " + " -> ".join(
+            s.kind for s in chain
+        )
+    return AdapterProposal(
+        producer=producer,
+        consumer=consumer,
+        producer_shape=edge.producer_shape,
+        consumer_shape=edge.consumer_shape,
+        chain=chain,
+        reason=reason,
+    )
+
+
+__all__ = [
+    "AdapterProposal",
+    "VerificationResult",
+    "suggest_adapters",
+    "suggest_dim_env",
+    "verify_and_estimate",
+]