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

mas/lab/controller/schemas/pipeline-step-types-pre.json

@@ -0,0 +1,35 @@
+{
+  "$comment": "Registry of all pipeline step types with their config schemas. Use this to build a dynamic pipeline editor in React.",
+  "step_types": [
+    {
+      "type": "service_start",
+      "label": "Start Service",
+      "description": "Start an infrastructure service (Neo4j, OTel collector, etc.) before the benchmark loop.",
+      "phase": "pre",
+      "category": "infrastructure",
+      "config": {
+        "service": {
+          "type": "string",
+          "required": true,
+          "description": "Service name declared in the infra bundle (e.g. neo4j, otel-collector)"
+        },
+        "health_timeout": {
+          "type": "integer",
+          "default": 60,
+          "description": "Seconds to wait for the service health check to pass"
+        }
+      }
+    }
+  ],
+  "categories": [
+    { "id": "data", "label": "Data", "color": "#3b82f6" },
+    { "id": "execution", "label": "Execution", "color": "#8b5cf6" },
+    { "id": "extraction", "label": "Extraction", "color": "#06b6d4" },
+    { "id": "normalization", "label": "Normalization", "color": "#14b8a6" },
+    { "id": "analysis", "label": "Analysis", "color": "#f59e0b" },
+    { "id": "evaluation", "label": "Evaluation", "color": "#ef4444" },
+    { "id": "visualization", "label": "Visualization", "color": "#22c55e" },
+    { "id": "graph", "label": "Graph DB", "color": "#a855f7" },
+    { "id": "infrastructure", "label": "Infrastructure", "color": "#64748b" }
+  ]
+}

mas/lab/controller/scope_catalog.py

