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

mas/lab/controller/registry.py

@@ -0,0 +1,83 @@
+#  Copyright (c) 2026 Cisco Systems, Inc. and its affiliates
+#  SPDX-License-Identifier: Apache-2.0
+"""Worker registry — thread-safe in-process store."""
+from __future__ import annotations
+
+import threading
+from typing import Dict, List, Optional
+
+from mas.lab.controller.worker_model import WorkerKind, WorkerRecord, WorkerStatus, new_worker_id
+
+
+class WorkerRegistry:
+    def __init__(self) -> None:
+        self._workers: Dict[str, WorkerRecord] = {}
+        self._lock = threading.Lock()
+
+    def create(
+        self,
+        kind: WorkerKind,
+        *,
+        spec: Optional[dict] = None,
+        command: str = "",
+        endpoint: str = "",
+        parent_id: Optional[str] = None,
+        worker_id: Optional[str] = None,
+    ) -> WorkerRecord:
+        prefix = {"application": "app", "benchmark": "bench", "pipeline": "pipe"}.get(
+            kind.value, "w"
+        )
+        record = WorkerRecord(
+            id=worker_id or new_worker_id(prefix),
+            kind=kind,
+            spec=dict(spec or {}),
+            command=command,
+            endpoint=endpoint,
+            parent_id=parent_id,
+        )
+        with self._lock:
+            self._workers[record.id] = record
+        return record
+
+    def get(self, worker_id: str) -> Optional[WorkerRecord]:
+        with self._lock:
+            return self._workers.get(worker_id)
+
+    def list_workers(
+        self,
+        *,
+        kind: Optional[WorkerKind] = None,
+        status: Optional[WorkerStatus] = None,
+    ) -> List[WorkerRecord]:
+        with self._lock:
+            items = list(self._workers.values())
+        if kind is not None:
+            items = [w for w in items if w.kind == kind]
+        if status is not None:
+            items = [w for w in items if w.status == status]
+        items.sort(key=lambda w: w.created_at, reverse=True)
+        return items
+
+    def update(self, worker_id: str, **fields: object) -> Optional[WorkerRecord]:
+        with self._lock:
+            record = self._workers.get(worker_id)
+            if record is None:
+                return None
+            for key, value in fields.items():
+                if hasattr(record, key):
+                    setattr(record, key, value)
+            return record
+
+    def cancel(self, worker_id: str) -> bool:
+        record = self.get(worker_id)
+        if record is None:
+            return False
+        if record.status in (WorkerStatus.COMPLETED, WorkerStatus.FAILED, WorkerStatus.CANCELLED):
+            return True
+        record.status = WorkerStatus.CANCELLED
+        record.finished_at = record.finished_at or __import__("time").time()
+        return True
+
+    def drop(self, worker_id: str) -> bool:
+        with self._lock:
+            return self._workers.pop(worker_id, None) is not None

mas/lab/controller/routes/__init__.py

