mas-lab-component-controller 0.2.0__tar.gz

mas_lab_component_controller-0.2.0/.coveragerc

@@ -0,0 +1,7 @@
+[run]
+source = mas.lab.controller.fastapi_app
+omit =
+
+[report]
+show_missing = true
+skip_empty = true

mas_lab_component_controller-0.2.0/.gitignore

@@ -0,0 +1,86 @@
+*.pyc
+__pycache__/
+*.egg-info/
+.DS_Store
+dist/
+build/
+.venv/
+.demo-ui/
+.demo-ui-mock/
+.env
+.env.local
+.env.*.local
+config.yaml
+!lab/src/mas/lab/templates/**/config.yaml
+!docs/tutorials/**/config.yaml
+!labs/**/config.yaml
+!library-samples/sample-workspace/config.yaml
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.test-venv/
+node_modules/
+*.log
+docs/tutorials/**/logs/
+.hypothesis/
+compliance-report.json
+COMPLIANCE_REPORT.md
+compliance/results/
+
+# MkDocs build output
+site/
+
+.vscode/
+.cursor/
+.claude/
+
+# Test / coverage artifacts
+.coverage
+coverage.xml
+coverage.json
+**/coverage.json
+
+# LaTeX build artifacts
+*.fdb_latexmk
+*.fls
+*.aux
+*.out
+*.toc
+*.synctex.gz
+
+# Run output / artifacts
+**/output/*.jsonl
+**/output/benchmark
+**/output/meta.json
+**/output/current_run_id.txt
+**/output/*/
+.tutorial-cache/
+tests/.tutorial-engine-cache/
+.demo-cache/
+# Local mas-ctl chat traces next to an agent (fixtures live under fixtures/ or T01 traces/)
+docs/tutorials/**/agents/**/traces/
+
+# Backup files
+*.bak
+*.bak2
+
+# Legacy dead code (removed from repo)
+lab/src/mas/lab/_cli_legacy.py
+.deepeval/
+~/.mas/
+
+
+# Docker local secrets + data (never commit)
+docker/.env
+docker/data/*
+!docker/data/.gitkeep
+
+# Local protocol compliance checkouts and reports
+compliance/vendor/
+
+# Local harness playbooks (not published)
+AGENTS.md
+# .agents/
+COVERAGE_REPORT.md
+MANIFEST_SCHEMA_MAPPING.md
+.lycheecache

mas_lab_component_controller-0.2.0/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.5
+Name: mas-lab-component-controller
+Version: 0.2.0
+Summary: MAS Lab controller daemon — workers, IPC, HTTP API for CLI and UI.
+License: Apache-2.0
+Requires-Python: >=3.11
+Requires-Dist: click>=8.0
+Requires-Dist: fastapi>=0.110
+Requires-Dist: mas-lab-component-bench
+Requires-Dist: mas-lab-component-core
+Requires-Dist: mas-lab-ctl
+Requires-Dist: mas-lab-runtime
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: uvicorn[standard]>=0.27
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0; extra == 'dev'
+Requires-Dist: pytest>=9.0; extra == 'dev'

mas_lab_component_controller-0.2.0/README.md

@@ -0,0 +1,190 @@
+<!--
+  Copyright (c) 2026 Cisco Systems, Inc. and its affiliates
+  SPDX-License-Identifier: Apache-2.0
+-->
+# lab/components/controller
+
+`lab/components/controller` is the control plane for MAS Lab experiments. It runs long-lived work (benchmarks, agent runs, pipelines) in background workers, exposes a REST API for the web UI, and provides Unix-socket inter-process communication (IPC) for the CLI.
+
+Use it when you start experiments through `mas-lab benchmark run` or the `ui/` web app; both talk to this daemon.
+
+```bash
+mas-lab serve    # foreground controller; HTTP API on http://localhost:8090
+```
+
+## Overview
+
+| Piece | Role |
+|-------|------|
+| **Daemon** | Long-lived process: worker registry, HTTP server, Unix socket IPC |
+| **Workers** | `benchmark`, `application`, `pipeline` jobs with captured stdout/stderr |
+| **HTTP API** | FastAPI on port 9000 — libraries, CRUD, job submit/poll |
+| **ManifestStore** | Reads/writes lab library YAML (experiments, pipelines, overlays, …) |
+| **ControllerClient** | CLI helper: auto-start daemon, submit jobs, poll workers |
+
+The CLI and UI share one job model: submit, receive a `job_id` / `worker_id`, then poll until the state is `completed`, `failed` or `cancelled`. Polling uses REST.
+
+
+## Installation
+
+```bash
+# Full stack (meta-package)
+uv pip install mas-lab
+
+# Lab components only
+uv pip install -e ./lab/components/core \
+               -e ./lab/components/bench \
+               -e ./lab/components/controller
+```
+
+---
+
+## Quick start
+
+### 1. Start the controller (backend)
+
+**Foreground** (recommended for development — logs in terminal):
+
+```bash
+task install              # from repo root — installs lab/components/controller into .venv
+mas-lab serve
+# HTTP API → http://localhost:8090  (use --port to change)
+# Unix socket → $XDG_DATA_HOME/mas/controller.sock
+```
+
+**Background daemon** (default HTTP port 9000):
+
+```bash
+mas-lab control start
+mas-lab control status    # confirm running + port
+```
+
+Stop: `mas-lab control stop`
+
+### 2. Connect mas-lab-ui (frontend)
+
+In the `ui/` directory at the mas-lab repo root:
+
+```bash
+yarn install
+export VITE_API_BASE_URL=http://localhost:8090
+yarn dev
+# Open http://localhost:5173 (Vite default)
+```
+
+The UI calls `/api/libraries/*`, `/api/jobs/*`, `/api/schemas/*`, and related routes.
+Manifest schemas are served from installed packages (`mas-runtime`, `lab/components/bench`,
+`lab/components/core`) — not vendored inside the controller. Contract tests mirror the UI
+surface (`lab/components/controller/tests/test_api_calls_contract.py`).
+
+### 3. Run a benchmark via the daemon
+
+All `mas-lab benchmark run` invocations go through the controller:
+
+```bash
+# Blocking: submit + poll + stream stdout/stderr until done
+mas-lab benchmark run my-lab/experiments/smoke.yaml --dry-run
+
+# Detached: print worker id and exit
+mas-lab benchmark run my-lab/experiments/smoke.yaml --dry-run -b
+
+# Follow a detached worker
+mas-lab worker follow <worker_id>
+```
+
+---
+
+## Architecture
+
+```text
+┌─────────────┐     Unix socket      ┌──────────────────┐
+│  mas-lab    │ ───────────────────► │  Controller      │
+│  CLI        │   submit_benchmark   │  daemon          │
+│             │   get_worker (poll)  │                  │
+└─────────────┘                      │  WorkerRegistry  │
+                                     │  WorkerRunner    │
+┌─────────────┐     HTTP :9000       │  ManifestStore   │
+│  mas-lab-ui │ ───────────────────► │  FastAPI app     │
+│  (React)    │   /api/jobs/{id}     │  schema_registry │
+└─────────────┘   /api/schemas/*     └────────┬─────────┘
+     polls ──────────────────────────────────┤
+                                              ▼
+                                    benchmark / application / pipeline workers
+                                    (stdout/stderr → pollable buffers)
+```
+
+| Transport | Used by | Typical calls |
+|-----------|---------|---------------|
+| Unix socket | CLI | `submit_benchmark`, `get_worker`, `cancel_worker`, `ping` |
+| HTTP REST | UI | `POST /api/libraries/{lib}/benchmark/run`, `GET /api/jobs/{id}` |
+
+Environment variables (defaults):
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `MAS_HOME` | `$XDG_DATA_HOME/mas` | Config and socket parent dir |
+| `MAS_CONTROLLER_SOCKET` | `$XDG_DATA_HOME/mas/controller.sock` | Unix socket path |
+| `MAS_CONTROLLER_PORT` | `9000` | HTTP API port |
+
+---
+
+## CLI commands
+
+```bash
+mas-lab control start|stop|status|restart   # daemon lifecycle
+mas-lab worker list [--kind benchmark]      # list workers
+mas-lab worker show <id>                    # JSON detail
+mas-lab worker follow <id>                  # poll + stream until done
+mas-lab worker cancel <id>
+mas-lab serve                               # foreground controller + HTTP
+```
+
+Benchmark and application runs are submitted through the daemon automatically;
+see [lab/components/bench](../bench/README.md) for experiment YAML format.
+
+---
+
+## Package layout
+
+```
+components/controller/src/mas/lab/controller/
+├── daemon.py           # Main loop: socket IPC + HTTP
+├── fastapi_app.py      # REST API (mas-lab-ui contract)
+├── api.py              # ControllerAPI (libraries, workers, manifests)
+├── client.py           # ControllerClient, follow_worker, start_daemon
+├── workers.py          # Benchmark / application / pipeline workers
+├── io_capture.py       # Redirect stdout/stderr into worker records
+├── manifest_store.py   # Lab library CRUD on disk
+├── registry.py         # WorkerRegistry
+├── cli.py              # mas-lab control / worker commands
+├── schema_registry.py  # Resolve schemas from mas-runtime / bench / core packages
+└── schemas/            # Controller-local pipeline step-type registry only
+```
+
+---
+
+## Documentation
+
+### User documentation
+
+| Document | Description |
+|----------|-------------|
+| [../../docs/user-guide.md](../../docs/user-guide.md) | End-to-end MAS Lab user guide |
+| [../../docs/benchmark.md](../../docs/benchmark.md) | Benchmark quickstart and lifecycle |
+
+### Developer documentation
+
+| Document | Description |
+|----------|-------------|
+| [../../../docs/references/schemas.md](../../../docs/references/schemas.md) | Package-owned schemas, `/api/schemas`, UI vs runtime |
+| [../../../runtime/docs/dev/schemas/agent-manifest.md](../../../runtime/docs/dev/schemas/agent-manifest.md) | Runtime agent manifest reference |
+| [../../../runtime/docs/dev/schemas/mas-topology.md](../../../runtime/docs/dev/schemas/mas-topology.md) | MAS topology / workflow reference |
+| [../bench/README.md](../bench/README.md) | Experiment and post-processing pipeline YAML |
+
+### Related components
+
+| Component | README |
+|-----------|--------|
+| `lab/components/core` | [../core/README.md](../core/README.md) |
+| `lab/components/bench` | [../bench/README.md](../bench/README.md) |
+| `mas-lab-ui` | [mas-lab-ui README](https://github.com/mas-framework/mas-lab-ui) |

mas_lab_component_controller-0.2.0/pyproject.toml

@@ -0,0 +1,39 @@
+#  Copyright (c) 2026 Cisco Systems, Inc. and its affiliates
+#  SPDX-License-Identifier: Apache-2.0
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mas-lab-component-controller"
+version = "0.2.0"
+description = "MAS Lab controller daemon — workers, IPC, HTTP API for CLI and UI."
+requires-python = ">=3.11"
+license = {text = "Apache-2.0"}
+
+dependencies = [
+    "mas-lab-component-core",
+    "mas-lab-component-bench",
+    "mas-lab-runtime",
+    "mas-lab-ctl",
+    "click>=8.0",
+    "pyyaml>=6.0",
+    "fastapi>=0.110",
+    "python-multipart>=0.0.9",
+    "uvicorn[standard]>=0.27",
+    "pydantic>=2.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=9.0",
+    "pytest-asyncio",
+    "pytest-cov>=6.0",
+    "httpx>=0.27",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mas"]
+
+[project.entry-points."mas.lab.cli.components"]
+controller = "mas.lab.controller.cli:ControllerCliComponent"

mas_lab_component_controller-0.2.0/src/mas/lab/controller/__init__.py

@@ -0,0 +1,7 @@
+#  Copyright (c) 2026 Cisco Systems, Inc. and its affiliates
+#  SPDX-License-Identifier: Apache-2.0
+"""MAS Lab controller — daemon, workers, and HTTP API."""
+from mas.lab.controller.api import ControllerAPI
+from mas.lab.controller.lab_registry import LabRegistry, get_lab_registry
+
+__all__ = ["ControllerAPI", "LabRegistry", "get_lab_registry"]

mas_lab_component_controller-0.2.0/src/mas/lab/controller/__main__.py

@@ -0,0 +1,5 @@
+#  Copyright (c) 2026 Cisco Systems, Inc. and its affiliates
+#  SPDX-License-Identifier: Apache-2.0
+# Reference entry point for running the controller HTTP API directly (PR #5).
+# Prefer: mas-lab control start  or  mas-lab serve
+from mas.lab.controller.fastapi_app import app  # noqa: F401

mas_lab_component_controller-0.2.0/src/mas/lab/controller/agent_chat.py

@@ -0,0 +1,226 @@
+#  Copyright (c) 2026 Cisco Systems, Inc. and its affiliates
+#  SPDX-License-Identifier: Apache-2.0
+"""In-process agent chat for the controller UI.
+
+Runs agents via v2 ``SessionController`` (no subprocess / stdout capture) and
+returns structured interaction fields: user query in, agent response or error out.
+"""
+from __future__ import annotations
+
+import logging
+import re
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal, Optional
+
+import yaml
+
+logger = logging.getLogger(__name__)
+
+_STATUS = Literal["ok", "error"]
+
+
+@dataclass(frozen=True)
+class AgentTurnResult:
+    status: _STATUS
+    response: str = ""
+    error_message: str = ""
+    error_detail: str = ""
+    session_id: str = ""
+
+
+def format_error(raw: str) -> tuple[str, str]:
+    """Return (short_message, full_detail) from a raw agent/LLM error string."""
+    full = (raw or "").strip()
+    if not full:
+        return "Agent execution failed.", ""
+
+    short = full
+
+    msg_match = re.search(r"['\"]message['\"]\s*:\s*['\"]([^'\"]+)['\"]", full)
+    if msg_match:
+        short = msg_match.group(1)
+    elif "ExceededBudget" in full:
+        budget_match = re.search(r"(ExceededBudget:[^\n'\"]+)", full)
+        if budget_match:
+            short = budget_match.group(1).strip()
+
+    if len(short) > 240:
+        short = short[:237] + "..."
+
+    return short, full
+
+
+class _SilentDisplay:
+    """No-op conversation display for embedded UI turns."""
+
+    def on_user(self, text: str, *, turn_id: str = "") -> None:
+        return
+
+    def on_agent(self, text: str) -> None:
+        return
+
+    def on_turn_error(self, message: str, *, detail: str = "") -> None:
+        return
+
+    def on_hitl_request(self, request: object) -> None:
+        return
+
+    def on_working(self, message: str = "Agent working…") -> None:
+        return
+
+    def end_working(self) -> None:
+        return
+
+    def on_system(self, message: str) -> None:
+        return
+
+    def on_error(self, message: str) -> None:
+        return
+
+
+def _load_workspace_dotenv(base_dir: Path) -> None:
+    """Load optional .env files; container env from docker/.env still wins (override=False)."""
+    import os
+
+    try:
+        from dotenv import load_dotenv
+    except ImportError:
+        return
+
+    candidates = [
+        Path("/workspace/.env"),
+        base_dir / ".env",
+        Path(os.environ.get("MAS_WORKSPACE_ROOT", "")) / ".env",
+    ]
+    for path in candidates:
+        if path.is_file():
+            load_dotenv(path, override=False)
+
+
+def _quiet_logging_for_chat() -> None:
+    """Suppress exchange logs; UI chat must not capture CLI-style stdout."""
+    import os
+
+    from mas.ctl.logging_setup import setup_logging
+
+    os.environ.pop("LOG_LEVEL", None)
+    setup_logging(verbosity=0)
+    logging.getLogger("mas.runtime").setLevel(logging.WARNING)
+    logging.getLogger("mas.ctl").setLevel(logging.WARNING)
+
+
+def run_agent_turn(
+    manifest_yaml: str,
+    query: str,
+    *,
+    base_dir: Path,
+    flavour: Optional[str] = None,
+    session_id: Optional[str] = None,
+) -> AgentTurnResult:
+    """Execute one user → agent turn in-process via v2 SessionController."""
+    from mas.ctl.infra.resolve import resolve_infra_refs
+    from mas.ctl.runtime_cli import pattern_from_manifest
+    from mas.ctl.session.bootstrap import InstantiationOptions, instantiate_runtime
+    from mas.ctl.session.controller import ConversationConfig, SessionController
+    from mas.ctl.session.hitl_config import resolve_hitl_from_manifest
+    from mas.ctl.ui.turn_result import turn_to_agent_result
+    from mas.ctl.workspace.config import (
+        UserConfig,
+        WorkspaceConfig,
+        merge_infra_interceptors,
+        merge_infra_refs,
+    )
+
+    _quiet_logging_for_chat()
+    _load_workspace_dotenv(base_dir)
+
+    base_dir = Path(base_dir)
+    sid = session_id or f"ui:{uuid.uuid4()}"
+    prompt = (query or "").strip()
+    if not prompt:
+        return AgentTurnResult(
+            status="error",
+            error_message="No query provided.",
+            session_id=sid,
+        )
+
+    try:
+        current_manifest = yaml.safe_load(manifest_yaml)
+    except yaml.YAMLError as exc:
+        return AgentTurnResult(
+            status="error",
+            error_message=f"Invalid manifest YAML: {exc}",
+            error_detail=str(exc),
+            session_id=sid,
+        )
+
+    if not isinstance(current_manifest, dict):
+        return AgentTurnResult(
+            status="error",
+            error_message="Manifest must be a YAML mapping.",
+            session_id=sid,
+        )
+
+    try:
+        workspace = WorkspaceConfig.load(base_dir)
+        user = UserConfig.load()
+        pattern = pattern_from_manifest(current_manifest)
+        merged_infra = merge_infra_refs(
+            workspace_refs=workspace.effective_infra_refs,
+            user_refs=[user.default_infra] if user.default_infra else [],
+            cli_refs=[],
+            workspace_found=workspace.found,
+        )
+        resolved_infra = resolve_infra_refs(
+            merged_infra,
+            anchor=base_dir,
+            workspace=workspace,
+            user=user,
+            interceptors=merge_infra_interceptors(
+                workspace_interceptors=workspace.infra_interceptors,
+                cli_interceptors=[],
+            ),
+        )
+        hitl_responder, hitl_terminal = resolve_hitl_from_manifest(
+            current_manifest, session_interactive=False
+        )
+        instance, _store = instantiate_runtime(
+            InstantiationOptions(
+                pattern_plugin_id=pattern,
+                agent_manifest=current_manifest,
+                manifest_dir=base_dir,
+                resolved_infra=resolved_infra,
+                workspace=workspace,
+                validate_manifests=False,
+            ),
+            hitl=hitl_responder,
+        )
+        controller = SessionController(
+            instance=instance,
+            display=_SilentDisplay(),
+            hitl_terminal=hitl_terminal,
+            config=ConversationConfig(single_turn=True),
+            verbose=0,
+            session_id=sid,
+        )
+        turn = controller.run_turn(prompt, turn_id=sid, auto_hitl=True)
+        mapped = turn_to_agent_result(turn)
+    except Exception as exc:
+        logger.debug("Agent session failed", exc_info=True)
+        short, full = format_error(str(exc))
+        return AgentTurnResult(
+            status="error",
+            error_message=short,
+            error_detail=full,
+            session_id=sid,
+        )
+
+    return AgentTurnResult(
+        status=mapped.status,
+        response=mapped.response,
+        error_message=mapped.error_message,
+        error_detail=mapped.error_detail,
+        session_id=sid,
+    )