@@ -0,0 +1,266 @@
+#  Copyright (c) 2026 Cisco Systems, Inc. and its affiliates
+#  SPDX-License-Identifier: Apache-2.0
+"""Libraries and labs as first-class scopes (a lab is never a library)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Iterable
+
+from mas.lab.controller.kinds import LAB_KINDS, LIBRARY_BASE_KINDS
+from mas.lab.controller.path_safety import UnsafeNameError, ensure_inside
+from mas.runtime.constants import LAB_CONFIG_FILENAME, LIBRARY_MANIFEST_FILENAME
+from mas.runtime.spec.source import load_yaml_file
+
+
+def _title_from_slug(slug: str) -> str:
+    return slug.replace("-", " ").replace("_", " ").title()
+
+
+def _description_of(path: Path) -> str:
+    from mas.lab.controller.lab_registry import _library_description
+
+    return _library_description(path)
+
+
+def _is_lab_root(path: Path) -> bool:
+    if path.name.endswith(".lab"):
+        return True
+    return (path / LAB_CONFIG_FILENAME).is_file() and not (path / LIBRARY_MANIFEST_FILENAME).is_file()
+
+
+def _origin_from_source(source: str, *, path: Path) -> str:
+    src = source or ""
+    if src.startswith("entry-point"):
+        return "package"
+    if src.startswith("lab-local") or src.startswith("lab:"):
+        return "lab"
+    if "labs_search_paths" in src or "cwd-walk" in src or "labs_root" in src or "find_workspace_root" in src:
+        return "lab" if _is_lab_root(path) else "workspace"
+    if src.startswith("path:") or "MAS_LIBRARY_PATHS" in src:
+        return "path"
+    if src.startswith("manifest_libraries"):
+        return "workspace"
+    if _is_lab_root(path):
+        return "lab"
+    return "workspace"
+
+
+@dataclass
+class Scope:
+    id: str
+    kind: str
+    name: str
+    title: str
+    description: str
+    origin: str
+    writable: bool
+    root: Path
+    libraries: list[str] = field(default_factory=list)
+    owner: str | None = None
+    kinds: list[str] = field(default_factory=list)
+    counts: dict[str, int] = field(default_factory=dict)
+
+    def to_public(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "id": self.id,
+            "kind": self.kind,
+            "name": self.name,
+            "title": self.title,
+            "description": self.description,
+            "origin": self.origin,
+            "writable": self.writable,
+            "kinds": list(self.kinds),
+        }
+        if self.libraries:
+            payload["libraries"] = list(self.libraries)
+        if self.owner:
+            payload["owner"] = self.owner
+        if self.counts:
+            payload["counts"] = dict(self.counts)
+        return payload
+
+
+class ScopeCatalog:
+    """Index of library and lab scopes derived from :class:`LabRegistry`."""
+
+    def __init__(self, scopes: dict[str, Scope]):
+        self._scopes = scopes
+
+    def all(self) -> list[Scope]:
+        def _sort_key(scope: Scope) -> tuple[str, str]:
+            return (scope.kind, scope.name)
+
+        return sorted(self._scopes.values(), key=_sort_key)
+
+    def get(self, scope_id: str) -> Scope:
+        scope = self._scopes.get(scope_id)
+        if scope is None:
+            # Allow a bare slug: try library first, then lab (old UI URLs).
+            if ":" not in scope_id:
+                for prefix in ("library:", "lab:"):
+                    found = self._scopes.get(f"{prefix}{scope_id}")
+                    if found is not None:
+                        return found
+            raise KeyError(scope_id)
+        return scope
+
+    def visible_libraries(self, scope_id: str) -> list[Scope]:
+        """Libraries this scope may reference, in documented search order.
+
+        Lab-local libraries first, then workspace, installed (package), path.
+        """
+        origin_order = {"lab": 0, "workspace": 1, "package": 2, "path": 3}
+        scope = self.get(scope_id)
+        libraries = [s for s in self.all() if s.kind == "library"]
+        if scope.kind == "lab":
+            owned = [s for s in libraries if s.owner == scope.id]
+            others = [s for s in libraries if s.owner != scope.id]
+            owned.sort(key=lambda s: s.name)
+            others.sort(key=lambda s: (origin_order.get(s.origin, 9), s.name))
+            return owned + others
+        libraries.sort(key=lambda s: (origin_order.get(s.origin, 9), s.name))
+        return libraries
+
+    @classmethod
+    def from_registry(
+        cls,
+        registry: Any,
+        *,
+        read_only_slugs: Iterable[str] | None = None,
+    ) -> "ScopeCatalog":
+        read_only = set(read_only_slugs or ())
+        libraries: dict[str, Path] = dict(registry.library_paths())
+        sources: dict[str, str] = dict(getattr(registry, "_library_sources", {}) or {})
+
+        labs: list[Scope] = []
+        lib_scopes: list[Scope] = []
+
+        for slug, path in libraries.items():
+            source = sources.get(slug, "")
+            origin = _origin_from_source(source, path=path)
+            if _is_lab_root(path):
+                name = slug
+                try:
+                    doc = load_yaml_file(path / LAB_CONFIG_FILENAME) if (path / LAB_CONFIG_FILENAME).is_file() else {}
+                    lab_block = (doc or {}).get("lab") or {}
+                    name = str(lab_block.get("name") or slug)
+                except Exception:
+                    name = slug
+                labs.append(
+                    Scope(
+                        id=f"lab:{name}",
+                        kind="lab",
+                        name=name,
+                        title=_title_from_slug(name),
+                        description=_description_of(path),
+                        origin="lab",
+                        writable=True,
+                        root=path.resolve(),
+                        kinds=list(LAB_KINDS),
+                    )
+                )
+                continue
+            # A lab root is never a library, even if someone added library.yaml.
+            writable = origin != "package" and slug not in read_only
+            lib_scopes.append(
+                Scope(
+                    id=f"library:{slug}",
+                    kind="library",
+                    name=slug,
+                    title=_title_from_slug(slug),
+                    description=_description_of(path),
+                    origin=origin if origin != "lab" else "workspace",
+                    writable=writable,
+                    root=path.resolve(),
+                    kinds=list(LIBRARY_BASE_KINDS),
+                )
+            )
+
+        # Nested lab-local libraries (lab.libraries + immediate children with library.yaml).
+        known_roots = {s.root for s in lib_scopes}
+        for lab in labs:
+            for child in _lab_local_libraries(lab.root):
+                if child.resolve() in known_roots:
+                    continue
+                slug = child.name
+                lib_scopes.append(
+                    Scope(
+                        id=f"library:{slug}",
+                        kind="library",
+                        name=slug,
+                        title=_title_from_slug(slug),
+                        description=_description_of(child),
+                        origin="lab",
+                        writable=True,
+                        root=child.resolve(),
+                        owner=lab.id,
+                        kinds=list(LIBRARY_BASE_KINDS),
+                    )
+                )
+                known_roots.add(child.resolve())
+
+        for lib in lib_scopes:
+            for lab in labs:
+                try:
+                    lib.root.relative_to(lab.root)
+                except ValueError:
+                    continue
+                lib.origin = "lab"
+                lib.owner = lab.id
+                break
+
+        by_id = {s.id: s for s in labs + lib_scopes}
+        for lab in labs:
+            lab.libraries = [
+                s.id for s in lib_scopes if s.owner == lab.id
+            ]
+        return cls(by_id)
+
+
+def _lab_local_libraries(lab_root: Path) -> list[Path]:
+    found: list[Path] = []
+    seen: set[Path] = set()
+    config = lab_root / LAB_CONFIG_FILENAME
+    if config.is_file():
+        try:
+            doc = load_yaml_file(config) or {}
+        except Exception:
+            doc = {}
+        listed = ((doc.get("lab") or {}).get("libraries")) or []
+        for rel in listed:
+            try:
+                child = ensure_inside(lab_root, lab_root / str(rel))
+            except (UnsafeNameError, OSError):
+                continue
+            if (child / LIBRARY_MANIFEST_FILENAME).is_file() and child not in seen:
+                found.append(child)
+                seen.add(child)
+    if lab_root.is_dir():
+        for child in sorted(lab_root.iterdir()):
+            if child.is_dir() and (child / LIBRARY_MANIFEST_FILENAME).is_file() and child.resolve() not in seen:
+                found.append(child.resolve())
+                seen.add(child.resolve())
+    return found
+
+
+def get_scope_catalog(store: Any | None = None) -> ScopeCatalog:
+    """Build a catalog from the current manifest store / registry."""
+    if store is None:
+        from mas.lab.controller.deps import get_manifest_store
+
+        store = get_manifest_store()
+    registry = getattr(store, "_registry", None)
+    if registry is None:
+        from mas.lab.controller.lab_registry import get_lab_registry
+
+        registry = get_lab_registry()
+    read_only = getattr(store, "_read_only_slugs", None)
+    catalog = ScopeCatalog.from_registry(registry, read_only_slugs=read_only)
+    from mas.lab.controller.workspace_library import workspace_scope
+
+    extra = workspace_scope()
+    if extra is not None and extra.id not in catalog._scopes:
+        catalog._scopes[extra.id] = extra
+    return catalog

mas/lab/controller/scope_service.py

@@ -0,0 +1,134 @@
+#  Copyright (c) 2026 Cisco Systems, Inc. and its affiliates
+#  SPDX-License-Identifier: Apache-2.0
+"""Create lab scopes on a writable labs search path."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from mas.lab.controller.item_service import ItemError, _catalog
+from mas.lab.controller.path_safety import UnsafeNameError, validate_name
+from mas.runtime.constants import LAB_CONFIG_FILENAME, LIBRARY_MANIFEST_FILENAME
+
+
+def create_lab(
+    *,
+    name: str,
+    description: str = "",
+    local_library: bool = True,
+    store: Any | None = None,
+) -> Any:
+    """Write ``{name}.lab`` under the first writable labs search path."""
+    try:
+        name = validate_name(name)
+    except UnsafeNameError as exc:
+        raise ItemError(400, str(exc)) from exc
+    if store is None:
+        from mas.lab.controller.deps import get_manifest_store
+
+        store = get_manifest_store()
+    catalog = _catalog(store)
+    try:
+        catalog.get(f"lab:{name}")
+    except KeyError:
+        pass
+    else:
+        raise ItemError(409, f"lab {name!r} already exists")
+    parent = _labs_parent(store)
+    lab_dir = parent / f"{name}.lab"
+    if lab_dir.exists():
+        raise ItemError(409, f"lab directory {lab_dir.name} already exists")
+    lab_dir.mkdir(parents=True)
+    (lab_dir / "experiments").mkdir()
+    (lab_dir / "overlays").mkdir()
+    (lab_dir / "datasets").mkdir()
+    lib_rel = ""
+    if local_library:
+        lib_rel = f"{name.replace('-', '_')}_lab"
+        lib_dir = lab_dir / lib_rel
+        lib_dir.mkdir()
+        (lib_dir / "apps").mkdir()
+        (lib_dir / LIBRARY_MANIFEST_FILENAME).write_text(
+            _library_manifest(lib_rel, name),
+            encoding="utf-8",
+        )
+    (lab_dir / LAB_CONFIG_FILENAME).write_text(
+        _lab_config(name, description, lib_rel),
+        encoding="utf-8",
+    )
+    _register_created(store, name, lab_dir)
+    return _catalog(store).get(f"lab:{name}")
+
+
+def _labs_parent(store: Any) -> Path:
+    registry = getattr(store, "_registry", None)
+    search_paths: list[str] = []
+    if registry is not None and hasattr(registry, "_labs_search_paths"):
+        search_paths = list(registry._labs_search_paths())
+    if not search_paths:
+        search_paths = ["labs"]
+    base = None
+    if registry is not None and hasattr(registry, "_workspace_root"):
+        base = registry._workspace_root()
+    if base is not None:
+        for entry in search_paths:
+            path = Path(str(entry)).expanduser()
+            if not path.is_absolute():
+                path = base / path
+            path = path.resolve()
+            if path.name.endswith(".lab"):
+                path = path.parent
+            path.mkdir(parents=True, exist_ok=True)
+            return path
+    for scope in _catalog(store).all():
+        if scope.kind == "lab" and scope.writable:
+            return scope.root.parent
+    fallback = Path.cwd() / "labs"
+    fallback.mkdir(parents=True, exist_ok=True)
+    return fallback
+
+
+def _register_created(store: Any, slug: str, lab_dir: Path) -> None:
+    resolved = lab_dir.resolve()
+    registry = getattr(store, "_registry", None)
+    was_live = bool(getattr(store, "_refreshed", False)) and bool(
+        getattr(registry, "_refreshed", False)
+    )
+    if registry is not None:
+        libraries = getattr(registry, "_libraries", None)
+        sources = getattr(registry, "_library_sources", None)
+        if isinstance(libraries, dict):
+            libraries[slug] = resolved
+        if isinstance(sources, dict):
+            sources[slug] = "created"
+        if hasattr(registry, "invalidate_manifest_cache"):
+            registry.invalidate_manifest_cache()
+    store_libs = getattr(store, "_libraries", None)
+    if isinstance(store_libs, dict):
+        store_libs[slug] = resolved
+    if was_live and hasattr(store, "refresh"):
+        store.refresh()
+    elif hasattr(store, "invalidate"):
+        store.invalidate()
+
+
+def _lab_config(name: str, description: str, library: str) -> str:
+    lines = ["lab:", f"  name: {name}"]
+    if description.strip():
+        lines.append(f"  description: {json.dumps(description.strip())}")
+    if library:
+        lines.append("  libraries:")
+        lines.append(f"    - {library}/")
+    return "\n".join(lines) + "\n"
+
+
+def _library_manifest(lib_name: str, lab_name: str) -> str:
+    desc = json.dumps(f"Local library for {lab_name}")
+    return (
+        "apiVersion: mas/v1\n"
+        "kind: Library\n"
+        f"name: {lib_name}\n"
+        f"description: {desc}\n"
+    )

