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

mas/lab/controller/manifest_store.py

@@ -0,0 +1,214 @@
+#  Copyright (c) 2026 Cisco Systems, Inc. and its affiliates
+#  SPDX-License-Identifier: Apache-2.0
+"""Library-scoped YAML manifest storage for the UI."""
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any, Dict, List
+
+from mas.runtime.constants import WORKSPACE_CONFIG_FILENAME
+from mas.lab.controller.lab_registry import LabRegistry, _library_description
+from mas.lab.controller.lab_registry import get_lab_registry
+from mas.ctl.overlay.canvas import overlay_is_layout_only
+from mas.runtime.spec.source import load_yaml_file
+
+logger = logging.getLogger(__name__)
+
+_SUBDIRS = {
+    "experiments": "experiments",
+    "pipelines": "pipelines",
+    "overlays": "overlays",
+    "datasets": "datasets",
+    "apps": "apps",
+    "scenarios": "scenarios",
+}
+
+
+class ManifestStore:
+    """Read/write YAML resources under library roots."""
+
+    def __init__(self, workspace: Any = None, *, registry: LabRegistry | None = None) -> None:
+        """Create a store, optionally injecting a specific ``registry``.
+
+        By default the store uses the process-wide :func:`get_lab_registry`
+        singleton. Pass ``registry`` (e.g. a ``LabRegistry`` built with
+        ``MAS_LAB_REGISTRY_EAGER_REFRESH=0`` and manually populated
+        ``_libraries``) to use an isolated registry instead — this is how
+        tests avoid both the global singleton and expensive discovery,
+        without bypassing ``__init__`` via ``__new__``.
+        """
+        self._workspace = workspace
+        self._registry = registry if registry is not None else get_lab_registry(workspace)
+        self._libraries: Dict[str, Path] = {}
+        self._refreshed = False
+
+    def _ensure_ready(self) -> None:
+        # Many tests override _libraries directly; avoid expensive discovery if already injected.
+        if self._libraries:
+            return
+        if not self._refreshed:
+            self.refresh()
+
+    def refresh(self) -> None:
+        self._registry.refresh()
+        self._libraries = self._registry.library_paths()
+        self._refreshed = True
+
+    def invalidate(self) -> None:
+        """Drop cached manifest-file listings (see LabRegistry.invalidate_manifest_cache)."""
+        self._registry.invalidate_manifest_cache()
+
+    def libraries(self) -> List[Dict[str, str]]:
+        self._ensure_ready()
+        items: List[Dict[str, str]] = []
+        for slug, path in sorted(self._libraries.items()):
+            items.append(
+                {
+                    "dir": slug,
+                    "name": slug.replace("-", " ").replace("_", " ").title(),
+                    "description": _library_description(path),
+                }
+            )
+        return items
+
+    def library_root(self, library: str) -> Path:
+        self._ensure_ready()
+        root = self._libraries.get(library)
+        if root is not None:
+            return root
+        return self._registry.library_root(library)
+
+    def list_experiments(self, library: str) -> List[Dict[str, Any]]:
+        root = self.library_root(library)
+        return [
+            LabRegistry._parse_experiment_metadata(p, root)
+            for p in self._registry._iter_experiment_files(root)
+        ]
+
+    def list_pipelines(self, library: str) -> List[Dict[str, Any]]:
+        root = self.library_root(library)
+        return [
+            LabRegistry._parse_pipeline_metadata(p, root)
+            for p in self._registry._iter_pipeline_files(root)
+        ]
+
+    def list_datasets_meta(self, library: str) -> List[Dict[str, str]]:
+        root = self.library_root(library)
+        return [
+            {
+                "name": path.name,
+                "path": str(path.relative_to(root)),
+                "description": LabRegistry._dataset_description(path),
+            }
+            for path in self._registry._iter_dataset_files(root)
+        ]
+
+    def list_overlays(self, library: str) -> List[Dict[str, Any]]:
+        root = self.library_root(library)
+        overlays: List[Dict[str, Any]] = []
+        for path in self._registry._iter_overlay_files(root):
+            rel = str(path.relative_to(root))
+            entry: Dict[str, Any] = {
+                "name": path.stem,
+                "filename": path.name,
+                "path": rel,
+                "ui_canvas": False,
+            }
+            try:
+                data = load_yaml_file(path)
+                meta = data.get("metadata", {})
+                entry["description"] = str(meta.get("description", "") or "")
+                entry["namespace"] = str((data.get("metadata") or {}).get("namespace", "global") or "global")
+                entry["ui_canvas"] = overlay_is_layout_only(data)
+            except Exception:
+                entry["description"] = ""
+                entry["namespace"] = "global"
+            overlays.append(entry)
+        return overlays
+
+    def collect_mas_resources(self, library: str) -> Dict[str, Dict[str, Any]]:
+        root = self.library_root(library)
+        return self._registry._collect_mas_resources(root)
+
+    def list_yaml_resources(self, library: str, resource: str) -> List[Dict[str, Any]]:
+        sub = _SUBDIRS.get(resource, resource)
+        root = self.library_root(library) / sub
+        if not root.exists():
+            return []
+        items: List[Dict[str, Any]] = []
+        for path in sorted(root.rglob("*.yaml")):
+            rel = path.relative_to(root)
+            name = path.stem if rel.parent == Path(".") else str(rel.with_suffix(""))
+            items.append({"name": name, "path": str(rel), "file": str(path)})
+        return items
+
+    def read_text(self, library: str, resource: str, name: str) -> str:
+        path = self._resolve_resource_path(library, resource, name)
+        return path.read_text(encoding="utf-8")
+
+    def write_text(self, library: str, resource: str, name: str, content: str) -> Path:
+        path = self._resolve_resource_path(library, resource, name, create=True)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(content.rstrip() + "\n", encoding="utf-8")
+        return path
+
+    def delete_resource(self, library: str, resource: str, name: str) -> None:
+        path = self._resolve_resource_path(library, resource, name)
+        if path.exists():
+            path.unlink()
+
+    def config_files(self, library: str) -> Dict[str, Dict[str, str]]:
+        """Infra, flavours, and workspace YAML for the control panel."""
+        root = self.library_root(library)
+        flavours: Dict[str, str] = {}
+        infra: Dict[str, str] = {}
+
+        for path in sorted(p for p in root.rglob("flavours/*") if p.suffix in (".yaml", ".yml")):
+            if path.is_file():
+                flavours[str(path.relative_to(root))] = path.read_text(encoding="utf-8")
+
+        for path in sorted(p for p in root.rglob("infra/*") if p.suffix in (".yaml", ".yml")):
+            if path.is_file():
+                infra[str(path.relative_to(root))] = path.read_text(encoding="utf-8")
+
+        ws_root = self._registry._workspace_root()
+        if ws_root is not None:
+            infra.update(LabRegistry.discover_workspace_infra(ws_root))
+        infra.update(LabRegistry.discover_bundled_infra())
+
+        workspace: Dict[str, str] = {}
+        if ws_root is not None:
+            ws_file = ws_root / WORKSPACE_CONFIG_FILENAME
+            if ws_file.is_file():
+                workspace[WORKSPACE_CONFIG_FILENAME] = ws_file.read_text(encoding="utf-8")
+        if not workspace:
+            local_ws = root / WORKSPACE_CONFIG_FILENAME
+            if local_ws.is_file():
+                workspace[WORKSPACE_CONFIG_FILENAME] = local_ws.read_text(encoding="utf-8")
+
+        return {
+            "infra": infra,
+            "flavours": flavours,
+            "workspace": workspace,
+        }
+
+    def _resolve_resource_path(
+        self,
+        library: str,
+        resource: str,
+        name: str,
+        *,
+        create: bool = False,
+    ) -> Path:
+        sub = _SUBDIRS.get(resource, resource)
+        root = self.library_root(library) / sub
+        candidate = (root / name).with_suffix(".yaml")
+        if candidate.exists() or create:
+            return candidate
+        for path in root.rglob("*.yaml"):
+            if path.stem == name or str(path.relative_to(root).with_suffix("")) == name:
+                return path
+        if create:
+            return candidate
+        raise FileNotFoundError(f"{resource}/{name} not found in library {library!r}")

