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

mas/lab/controller/routes/jobs.py

@@ -0,0 +1,107 @@
+#  Copyright (c) 2026 Cisco Systems, Inc. and its affiliates
+#  SPDX-License-Identifier: Apache-2.0
+"""Job management endpoints."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from fastapi import APIRouter, HTTPException
+from mas.lab.controller.api import peek_controller_api
+from mas.lab.controller.jobs import JobStatus, _jobs
+
+router = APIRouter()
+
+_TERMINAL = {JobStatus.COMPLETED, JobStatus.FAILED, JobStatus.CANCELLED, JobStatus.TIMEOUT}
+
+
+def _origin_of(job) -> str | None:
+    from mas.lab.controller.jobs import _job_origin
+
+    return _job_origin(job.request_body)
+
+
+@router.get("/api/jobs", tags=["Jobs"])
+async def list_jobs(status: Optional[str] = None, origin: Optional[str] = None):
+    """List FastAPI jobs plus in-process controller workers."""
+    jobs = _jobs.values()
+    if status:
+        jobs = [j for j in jobs if j.status.value == status]
+    else:
+        jobs = list(jobs)
+    jobs.sort(key=lambda j: j.created_at, reverse=True)
+    summaries = [j.to_summary() for j in jobs]
+    if origin:
+        summaries = [item for item in summaries if item.get("origin") == origin]
+    seen = {item["id"] for item in summaries}
+    api = peek_controller_api()
+    if api is not None:
+        for worker in api.list_jobs(status=status):
+            if worker.get("id") in seen:
+                continue
+            if origin and worker.get("origin") != origin:
+                continue
+            summaries.append(worker)
+    return {"jobs": summaries}
+
+
+@router.get("/api/jobs/{job_id}", tags=["Jobs"])
+async def get_job(job_id: str):
+    """Get full details of a specific job (including stdout/stderr)."""
+    job = _jobs.get(job_id)
+    if job:
+        return job.to_dict()
+    api = peek_controller_api()
+    detail = api.get_job(job_id) if api is not None else None
+    if detail:
+        return detail
+    from mas.lab.controller.ui_stream.app import state as ui_state
+
+    replay = ui_state.lookup_job(job_id)
+    if replay:
+        return replay
+    raise HTTPException(status_code=404, detail=f"Job {job_id} not found")
+
+
+@router.delete("/api/jobs/{job_id}", tags=["Jobs"])
+async def cancel_job(job_id: str):
+    """Cancel a running job and drop it from the in-memory list."""
+    job = _jobs.get(job_id)
+    if job:
+        if job.status in _TERMINAL:
+            # Nothing to cancel -- the job already reached a terminal state
+            # (completed/failed/cancelled/timeout) on its own; say so
+            # distinctly rather than implying this call actually stopped
+            # something, so a caller can tell the two cases apart.
+            del _jobs[job_id]
+            return {"message": "already terminal, removed", "job_id": job_id}
+        if job._task and not job._task.done():
+            job._task.cancel()
+        del _jobs[job_id]
+        return {"message": "removed", "job_id": job_id}
+    api = peek_controller_api()
+    if api is not None and api.drop_worker(job_id):
+        return {"message": "removed", "job_id": job_id}
+    raise HTTPException(status_code=404, detail=f"Job {job_id} not found")
+
+
+@router.delete("/api/jobs", tags=["Jobs"])
+async def clear_finished_jobs(origin: Optional[str] = None):
+    """Remove jobs. With origin, UI-owned runs are dropped even if still running."""
+    purge_running = origin is not None
+    to_remove = [
+        jid
+        for jid, job in _jobs.items()
+        if (purge_running or job.status in _TERMINAL)
+        and (origin is None or _origin_of(job) == origin)
+    ]
+    for jid in to_remove:
+        job = _jobs[jid]
+        if job.status in (JobStatus.PENDING, JobStatus.RUNNING) and job._task and not job._task.done():
+            job._task.cancel()
+        del _jobs[jid]
+    removed = len(to_remove)
+    api = peek_controller_api()
+    if api is not None and origin:
+        removed += api.drop_workers(origin=origin, terminal_only=False)
+    return {"removed": removed}

mas/lab/controller/routes/libraries.py

@@ -0,0 +1,144 @@
+#  Copyright (c) 2026 Cisco Systems, Inc. and its affiliates
+#  SPDX-License-Identifier: Apache-2.0
+"""Library listing and resource discovery endpoints."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from fastapi import APIRouter
+
+from mas.lab.controller.routes._api import deps, jobs, LIBRARIES_DIR, validate_pipeline_yaml
+from mas.runtime.constants import LIBRARY_MANIFEST_FILENAME
+
+router = APIRouter()
+
+
+@router.get("/api/libraries", tags=["Libraries"])
+async def list_libraries():
+    """List available MAS libraries."""
+    import yaml as _yaml
+
+    discovered = deps.get_manifest_store().libraries()
+    if discovered:
+        return {"libraries": discovered}
+
+    libraries_dir = LIBRARIES_DIR
+    libraries = []
+    if not libraries_dir.exists():
+        return {"libraries": libraries}
+    for lib_dir in sorted(libraries_dir.iterdir()):
+        if not lib_dir.is_dir() or not lib_dir.name.startswith("library-"):
+            continue
+        lib_yaml = lib_dir / LIBRARY_MANIFEST_FILENAME
+        name = lib_dir.name
+        description = ""
+        if lib_yaml.exists():
+            with open(lib_yaml, encoding="utf-8") as f:
+                data = _yaml.safe_load(f)
+            if data:
+                name = data.get("name", lib_dir.name)
+                description = data.get("description", "").strip()
+        libraries.append({
+            "dir": lib_dir.name,
+            "name": name,
+            "description": description,
+        })
+    return {"libraries": libraries}
+
+
+@router.get("/api/runtime-runners", tags=["Benchmark"])
+async def list_runtime_runners():
+    """List registered lab runtime plugins (mas, langgraph, autogen, …)."""
+    from mas.lab.controller.api import ControllerAPI
+
+    return {"runners": ControllerAPI().list_runtime_runners()}
+
+
+@router.get("/api/libraries/{library_name}/tools", tags=["Libraries"])
+async def list_library_tools(library_name: str, namespaces: str = "global"):
+    """List available tools for a specific library.
+
+    The *namespaces* query parameter is a comma-separated list of scopes.
+    ``"global"`` returns tools under the library root ``tools/`` folder
+    (prefixed with ``global/``).  Any other value is treated as an app
+    name and returns tools under ``apps/{name}/tools/``.
+    """
+    lib_dir = deps.get_library_path(library_name)
+    ns_list = [n.strip() for n in namespaces.split(",") if n.strip()]
+    return {"tools": deps.discover_tools(lib_dir, ns_list)}
+
+
+@router.get("/api/libraries/{library_name}/skills", tags=["Libraries"])
+async def list_library_skills(library_name: str, namespaces: str = "global"):
+    """List available skills for a specific library.
+
+    ``namespaces`` is a comma-separated list of scopes: ``global`` for
+    library-root skills (prefixed ``global/``), or an app name for
+    app-scoped skills (no prefix).  Defaults to ``global``."""
+    lib_dir = deps.get_library_path(library_name)
+    ns_list = [n.strip() for n in namespaces.split(",") if n.strip()]
+    return {"skills": deps.discover_skills(lib_dir, ns_list)}
+
+
+@router.get("/api/libraries/{library_name}/documents", tags=["Libraries"])
+async def read_library_document(library_name: str, path: str):
+    """Read a file under the library root (MAS YAML, agent YAML, overlays)."""
+    from fastapi import HTTPException
+
+    rel = str(path or "").strip().lstrip("/")
+    if not rel or ".." in Path(rel).parts:
+        raise HTTPException(status_code=400, detail="invalid path")
+    lib_dir = deps.get_library_path(library_name).resolve()
+    target = (lib_dir / rel).resolve()
+    if not str(target).startswith(str(lib_dir)):
+        raise HTTPException(status_code=400, detail="path escapes library")
+    if not target.is_file():
+        raise HTTPException(status_code=404, detail=f"file not found: {rel}")
+    return {"path": rel, "content": target.read_text(encoding="utf-8")}
+
+
+@router.get("/api/libraries/{library_name}/topologies", tags=["Libraries"])
+async def list_library_topologies(library_name: str):
+    """List available topology manifests in a library."""
+    lib_dir = deps.get_library_path(library_name)
+    topo_dir = lib_dir / "topologies"
+    if not topo_dir.exists():
+        return {"topologies": []}
+    files = sorted(f.name for f in topo_dir.glob("*.yaml"))
+    return {"topologies": files}
+
+
+@router.get("/api/libraries/{library_name}/config-files", tags=["Libraries"])
+async def get_library_config_files(library_name: str):
+    """Return infra, flavour, and workspace config files for the control panel."""
+    return deps.get_manifest_store().config_files(library_name)
+
+
+@router.get("/api/libraries/{library_name}/pipelines", tags=["Libraries"])
+async def list_library_pipelines(library_name: str):
+    """List available pipeline definitions with metadata."""
+    pipelines = deps.get_manifest_store().list_pipelines(library_name)
+    return {"pipelines": pipelines}
+
+
+@router.get("/api/libraries/{library_name}/scenarios", tags=["Libraries"])
+async def list_scenarios(library_name: str):
+    """List available MAS scenario files (mas.yaml in apps/<name>/)."""
+    lib_dir = deps.get_library_path(library_name)
+    apps_dir = lib_dir / "apps"
+
+    if not apps_dir.exists():
+        return {"scenarios": []}
+
+    scenarios = []
+    for app_folder in sorted(apps_dir.iterdir()):
+        if not app_folder.is_dir():
+            continue
+        mas_file = app_folder / "mas.yaml"
+        if mas_file.exists():
+            scenarios.append({
+                "name": app_folder.name,
+                "path": f"apps/{app_folder.name}/mas.yaml",
+            })
+    return {"scenarios": scenarios}

