mas-lab-component-controller 0.2.0__py3-none-any.whl

mas/lab/controller/ui_stream/plugin_registry.py

@@ -0,0 +1,139 @@
+#  Copyright (c) 2026 Cisco Systems, Inc. and its affiliates
+#  SPDX-License-Identifier: Apache-2.0
+"""Discover demo-ui shell modules and registered plot kinds.
+
+Demo-ui has no ``src/plugins`` tree. Chrome and the plot host live next to
+``shell.js``. Plot *kinds* come from ``mas.lab.ui.plots`` providers.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from pathlib import Path
+from typing import Any
+
+_META = re.compile(
+    r"export const pluginMeta\s*=\s*(\{.*?\}|\[.*?\])\s*;",
+    re.S,
+)
+
+_SHELL = ("plot-host.js", "chrome.js", "player.js", "layout-picker.js", "notes-overlay.js")
+
+
+def demo_ui_src() -> Path:
+    env = os.environ.get("MAS_DEMO_UI_ROOT")
+    if env:
+        cand = Path(env).expanduser() / "src"
+        if cand.is_dir():
+            return cand
+    here = Path(__file__).resolve()
+    for parent in here.parents:
+        cand = parent / "demo-ui" / "src"
+        if cand.is_dir():
+            return cand
+    return Path.cwd() / "demo-ui" / "src"
+
+
+def plugins_dir() -> Path:
+    """Deprecated alias: there is no plugins folder. Returns ``demo-ui/src``."""
+    return demo_ui_src()
+
+
+def _parse_meta(text: str) -> list[dict[str, Any]]:
+    match = _META.search(text)
+    if not match:
+        return []
+    blob = match.group(1)
+    blob = re.sub(r"([,{]\s*)([A-Za-z_][A-Za-z0-9_]*)\s*:", r'\1"\2":', blob)
+    blob = blob.replace("'", '"')
+    blob = re.sub(r",(\s*[}\]])", r"\1", blob)
+    try:
+        data = json.loads(blob)
+    except json.JSONDecodeError:
+        return []
+    if isinstance(data, dict):
+        return [data]
+    if isinstance(data, list):
+        return [row for row in data if isinstance(row, dict)]
+    return []
+
+
+def _shell_rows() -> list[dict[str, Any]]:
+    root = demo_ui_src()
+    rows: list[dict[str, Any]] = []
+    for name in _SHELL:
+        path = root / name
+        if not path.is_file():
+            continue
+        module = f"/src/{name}"
+        metas = _parse_meta(path.read_text(encoding="utf-8"))
+        if not metas:
+            rows.append({"id": path.stem, "module": module, "kind": "chrome"})
+            continue
+        for meta in metas:
+            row = dict(meta)
+            row.setdefault("id", path.stem)
+            row["module"] = module
+            rows.append(row)
+    return rows
+
+
+def _plot_kind_rows() -> list[dict[str, Any]]:
+    rows: list[dict[str, Any]] = []
+    try:
+        from mas.lab.plots.providers import load_plot_providers
+
+        for provider in load_plot_providers():
+            for kind in sorted(provider.kinds):
+                stream = ""
+                try:
+                    stream = provider.stream_for(kind)
+                except Exception:
+                    stream = ""
+                rows.append(
+                    {
+                        "id": kind,
+                        "kind": "plot",
+                        "formats": ["html"],
+                        "realtime": True,
+                        "stream": stream,
+                        "module": "/src/plot-host.js",
+                    }
+                )
+    except Exception:
+        pass
+    return rows
+
+
+def list_plugins(
+    *,
+    kind: str | None = None,
+    format: str | None = None,
+    realtime: bool | None = None,
+) -> list[dict[str, Any]]:
+    rows = _shell_rows() + _plot_kind_rows()
+    seen: set[tuple[str, str]] = set()
+    unique: list[dict[str, Any]] = []
+    for row in rows:
+        key = (str(row.get("id") or ""), str(row.get("module") or ""))
+        if key in seen:
+            continue
+        seen.add(key)
+        unique.append(row)
+    out = unique
+    if kind:
+        out = [row for row in out if str(row.get("kind") or "") == kind]
+    if format:
+        out = [
+            row
+            for row in out
+            if format in [str(x) for x in (row.get("formats") or [])]
+            or str(row.get("format") or "") == format
+        ]
+    if realtime is True:
+        out = [row for row in out if row.get("realtime") is True]
+    if realtime is False:
+        out = [row for row in out if not row.get("realtime")]
+    return out

mas/lab/controller/ui_stream/refs.py

@@ -0,0 +1,259 @@
+#  Copyright (c) 2026 Cisco Systems, Inc. and its affiliates
+#  SPDX-License-Identifier: Apache-2.0
+"""ID-only DataSourceRef, topic matching, and event envelopes."""
+
+from __future__ import annotations
+
+import fnmatch
+from contextvars import ContextVar
+from dataclasses import asdict, dataclass
+from datetime import UTC, datetime
+from typing import Any, Literal
+
+_clock: ContextVar[str | None] = ContextVar("mas_ui_clock", default=None)
+_nonce: ContextVar[str | None] = ContextVar("mas_ui_nonce", default=None)
+
+
+def use_clock(value: str | None):
+    """Stamp envelopes with a clock owner (``server`` = DES owns timing)."""
+    return _clock.set(value)
+
+
+def use_nonce(value: str | None):
+    """Stamp envelopes with the UI registration nonce for this channel."""
+    return _nonce.set(value)
+
+
+def reset_clock(token) -> None:
+    _clock.reset(token)
+
+
+def reset_nonce(token) -> None:
+    _nonce.reset(token)
+
+Mode = Literal["live", "replay", "historical"]
+Source = Literal[
+    "command",
+    "result",
+    "control",
+    "native",
+    "telemetry",
+    "metric",
+    "job",
+    "catalog",
+    "spec",
+    "artifact",
+    "io",
+    "governance",
+    "custom",
+    "view",
+]
+
+STREAMS = {
+    "spec": "spec",
+    "observability": "native",
+    "hitl": "control",
+    "artifacts": "artifact",
+    "metrics": "metric",
+    "governance": "governance",
+}
+
+
+@dataclass
+class DataSourceRef:
+    library: str | None = None
+    experiment: str | None = None
+    scenario: str | None = None
+    test: str | None = None
+    run: str | None = None
+    session: str | None = None
+    overlay: str | None = None
+    batch: str | None = None
+    origin: str | None = None
+    mode: Mode | None = None
+
+    def merge(self, override: DataSourceRef | dict[str, Any] | None) -> DataSourceRef:
+        if override is None:
+            return DataSourceRef(**asdict(self))
+        data = asdict(self)
+        extra = asdict(override) if isinstance(override, DataSourceRef) else dict(override)
+        for key, value in extra.items():
+            if key not in data:
+                continue
+            if value is not None and value != "":
+                data[key] = value
+        return DataSourceRef(**data)
+
+    def as_dict(self) -> dict[str, Any]:
+        return {k: v for k, v in asdict(self).items() if v is not None}
+
+    def matches(self, other: DataSourceRef) -> bool:
+        for key in ("library", "experiment", "test", "run", "session", "overlay", "batch"):
+            mine = getattr(self, key)
+            theirs = getattr(other, key)
+            if mine and theirs and mine != theirs:
+                return False
+        # A panel that binds a scenario must not also paint unscoped or other-lane events.
+        if self.scenario and self.scenario != (other.scenario or ""):
+            return False
+        return True
+
+    def missing_for(self, required: tuple[str, ...]) -> list[str]:
+        return [name for name in required if not getattr(self, name)]
+
+    def coordinate(self) -> str:
+        return "|".join(
+            [
+                self.library or "",
+                self.experiment or "",
+                self.scenario or "",
+                self.test or "",
+                self.run or "",
+                self.session or "",
+            ]
+        )
+
+
+def envelope_from_mapping(data: dict[str, Any] | None) -> EventEnvelope:
+    row = data or {}
+    source = row.get("source") or "native"
+    allowed = {
+        "command",
+        "result",
+        "control",
+        "native",
+        "telemetry",
+        "metric",
+        "job",
+        "catalog",
+        "spec",
+        "artifact",
+        "io",
+        "governance",
+        "custom",
+        "view",
+    }
+    if source not in allowed:
+        source = "custom" if str(row.get("topic") or "").startswith("custom.") else "native"
+    return envelope(
+        str(row.get("topic") or "native.unknown"),
+        ref_from_mapping(row.get("ref") if isinstance(row.get("ref"), dict) else {}),
+        source,  # type: ignore[arg-type]
+        row.get("payload"),
+        replay=bool(row.get("replay", True)),
+        event_id=row.get("id"),
+        ts=row.get("ts") if isinstance(row.get("ts"), str) else None,
+        clock=row.get("clock") or "server",
+        complete=row.get("complete") if isinstance(row.get("complete"), bool) else None,
+        artefact=str(row.get("artefact") or "") or None,
+        uri=str(row.get("uri") or "") or None,
+        path=str(row.get("path") or "") or None,
+        inputs=list(row.get("inputs") or []) or None,
+        outputs=list(row.get("outputs") or []) or None,
+        nonce=str(row["nonce"]) if row.get("nonce") else None,
+    )
+
+
+def ref_from_mapping(data: dict[str, Any] | None) -> DataSourceRef:
+    if not data:
+        return DataSourceRef()
+    allowed = {f.name for f in DataSourceRef.__dataclass_fields__.values()}
+    filtered = {k: v for k, v in data.items() if k in allowed and v not in (None, "")}
+    return DataSourceRef(**filtered)
+
+
+@dataclass
+class EventEnvelope:
+    topic: str
+    ts: str
+    ref: DataSourceRef
+    source: Source
+    payload: Any = None
+    replay: bool = False
+    id: str | None = None
+    clock: str | None = None
+    complete: bool | None = None
+    artefact: str | None = None
+    uri: str | None = None
+    path: str | None = None
+    inputs: list[str] | None = None
+    outputs: list[str] | None = None
+    nonce: str | None = None
+
+    def as_dict(self) -> dict[str, Any]:
+        data = {
+            "topic": self.topic,
+            "ts": self.ts,
+            "ref": self.ref.as_dict(),
+            "source": self.source,
+            "payload": self.payload,
+            "replay": self.replay,
+            "id": self.id,
+        }
+        if self.clock:
+            data["clock"] = self.clock
+        if self.artefact:
+            data["artefact"] = self.artefact
+        if self.uri:
+            data["uri"] = self.uri
+        if self.path:
+            data["path"] = self.path
+        if self.inputs:
+            data["inputs"] = list(self.inputs)
+        if self.outputs:
+            data["outputs"] = list(self.outputs)
+        if self.complete is not None:
+            data["complete"] = self.complete
+        if self.nonce:
+            data["nonce"] = self.nonce
+        return data
+
+
+def now_iso() -> str:
+    return datetime.now(UTC).isoformat()
+
+
+def topic_matches(declared: list[str] | tuple[str, ...], topic: str) -> bool:
+    if not declared:
+        return True
+    return any(fnmatch.fnmatchcase(topic, glob) for glob in declared)
+
+
+def envelope(
+    topic: str,
+    ref: DataSourceRef,
+    source: Source,
+    payload: Any,
+    *,
+    replay: bool = False,
+    event_id: str | None = None,
+    ts: str | None = None,
+    clock: str | None = None,
+    complete: bool | None = None,
+    artefact: str | None = None,
+    uri: str | None = None,
+    path: str | None = None,
+    inputs: list[str] | None = None,
+    outputs: list[str] | None = None,
+    nonce: str | None = None,
+) -> EventEnvelope:
+    from mas.lab.controller.ui_stream.artefact_bind import link_for_topic
+
+    link = link_for_topic(topic, ref.as_dict(), complete=complete)
+    return EventEnvelope(
+        topic=topic,
+        ts=ts or now_iso(),
+        ref=ref,
+        source=source,
+        payload=payload,
+        replay=replay,
+        id=event_id,
+        clock=clock or _clock.get(),
+        complete=complete if complete is not None else link.complete,
+        artefact=artefact or link.name,
+        uri=uri or link.uri,
+        path=path or link.path,
+        inputs=list(inputs) if inputs is not None else list(link.inputs),
+        outputs=list(outputs) if outputs is not None else list(link.outputs),
+        nonce=nonce if nonce is not None else _nonce.get(),
+    )

mas/lab/controller/ui_stream/replay.py

@@ -0,0 +1,236 @@
+#  Copyright (c) 2026 Cisco Systems, Inc. and its affiliates
+#  SPDX-License-Identifier: Apache-2.0
+"""Filter recorded native events for the demo UI bus."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Iterable, Iterator
+
+from mas.lab.controller.ui_stream.governance import compact_context_record
+from mas.lab.controller.ui_stream.metrics import coerce_timestamp
+
+KEEP_KINDS = frozenset(
+    {
+        # NOTE: "context_assembled"/"context_usage" are deliberately absent --
+        # they carry prompt/message content and are pull-only, demand-driven
+        # (see docs/ui/live.md's "Governance / context stream" and
+        # ingest.py's NativeIngest._wants_context()). They only reach replay
+        # via demo_records(..., extra_kinds=extra_native_kinds(["context"]))
+        # when a mounted plugin actually subscribed to governance.context --
+        # same gate the live path already enforces. Putting them back here
+        # would leak context on every replay regardless of subscription.
+        "mas_call_start",
+        "mas_call_end",
+        "execution_start",
+        "execution_end",
+        "llm_call_start",
+        "llm_call_end",
+        "tool_call_start",
+        "tool_call_end",
+        "user_response",
+        "client_response",
+        "hitl_gate",
+        "hitl_resolve",
+        "hitl_request",
+        "metric",
+        "governance_decision",
+        "control.structure",
+        "control.context",
+        "scope.progress",
+    }
+)
+
+
+def parse_jsonl(text: str) -> list[dict[str, Any]]:
+    records: list[dict[str, Any]] = []
+    for line in str(text or "").splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            item = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(item, dict):
+            records.append(item)
+    return records
+
+
+def demo_records(
+    records: Iterable[dict[str, Any]],
+    *,
+    extra_kinds: Iterable[str] = (),
+) -> Iterator[dict[str, Any]]:
+    keep = KEEP_KINDS | frozenset(extra_kinds)
+    for record in records:
+        kind = str(record.get("kind") or "")
+        if kind not in keep:
+            continue
+        if kind in {"context_assembled", "context_usage"}:
+            yield compact_context_record(record)
+        else:
+            yield record
+
+
+def metric_record_from_artefact(path: Path) -> dict[str, Any] | None:
+    """Turn a cached ``metrics.json`` into a bus ``kind: metric`` record."""
+    try:
+        doc = json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return None
+    if not isinstance(doc, dict):
+        return None
+    try:
+        from mas.library.lab.steps.services.metric_event import flatten_mce_document
+    except Exception:
+        return None
+    metrics = flatten_mce_document(doc)
+    if not metrics:
+        return None
+    record: dict[str, Any] = {"kind": "metric", "name": "eval_mce", "metrics": metrics}
+    if doc.get("scenario"):
+        record["scenario"] = doc["scenario"]
+    return record
+
+
+def metric_records_from_progress(path: Path) -> list[dict[str, Any]]:
+    """Wrap ``progress.jsonl`` rows as ``kind: metric`` records."""
+    if not path.is_file():
+        return []
+    out: list[dict[str, Any]] = []
+    for record in parse_jsonl(path.read_text(encoding="utf-8")):
+        if not isinstance(record, dict):
+            continue
+        wrapped = {
+            "kind": "metric",
+            "name": str(record.get("name") or "eval_progress"),
+            "metrics": record,
+        }
+        ts = record.get("snapshot_at") or record.get("timestamp") or record.get("ts")
+        if ts:
+            wrapped["timestamp"] = ts
+        if record.get("scenario"):
+            wrapped["scenario"] = record["scenario"]
+        out.append(wrapped)
+    return out
+
+
+def custom_panel_records(path: Path | None) -> list[dict[str, Any]]:
+    """Read a persisted ``custom.{owner}.jsonl`` sibling trace for replay.
+
+    Each line is already a complete ``kind: custom.{owner}`` record (stamped
+    with ``ts`` at write time) -- no transform needed, unlike the
+    metric/progress readers above.
+    """
+    if path is None or not path.is_file():
+        return []
+    out: list[dict[str, Any]] = []
+    for record in parse_jsonl(path.read_text(encoding="utf-8")):
+        if isinstance(record, dict) and str(record.get("kind") or "").startswith("custom."):
+            out.append(record)
+    return out
+
+
+def _record_ts(record: dict[str, Any]) -> float:
+    return coerce_timestamp(record.get("timestamp", record.get("ts", record.get("snapshot_at")))) or 0.0
+
+
+def metric_anchor(record: dict[str, Any]) -> tuple[str, str]:
+    """Live+cache join uses (kind, agent_id), never call_id or wall clock."""
+    return (str(record.get("kind") or ""), str(record.get("agent_id") or ""))
+
+
+def synthesize_metric_ticks(records: Iterable[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Replay ticks by folding the same trace-stats counters used live."""
+    try:
+        from mas.library.lab.steps.extract.trace_stats import (
+            empty_trace_stats,
+            fold_trace_event,
+            public_trace_stats,
+        )
+    except Exception:
+        return []
+    stats = empty_trace_stats()
+    ticks: list[dict[str, Any]] = []
+    last: dict[str, Any] | None = None
+    nth: dict[tuple[str, str], int] = {}
+    emit_kinds = {"llm_call_end", "tool_call_end", "execution_end", "mas_call_end"}
+    for seq, record in enumerate(records or []):
+        if not isinstance(record, dict):
+            continue
+        kind = str(record.get("kind") or "")
+        if kind == "metric":
+            continue
+        fold_trace_event(stats, record)
+        pub = public_trace_stats(stats)
+        key = metric_anchor(record)
+        nth[key] = nth.get(key, 0) + 1
+        if kind not in emit_kinds or not pub:
+            continue
+        if pub == last:
+            continue
+        last = dict(pub)
+        tick: dict[str, Any] = {
+            "kind": "metric",
+            "name": "trace_stats",
+            "metrics": pub,
+            "seq": seq,
+            "anchor_kind": kind,
+            "agent_id": record.get("agent_id"),
+            "nth": nth[key],
+        }
+        ts = record.get("timestamp", record.get("ts"))
+        if ts is not None:
+            tick["timestamp"] = ts
+        if record.get("call_id"):
+            tick["call_id"] = record["call_id"]
+        if record.get("scenario"):
+            tick["scenario"] = record["scenario"]
+        ticks.append(tick)
+    return ticks
+
+
+def stamp_artefact_metrics(record: dict[str, Any] | None, events: Iterable[dict[str, Any]]) -> dict[str, Any] | None:
+    """Put final metrics.json at the end of replay, not at t=0."""
+    if not record:
+        return None
+    if record.get("timestamp") not in (None, ""):
+        return record
+    last = 0.0
+    for item in events or []:
+        last = max(last, _record_ts(item))
+    if last:
+        record = {**record, "timestamp": last}
+    return record
+
+
+def merge_replay_records(*groups: Iterable[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Stable time-order merge so progress ticks with native events instead of dumping at the end."""
+    merged: list[dict[str, Any]] = []
+    for group in groups:
+        merged.extend(list(group or []))
+    indexed = list(enumerate(merged))
+    indexed.sort(key=lambda item: (_record_ts(item[1]), item[0]))
+    return [item[1] for item in indexed]
+
+
+def trace_metric_records(
+    *,
+    metrics: Path | None = None,
+    progress: Path | None = None,
+    events: Iterable[dict[str, Any]] | None = None,
+) -> list[dict[str, Any]]:
+    extra: list[dict[str, Any]] = []
+    native = list(events or [])
+    authored = metric_records_from_progress(progress) if progress is not None else []
+    if authored:
+        extra.extend(authored)
+    else:
+        extra.extend(synthesize_metric_ticks(native))
+    if metrics is not None:
+        artefact = stamp_artefact_metrics(metric_record_from_artefact(metrics), native)
+        if artefact is not None:
+            extra.append(artefact)
+    return extra