@@ -0,0 +1,82 @@
+#  Copyright (c) 2026 Cisco Systems, Inc. and its affiliates
+#  SPDX-License-Identifier: Apache-2.0
+"""FastAPI route registration for the MAS Lab controller API."""
+
+from __future__ import annotations
+
+from fastapi import FastAPI
+from mas.lab.controller.routes import (
+    apps,
+    artifacts,
+    benchmark,
+    choices,
+    datasets,
+    design_patterns,
+    eval_output,
+    experiments,
+    health,
+    items,
+    jobs,
+    libraries,
+    overlays,
+    pipelines,
+    registry,
+    run,
+    runs,
+    scopes,
+    uploads,
+    validate,
+)
+
+_DEPRECATED_PREFIXES = (
+    "/api/libraries",
+    "/api/jobs",
+    "/api/experiments",
+)
+
+
+def register_routes(app: FastAPI) -> None:
+    """Attach all API routers to the application."""
+    app.include_router(jobs.router)
+    app.include_router(registry.router)
+    app.include_router(libraries.router)
+    app.include_router(overlays.router)
+    app.include_router(validate.router)
+    app.include_router(run.router)
+    app.include_router(datasets.router)
+    app.include_router(benchmark.router)
+    app.include_router(experiments.router)
+    app.include_router(pipelines.router)
+    app.include_router(eval_output.router)
+    app.include_router(apps.router)
+    app.include_router(health.router)
+    app.include_router(scopes.router)
+    app.include_router(items.router)
+    app.include_router(choices.router)
+    app.include_router(design_patterns.router)
+    app.include_router(runs.router)
+    app.include_router(artifacts.router)
+    app.include_router(uploads.router)
+    _mark_app_deprecated(app)
+
+
+def _iter_api_routes(node) -> list:
+    routes = []
+    for route in getattr(node, "routes", []) or []:
+        original = getattr(route, "original_router", None)
+        if original is not None:
+            routes.extend(_iter_api_routes(original))
+            continue
+        nested = getattr(route, "app", None)
+        if nested is not None and hasattr(nested, "routes") and nested is not node:
+            routes.extend(_iter_api_routes(nested))
+        routes.append(route)
+    return routes
+
+
+def _mark_app_deprecated(app: FastAPI) -> None:
+    for route in _iter_api_routes(app):
+        path = getattr(route, "path", "") or ""
+        if any(path == prefix or path.startswith(prefix + "/") for prefix in _DEPRECATED_PREFIXES):
+            if hasattr(route, "deprecated"):
+                route.deprecated = True

mas/lab/controller/routes/_api.py

@@ -0,0 +1,15 @@
+#  Copyright (c) 2026 Cisco Systems, Inc. and its affiliates
+#  SPDX-License-Identifier: Apache-2.0
+"""Shared imports for route modules — patch ``mas.lab.controller.deps`` in tests."""
+
+from mas.lab.controller import deps, jobs
+from mas.lab.controller.constants import LIBRARIES_DIR, MAS_LAB_ROOT
+from mas.lab.controller.pipeline_validation import validate_pipeline_yaml
+
+__all__ = [
+    "LIBRARIES_DIR",
+    "MAS_LAB_ROOT",
+    "deps",
+    "jobs",
+    "validate_pipeline_yaml",
+]

mas/lab/controller/routes/apps.py

