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

mas/lab/controller/routes/run.py

@@ -0,0 +1,215 @@
+#  Copyright (c) 2026 Cisco Systems, Inc. and its affiliates
+#  SPDX-License-Identifier: Apache-2.0
+"""Agent and MAS run endpoints."""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+from fastapi import APIRouter, HTTPException
+
+from mas.lab.controller.constants import WEB_SEARCH_CACHE_DIR
+from mas.lab.controller.models import MultiTurnRequest, RunAgentRequest, RunMASRequest
+from mas.lab.controller.routes._api import deps, jobs, LIBRARIES_DIR, validate_pipeline_yaml
+
+router = APIRouter()
+
+
+def _resolve_overlay_arg(lib_dir: Path, ov: str) -> str:
+    raw = Path(ov)
+    if raw.is_file():
+        try:
+            return str(raw.resolve().relative_to(lib_dir.resolve()))
+        except ValueError:
+            return str(raw)
+    candidate = lib_dir / ov
+    if candidate.is_file():
+        return str(candidate.relative_to(lib_dir))
+    stem = raw.stem
+    hits = [
+        path
+        for path in lib_dir.rglob(f"{stem}.yaml")
+        if "overlays" in path.parts and "versions" not in path.parts
+    ]
+    hits.sort(key=lambda path: (0 if path.parent.name == "overlays" else 1, str(path)))
+    if hits:
+        return str(hits[0].relative_to(lib_dir))
+    return ov
+
+
+def _infra_args(lib_dir: Path, infra_refs: list[str]) -> list[str]:
+    args: list[str] = []
+    if infra_refs:
+        for item in infra_refs:
+            path = Path(item)
+            resolved = path if path.is_absolute() else (lib_dir / item)
+            args += ["--infra-ref", str(resolved)]
+        return args
+    seen: set[Path] = set()
+    for infra_dir in [lib_dir / "infra", lib_dir.parent / "infra"]:
+        if infra_dir.is_dir():
+            for infra_file in sorted(infra_dir.glob("*.yaml")):
+                resolved = infra_file.resolve()
+                if resolved not in seen:
+                    seen.add(resolved)
+                    args += ["--infra-ref", str(infra_file)]
+    return args
+
+
+@router.post("/api/libraries/{library_name}/run", tags=["Libraries"], status_code=202)
+async def run_agent(library_name: str, req: RunAgentRequest):
+    """Run an agent with a single query in-process. Returns a job_id for polling."""
+    lib_dir = deps.get_library_path(library_name)
+
+    if req.no_cache and WEB_SEARCH_CACHE_DIR.exists():
+        shutil.rmtree(WEB_SEARCH_CACHE_DIR, ignore_errors=True)
+
+    job = jobs.submit_agent_chat_job(
+        endpoint=f"/api/libraries/{library_name}/run",
+        manifest_yaml=req.manifest_yaml,
+        query=req.query,
+        lib_dir=lib_dir,
+        flavour=req.flavour,
+        session_id=req.session_id,
+        timeout=req.timeout,
+        request_body={"query": req.query, "flavour": req.flavour},
+    )
+    return {
+        "job_id": job.id,
+        "status": job.status.value,
+        "session_id": job.session_id,
+        "command": job.command,
+    }
+
+
+@router.post("/api/libraries/{library_name}/run/multi-turn", tags=["Libraries"], status_code=202)
+async def run_agent_multi_turn(library_name: str, req: MultiTurnRequest):
+    """Run an agent with multiple sequential queries. Returns a job_id for polling."""
+    lib_dir = deps.get_library_path(library_name)
+
+    tmp = tempfile.NamedTemporaryFile(
+        mode="w", suffix=".yaml", prefix="agent-mt-", delete=False, dir=str(lib_dir)
+    )
+    tmp.write(req.manifest_yaml)
+    tmp.close()
+    tmp_path = Path(tmp.name)
+
+    cmd = ["mas-runtime", "run-agent", tmp_path.name]
+    if req.verbose:
+        cmd.append("-v")
+    for ov in req.overlays:
+        cmd += ["--overlay", ov]
+    if req.flavour:
+        cmd += ["--flavour", req.flavour]
+    for q in req.queries:
+        cmd += ["-q", q]
+    job = jobs.submit_job(
+        endpoint=f"/api/libraries/{library_name}/run/multi-turn",
+        cmd=cmd,
+        cwd=lib_dir,
+        timeout=req.timeout,
+        request_body=req.model_dump(),
+        cleanup_paths=[tmp_path],
+    )
+    return {"job_id": job.id, "status": job.status.value, "command": job.command}
+
+
+@router.post("/api/libraries/{library_name}/run-mas", tags=["Libraries"], status_code=202)
+async def run_mas(library_name: str, req: RunMASRequest):
+    """Run a MAS with a single query. Returns a job_id for polling."""
+    import yaml
+
+    lib_dir = deps.get_library_path(library_name)
+    cleanup_paths: list[Path] = []
+    mas_rel: str
+
+    if req.mas_path:
+        mas_file = lib_dir / req.mas_path
+        if not mas_file.is_file():
+            raise HTTPException(status_code=404, detail=f"MAS not found: {req.mas_path}")
+        mas_rel = req.mas_path
+    elif req.manifest_yaml.strip():
+        manifest_dir = lib_dir
+        try:
+            manifest_data = yaml.safe_load(req.manifest_yaml)
+            mas_name = (manifest_data or {}).get("metadata", {}).get("name", "")
+            if mas_name:
+                app_dir = lib_dir / "apps" / mas_name
+                if app_dir.is_dir():
+                    manifest_dir = app_dir
+        except Exception:
+            pass
+        tmp = tempfile.NamedTemporaryFile(
+            mode="w", suffix=".yaml", prefix="mas-run-", delete=False, dir=str(manifest_dir)
+        )
+        tmp.write(req.manifest_yaml)
+        tmp.close()
+        tmp_path = Path(tmp.name)
+        cleanup_paths.append(tmp_path)
+        mas_rel = str(tmp_path.relative_to(lib_dir))
+    else:
+        raise HTTPException(status_code=400, detail="needs: mas_path or manifest_yaml")
+
+    cmd = ["mas-ctl"]
+    if req.verbose:
+        cmd.append("-v")
+    cmd += ["run-mas", mas_rel]
+    for ov in req.overlays:
+        cmd += ["--overlay", _resolve_overlay_arg(lib_dir, ov)]
+    if req.flavour:
+        cmd += ["--flavour", req.flavour]
+    cmd += _infra_args(lib_dir, req.infra_refs)
+    cmd += ["-q", req.query]
+    env_override: dict[str, str] = {}
+    if req.demo_ui_ingest_url:
+        env_override["MAS_DEMO_UI_INGEST_URL"] = req.demo_ui_ingest_url
+    if req.demo_ui_ref:
+        env_override["MAS_DEMO_UI_REF"] = json.dumps(req.demo_ui_ref)
+    events_file = Path(tempfile.mkdtemp(prefix="mas-demo-ui-")) / "traces" / "events.jsonl"
+    events_file.parent.mkdir(parents=True, exist_ok=True)
+    env_override["MAS_EVENTS_FILE"] = str(events_file)
+    _run_pre_steps(lib_dir, req.pre)
+    job = jobs.submit_job(
+        endpoint=f"/api/libraries/{library_name}/run-mas",
+        cmd=cmd,
+        cwd=lib_dir,
+        timeout=req.timeout,
+        env_override=env_override or None,
+        request_body={
+            "query": req.query,
+            "flavour": req.flavour,
+            "mas_path": req.mas_path,
+            "demo_ui_ref": req.demo_ui_ref,
+        },
+        cleanup_paths=cleanup_paths,
+    )
+    return {
+        "job_id": job.id,
+        "status": job.status.value,
+        "command": job.command,
+        "events_path": str(events_file),
+    }
+
+
+def _run_pre_steps(lib_dir: Path, steps: list[dict]) -> None:
+    for step in steps or []:
+        kind = str(step.get("type") or "shell")
+        command = str(step.get("command") or (step.get("config") or {}).get("command") or "").strip()
+        if kind != "shell" or not command:
+            continue
+        completed = subprocess.run(
+            ["/bin/sh", "-c", command],
+            cwd=str(lib_dir),
+            check=False,
+            capture_output=True,
+            text=True,
+        )
+        if completed.returncode != 0:
+            raise HTTPException(
+                status_code=400,
+                detail=f"pre shell failed ({completed.returncode}): {command}\n{completed.stderr}",
+            )