mas/lab/controller/routes/overlays.py

@@ -0,0 +1,164 @@
+#  Copyright (c) 2026 Cisco Systems, Inc. and its affiliates
+#  SPDX-License-Identifier: Apache-2.0
+"""Overlay CRUD and validation endpoints."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from fastapi import APIRouter, HTTPException
+
+from mas.lab.controller.models import SaveOverlayRequest, ValidateRequest
+from mas.lab.controller.routes._api import deps, jobs, LIBRARIES_DIR, validate_pipeline_yaml
+
+router = APIRouter()
+
+
+def _overlay_dir_for_namespace(lib_dir: Path, namespace: str | None) -> Path:
+    """Return the overlays directory for the given namespace.
+
+    ``"global"`` or ``None`` → ``{lib_dir}/overlays/``
+    anything else            → ``{lib_dir}/apps/{namespace}/overlays/``
+    """
+    if not namespace or namespace == "global":
+        return lib_dir / "overlays"
+    return lib_dir / "apps" / namespace / "overlays"
+
+
+def _extract_namespace_from_yaml(content: str) -> str:
+    """Extract the namespace from overlay YAML content.
+
+    Checks root-level ``x-namespace`` first (UI-generated overlays), then
+    falls back to ``metadata.namespace``, defaulting to ``"global"``.
+    """
+    import yaml as _yaml
+    try:
+        doc = _yaml.safe_load(content) or {}
+        return str(
+            doc.get("x-namespace")
+            or (doc.get("metadata") or {}).get("namespace")
+            or "global"
+        )
+    except Exception:
+        return "global"
+
+
+def _find_overlay_file(lib_dir: Path, overlay_name: str) -> Path | None:
+    """Search for an overlay file across global, app-scoped, and nested app dirs."""
+    filename = f"{overlay_name}.yaml" if not overlay_name.endswith(".yaml") else overlay_name
+    global_path = lib_dir / "overlays" / filename
+    if global_path.exists():
+        return global_path
+    apps_dir = lib_dir / "apps"
+    if apps_dir.exists():
+        for pattern in (f"*/overlays/{filename}", f"*/*/overlays/{filename}"):
+            matches = sorted(apps_dir.glob(pattern))
+            if matches:
+                return matches[0]
+    return None
+
+
+@router.post("/api/libraries/{library_name}/overlays/validate", tags=["Libraries"])
+async def validate_overlay(library_name: str, req: ValidateRequest):
+    """Validate a kind: Overlay overlay manifest.
+
+    Uses the same schema (overlay.schema.yaml) regardless of whether the overlay
+    is intended for mas-ctl run-mas or mas-lab benchmark run — the schema does
+    not differentiate between the two usage contexts.
+    """
+    lib_dir = deps.get_library_path(library_name)
+    errors = await deps.validate_overlay_content(req.manifest_yaml, lib_dir)
+    if errors is None:
+        return {"status": "OK", "errors": []}
+    raise HTTPException(status_code=422, detail=errors)
+
+
+@router.get("/api/libraries/{library_name}/overlays", tags=["Libraries"])
+async def list_library_overlays(library_name: str):
+    """List available overlay files with name and description (includes nested lab modules)."""
+    return {"overlays": deps.get_manifest_store().list_overlays(library_name)}
+
+
+@router.post("/api/libraries/{library_name}/overlays", tags=["Libraries"], status_code=201)
+async def create_overlay(library_name: str, req: SaveOverlayRequest):
+    """Create a new overlay definition.
+
+    Storage location is determined by ``metadata.namespace`` in the YAML content:
+    ``global`` → ``{lib}/overlays/``, otherwise → ``{lib}/apps/{ns}/overlays/``.
+    """
+    lib_dir = deps.get_library_path(library_name)
+    namespace = _extract_namespace_from_yaml(req.content)
+    overlay_dir = _overlay_dir_for_namespace(lib_dir, namespace)
+    overlay_dir.mkdir(parents=True, exist_ok=True)
+
+    filename = f"{req.name}.yaml" if not req.name.endswith(".yaml") else req.name
+    file_path = overlay_dir / filename
+
+    if file_path.exists():
+        raise HTTPException(status_code=409, detail=f"Overlay '{req.name}' already exists")
+
+    if req.run_validation:
+        result = await deps.validate_overlay_content(req.content, lib_dir)
+        if result is not None:
+            raise HTTPException(status_code=422, detail=result)
+
+    file_path.write_text(req.content, encoding="utf-8")
+    deps.get_manifest_store().invalidate()
+    return {"name": req.name, "filename": filename}
+
+
+@router.get("/api/libraries/{library_name}/overlays/{overlay_name}", tags=["Libraries"])
+async def get_overlay(library_name: str, overlay_name: str):
+    """Return the content of a specific overlay definition."""
+    lib_dir = deps.get_library_path(library_name)
+    file_path = _find_overlay_file(lib_dir, overlay_name)
+
+    if file_path is None:
+        raise HTTPException(status_code=404, detail=f"Overlay '{overlay_name}' not found")
+
+    return {"name": overlay_name, "filename": file_path.name, "content": file_path.read_text(encoding="utf-8")}
+
+
+@router.put("/api/libraries/{library_name}/overlays/{overlay_name}", tags=["Libraries"])
+async def update_overlay(library_name: str, overlay_name: str, req: SaveOverlayRequest):
+    """Update an existing overlay definition. Supports rename and namespace change."""
+    lib_dir = deps.get_library_path(library_name)
+    old_path = _find_overlay_file(lib_dir, overlay_name)
+
+    if old_path is None:
+        raise HTTPException(status_code=404, detail=f"Overlay '{overlay_name}' not found")
+
+    namespace = _extract_namespace_from_yaml(req.content)
+    new_overlay_dir = _overlay_dir_for_namespace(lib_dir, namespace)
+    new_overlay_dir.mkdir(parents=True, exist_ok=True)
+
+    new_filename = f"{req.name}.yaml" if not req.name.endswith(".yaml") else req.name
+    new_path = new_overlay_dir / new_filename
+
+    if new_path != old_path and new_path.exists():
+        raise HTTPException(status_code=409, detail=f"Overlay '{req.name}' already exists")
+
+    if req.run_validation:
+        result = await deps.validate_overlay_content(req.content, lib_dir)
+        if result is not None:
+            raise HTTPException(status_code=422, detail=result)
+
+    if old_path != new_path:
+        old_path.unlink()
+    new_path.write_text(req.content, encoding="utf-8")
+    deps.get_manifest_store().invalidate()
+    return {"name": req.name, "filename": new_filename}
+
+
+@router.delete("/api/libraries/{library_name}/overlays/{overlay_name}", tags=["Libraries"])
+async def delete_overlay(library_name: str, overlay_name: str):
+    """Delete an overlay definition."""
+    lib_dir = deps.get_library_path(library_name)
+    file_path = _find_overlay_file(lib_dir, overlay_name)
+
+    if file_path is None:
+        raise HTTPException(status_code=404, detail=f"Overlay '{overlay_name}' not found")
+
+    file_path.unlink()
+    deps.get_manifest_store().invalidate()
+    return {"deleted": overlay_name}

mas/lab/controller/routes/pipelines.py

@@ -0,0 +1,139 @@
+#  Copyright (c) 2026 Cisco Systems, Inc. and its affiliates
+#  SPDX-License-Identifier: Apache-2.0
+"""Pipeline run, validation, and CRUD endpoints."""
+
+from __future__ import annotations
+
+import tempfile
+from pathlib import Path
+
+from fastapi import APIRouter, HTTPException
+
+from mas.lab.controller.models import PipelineRunRequest, SavePipelineRequest, ValidateRequest
+from mas.lab.controller.routes._api import deps, jobs, LIBRARIES_DIR, validate_pipeline_yaml
+
+router = APIRouter()
+
+
+@router.post("/api/libraries/{library_name}/pipeline/run", tags=["Libraries"], status_code=202)
+async def pipeline_run(library_name: str, req: PipelineRunRequest):
+    """Run an analysis pipeline. Returns a job_id for polling."""
+    lib_dir = deps.get_library_path(library_name)
+
+    cleanup_paths: list[Path] = []
+
+    # Support inline YAML content (has newlines) or a filename
+    if "\n" in req.pipeline_yaml:
+        tmp = tempfile.NamedTemporaryFile(
+            mode="w", suffix=".yaml", prefix="pipeline-", delete=False, dir=str(lib_dir)
+        )
+        tmp.write(req.pipeline_yaml)
+        tmp.close()
+        pipeline_path = Path(tmp.name).name
+        cleanup_paths.append(Path(tmp.name))
+    else:
+        pipeline_path = req.pipeline_yaml
+
+    cmd = ["mas-lab", "benchmark", "pipeline", "run", pipeline_path]
+    if req.only:
+        cmd += ["--only"] + req.only
+    job = jobs.submit_job(
+        endpoint=f"/api/libraries/{library_name}/pipeline/run",
+        cmd=cmd,
+        cwd=lib_dir,
+        timeout=req.timeout,
+        request_body=req.model_dump(),
+        cleanup_paths=cleanup_paths,
+    )
+    return {"job_id": job.id, "status": job.status.value, "command": job.command}
+
+
+@router.post("/api/libraries/{library_name}/pipelines/validate", tags=["Libraries"])
+async def validate_pipeline(library_name: str, req: ValidateRequest):
+    """Validate a pipeline manifest against the schema and check DAG integrity."""
+    deps.get_library_path(library_name)
+    result = validate_pipeline_yaml(req.manifest_yaml)
+    if result["valid"]:
+        return {"status": "OK Pipeline", "errors": []}
+    raise HTTPException(status_code=422, detail=result["errors"])
+
+
+@router.post("/api/libraries/{library_name}/pipelines", tags=["Libraries"], status_code=201)
+async def create_pipeline(library_name: str, req: SavePipelineRequest):
+    """Create a new pipeline definition in the library's pipelines/ directory."""
+    lib_dir = deps.get_library_path(library_name)
+    pipe_dir = lib_dir / "pipelines"
+    pipe_dir.mkdir(parents=True, exist_ok=True)
+
+    filename = f"{req.name}.yaml" if not req.name.endswith(".yaml") else req.name
+    file_path = pipe_dir / filename
+
+    if file_path.exists():
+        raise HTTPException(status_code=409, detail=f"Pipeline '{req.name}' already exists")
+
+    if req.run_validation:
+        result = validate_pipeline_yaml(req.content)
+        if not result["valid"]:
+            raise HTTPException(status_code=422, detail=result["errors"])
+
+    file_path.write_text(req.content, encoding="utf-8")
+    deps.get_manifest_store().invalidate()
+    return {"name": req.name, "filename": filename}
+
+
+@router.get("/api/libraries/{library_name}/pipelines/{pipeline_name}", tags=["Libraries"])
+async def get_pipeline(library_name: str, pipeline_name: str):
+    """Return the content of a specific pipeline definition."""
+    lib_dir = deps.get_library_path(library_name)
+    filename = f"{pipeline_name}.yaml" if not pipeline_name.endswith(".yaml") else pipeline_name
+    file_path = lib_dir / "pipelines" / filename
+
+    if not file_path.exists():
+        raise HTTPException(status_code=404, detail=f"Pipeline '{pipeline_name}' not found")
+
+    return {"name": pipeline_name, "filename": filename, "content": file_path.read_text(encoding="utf-8")}
+
+
+@router.put("/api/libraries/{library_name}/pipelines/{pipeline_name}", tags=["Libraries"])
+async def update_pipeline(library_name: str, pipeline_name: str, req: SavePipelineRequest):
+    """Update an existing pipeline definition. Supports rename via req.name."""
+    lib_dir = deps.get_library_path(library_name)
+    pipe_dir = lib_dir / "pipelines"
+
+    old_filename = f"{pipeline_name}.yaml" if not pipeline_name.endswith(".yaml") else pipeline_name
+    old_path = pipe_dir / old_filename
+
+    if not old_path.exists():
+        raise HTTPException(status_code=404, detail=f"Pipeline '{pipeline_name}' not found")
+
+    new_filename = f"{req.name}.yaml" if not req.name.endswith(".yaml") else req.name
+    new_path = pipe_dir / new_filename
+
+    if req.name != pipeline_name and new_path.exists():
+        raise HTTPException(status_code=409, detail=f"Pipeline '{req.name}' already exists")
+
+    if req.run_validation:
+        result = validate_pipeline_yaml(req.content)
+        if not result["valid"]:
+            raise HTTPException(status_code=422, detail=result["errors"])
+
+    if old_path != new_path:
+        old_path.unlink()
+    new_path.write_text(req.content, encoding="utf-8")
+    deps.get_manifest_store().invalidate()
+    return {"name": req.name, "filename": new_filename}
+
+
+@router.delete("/api/libraries/{library_name}/pipelines/{pipeline_name}", tags=["Libraries"])
+async def delete_pipeline(library_name: str, pipeline_name: str):
+    """Delete a pipeline definition."""
+    lib_dir = deps.get_library_path(library_name)
+    filename = f"{pipeline_name}.yaml" if not pipeline_name.endswith(".yaml") else pipeline_name
+    file_path = lib_dir / "pipelines" / filename
+
+    if not file_path.exists():
+        raise HTTPException(status_code=404, detail=f"Pipeline '{pipeline_name}' not found")
+
+    file_path.unlink()
+    deps.get_manifest_store().invalidate()
+    return {"deleted": pipeline_name}

