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

mas/lab/controller/routes/benchmark.py

@@ -0,0 +1,307 @@
+#  Copyright (c) 2026 Cisco Systems, Inc. and its affiliates
+#  SPDX-License-Identifier: Apache-2.0
+"""Benchmark run endpoints and global experiment results."""
+
+from __future__ import annotations
+
+import shutil
+import tempfile
+from pathlib import Path
+
+from fastapi import APIRouter, HTTPException, UploadFile
+from fastapi.responses import FileResponse
+
+from mas.lab.controller.deps import build_tree
+from mas.lab.controller.models import (
+    BenchmarkAnalyzeRequest,
+    BenchmarkExportRequest,
+    BenchmarkImportRequest,
+    BenchmarkRunRequest,
+)
+from mas.lab.controller.routes._api import MAS_LAB_ROOT, deps, jobs, LIBRARIES_DIR, validate_pipeline_yaml
+
+router = APIRouter()
+
+
+@router.post("/api/libraries/{library_name}/benchmark/run", tags=["Libraries"], status_code=202)
+async def benchmark_run(library_name: str, req: BenchmarkRunRequest):
+    """Run a benchmark experiment. Returns a job_id for polling."""
+    lib_dir = deps.get_library_path(library_name)
+
+    cleanup_paths: list[Path] = []
+
+    # If the value looks like YAML content (has newlines), write to a temp file
+    if "\n" in req.experiment_yaml:
+        tmp = tempfile.NamedTemporaryFile(
+            mode="w", suffix=".yaml", prefix="experiment-", delete=False, dir=str(lib_dir)
+        )
+        tmp.write(req.experiment_yaml)
+        tmp.close()
+        experiment_path = Path(tmp.name).name
+        cleanup_paths.append(Path(tmp.name))
+    else:
+        experiment_path = req.experiment_yaml
+
+    cmd = ["mas-lab", "benchmark", "run", experiment_path]
+    if req.progress:
+        cmd.append("--progress")
+    if req.force:
+        cmd.append("--force")
+    if req.max_runs is not None:
+        cmd += ["--max-runs", str(req.max_runs)]
+    if req.flavour:
+        cmd += ["--flavour", req.flavour]
+    job = jobs.submit_job(
+        endpoint=f"/api/libraries/{library_name}/benchmark/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}/benchmark/analyze", tags=["Libraries"], status_code=202)
+async def benchmark_analyze(library_name: str, req: BenchmarkAnalyzeRequest):
+    """Regenerate statistics/plots for an existing benchmark run."""
+    lib_dir = deps.get_library_path(library_name)
+    cmd = ["mas-lab", "benchmark", "analyze", req.benchmark_id]
+    if req.experiment_yaml:
+        cmd += ["--experiment-yaml", req.experiment_yaml]
+    job = jobs.submit_job(
+        endpoint=f"/api/libraries/{library_name}/benchmark/analyze",
+        cmd=cmd,
+        cwd=lib_dir,
+        timeout=req.timeout,
+        request_body=req.model_dump(),
+    )
+    return {"job_id": job.id, "status": job.status.value, "command": job.command}
+
+
+@router.post("/api/libraries/{library_name}/benchmark/export", tags=["Libraries"], status_code=202)
+async def benchmark_export(library_name: str, req: BenchmarkExportRequest):
+    """Export a benchmark run to a portable .tar.gz archive."""
+    lib_dir = deps.get_library_path(library_name)
+    cmd = ["mas-lab", "benchmark", "export", req.benchmark_id]
+    if req.output:
+        cmd += ["--output", req.output]
+    if not req.include_trace_cache:
+        cmd.append("--no-trace-cache")
+    if req.dry_run:
+        cmd.append("--dry-run")
+    job = jobs.submit_job(
+        endpoint=f"/api/libraries/{library_name}/benchmark/export",
+        cmd=cmd,
+        cwd=lib_dir,
+        timeout=req.timeout,
+        request_body=req.model_dump(),
+    )
+    return {"job_id": job.id, "status": job.status.value, "command": job.command}
+
+
+@router.get("/api/libraries/{library_name}/benchmark/download", tags=["Libraries"])
+async def benchmark_download(library_name: str, benchmark_id: str):
+    """Export and download a benchmark run as a .tar.gz file."""
+    import subprocess
+
+    lib_dir = deps.get_library_path(library_name)
+    tmp_dir = Path(tempfile.mkdtemp())
+    out_path = tmp_dir / f"{benchmark_id}.tar.gz"
+
+    cmd = ["mas-lab", "benchmark", "export", benchmark_id, "--output", str(out_path)]
+    result = subprocess.run(cmd, cwd=lib_dir, capture_output=True, text=True, timeout=120)
+    if result.returncode != 0:
+        shutil.rmtree(tmp_dir, ignore_errors=True)
+        detail = result.stderr.strip().split("\n")[-1] if result.stderr else "Export failed"
+        raise HTTPException(status_code=400, detail=detail)
+
+    if not out_path.exists():
+        shutil.rmtree(tmp_dir, ignore_errors=True)
+        raise HTTPException(status_code=500, detail="Export produced no output file")
+
+    from starlette.background import BackgroundTask
+
+    return FileResponse(
+        out_path,
+        filename=out_path.name,
+        media_type="application/gzip",
+        background=BackgroundTask(shutil.rmtree, tmp_dir, True),
+    )
+
+
+@router.post("/api/libraries/{library_name}/benchmark/import", tags=["Libraries"], status_code=202)
+async def benchmark_import(library_name: str, req: BenchmarkImportRequest):
+    """Import a benchmark archive produced by benchmark export."""
+    lib_dir = deps.get_library_path(library_name)
+    cmd = ["mas-lab", "benchmark", "import", req.tarball]
+    if req.output_dir:
+        cmd += ["--output-dir", req.output_dir]
+    if req.trace_cache_dir:
+        cmd += ["--trace-cache", req.trace_cache_dir]
+    if req.dry_run:
+        cmd.append("--dry-run")
+    job = jobs.submit_job(
+        endpoint=f"/api/libraries/{library_name}/benchmark/import",
+        cmd=cmd,
+        cwd=lib_dir,
+        timeout=req.timeout,
+        request_body=req.model_dump(),
+    )
+    return {"job_id": job.id, "status": job.status.value, "command": job.command}
+
+
+@router.post("/api/libraries/{library_name}/benchmark/upload-import", tags=["Libraries"], status_code=202)
+async def benchmark_upload_import(library_name: str, file: UploadFile):
+    """Accept a .tar.gz upload and import it as a benchmark run."""
+    lib_dir = deps.get_library_path(library_name)
+
+    tmp = tempfile.NamedTemporaryFile(
+        suffix=".tar.gz", prefix="bench-import-", delete=False, dir=str(lib_dir)
+    )
+    try:
+        contents = await file.read()
+        tmp.write(contents)
+        tmp.close()
+
+        cmd = ["mas-lab", "benchmark", "import", tmp.name]
+        job = jobs.submit_job(
+            endpoint=f"/api/libraries/{library_name}/benchmark/upload-import",
+            cmd=cmd,
+            cwd=lib_dir,
+            timeout=120,
+            request_body={"filename": file.filename},
+            cleanup_paths=[Path(tmp.name)],
+        )
+        return {"job_id": job.id, "status": job.status.value, "command": job.command}
+    except Exception:
+        Path(tmp.name).unlink(missing_ok=True)
+        raise
+
+
+@router.get("/api/experiments", tags=["Benchmark"])
+async def list_experiments():
+    """List all experiment runs with metadata."""
+    mas_lab_root = MAS_LAB_ROOT
+    labs_dir = mas_lab_root / "labs"
+    if not labs_dir.exists():
+        return {"experiments": []}
+
+    experiments = []
+    for d in sorted(labs_dir.iterdir()):
+        if not d.is_dir():
+            continue
+        entry: dict = {"name": d.name}
+        meta_file = d / "metadata.yaml"
+        if meta_file.exists():
+            import yaml
+            meta = yaml.safe_load(meta_file.read_text(encoding="utf-8"))
+            entry["status"] = meta.get("status", "unknown")
+            entry["description"] = meta.get("experiment_description", "")
+            entry["started_at"] = meta.get("started_at")
+            entry["completed_at"] = meta.get("completed_at")
+            entry["duration_seconds"] = meta.get("duration_seconds")
+            entry["n_scenarios"] = meta.get("n_scenarios")
+            entry["completed_scenarios"] = meta.get("completed_scenarios")
+            entry["failed_scenarios"] = meta.get("failed_scenarios")
+        experiments.append(entry)
+    return {"experiments": experiments}
+
+
+@router.get("/api/experiments/definitions", tags=["Libraries"])
+async def list_all_experiment_definitions():
+    """All experiment definitions across discovered libraries."""
+    experiments = deps.get_manifest_store()._registry.list_all_experiments()
+    return {"experiments": experiments}
+
+
+@router.get("/api/experiments/{experiment_name}", tags=["Benchmark"])
+async def get_experiment(experiment_name: str):
+    """Return experiment metadata and file tree."""
+    mas_lab_root = MAS_LAB_ROOT
+    exp_dir = mas_lab_root / "labs" / experiment_name
+    if not exp_dir.exists() or not exp_dir.is_dir():
+        raise HTTPException(status_code=404, detail=f"Experiment '{experiment_name}' not found")
+
+    metadata = {}
+    meta_file = exp_dir / "metadata.yaml"
+    if meta_file.exists():
+        import yaml
+        metadata = yaml.safe_load(meta_file.read_text(encoding="utf-8"))
+
+    tree = build_tree(exp_dir, exp_dir)
+
+    return {
+        "name": experiment_name,
+        "metadata": metadata,
+        "tree": tree,
+    }
+
+
+@router.get("/api/experiments/{experiment_name}/file", tags=["Benchmark"])
+async def get_experiment_file(experiment_name: str, path: str):
+    """Read a file from an experiment's output directory.
+
+    Pass the relative path as a query parameter, e.g.
+    ``?path=metrics/answer_relevancy.csv``
+    """
+    mas_lab_root = MAS_LAB_ROOT
+    exp_dir = mas_lab_root / "labs" / experiment_name
+    if not exp_dir.exists():
+        raise HTTPException(status_code=404, detail=f"Experiment '{experiment_name}' not found")
+
+    file_path = (exp_dir / path).resolve()
+    # Allow paths inside the experiment dir or the trace/data cache (symlinked runs).
+    # Trace symlinks may point to the XDG cache dir (~/.cache/mas/) which is
+    # separate from MAS_LAB_ROOT (~/.local/share/mas/).
+    from mas.runtime.xdg import mas_cache_root
+    allowed_roots = [
+        str(exp_dir.resolve()),
+        str((mas_lab_root / "data").resolve()),
+        str(mas_cache_root().resolve()),
+    ]
+    if not any(str(file_path).startswith(root) for root in allowed_roots):
+        raise HTTPException(status_code=403, detail="Path traversal not allowed")
+    if not file_path.exists() or not file_path.is_file():
+        raise HTTPException(status_code=404, detail=f"File not found: {path}")
+
+    # For text files, return content inline; for others, return as download
+    text_suffixes = {".json", ".jsonl", ".yaml", ".yml", ".csv", ".txt", ".html", ".md", ".fingerprint", ".svg"}
+    if file_path.suffix in text_suffixes:
+        content = file_path.read_text(encoding="utf-8")
+        return {"path": path, "content": content}
+
+    # Raster images are inlined too: the UI fetches this endpoint as JSON and
+    # builds a `data:` URI, so return the bytes base64-encoded rather than as a
+    # binary FileResponse (which the JSON client cannot parse).
+    raster_suffixes = {".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp"}
+    if file_path.suffix.lower() in raster_suffixes:
+        import base64
+
+        content = base64.b64encode(file_path.read_bytes()).decode("ascii")
+        return {"path": path, "content": content}
+
+    return FileResponse(file_path, filename=file_path.name)
+
+
+@router.delete("/api/experiments/{experiment_name}", tags=["Benchmark"])
+async def delete_experiment(experiment_name: str):
+    """Delete an experiment's results and clear the trace cache."""
+    mas_lab_root = MAS_LAB_ROOT
+    exp_dir = mas_lab_root / "labs" / experiment_name
+    if not exp_dir.exists() or not exp_dir.is_dir():
+        raise HTTPException(status_code=404, detail=f"Experiment '{experiment_name}' not found")
+
+    shutil.rmtree(exp_dir)
+
+    cache_dir = mas_lab_root / "data" / "trace-cache"
+    cache_cleared = False
+    if cache_dir.exists():
+        shutil.rmtree(cache_dir)
+        cache_cleared = True
+
+    return {
+        "deleted": experiment_name,
+        "experiment_path": str(exp_dir),
+        "trace_cache_cleared": cache_cleared,
+    }