mas/lab/controller/manifest_validation.py

@@ -0,0 +1,90 @@
+#  Copyright (c) 2026 Cisco Systems, Inc. and its affiliates
+#  SPDX-License-Identifier: Apache-2.0
+"""In-process manifest validation for controller HTTP routes (no CLI subprocess)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from mas.ctl.validate.schemas import declared_kind, schema_path_for_kind
+from mas.ctl.validate.validator import validate_data
+
+
+def validate_manifest_yaml_content(
+    manifest_yaml: str,
+    *,
+    base_dir: Path,
+    kind: str | None = None,
+    resolve_refs: bool = True,
+) -> dict[str, Any]:
+    """Validate inline YAML; return legacy CLI-shaped dict for API compatibility."""
+    try:
+        data = yaml.safe_load(manifest_yaml)
+    except yaml.YAMLError as exc:
+        return {
+            "exit_code": 1,
+            "stdout": "",
+            "stderr": f"YAML parse error: {exc}",
+            "command": "validate_data",
+            "valid": False,
+        }
+
+    if not isinstance(data, dict):
+        return {
+            "exit_code": 1,
+            "stdout": "",
+            "stderr": "manifest must be a YAML mapping",
+            "command": "validate_data",
+            "valid": False,
+        }
+
+    resolved_kind = kind or declared_kind(data)
+    if resolved_kind is None or schema_path_for_kind(resolved_kind) is None:
+        return {
+            "exit_code": 0,
+            "stdout": "",
+            "stderr": "",
+            "command": "validate_data",
+            "valid": True,
+        }
+
+    result = validate_data(
+        data,
+        source="<inline>",
+        kind=resolved_kind,
+        base_dir=base_dir,
+        resolve_refs=resolve_refs,
+    )
+
+    errors = [i for i in result.issues if i.level == "error"]
+    warnings = [i for i in result.issues if i.level == "warning"]
+    lines = [f"[{i.level}] {i.message}" for i in errors + warnings]
+    stderr = "\n".join(lines)
+
+    return {
+        "exit_code": 0 if result.ok else 1,
+        "stdout": "",
+        "stderr": stderr,
+        "command": "validate_data",
+        "valid": result.ok,
+        "issues": [{"level": i.level, "message": i.message, "path": i.path} for i in result.issues],
+    }
+
+
+def validate_overlay_yaml_content(content: str, *, base_dir: Path) -> list[str] | None:
+    """Validate overlay YAML; return error strings or None when valid."""
+    outcome = validate_manifest_yaml_content(
+        content,
+        base_dir=base_dir,
+        kind="overlay",
+        resolve_refs=False,
+    )
+    if outcome.get("valid"):
+        return None
+    stderr = str(outcome.get("stderr") or "").strip()
+    if stderr:
+        return [line.strip() for line in stderr.splitlines() if line.strip()]
+    return ["Validation failed"]

mas/lab/controller/models.py

@@ -0,0 +1,215 @@
+#  Copyright (c) 2026 Cisco Systems, Inc. and its affiliates
+#  SPDX-License-Identifier: Apache-2.0
+"""Pydantic request/response models for the FastAPI controller API."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import AliasChoices, BaseModel, Field
+
+from mas.lab.controller.constants import MAX_TIMEOUT
+
+
+class ValidateRequest(BaseModel):
+    manifest_yaml: str = Field(
+        ...,
+        description="Full YAML manifest content to validate (agent or MAS)",
+    )
+
+
+class SaveOverlayRequest(BaseModel):
+    name: str = Field(..., description="Overlay name (used as filename, without .yaml)")
+    content: str = Field(..., description="Full overlay YAML content")
+    run_validation: bool = Field(default=True, description="Validate against schema before saving")
+
+
+class RunAgentRequest(BaseModel):
+    manifest_yaml: str = Field(..., description="Full agent YAML manifest content to run")
+    query: str = Field(..., description="The question to send to the agent")
+    flavour: Optional[str] = Field(
+        default=None,
+        description="Flavour name (e.g., 'local', 'local-benchmark')",
+    )
+    session_id: Optional[str] = Field(
+        default=None,
+        description="Stable session id for multi-turn chat memory",
+    )
+    verbose: bool = Field(
+        default=False,
+        description="Deprecated: chat runs in-process without CLI stdout",
+    )
+    no_cache: bool = Field(default=True, description="Clear web search cache before running")
+    timeout: int = Field(default=60, ge=1, le=MAX_TIMEOUT, description="Timeout in seconds")
+
+
+class MultiTurnRequest(BaseModel):
+    manifest_yaml: str = Field(..., description="Full agent YAML manifest content to run")
+    queries: list[str] = Field(
+        ...,
+        min_length=1,
+        description="Ordered list of queries for a multi-turn conversation",
+    )
+    overlays: list[str] = Field(
+        default_factory=list,
+        description="Overlay filenames to apply (relative to library dir)",
+    )
+    flavour: Optional[str] = Field(default=None, description="Flavour name")
+    verbose: bool = Field(default=True, description="Enable verbose output")
+    timeout: int = Field(default=90, ge=1, le=MAX_TIMEOUT, description="Timeout in seconds")
+
+
+class RunMASRequest(BaseModel):
+    manifest_yaml: str = Field(
+        default="",
+        description="Full MAS YAML. Ignored when mas_path is set.",
+    )
+    mas_path: Optional[str] = Field(
+        default=None,
+        description="MAS file relative to the library root (preferred: keeps agent refs valid).",
+    )
+    query: str = Field(..., description="The question to send to the MAS")
+    overlays: list[str] = Field(
+        default_factory=list,
+        description="Overlay names or paths relative to the library dir",
+    )
+    infra_refs: list[str] = Field(
+        default_factory=list,
+        description="If set, only these infra files are passed to mas-ctl (no directory glob).",
+    )
+    pre: list[dict] = Field(
+        default_factory=list,
+        description="Inline pipeline-style steps run in the library cwd before mas-ctl (type: shell).",
+    )
+    demo_ui_ingest_url: Optional[str] = Field(
+        default=None,
+        description="When set, mas-ctl POSTs live native records to this demo-ui ingest URL.",
+    )
+    demo_ui_ref: Optional[dict] = Field(
+        default=None,
+        description="Data-source ref stamped onto live ingest records.",
+    )
+    flavour: Optional[str] = Field(default=None, description="Flavour name")
+    verbose: bool = Field(default=True, description="Enable verbose output")
+    timeout: int = Field(default=90, ge=1, le=MAX_TIMEOUT, description="Timeout in seconds")
+
+
+class SaveDatasetRequest(BaseModel):
+    name: str = Field(..., description="Dataset filename (e.g. my-dataset.yaml)")
+    content: str = Field(..., description="Full dataset YAML content")
+
+
+class ExperimentRunRequest(BaseModel):
+    experiment_yaml: str = Field(
+        ...,
+        description="Experiment filename or path relative to the library root",
+    )
+    query: str = Field(
+        default="",
+        description="Optional prompt override shown in the demo-ui selector",
+    )
+    infra_refs: list[str] = Field(
+        default_factory=list,
+        description="Extra infra files relative to the library root (LLM cache, model pin)",
+    )
+    pre: list[dict] = Field(
+        default_factory=list,
+        description="Inline pipeline-style steps run in the library cwd before the worker starts",
+    )
+    demo_ui_ingest_url: Optional[str] = Field(
+        default=None,
+        description="When set, the in-process worker POSTs live native records here",
+    )
+    demo_ui_ref: Optional[dict] = Field(
+        default=None,
+        description="Data-source ref stamped onto live ingest records",
+    )
+    force: bool = Field(default=True, description="Force a new run even if a previous exists")
+    max_runs: Optional[int] = Field(default=1, description="Cap n_runs for a live experiment")
+    timeout: int = Field(default=MAX_TIMEOUT, ge=1, le=MAX_TIMEOUT, description="Timeout in seconds")
+
+
+class BenchmarkRunRequest(BaseModel):
+    experiment_yaml: str = Field(
+        ...,
+        description="Full experiment YAML content, or a filename relative to the library dir",
+    )
+    progress: bool = Field(default=True, description="Show progress bar")
+    max_runs: Optional[int] = Field(
+        default=None,
+        validation_alias=AliasChoices("max_runs", "n_runs"),
+        description="Override n_runs from config",
+    )
+    force: bool = Field(default=True, description="Force a new run even if a previous exists")
+    flavour: Optional[str] = Field(default=None, description="Flavour name")
+    timeout: int = Field(default=MAX_TIMEOUT, ge=1, le=MAX_TIMEOUT, description="Timeout in seconds")
+
+
+class BenchmarkAnalyzeRequest(BaseModel):
+    benchmark_id: str = Field(..., description="Benchmark run id (short or full)")
+    experiment_yaml: Optional[str] = Field(
+        default=None,
+        description="Optional experiment YAML path when auto-detect fails",
+    )
+    timeout: int = Field(default=120, ge=1, le=MAX_TIMEOUT, description="Timeout in seconds")
+
+
+class BenchmarkExportRequest(BaseModel):
+    benchmark_id: str = Field(..., description="Benchmark run id (short, full, last, or latest)")
+    output: Optional[str] = Field(default=None, description="Output .tar.gz path (default: cwd)")
+    include_trace_cache: bool = Field(default=True, description="Pack trace-cache entries")
+    dry_run: bool = Field(default=False, description="List archive contents without writing")
+    timeout: int = Field(default=300, ge=1, le=MAX_TIMEOUT, description="Timeout in seconds")
+
+
+class BenchmarkImportRequest(BaseModel):
+    tarball: str = Field(..., description="Path to .tar.gz produced by benchmark export")
+    output_dir: Optional[str] = Field(default=None, description="Restore benchmark output here")
+    trace_cache_dir: Optional[str] = Field(default=None, description="Restore trace-cache entries here")
+    dry_run: bool = Field(default=False, description="Inspect archive without writing")
+    timeout: int = Field(default=300, ge=1, le=MAX_TIMEOUT, description="Timeout in seconds")
+
+
+class PipelineRunRequest(BaseModel):
+    pipeline_yaml: str = Field(
+        default="pipelines/full-pipeline-topology-comparison.yaml",
+        description="Pipeline YAML path (relative to library dir)",
+    )
+    only: list[str] = Field(
+        default_factory=list,
+        description="Run only these steps (e.g., ['extract', 'evaluate'])",
+    )
+    timeout: int = Field(default=MAX_TIMEOUT, ge=1, le=MAX_TIMEOUT, description="Timeout in seconds")
+
+
+class SavePipelineRequest(BaseModel):
+    name: str = Field(..., description="Pipeline name (used as filename, without .yaml)")
+    content: str = Field(..., description="Full pipeline YAML content")
+    run_validation: bool = Field(default=True, description="Validate against schema before saving")
+
+
+class SaveExperimentRequest(BaseModel):
+    name: str = Field(..., description="Experiment name (used as filename, without .yaml)")
+    content: str = Field(..., description="Full experiment YAML content")
+
+
+class EvalOutputRequest(BaseModel):
+    events_file: str = Field(
+        ...,
+        description="Path to events.jsonl (relative to library dir or absolute)",
+    )
+    metrics: list[str] = Field(
+        default=["answer_relevancy"],
+        description="Metric names to compute",
+    )
+    model: str = Field(default="azure/gpt-4o", description="LLM judge model")
+    timeout: int = Field(default=90, ge=1, le=MAX_TIMEOUT, description="Timeout in seconds")
+
+
+class SaveMASResourceRequest(BaseModel):
+    mas_name: str = Field(..., description="MAS name (becomes the app folder name under apps/)")
+    mas_yaml: str = Field(..., description="MAS manifest YAML content")
+    agents: dict[str, str] = Field(
+        default_factory=dict,
+        description="Map of agent name → agent YAML content (stored in apps/<mas_name>/agents/)",
+    )