mas/lab/controller/sessions.py

@@ -0,0 +1,63 @@
+#  Copyright (c) 2026 Cisco Systems, Inc. and its affiliates
+#  SPDX-License-Identifier: Apache-2.0
+"""Client session registry — idle auto-shutdown when no users and no workers."""
+from __future__ import annotations
+
+import os
+import time
+from typing import TYPE_CHECKING, Optional
+
+from mas.lab.controller.worker_model import WorkerStatus
+
+if TYPE_CHECKING:
+    from mas.lab.controller.api import ControllerAPI
+
+IDLE_SHUTDOWN_SEC = float(os.environ.get("MAS_CONTROLLER_IDLE_SEC", "30"))
+
+
+class SessionRegistry:
+    """Track CLI / test client sessions; signal idle shutdown when empty."""
+
+    def __init__(self) -> None:
+        self._sessions: dict[str, float] = {}
+        self._idle_since: Optional[float] = None
+
+    def acquire(self, session_id: str) -> None:
+        self._sessions[session_id] = time.time()
+        self._idle_since = None
+
+    def release(self, session_id: str) -> None:
+        self._sessions.pop(session_id, None)
+
+    def touch(self, session_id: str) -> None:
+        if session_id in self._sessions:
+            self._sessions[session_id] = time.time()
+
+    def count(self) -> int:
+        return len(self._sessions)
+
+    def active_worker_count(self, api: ControllerAPI) -> int:
+        return sum(
+            1
+            for w in api.workers.list_workers()
+            if w.status in (WorkerStatus.PENDING, WorkerStatus.RUNNING)
+        )
+
+    def should_shutdown(self, api: ControllerAPI, *, idle_sec: float | None = None) -> bool:
+        """True when no sessions, no active workers, and idle for *idle_sec*."""
+        threshold = idle_sec if idle_sec is not None else IDLE_SHUTDOWN_SEC
+        if self._sessions or self.active_worker_count(api) > 0:
+            self._idle_since = None
+            return False
+        now = time.time()
+        if self._idle_since is None:
+            self._idle_since = now
+            return threshold <= 0
+        return (now - self._idle_since) >= threshold
+
+    def status(self) -> dict:
+        return {
+            "sessions": self.count(),
+            "idle_since": self._idle_since,
+            "idle_shutdown_sec": IDLE_SHUTDOWN_SEC,
+        }