mas/lab/controller/routes/choices.py

@@ -0,0 +1,141 @@
+#  Copyright (c) 2026 Cisco Systems, Inc. and its affiliates
+#  SPDX-License-Identifier: Apache-2.0
+"""Registry-driven picker lists for the UI (models, patterns, tools, …)."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, HTTPException, Query, Request
+from mas.lab.controller.deps import store_from_request
+from mas.lab.controller.manifest_layout import item_ref, layout_for
+from mas.lab.controller.scope_catalog import get_scope_catalog
+
+router = APIRouter()
+
+_CHOICE_KINDS = (
+    "models",
+    "design-patterns",
+    "step-types",
+    "runners",
+    "tools",
+    "skills",
+    "overlays",
+)
+
+_CHOICE_KIND_TO_LAYOUT = {
+    "tools": "tool",
+    "skills": "skill",
+    "overlays": "overlay",
+}
+
+
+@router.get("/api/choices/{choice_kind}", tags=["Choices"])
+async def get_choices(
+    choice_kind: str,
+    request: Request,
+    scope: str | None = Query(default=None),
+):
+    if choice_kind not in _CHOICE_KINDS:
+        raise HTTPException(status_code=404, detail=f"unknown choices {choice_kind!r}")
+    if choice_kind == "models":
+        return _models()
+    if choice_kind == "design-patterns":
+        return await _design_patterns(request)
+    if choice_kind == "step-types":
+        from mas.lab.controller.lab_registry import get_lab_registry
+
+        return get_lab_registry().pipeline_step_types()
+    if choice_kind == "runners":
+        from mas.lab.controller.api import ControllerAPI
+
+        return {"runners": ControllerAPI().list_runtime_runners()}
+    layout_kind = _CHOICE_KIND_TO_LAYOUT.get(choice_kind)
+    if layout_kind is not None:
+        return _scope_items(request, layout_kind, scope)
+    raise HTTPException(status_code=404, detail=f"unknown choices {choice_kind!r}")
+
+
+def _models() -> dict:
+    from mas.lab.controller.lab_registry import get_lab_registry
+
+    reg = get_lab_registry()
+    default = reg.default_model()
+    aliases: list[dict] = []
+    seen: set[str] = set()
+    # Infra aliases from the active workspace plus the logical default.
+    try:
+        defaults = reg.agent_defaults()
+        model = (defaults.get("models") or [{}])
+        if isinstance(model, list):
+            for entry in model:
+                ident = str((entry or {}).get("model") or "")
+                if ident and ident not in seen:
+                    aliases.append({"id": ident, "label": ident, "source": "defaults"})
+                    seen.add(ident)
+    except Exception:
+        pass
+    if default and default not in seen:
+        aliases.insert(0, {"id": default, "label": default, "source": "default"})
+        seen.add(default)
+    # generic-model and other infra aliases if the runtime exposes them.
+    try:
+        from mas.runtime.registry import get_registry
+
+        for item in get_registry().list("llm") or []:
+            ident = str(item.get("urn") or item.get("name") or "")
+            if ident and ident not in seen:
+                aliases.append({"id": ident, "label": ident, "source": "infra"})
+                seen.add(ident)
+    except Exception:
+        pass
+    return {"models": aliases, "default": default}
+
+
+async def _design_patterns(request: Request) -> dict:
+    from mas.lab.controller.routes.design_patterns import list_design_patterns
+
+    return await list_design_patterns()
+
+
+def _scope_items(request: Request, kind: str, scope_id: str | None) -> dict:
+    store = store_from_request(request)
+    catalog = get_scope_catalog(store)
+    if scope_id:
+        try:
+            scopes = [catalog.get(scope_id)]
+        except KeyError as exc:
+            raise HTTPException(status_code=404, detail=f"scope {scope_id!r} not found") from exc
+    else:
+        scopes = [s for s in catalog.all() if s.kind == "library"]
+    items: list[dict] = []
+    for scope in scopes:
+        try:
+            located = layout_for(kind).list_located(scope)
+        except KeyError:
+            continue
+        for item in located:
+            namespace = "global"
+            if kind == "overlay":
+                try:
+                    from mas.runtime.spec.source import load_yaml_file
+
+                    doc = load_yaml_file(item.manifest_path) or {}
+                    namespace = str(
+                        (doc.get("metadata") or {}).get("namespace")
+                        or doc.get("x-namespace")
+                        or "global"
+                    )
+                except Exception:
+                    namespace = "global"
+            items.append(
+                {
+                    "id": item.item_id,
+                    "name": item.name,
+                    "title": item.title or item.name,
+                    "summary": item.summary,
+                    "ref": item_ref(scope, item.item_id),
+                    "namespace": namespace,
+                    "scope": scope.id,
+                }
+            )
+    key = {"tool": "tools", "skill": "skills", "overlay": "overlays"}[kind]
+    return {key: items}

mas/lab/controller/routes/datasets.py

@@ -0,0 +1,91 @@
+#  Copyright (c) 2026 Cisco Systems, Inc. and its affiliates
+#  SPDX-License-Identifier: Apache-2.0
+"""Dataset CRUD endpoints."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, HTTPException
+
+from mas.lab.controller.deps import ensure_yaml_ext
+from mas.lab.controller.models import SaveDatasetRequest
+from mas.lab.controller.routes._api import deps, jobs, LIBRARIES_DIR, validate_pipeline_yaml
+
+router = APIRouter()
+
+
+@router.get("/api/libraries/{library_name}/datasets", tags=["Libraries"])
+def list_datasets(library_name: str):
+    """List available dataset YAML files under datasets/."""
+    datasets = deps.get_manifest_store().list_datasets_meta(library_name)
+    return {"datasets": datasets}
+
+
+@router.post("/api/libraries/{library_name}/datasets", tags=["Libraries"], status_code=201)
+def create_dataset(library_name: str, req: SaveDatasetRequest):
+    """Create a new dataset file in the library's datasets/ directory."""
+    lib_dir = deps.get_library_path(library_name)
+    datasets_dir = lib_dir / "datasets"
+    datasets_dir.mkdir(parents=True, exist_ok=True)
+
+    filename = ensure_yaml_ext(req.name)
+    file_path = datasets_dir / filename
+
+    if file_path.exists():
+        raise HTTPException(status_code=409, detail=f"Dataset '{filename}' already exists")
+
+    file_path.write_text(req.content, encoding="utf-8")
+    deps.get_manifest_store().invalidate()
+    return {"name": filename}
+
+
+@router.get("/api/libraries/{library_name}/datasets/{dataset_name:path}", tags=["Libraries"])
+def get_dataset(library_name: str, dataset_name: str):
+    """Return the content of a specific dataset."""
+    lib_dir = deps.get_library_path(library_name)
+    file_path = lib_dir / "datasets" / dataset_name
+    if not file_path.exists() and not dataset_name.lower().endswith((".yaml", ".yml")):
+        file_path = lib_dir / "datasets" / f"{dataset_name}.yaml"
+
+    if not file_path.exists():
+        raise HTTPException(status_code=404, detail=f"Dataset '{dataset_name}' not found")
+
+    return {"name": file_path.name, "content": file_path.read_text(encoding="utf-8")}
+
+
+@router.put("/api/libraries/{library_name}/datasets/{dataset_name:path}", tags=["Libraries"])
+def update_dataset(library_name: str, dataset_name: str, req: SaveDatasetRequest):
+    """Update an existing dataset. Supports rename via req.name."""
+    lib_dir = deps.get_library_path(library_name)
+    datasets_dir = lib_dir / "datasets"
+
+    dataset_name = ensure_yaml_ext(dataset_name)
+    new_name = ensure_yaml_ext(req.name)
+
+    old_path = datasets_dir / dataset_name
+    if not old_path.exists():
+        raise HTTPException(status_code=404, detail=f"Dataset '{dataset_name}' not found")
+
+    new_path = datasets_dir / new_name
+    if new_name != dataset_name and new_path.exists():
+        raise HTTPException(status_code=409, detail=f"Dataset '{new_name}' already exists")
+
+    if old_path != new_path:
+        old_path.unlink()
+    new_path.write_text(req.content, encoding="utf-8")
+    deps.get_manifest_store().invalidate()
+    return {"name": new_name}
+
+
+@router.delete("/api/libraries/{library_name}/datasets/{dataset_name:path}", tags=["Libraries"])
+def delete_dataset(library_name: str, dataset_name: str):
+    """Delete a dataset file."""
+    lib_dir = deps.get_library_path(library_name)
+    dataset_name = ensure_yaml_ext(dataset_name)
+    file_path = lib_dir / "datasets" / dataset_name
+
+    if not file_path.exists():
+        raise HTTPException(status_code=404, detail=f"Dataset '{dataset_name}' not found")
+
+    file_path.unlink()
+    deps.get_manifest_store().invalidate()
+    return {"deleted": dataset_name}