mas/lab/controller/path_safety.py

@@ -0,0 +1,68 @@
+#  Copyright (c) 2026 Cisco Systems, Inc. and its affiliates
+#  SPDX-License-Identifier: Apache-2.0
+"""Name and path guards for every controller write."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from mas.lab.controller.kinds import NAME_PATTERN, VERSION_PATTERN
+
+_NAME_RE = re.compile(NAME_PATTERN)
+_VERSION_RE = re.compile(VERSION_PATTERN)
+
+
+class UnsafeNameError(ValueError):
+    """A user-supplied name, version, or item id failed the allow-list."""
+
+
+def validate_name(name: str) -> str:
+    text = str(name or "").strip()
+    if not text or not _NAME_RE.fullmatch(text):
+        raise UnsafeNameError(f"invalid name {name!r}")
+    if text.startswith("."):
+        raise UnsafeNameError(f"hidden name {name!r} is not allowed")
+    if ".." in text or "/" in text or "\\" in text:
+        raise UnsafeNameError(f"path-like name {name!r} is not allowed")
+    return text
+
+
+def validate_version(version: str | None) -> str | None:
+    if version is None or str(version).strip() == "":
+        return None
+    text = str(version).strip()
+    if not _VERSION_RE.fullmatch(text):
+        raise UnsafeNameError(f"invalid version {version!r}")
+    return text
+
+
+def parse_item_id(item_id: str) -> tuple[str, str | None]:
+    """Split ``name`` or ``name@version``. Reject path-like ids."""
+    text = str(item_id or "").strip()
+    if not text or text.startswith(".") or ".." in text or "/" in text or "\\" in text:
+        raise UnsafeNameError(f"invalid item id {item_id!r}")
+    if "@" not in text:
+        return validate_name(text), None
+    name, _, version = text.rpartition("@")
+    return validate_name(name), validate_version(version)
+
+
+def ensure_inside(root: Path, target: Path) -> Path:
+    """Resolve *target* and require it to stay under *root* (no symlink escape)."""
+    root_resolved = root.resolve()
+    target_resolved = target.resolve()
+    try:
+        target_resolved.relative_to(root_resolved)
+    except ValueError as exc:
+        raise UnsafeNameError("path is outside the scope root") from exc
+    return target_resolved
+
+
+def is_hidden_under(root: Path, target: Path) -> bool:
+    """True when any relative part is a dot-directory (staging leftovers, ``.git``)."""
+    try:
+        rel = target.resolve().relative_to(root.resolve())
+    except ValueError:
+        return True
+    return any(part.startswith(".") for part in rel.parts)

mas/lab/controller/pipeline_validation.py

@@ -0,0 +1,79 @@
+#  Copyright (c) 2026 Cisco Systems, Inc. and its affiliates
+#  SPDX-License-Identifier: Apache-2.0
+"""Pipeline YAML validation helpers."""
+
+from __future__ import annotations
+
+
+def validate_pipeline_yaml(content: str) -> dict:
+    """Validate pipeline YAML content against the JSON schema and check DAG integrity.
+
+    Returns {"valid": True} or {"valid": False, "errors": [...]}.
+    """
+    import json
+
+    import jsonschema
+    import yaml as _yaml
+
+    errors: list[str] = []
+
+    try:
+        doc = _yaml.safe_load(content)
+    except _yaml.YAMLError as exc:
+        return {"valid": False, "errors": [f"YAML parse error: {exc}"]}
+
+    if not isinstance(doc, dict):
+        return {"valid": False, "errors": ["Document must be a YAML mapping"]}
+
+    # JSON Schema validation (bench package: pipeline-manifest.schema.json)
+    try:
+        from mas.lab.controller.schema_registry import read_schema_text
+
+        _, schema_text = read_schema_text("pipeline")
+        schema = json.loads(schema_text)
+        jsonschema.validate(doc, schema)
+    except jsonschema.ValidationError as exc:
+        errors.append(f"Schema: {exc.message} (at {'/'.join(str(p) for p in exc.absolute_path)})")
+    except Exception as exc:
+        errors.append(f"Schema validation error: {exc}")
+
+    # DAG integrity checks
+    steps = (doc.get("spec") or {}).get("steps") or []
+    step_names = {s["name"] for s in steps if "name" in s}
+    seen: set[str] = set()
+    for s in steps:
+        name = s.get("name", "<unnamed>")
+        if name in seen:
+            errors.append(f"Duplicate step name: '{name}'")
+        seen.add(name)
+        for dep in s.get("depends_on", []):
+            if dep not in step_names:
+                errors.append(f"Step '{name}' depends on unknown step '{dep}'")
+            if dep == name:
+                errors.append(f"Step '{name}' depends on itself")
+
+    # Cycle detection (topological sort)
+    if not errors:
+        adj: dict[str, list[str]] = {s["name"]: s.get("depends_on", []) for s in steps}
+        visited: set[str] = set()
+        in_stack: set[str] = set()
+
+        def _has_cycle(node: str) -> bool:
+            if node in in_stack:
+                return True
+            if node in visited:
+                return False
+            visited.add(node)
+            in_stack.add(node)
+            for dep in adj.get(node, []):
+                if _has_cycle(dep):
+                    return True
+            in_stack.discard(node)
+            return False
+
+        for step_name in adj:
+            if _has_cycle(step_name):
+                errors.append("Dependency cycle detected in pipeline steps")
+                break
+
+    return {"valid": len(errors) == 0, "errors": errors}