@@ -0,0 +1,190 @@
+#  Copyright (c) 2026 Cisco Systems, Inc. and its affiliates
+#  SPDX-License-Identifier: Apache-2.0
+"""MAS app resource CRUD endpoints."""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+import yaml
+from fastapi import APIRouter, HTTPException
+
+from mas.ctl.overlay.canvas import apply_ui_canvas_to_yaml, persist_ui_canvas_yaml
+from mas.lab.controller.lab_registry import LabRegistry
+from mas.lab.controller.models import SaveMASResourceRequest
+from mas.lab.controller.routes._api import deps, jobs, LIBRARIES_DIR, validate_pipeline_yaml
+
+router = APIRouter()
+
+
+def _persist_ui_canvas(app_dir: Path, mas_yaml: str, agents: dict[str, str], mas_name: str) -> tuple[str, dict[str, str]]:
+    """Move canvas ``x-*`` fields from MAS/agent YAML onto a layout-only Overlay."""
+    return persist_ui_canvas_yaml(app_dir, mas_yaml, agents, mas_name=mas_name)
+
+
+def _write_mas_resource(apps_dir: Path, mas_name: str, mas_yaml: str, agents: dict[str, str]) -> dict:
+    """Write a MAS manifest + agent files to disk. Returns summary."""
+    app_dir = apps_dir / mas_name
+    app_dir.mkdir(parents=True, exist_ok=True)
+    mas_yaml, agents = _persist_ui_canvas(app_dir, mas_yaml, agents, mas_name)
+
+    mas_file = app_dir / "mas.yaml"
+    mas_file.write_text(mas_yaml, encoding="utf-8")
+
+    created_agents = []
+    if agents:
+        agents_dir = app_dir / "agents"
+        agents_dir.mkdir(parents=True, exist_ok=True)
+        for agent_name, agent_content in agents.items():
+            filename = f"{agent_name}.yaml" if not agent_name.endswith(".yaml") else agent_name
+            (agents_dir / filename).write_text(agent_content, encoding="utf-8")
+            created_agents.append(filename)
+
+    return {
+        "mas_name": mas_name,
+        "mas_file": f"apps/{mas_name}/mas.yaml",
+        "agents": sorted(created_agents),
+    }
+
+
+@router.post("/api/libraries/{library_name}/apps", tags=["Libraries"], status_code=201)
+async def save_mas_resource(library_name: str, req: SaveMASResourceRequest):
+    """Save a MAS manifest + agent files under apps/<mas_name>/."""
+    lib_dir = deps.get_library_path(library_name)
+    apps_dir = lib_dir / "apps"
+    app_dir = apps_dir / req.mas_name
+
+    if (app_dir / "mas.yaml").exists():
+        raise HTTPException(
+            status_code=409,
+            detail=f"MAS resource '{req.mas_name}' already exists",
+        )
+
+    result = _write_mas_resource(apps_dir, req.mas_name, req.mas_yaml, req.agents)
+    return result
+
+
+@router.put("/api/libraries/{library_name}/apps/{old_mas_name}", tags=["Libraries"])
+async def update_mas_resource(library_name: str, old_mas_name: str, req: SaveMASResourceRequest):
+    """Update a MAS resource. Overwrites mas.yaml and agents/ only, preserving other app contents."""
+    lib_dir = deps.get_library_path(library_name)
+    apps_dir = lib_dir / "apps"
+    old_app_dir = apps_dir / old_mas_name
+
+    if not (old_app_dir / "mas.yaml").exists():
+        raise HTTPException(
+            status_code=404,
+            detail=f"MAS resource '{old_mas_name}' not found",
+        )
+
+    renaming = req.mas_name != old_mas_name
+    if renaming:
+        new_app_dir = apps_dir / req.mas_name
+        if new_app_dir.exists() and (new_app_dir / "mas.yaml").exists():
+            raise HTTPException(
+                status_code=409,
+                detail=f"MAS resource '{req.mas_name}' already exists",
+            )
+
+    if renaming:
+        target_dir = apps_dir / req.mas_name
+        old_app_dir.rename(target_dir)
+    else:
+        target_dir = old_app_dir
+
+    target_dir.mkdir(parents=True, exist_ok=True)
+    mas_yaml, agents = _persist_ui_canvas(target_dir, req.mas_yaml, req.agents, req.mas_name)
+    (target_dir / "mas.yaml").write_text(mas_yaml, encoding="utf-8")
+
+    agents_dir = target_dir / "agents"
+    if agents_dir.exists():
+        shutil.rmtree(agents_dir)
+    if agents:
+        agents_dir.mkdir(parents=True, exist_ok=True)
+        for agent_name, agent_content in agents.items():
+            filename = f"{agent_name}.yaml" if not agent_name.endswith(".yaml") else agent_name
+            (agents_dir / filename).write_text(agent_content, encoding="utf-8")
+
+    return {
+        "mas_name": req.mas_name,
+        "mas_file": f"apps/{req.mas_name}/mas.yaml",
+        "agents": sorted(
+            f"{a}.yaml" if not a.endswith(".yaml") else a for a in agents
+        ),
+    }
+
+
+@router.get("/api/libraries/{library_name}/apps", tags=["Libraries"])
+async def list_mas_resources(library_name: str):
+    """List all MAS resources with their manifests and agents."""
+    return {"mas_resources": deps.get_manifest_store().collect_mas_resources(library_name)}
+
+
+@router.get("/api/libraries/{library_name}/apps/{mas_name}", tags=["Libraries"])
+async def get_mas_resource(library_name: str, mas_name: str):
+    """Return a single MAS resource (manifest + agents)."""
+    resources = deps.get_manifest_store().collect_mas_resources(library_name)
+    entry = resources.get(mas_name)
+    if entry is None:
+        raise HTTPException(
+            status_code=404,
+            detail=f"MAS resource '{mas_name}' not found",
+        )
+
+    mas_yaml = entry["mas_yaml"]
+    agents = dict(entry.get("agents") or {})
+    store = deps.get_manifest_store()
+    lib_dir = deps.get_library_path(library_name)
+    mas_path = entry.get("path")
+    mas_dir = (lib_dir / mas_path).parent if mas_path else lib_dir / "apps" / mas_name
+    registry = getattr(store, "_registry", None)
+    if not isinstance(registry, LabRegistry):
+        registry = LabRegistry._ephemeral()
+    target_name = mas_name
+    try:
+        mas_doc = yaml.safe_load(mas_yaml) or {}
+        if isinstance(mas_doc, dict):
+            target_name = str((mas_doc.get("metadata") or {}).get("name") or mas_name).strip() or mas_name
+    except Exception:
+        pass
+    seen: set[Path] = set()
+    matched: list[tuple[Path, dict]] = []
+    for name in (target_name, mas_name):
+        for path, doc in registry.layout_overlays_targeting(lib_dir, kind="MAS", name=name):
+            key = path.resolve()
+            if key in seen:
+                continue
+            seen.add(key)
+            matched.append((path, doc))
+    mas_yaml, agents, overlay_path = apply_ui_canvas_to_yaml(
+        mas_dir, mas_yaml, agents, overlays=matched
+    )
+    body: dict = {
+        "mas_name": mas_name,
+        "mas_yaml": mas_yaml,
+        "agents": agents,
+    }
+    if overlay_path is not None:
+        try:
+            body["ui_canvas_overlay"] = str(overlay_path.relative_to(lib_dir))
+        except ValueError:
+            body["ui_canvas_overlay"] = str(overlay_path)
+    return body
+
+
+@router.delete("/api/libraries/{library_name}/apps/{mas_name}", tags=["Libraries"])
+async def delete_mas_resource(library_name: str, mas_name: str):
+    """Delete a MAS app folder (manifest + agents)."""
+    lib_dir = deps.get_library_path(library_name)
+    apps_dir = lib_dir / "apps"
+    app_dir = apps_dir / mas_name
+
+    if not (app_dir / "mas.yaml").exists():
+        raise HTTPException(
+            status_code=404,
+            detail=f"MAS resource '{mas_name}' not found",
+        )
+
+    shutil.rmtree(app_dir)
+    return {"deleted": mas_name}