mas/lab/controller/routes/design_patterns.py

@@ -0,0 +1,121 @@
+#  Copyright (c) 2026 Cisco Systems, Inc. and its affiliates
+#  SPDX-License-Identifier: Apache-2.0
+"""Design-pattern catalog endpoint for the agent / overlay canvas builders."""
+
+from __future__ import annotations
+
+import logging
+
+from fastapi import APIRouter
+from mas.lab.controller.routes._api import deps
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+# Config keys advertised to the UI. Sourced from the design-pattern-config
+# fragment (``mas/v1#design-pattern-config``); the constant below is a fallback
+# for deployments that don't ship the runtime schema docs.
+_CONFIG_KEYS_FALLBACK = (
+    "max_steps",
+    "max_rounds",
+    "critique_turns",
+    "enable_peer_context",
+    "parallel",
+)
+
+
+def _config_keys() -> list[str]:
+    """Property names from the design-pattern-config fragment (best effort)."""
+    try:
+        from mas.lab.schemas.paths import runtime_schema_dir
+        from mas.runtime.spec.source import load_yaml_file
+
+        path = runtime_schema_dir() / "fragments" / "design-pattern-config.schema.yaml"
+        doc = load_yaml_file(path)
+        keys = list((doc.get("properties") or {}).keys())
+        if keys:
+            return keys
+    except Exception as exc:  # pragma: no cover - schema is optional at runtime
+        logger.debug("design-pattern-config fragment unavailable: %s", exc)
+    return list(_CONFIG_KEYS_FALLBACK)
+
+
+def _pattern_type(urn: str) -> str:
+    """Manifest name for ``spec.design_pattern.type`` — final URN segment.
+
+    e.g. ``mas.dp.deterministic_staged_debate`` -> ``deterministic_staged_debate``.
+    """
+    return urn.rsplit(".", 1)[-1] if "." in urn else urn
+
+
+def _library_of(module: str) -> str:
+    """Grouping key derived from the plugin module (OSS vs experimental).
+
+    ``mas.library.standard.plugins...`` -> ``standard``
+    ``mas.library.lab.plugins...``      -> ``lab``
+    """
+    parts = module.split(".")
+    if len(parts) >= 3 and parts[0] == "mas" and parts[1] == "library":
+        return parts[2]
+    return "unknown"
+
+
+def _label(type_name: str, description: str) -> str:
+    """Human label: registry description if present, else a titleized name."""
+    desc = (description or "").strip()
+    if desc:
+        return desc.splitlines()[0]
+    return type_name.replace("_", " ").title()
+
+
+def _resolve_default(raw: str) -> str:
+    """Map the default binding (e.g. ``react@v1``) onto a pattern ``type``."""
+    if not raw:
+        return ""
+    try:
+        from mas.runtime.registry import get_registry
+
+        registry = get_registry()
+        urn = registry.urn_for(raw) or registry.urn_for(raw.split("@", 1)[0])
+        if urn:
+            return _pattern_type(urn)
+    except Exception as exc:  # pragma: no cover - defensive
+        logger.debug("could not resolve default design pattern %r: %s", raw, exc)
+    return raw.split("@", 1)[0]
+
+
+@router.get("/api/design-patterns", tags=["Registry"])
+async def list_design_patterns():
+    """Design-pattern plugins for the agent / overlay canvas builders.
+
+    Reshapes ``LabRegistry.list("design_pattern")`` into a UI-friendly catalog:
+    each entry carries a manifest ``type``, a display ``label``, the source
+    ``library`` (so the UI can group OSS vs experimental patterns) and the
+    ``config_keys`` a pattern may accept.
+    """
+    from mas.lab.controller.lab_registry import get_lab_registry
+
+    ws = getattr(deps.get_manifest_store(), "_workspace", None)
+    reg = get_lab_registry(ws)
+
+    config_keys = _config_keys()
+    patterns = []
+    for entry in reg.list("design_pattern"):
+        urn = entry.get("urn", "")
+        type_name = _pattern_type(urn)
+        patterns.append(
+            {
+                "type": type_name,
+                "label": _label(type_name, entry.get("description", "")),
+                "description": (entry.get("description") or "").strip(),
+                "library": _library_of(entry.get("module", "")),
+                "config_keys": config_keys,
+            }
+        )
+
+    # Standard (OSS) patterns first, then everything else, alphabetically.
+    patterns.sort(key=lambda p: (p["library"] != "standard", p["type"]))
+
+    default_binding = (reg.agent_defaults().get("design_pattern") or {}).get("type", "")
+    return {"patterns": patterns, "default": _resolve_default(default_binding)}