mas/lab/controller/settings.py

@@ -0,0 +1,65 @@
+#  Copyright (c) 2026 Cisco Systems, Inc. and its affiliates
+#  SPDX-License-Identifier: Apache-2.0
+"""Explicit controller settings (no environment variables in runtime code)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+_LOOPBACK_UI_ORIGINS = (
+    "http://localhost:5173",
+    "http://127.0.0.1:5173",
+    "http://localhost:4173",
+    "http://127.0.0.1:4173",
+    "http://localhost:8080",
+    "http://127.0.0.1:8080",
+    "http://localhost:8090",
+    "http://127.0.0.1:8090",
+)
+
+
+def is_loopback_host(host: str) -> bool:
+    """True for binds that only listen on the local machine."""
+    return host in {"127.0.0.1", "localhost", "::1"}
+
+
+@dataclass
+class ControllerSettings:
+    """Flags the daemon / ``mas-lab serve`` pass into :func:`create_app`."""
+
+    host: str = "127.0.0.1"
+    port: int = 8090
+    cors_origins: list[str] = field(default_factory=list)
+    token: str | None = None
+    state_dir: Path | None = None
+    api_version: str = "0.3.0"
+
+    @property
+    def auth_mode(self) -> str:
+        return "bearer" if self.token else "none"
+
+    @property
+    def cors_allow_origins(self) -> list[str]:
+        if self.cors_origins:
+            return list(self.cors_origins)
+        if is_loopback_host(self.host):
+            return list(_LOOPBACK_UI_ORIGINS)
+        return []
+
+    @property
+    def resolved_state_dir(self) -> Path:
+        if self.state_dir is not None:
+            return Path(self.state_dir)
+        from mas.lab.controller.config import controller_dir
+
+        return controller_dir() / "state"
+
+
+def load_token_file(path: Path) -> str:
+    """Read a bearer token from a file. Empty files are treated as no token."""
+    text = path.read_text(encoding="utf-8").strip()
+    if not text:
+        raise ValueError(f"token file {path} is empty")
+    return text

mas/lab/controller/ui_stream/__init__.py

@@ -0,0 +1,13 @@
+#  Copyright (c) 2026 Cisco Systems, Inc. and its affiliates
+#  SPDX-License-Identifier: Apache-2.0
+from mas.lab.controller.ui_stream.app import mount_ui_stream, state
+from mas.lab.controller.ui_stream.refs import STREAMS, DataSourceRef, envelope, ref_from_mapping
+
+__all__ = [
+    "DataSourceRef",
+    "STREAMS",
+    "envelope",
+    "mount_ui_stream",
+    "ref_from_mapping",
+    "state",
+]