mas/lab/controller/routes/registry.py

@@ -0,0 +1,40 @@
+#  Copyright (c) 2026 Cisco Systems, Inc. and its affiliates
+#  SPDX-License-Identifier: Apache-2.0
+"""Registry and discovery endpoints."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter
+
+from mas.lab.controller.routes._api import deps, jobs, LIBRARIES_DIR, validate_pipeline_yaml
+
+router = APIRouter()
+
+
+@router.get("/api/registry", tags=["Registry"])
+async def list_registry():
+    """Unified lab + runtime registry catalog."""
+    from mas.lab.controller.lab_registry import get_lab_registry
+
+    ws = getattr(deps.get_manifest_store(), "_workspace", None)
+    return {"registry": get_lab_registry(ws).catalog()}
+
+
+@router.get("/api/defaults", tags=["Registry"])
+async def get_defaults():
+    """Agent and infra defaults (design pattern, model) for UI and playground."""
+    from mas.lab.controller.lab_registry import get_lab_registry
+
+    ws = getattr(deps.get_manifest_store(), "_workspace", None)
+    reg = get_lab_registry(ws)
+    return {
+        "agent": reg.agent_defaults(),
+        "default_model": reg.default_model(),
+    }
+
+
+@router.get("/api/discovery", tags=["Registry"])
+async def get_discovery_report():
+    """Paths scanned, libraries resolved, and runtime entry points (debug)."""
+    store = deps.get_manifest_store()
+    return store._registry.discovery_report()