mas/lab/controller/routes/artifacts.py

@@ -0,0 +1,37 @@
+#  Copyright (c) 2026 Cisco Systems, Inc. and its affiliates
+#  SPDX-License-Identifier: Apache-2.0
+"""Serve run artifacts by issued id only."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, HTTPException
+from fastapi.responses import FileResponse, PlainTextResponse
+from mas.lab.controller.artifacts import get_artifact_registry
+
+router = APIRouter()
+
+_TEXT_TYPES = {
+    "text/plain",
+    "text/csv",
+    "text/yaml",
+    "text/html",
+    "text/xml",
+    "application/json",
+    "application/yaml",
+    "image/svg+xml",
+}
+
+
+@router.get("/api/artifacts/{artifact_id}", tags=["Artifacts"])
+async def get_artifact(artifact_id: str, download: bool = False):
+    art = get_artifact_registry().get(artifact_id)
+    if art is None or art.path is None or not art.path.is_file():
+        raise HTTPException(status_code=404, detail="artifact not found")
+    if download or art.media_type not in _TEXT_TYPES and not art.media_type.startswith("text/"):
+        return FileResponse(
+            path=str(art.path),
+            media_type=art.media_type,
+            filename=art.name,
+        )
+    text = art.path.read_text(encoding="utf-8", errors="replace")
+    return PlainTextResponse(text, media_type=art.media_type or "text/plain")