mas/lab/controller/routes/runs.py

@@ -0,0 +1,392 @@
+#  Copyright (c) 2026 Cisco Systems, Inc. and its affiliates
+#  SPDX-License-Identifier: Apache-2.0
+"""Start, list, stream, and delete runs. Bodies carry item ids, never paths."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import shutil
+import tempfile
+from pathlib import Path
+from typing import Optional
+
+from fastapi import APIRouter, HTTPException, Request
+from fastapi.responses import StreamingResponse
+from mas.lab.controller import run_bridge
+from mas.lab.controller.api import peek_controller_api
+from mas.lab.controller.artifacts import get_artifact_registry
+from mas.lab.controller.constants import MAX_TIMEOUT
+from mas.lab.controller.deps import store_from_request
+from mas.lab.controller.item_service import ItemError, get_item
+from mas.lab.controller.kinds import KIND_CATALOG
+from mas.lab.controller.run_store import _now, get_run_store, new_run
+from pydantic import BaseModel, Field
+
+router = APIRouter()
+
+
+_RUN_ACTIONS = {"run", "analyze", "import", "export"}
+
+
+class StartRunRequest(BaseModel):
+    scope: str
+    kind: str
+    item: str
+    overlays: list[str] = Field(default_factory=list)
+    bind: Optional[str] = None
+    query: Optional[str] = None
+    manifest: Optional[str] = None
+    action: str = "run"
+    timeout: int = Field(default=MAX_TIMEOUT, ge=1, le=MAX_TIMEOUT)
+
+
+@router.post("/api/runs", tags=["Runs"], status_code=202)
+async def start_run(req: StartRunRequest, request: Request):
+    store = store_from_request(request)
+    action = (req.action or "run").lower()
+    if action not in _RUN_ACTIONS:
+        raise HTTPException(status_code=400, detail=f"unknown run action {req.action!r}")
+    if action == "run" and not KIND_CATALOG.get(req.kind, {}).get("runnable"):
+        raise HTTPException(status_code=400, detail=f"cannot run kind {req.kind!r}")
+    cwd = _cwd_for(req.scope, store)
+    if action == "run" and not req.manifest:
+        try:
+            get_item(req.scope, req.kind, req.item, store=store)
+        except ItemError as exc:
+            raise HTTPException(status_code=exc.status, detail=exc.detail) from exc
+    run = new_run(
+        scope=req.scope,
+        kind=req.kind,
+        item=req.item,
+        request_summary={
+            "overlays": req.overlays,
+            "bind": req.bind,
+            "query": req.query,
+            "action": action,
+            "has_inline_manifest": bool(req.manifest),
+            "source": "ui",
+        },
+    )
+    runs = get_run_store()
+    run.status = "running"
+    run.started_at = _now()
+    if req.query:
+        run.log_lines.append(req.query)
+    runs.save(run)
+
+    api = peek_controller_api()
+    if api is not None and action == "run":
+        path, cleanup = _item_path(req, store)
+        submitted = run_bridge.submit_run(api, req, path, cwd)
+        worker_id = submitted.get("worker_id") or submitted.get("job_id")
+        run.job_id = worker_id
+        detail = api.get_worker(worker_id) if worker_id else None
+        if detail:
+            run_bridge.apply_worker_to_run(run, detail, cwd=cwd)
+            if run.status not in {"pending", "running"}:
+                _attach_artifacts(run, cwd)
+        status = (detail or submitted).get("status")
+        if str(status) in run_bridge._TERMINAL:
+            for leftover in cleanup:
+                shutil.rmtree(leftover, ignore_errors=True)
+        else:
+            run_bridge.register_cleanup(run.id, cleanup)
+        runs.save(run)
+        return {"id": run.id, "status": run.status, "job_id": run.job_id}
+
+    cmd, cleanup = _command_for_run(req, store, cwd=cwd)
+    from mas.lab.controller import jobs as jobs_mod
+
+    job = jobs_mod.submit_job(
+        endpoint="/api/runs",
+        cmd=cmd,
+        cwd=cwd,
+        timeout=req.timeout,
+        request_body=req.model_dump(),
+        cleanup_paths=cleanup or None,
+    )
+    run.job_id = job.id
+    if job.status in jobs_mod.TERMINAL_STATUSES:
+        _apply_job_to_run(run, job, cwd=cwd)
+    else:
+        asyncio.create_task(_follow_job(run.id, job.id, cwd))
+    runs.save(run)
+
+    return {"id": run.id, "status": run.status, "job_id": job.id}
+
+
+def _item_path(req: StartRunRequest, store) -> tuple[Path, list[Path]]:
+    cleanup: list[Path] = []
+    if req.manifest:
+        tmp_dir = Path(tempfile.mkdtemp(prefix="mas-run-"))
+        path = tmp_dir / f"{req.kind}.yaml"
+        path.write_text(req.manifest, encoding="utf-8")
+        cleanup.append(tmp_dir)
+        return path, cleanup
+    from mas.lab.controller.manifest_layout import layout_for
+    from mas.lab.controller.scope_catalog import get_scope_catalog
+
+    try:
+        scope = get_scope_catalog(store).get(req.scope)
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail=f"scope {req.scope!r} not found") from exc
+    located = layout_for(req.kind).locate(scope, req.item)
+    if located is None or not located.manifest_path.is_file():
+        raise HTTPException(status_code=404, detail=f"{req.kind} {req.item!r} not found")
+    return located.manifest_path, cleanup
+
+
+def _command_for_run(req: StartRunRequest, store, *, cwd: Path) -> tuple[list[str], list[Path]]:
+    """Build the mas-ctl / mas-lab argv for a started run."""
+    action = (req.action or "run").lower()
+    if action in {"analyze", "export"} and ("/" in req.item or "\\" in req.item or ".." in req.item):
+        raise HTTPException(status_code=400, detail="item must be an id, not a path")
+    if action == "analyze":
+        return ["mas-lab", "benchmark", "analyze", req.item], []
+    if action == "import":
+        from mas.lab.controller.uploads import get_upload_store
+
+        uploaded = get_upload_store().get(req.item)
+        if uploaded is None:
+            raise HTTPException(status_code=404, detail=f"upload {req.item!r} not found")
+        return ["mas-lab", "benchmark", "import", str(uploaded.path)], []
+    if action == "export":
+        out_dir = cwd / "output"
+        out_dir.mkdir(parents=True, exist_ok=True)
+        out_path = out_dir / f"{Path(req.item).name}.tar.gz"
+        return ["mas-lab", "benchmark", "export", req.item, "--output", str(out_path)], []
+    path, cleanup = _item_path(req, store)
+    if req.kind == "experiment":
+        return ["mas-lab", "benchmark", "run", str(path)], cleanup
+    if req.kind == "pipeline":
+        return ["mas-lab", "benchmark", "pipeline", "run", str(path)], cleanup
+    cmd = ["mas-ctl", "run-mas", str(path)]
+    if req.query:
+        cmd.extend(["-q", req.query])
+    for overlay in req.overlays:
+        cmd.extend(["--overlay", overlay])
+    return cmd, cleanup
+
+
+def _apply_job_to_run(run, job, *, cwd: Path | None = None) -> None:
+    status = job.status.value if hasattr(job.status, "value") else str(job.status)
+    run.status = {
+        "pending": "pending",
+        "running": "running",
+        "completed": "completed",
+        "failed": "failed",
+        "cancelled": "failed",
+        "timeout": "failed",
+        "interrupted": "interrupted",
+    }.get(status, status)
+    run.exit_code = job.exit_code
+    if job.started_at:
+        run.started_at = job.started_at
+    run.finished_at = job.finished_at
+    seen = set(run.log_lines)
+    for chunk in (job.stdout, job.stderr, job.error):
+        text = (chunk or "").rstrip()
+        if text and text not in seen:
+            run.log_lines.append(text)
+            seen.add(text)
+    if run.status not in {"pending", "running"}:
+        _attach_artifacts(run, cwd)
+
+
+def _attach_artifacts(run, cwd: Path | None) -> None:
+    registry = get_artifact_registry()
+    if registry.for_run(run.id):
+        return
+    root = None
+    if run.result_dir:
+        candidate = Path(run.result_dir)
+        if candidate.is_dir():
+            root = candidate
+    if root is None and cwd is not None:
+        for name in ("output", "results"):
+            candidate = cwd / name
+            if candidate.is_dir():
+                root = candidate
+                break
+    if root is None:
+        return
+    registry.register_tree(run.id, root)
+    run.result_dir = str(root)
+
+
+async def _follow_job(run_id: str, job_id: str, cwd: Path) -> None:
+    from mas.lab.controller import jobs as jobs_mod
+
+    store = get_run_store()
+    while True:
+        job = jobs_mod.get_job(job_id)
+        run = store.get(run_id)
+        if run is None or job is None:
+            return
+        _apply_job_to_run(run, job, cwd=cwd)
+        store.save(run)
+        if job.status in jobs_mod.TERMINAL_STATUSES:
+            return
+        await asyncio.sleep(0.2)
+
+
+def _lookup_run(run_id: str):
+    store = get_run_store()
+    return store.get(run_id) or next((row for row in store.list() if row.job_id == run_id), None)
+
+
+def _cwd_for(scope_id: str, store) -> Path:
+    from mas.lab.controller.scope_catalog import get_scope_catalog
+
+    try:
+        return get_scope_catalog(store).get(scope_id).root
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail=f"scope {scope_id!r} not found") from exc
+
+
+def _adopt_labs_dir_runs(store) -> None:
+    """Expose ``paths.labs_dir`` / XDG experiment trees as completed runs.
+
+    ``mas-lab benchmark import`` and ``task fetch-results`` land here, not in
+    the controller run store. The experiment page lists runs by ``item``
+    name, so a matching folder becomes a result tree the UI can open.
+    """
+    try:
+        from mas.lab.paths import labs_root
+
+        root = labs_root()
+    except Exception:
+        return
+    if not root.is_dir():
+        return
+    from mas.lab.controller.manifest_layout import layout_for
+    from mas.lab.controller.scope_catalog import get_scope_catalog
+
+    try:
+        layout = layout_for("experiment")
+        catalog = get_scope_catalog(store)
+    except Exception:
+        return
+    runs = get_run_store()
+    known: set[tuple[str, str, str]] = set()
+    for row in runs.list():
+        if not row.result_dir:
+            continue
+        try:
+            known.add((row.scope, row.item, str(Path(row.result_dir).resolve())))
+        except OSError:
+            continue
+    for scope in catalog.all():
+        try:
+            located = layout.list_located(scope)
+        except Exception:
+            continue
+        for item in located:
+            out = root / item.item_id
+            if not out.is_dir():
+                continue
+            try:
+                resolved = str(out.resolve())
+            except OSError:
+                continue
+            if (scope.id, item.item_id, resolved) in known:
+                continue
+            run = new_run(
+                scope=scope.id,
+                kind="experiment",
+                item=item.item_id,
+                request_summary={"source": "labs_dir", "action": "import"},
+            )
+            run.id = f"labsdir-{scope.id.replace(':', '-')}-{item.item_id}"
+            run.status = "completed"
+            run.result_dir = resolved
+            runs.save(run)
+            _attach_artifacts(run, out)
+            runs.save(run)
+            known.add((scope.id, item.item_id, resolved))
+
+
+def _sync_runs(store) -> None:
+    run_bridge.sync_workers(store)
+    _adopt_labs_dir_runs(store)
+
+
+@router.get("/api/runs", tags=["Runs"])
+async def list_runs(request: Request):
+    _sync_runs(store_from_request(request))
+    return {"runs": [r.to_public() for r in get_run_store().list()]}
+
+
+@router.get("/api/runs/{run_id}", tags=["Runs"])
+async def get_run(run_id: str, request: Request):
+    _sync_runs(store_from_request(request))
+    run = _lookup_run(run_id)
+    if run is None:
+        raise HTTPException(status_code=404, detail=f"run {run_id} not found")
+    run_bridge.refresh_run(run)
+    get_run_store().save(run)
+    return run.to_public()
+
+
+@router.get("/api/runs/{run_id}/events", tags=["Runs"])
+async def run_events(run_id: str, request: Request):
+    _sync_runs(store_from_request(request))
+    run = _lookup_run(run_id)
+    if run is None:
+        raise HTTPException(status_code=404, detail=f"run {run_id} not found")
+    tracked_id = run.id
+
+    async def gen():
+        last = 0
+        while True:
+            current = get_run_store().get(tracked_id)
+            if current is None:
+                break
+            run_bridge.refresh_run(current)
+            get_run_store().save(current)
+            lines = current.log_lines[last:]
+            for line in lines:
+                yield f"event: log\ndata: {json.dumps({'line': line})}\n\n"
+            last += len(lines)
+            yield f"event: status\ndata: {json.dumps({'status': current.status})}\n\n"
+            if current.status not in {"pending", "running"}:
+                yield f"event: done\ndata: {json.dumps({'status': current.status})}\n\n"
+                break
+            import asyncio
+
+            await asyncio.sleep(0.2)
+
+    return StreamingResponse(gen(), media_type="text/event-stream")
+
+
+@router.get("/api/runs/{run_id}/artifacts", tags=["Runs"])
+async def run_artifacts(run_id: str, request: Request):
+    _sync_runs(store_from_request(request))
+    run = _lookup_run(run_id)
+    if run is None:
+        raise HTTPException(status_code=404, detail=f"run {run_id} not found")
+    arts = get_artifact_registry().for_run(run.id)
+    if not arts:
+        cwd = None
+        try:
+            cwd = _cwd_for(run.scope, None)
+        except HTTPException:
+            cwd = Path(run.result_dir) if run.result_dir else None
+        _attach_artifacts(run, cwd)
+        get_run_store().save(run)
+        arts = get_artifact_registry().for_run(run.id)
+    return {"artifacts": [a.public_dict() for a in arts]}
+
+
+@router.delete("/api/runs/{run_id}", tags=["Runs"])
+async def delete_run(run_id: str):
+    store = get_run_store()
+    run = _lookup_run(run_id)
+    if run is None:
+        raise HTTPException(status_code=404, detail=f"run {run_id} not found")
+    if run.job_id:
+        run_bridge.forget_worker(run.job_id)
+    get_artifact_registry().drop_run(run.id)
+    store.delete(run.id)
+    return {"ok": True}