chemunited-workflow 0.0.1__tar.gz

chemunited_workflow-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Automated Chemistry @ Max Plank Institute of Colloids and Interfaces
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

chemunited_workflow-0.0.1/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.4
+Name: chemunited-workflow
+Version: 0.0.1
+Summary: Conditional NetworkX-based workflow execution with loopbacks and parallel branches.
+License: MIT License
+        
+        Copyright (c) 2026 Automated Chemistry @ Max Plank Institute of Colloids and Interfaces
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Requires-Python: >=3.11
+License-File: LICENSE
+Requires-Dist: networkx>=3.2
+Requires-Dist: pydantic>=2.0
+Requires-Dist: loguru>=0.7
+Requires-Dist: rich>=13.0
+Requires-Dist: requests>=2.31
+Requires-Dist: fastapi!=0.136.3,>=0.111
+Requires-Dist: starlette>=1.0.1
+Requires-Dist: mcp[cli]>=1.0
+Requires-Dist: click>=8.1
+Requires-Dist: pint>=0.23
+Requires-Dist: pydantic-pint>=0.2
+Provides-Extra: server
+Requires-Dist: uvicorn>=0.29; extra == "server"
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pytest-mock>=3.12; extra == "test"
+Requires-Dist: responses>=0.25; extra == "test"
+Requires-Dist: httpx>=0.27; extra == "test"
+Dynamic: license-file

chemunited_workflow-0.0.1/README.md

@@ -0,0 +1,388 @@
+# chemunited-workflow
+
+A NetworkX-based workflow execution engine for conditional automation of chemistry experiments. Designed for hardware-in-the-loop laboratory protocols where operations depend on device responses, physical measurements, and branching conditions.
+
+## Features
+
+- **Conditional DAG execution** with loopbacks and parallel branches
+- **Device-centric HTTP clients** for hardware control (pipettes, reactors, pumps, etc.)
+- **Thread-safe parallel node execution** via `ThreadPoolExecutor`
+- **Physical unit handling** (volumes, temperatures, concentrations) using Pint
+- **Multiple deployment modes**: FastAPI REST API, MCP server, or direct Python execution
+- **Protocol versioning** with snapshot persistence and schema validation
+
+## Requirements
+
+- Python >= 3.11
+
+## Installation
+
+```bash
+git clone https://github.com/automatedchemistry/chemunited-workflow.git
+cd chemunited-workflow
+
+python -m venv .venv
+source .venv/bin/activate  # Windows: .venv\Scripts\activate
+
+# Core package
+pip install -e .
+
+# With API and MCP server support
+pip install -e ".[server]"
+
+# With test dependencies
+pip install -e ".[test]"
+```
+
+## Quick Start
+
+### 1. Define a workflow
+
+```python
+from chemunited_workflow import Process, Platform
+import networkx as nx
+from pydantic import BaseModel
+
+class MyConfig(BaseModel):
+    volume_ul: float
+    temperature_c: float
+
+class MyWorkflow(Process[MyConfig]):
+    def build_workflow(self) -> nx.DiGraph:
+        G = nx.DiGraph()
+        G.add_node("dispense",  method="dispense_step")
+        G.add_node("heat",      method="heat_step")
+        G.add_node("verify",    method="verify_step")
+        G.add_edge("dispense",  "heat",   condition=True)
+        G.add_edge("heat",      "verify", condition=True)
+        return G
+
+    def dispense_step(self, ctx):
+        client = self.platform["pump_01"]
+        r = client.post("dispense", json={"volume": self.config.volume_ul})
+        return r.status_code == 200
+
+    def heat_step(self, ctx):
+        client = self.platform["reactor_01"]
+        r = client.post("set_temp", json={"temp": self.config.temperature_c})
+        return r.status_code == 200
+
+    def verify_step(self, ctx):
+        client = self.platform["reactor_01"]
+        r = client.get("status")
+        return r.json()["ready"]
+```
+
+### 2. Configure device connectivity
+
+Create `connectivity/associations.json`:
+
+```json
+{
+  "server_url": "http://192.168.1.10",
+  "associations": [
+    { "component": "pump_01",    "component_url": "devices/pump_01" },
+    { "component": "reactor_01", "component_url": "devices/reactor_01" }
+  ]
+}
+```
+
+### 3. Run the workflow
+
+```python
+from pathlib import Path
+
+platform = Platform.from_project_dir(Path("my_project"))
+config = MyConfig(volume_ul=500, temperature_c=60.0)
+workflow = MyWorkflow(config, platform)
+result = workflow.run_workflow(start_node="dispense")
+print(result)
+```
+
+## Project Structure
+
+A typical project using this library looks like:
+
+```
+my_project/
+├── protocols/
+│   ├── __init__.py              # PROCESSES and CONFIGS dicts
+│   ├── main_parameters.py       # MainParameter Pydantic model
+│   └── my_workflow.py           # Process subclasses (also readable via read_process)
+├── connectivity/
+│   └── associations.json        # Device URL mapping
+├── protocols_hystoric/          # Versioned protocol snapshots
+└── log/                         # Execution logs
+    └── archive/                 # Archived logs (populated by archive_log)
+```
+
+`protocols/__init__.py` must export:
+
+```python
+from .my_workflow import MyWorkflow, MyConfig
+
+PROCESSES = {"my_workflow": MyWorkflow}
+CONFIGS   = {"my_workflow": MyConfig}
+```
+
+## Deployment Modes
+
+### FastAPI server
+
+The FastAPI server is project-agnostic. You can start it without a project and load one at runtime, or pass a project directory as a shortcut to pre-load it at startup.
+
+```bash
+# Start without a project — load one via PUT /project after startup
+chemunited-workflow --fastapi --port 3116
+
+# Start with a project pre-loaded (shortcut)
+chemunited-workflow my_project --fastapi --port 3116
+
+# Development with auto-reload
+chemunited-workflow --fastapi --reload
+```
+
+To load or switch projects at runtime:
+
+```bash
+curl -X PUT http://127.0.0.1:3116/project/ \
+  -H "Content-Type: application/json" \
+  -d '{"project_dir": "/absolute/path/to/my_project"}'
+```
+
+> **Windows paths:** Use forward slashes (`C:/Users/...`) or escaped backslashes (`C:\\Users\\...`) in JSON — bare backslashes are not valid JSON.
+
+You can switch to a different project at any time, as long as no run is currently active.
+
+### MCP server
+
+The MCP server is project-agnostic. It starts without a project and the LLM loads one at runtime by calling the `load_project` tool.
+
+```bash
+# MCP server over stdio — expose workflows as tools to Claude or other agents
+chemunited-workflow --mcp
+
+# MCP server over streamable HTTP, exposed at http://127.0.0.1:3117/mcp
+chemunited-workflow --mcp-http --port 3117
+```
+
+### MCP stdio
+
+The MCP server runs over **stdio** by default. It does not expose an HTTP
+address in this mode. Instead, the LLM client starts the server command and
+communicates through the process stdin/stdout streams:
+
+```json
+{
+  "mcpServers": {
+    "chemunited-workflow": {
+      "command": "chemunited-workflow",
+      "args": ["--mcp"]
+    }
+  }
+}
+```
+
+If you want to pin to a specific virtual environment, point `command` at that
+environment's script:
+
+```json
+{
+  "mcpServers": {
+    "chemunited-workflow": {
+      "command": "/absolute/path/to/.venv/bin/chemunited-workflow",
+      "args": ["--mcp"]
+    }
+  }
+}
+```
+
+On Windows, assuming this repository is checked out at `D:\Projects\chemunited-workflow`:
+
+```json
+{
+  "mcpServers": {
+    "chemunited-workflow": {
+      "command": "D:\\Projects\\chemunited-workflow\\.venv\\Scripts\\chemunited-workflow.exe",
+      "args": ["--mcp"]
+    }
+  }
+}
+```
+
+### MCP HTTP
+
+Use streamable HTTP when your MCP client asks for a URL or when you want the
+server to run independently of the LLM client process:
+
+```bash
+chemunited-workflow --mcp-http --host 127.0.0.1 --port 3117
+```
+
+The MCP HTTP address is:
+
+```text
+http://127.0.0.1:3117/mcp
+```
+
+On Windows:
+
+```bash
+.venv\Scripts\chemunited-workflow.exe --mcp-http --port 3117
+```
+
+Use `--mcp-path` to change the endpoint path:
+
+```bash
+chemunited-workflow --mcp-http --port 3117 --mcp-path /chemunited-mcp
+```
+
+Then the address becomes `http://127.0.0.1:3117/chemunited-mcp`.
+
+MCP HTTP is separate from the FastAPI REST API. FastAPI uses
+`http://127.0.0.1:3116/docs`; MCP HTTP uses the MCP endpoint path, such as
+`http://127.0.0.1:3117/mcp`.
+
+> **Note:** Once connected, ask the LLM to call `load_project` with the path to
+> your project directory. All other tools return an error until a project is loaded.
+
+## API Overview
+
+When running in `--fastapi` mode the following endpoints are available.
+
+All endpoints except `GET /project/` return HTTP `503` if no project has been loaded yet.
+
+### Project management
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/project/` | Return the currently loaded project directory, or `null` if none is loaded. Always returns `200` — use this as a readiness probe. |
+| `PUT` | `/project/` | Load or switch the active project. Body: `{"project_dir": "/path/to/project"}`. Returns `409` if a run is currently active. |
+
+### Processes
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/processes/` | List available workflow processes |
+| `GET` | `/processes/{name}/schema` | JSON schema for a process config |
+| `GET` | `/processes/{name}/source` | Full source code of a process file |
+
+### Snapshots
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/snapshots/` | List saved protocol snapshots |
+| `GET` | `/snapshots/{filename}` | Read a snapshot by filename |
+| `POST` | `/snapshots/` | Save a new versioned snapshot |
+| `DELETE` | `/snapshots/{filename}` | Permanently delete a snapshot |
+
+### Run control
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/run/` | Start a workflow run from a snapshot. Body: `{"snapshot": "<snapshot filename>", "dry_run": false}`. `snapshot` is required; `dry_run` defaults to `false`. Returns HTTP `202` with a `run_id`. |
+| `GET` | `/run/active` | Return the active run id as `{"run_id": "<id>"}` or `{"run_id": null}` |
+| `GET` | `/run/{run_id}/status` | Poll run state and events. Events are cleared after each read; terminal states are `finished`, `failed`, and `cancelled`. |
+| `GET` | `/run/{run_id}/report` | Full execution report for a finished run |
+| `DELETE` | `/run/{run_id}` | Cancel an active run |
+| `GET` | `/run/{run_id}/stream` | Stream workflow events for a run |
+| `GET` | `/run/pool` | Drain pending device commands and delete their pool files; returns an empty list when no commands are pending |
+
+Example `POST /run/` request:
+
+```json
+{
+  "snapshot": "snapshot_20250101T120000.json",
+  "dry_run": false
+}
+```
+
+Use `dry_run: true` to simulate device calls. The workflow graph and node logic still run, but physical HTTP calls are suppressed.
+
+`POST /run/` accepts `timeout_commands` in the JSON body. Use values such as
+`"5 s"` or `"2 min"` to control feedback polling timeout; omit it for the
+default `"10 s"`, or pass `""` to poll without a timeout.
+
+### Logs
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/logs/` | List log file metadata, sorted most recent first |
+| `GET` | `/logs/search?query=...&max_results=50` | Search all active log files for matching lines, case-insensitive |
+| `GET` | `/logs/{filename}?tail=N` | Read a log file. `tail` is optional and returns only the last `N` lines. |
+| `POST` | `/logs/{filename}/archive` | Move a log to `log/archive/` |
+
+### Components
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/components/` | Return the full `associations.json` map |
+| `GET` | `/components/ping?timeout=2.0` | Check reachability of every device URL |
+
+Visit `/docs` for the interactive Swagger UI.
+
+## MCP Tools
+
+When running in `--mcp` or `--mcp-http` mode, the following tools are exposed to the connected LLM agent:
+
+| Tool | Description |
+|------|-------------|
+| `load_project` | Load or switch the active project by directory path. Rejected if a run is active. |
+| `get_project` | Return the currently loaded project path, or null if none is loaded. |
+| `list_processes` | Discover available process names and schemas |
+| `get_process_schema` | Full parameter schema for a named process |
+| `read_process` | Source code of a process definition file |
+| `list_snapshots` | List snapshots in `protocols_hystoric/` |
+| `get_snapshot` | Read a snapshot's full JSON content |
+| `create_snapshot` | Validate and save a new versioned snapshot |
+| `delete_snapshot` | Permanently delete a snapshot |
+| `start_run` | Execute a snapshot; returns a `run_id` |
+| `get_run_status` | Poll run state and events |
+| `get_run_report` | Full per-step execution report |
+| `cancel_run` | Cancel an active run |
+| `get_components` | Return the device connectivity map |
+| `ping_components` | Check reachability of all device URLs |
+| `list_logs` | List log files |
+| `read_log` | Read a log file's text content |
+| `search_logs` | Search log files for a query string |
+| `archive_log` | Move a log file to `log/archive/` |
+
+## How Execution Works
+
+1. **Graph definition** — `build_workflow()` returns a `networkx.DiGraph` where each node has a `method` attribute pointing to a method on the `Process` class, and edges carry boolean `condition` values.
+2. **Compilation** — `compile_workflow()` validates the graph, extracts loopback edges (cycles), and ensures the remaining graph is a DAG.
+3. **Execution** — `WorkflowExecutor` traverses the compiled graph using a `ThreadPoolExecutor`: nodes whose predecessors have all completed are scheduled concurrently; edge conditions are evaluated to route execution; loopbacks are triggered when a node returns `True` to repeat a section.
+4. **Events** — The executor emits `WorkflowExecutionEvent` objects for each state transition, consumed by the API to provide real-time status and log streaming.
+5. **Result** — A `WorkflowResult` is returned with the final state, per-node results, runtime, and any errors.
+
+## Physical Units
+
+Use `ChemUnitQuantity` for values that carry SI units:
+
+```python
+from chemunited_workflow import ChemUnitQuantity
+
+volume = ChemUnitQuantity.parse("500 ul")
+double = volume * 2          # 1000 ul
+in_ml  = volume.to("ml")     # 0.5 ml
+```
+
+Units are validated and propagated through arithmetic. `ChemQuantityValidator` integrates with Pydantic models.
+
+## Dry-Run Mode
+
+Pass `dry_run=True` to `Platform` to suppress all HTTP calls — useful for testing graph logic without hardware:
+
+```python
+platform = Platform.from_connectivity(path, dry_run=True)
+```
+
+## Running Tests
+
+```bash
+pytest tests/
+```
+
+## License
+
+MIT — Automated Chemistry, Max Planck Institute for Colloids and Interfaces.

chemunited_workflow-0.0.1/chemunited_workflow/__init__.py

@@ -0,0 +1,46 @@
+"""Public API for the workflow package."""
+
+from .clients import BaseClient, ComponentClient
+from .compiler import compile_workflow
+from .enums import NodeState, WorkflowEventType
+from .exceptions import ConcurrentClientAccessError
+from .executor import WorkflowExecutor
+from .models import (
+    LoopBackSpec,
+    NodeConfig,
+    NodeExecutionContext,
+    NodeRuntime,
+    WorkflowEdgeSpec,
+    WorkflowExecutionEvent,
+    WorkflowNodeSpec,
+    WorkflowResult,
+)
+from .platform import Platform
+from .process import Process
+from .quantity import ChemUnitQuantity, ChemQuantityValidator
+from .terminal import WorkflowLogger, configure_terminal_logging, create_run_log_path
+
+__all__ = [
+    "Process",
+    "Platform",
+    "BaseClient",
+    "ComponentClient",
+    "ConcurrentClientAccessError",
+    "WorkflowExecutor",
+    "compile_workflow",
+    "NodeConfig",
+    "WorkflowNodeSpec",
+    "WorkflowEdgeSpec",
+    "LoopBackSpec",
+    "NodeRuntime",
+    "NodeExecutionContext",
+    "WorkflowResult",
+    "NodeState",
+    "WorkflowEventType",
+    "WorkflowExecutionEvent",
+    "WorkflowLogger",
+    "configure_terminal_logging",
+    "create_run_log_path",
+    "ChemUnitQuantity",
+    "ChemQuantityValidator",
+]

chemunited_workflow-0.0.1/chemunited_workflow/api/__init__.py

@@ -0,0 +1,41 @@
+"""chemunited_workflow.api — FastAPI application factory."""
+
+from fastapi import FastAPI
+from fastapi.responses import RedirectResponse
+
+from .dependencies import get_project_holder
+from .project_holder import ProjectHolder
+from .routers.components import router as components_router
+from .routers.logs import router as logs_router
+from .routers.processes import router as processes_router
+from .routers.project import router as project_router
+from .routers.runner import router as runner_router
+from .routers.snapshots import read_router as snapshots_read_router
+from .routers.snapshots import write_router as snapshots_write_router
+
+
+def create_api() -> FastAPI:
+    """Create and return a configured FastAPI application.
+
+    The server starts with no project loaded. Use ``PUT /project`` to load a
+    project directory at runtime.
+    """
+    holder = ProjectHolder()
+
+    app = FastAPI(title="chemunited API")
+
+    @app.get("/", include_in_schema=False)
+    async def root():
+        return RedirectResponse(url="/docs")
+
+    app.dependency_overrides[get_project_holder] = lambda: holder
+
+    app.include_router(project_router)
+    app.include_router(processes_router)
+    app.include_router(snapshots_read_router)
+    app.include_router(snapshots_write_router)
+    app.include_router(runner_router)
+    app.include_router(components_router)
+    app.include_router(logs_router)
+
+    return app

chemunited_workflow-0.0.1/chemunited_workflow/api/dependencies.py

@@ -0,0 +1,35 @@
+"""FastAPI dependency functions for the chemunited API."""
+
+from __future__ import annotations
+
+from fastapi import Depends, HTTPException
+
+from .project_holder import ProjectHolder
+from .services.protocol import ProtocolService
+from .services.runner import RunnerService
+
+_NO_PROJECT_MSG = (
+    "No project loaded. Use PUT /project to load a project directory first."
+)
+
+
+def get_project_holder() -> ProjectHolder:
+    raise NotImplementedError("Dependency not wired — was create_api() called?")
+
+
+def get_protocol_service(
+    holder: ProjectHolder = Depends(get_project_holder),
+) -> ProtocolService:
+    svc = holder.protocol_service
+    if svc is None:
+        raise HTTPException(status_code=503, detail=_NO_PROJECT_MSG)
+    return svc
+
+
+def get_runner_service(
+    holder: ProjectHolder = Depends(get_project_holder),
+) -> RunnerService:
+    svc = holder.runner_service
+    if svc is None:
+        raise HTTPException(status_code=503, detail=_NO_PROJECT_MSG)
+    return svc

chemunited_workflow-0.0.1/chemunited_workflow/api/project_holder.py

@@ -0,0 +1,80 @@
+"""ProjectHolder — manages the optional active project and its services."""
+
+from __future__ import annotations
+
+import threading
+from pathlib import Path
+
+from chemunited_workflow.project_loader import ProjectModules
+
+from .run_store import RunStore
+from .services.protocol import ProtocolService
+from .services.runner import RunnerService
+
+
+class ProjectHolder:
+    """Thread-safe holder for the currently active project's service instances.
+
+    The ``RunStore`` is created once at construction and persists across project
+    switches so that in-flight run history is not lost.
+    """
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._run_store = RunStore()
+        self._project_dir: Path | None = None
+        self._protocol_service: ProtocolService | None = None
+        self._runner_service: RunnerService | None = None
+
+    # ── Read accessors ────────────────────────────────────────────────────────
+
+    @property
+    def project_dir(self) -> Path | None:
+        with self._lock:
+            return self._project_dir
+
+    @property
+    def protocol_service(self) -> ProtocolService | None:
+        with self._lock:
+            return self._protocol_service
+
+    @property
+    def runner_service(self) -> RunnerService | None:
+        with self._lock:
+            return self._runner_service
+
+    @property
+    def run_store(self) -> RunStore:
+        return self._run_store
+
+    def is_loaded(self) -> bool:
+        with self._lock:
+            return self._project_dir is not None
+
+    def active_run_id(self) -> str | None:
+        return self._run_store.active_run_id
+
+    # ── Mutation ──────────────────────────────────────────────────────────────
+
+    def load(self, modules: ProjectModules) -> None:
+        """Replace the active project.
+
+        Builds fresh ``ProtocolService`` and ``RunnerService`` instances (reusing
+        the same ``RunStore``), then swaps them under the lock.
+        """
+        new_protocol = ProtocolService(
+            project_dir=modules.project_dir,
+            processes=modules.processes,
+            configs=modules.configs,
+            main_parameter_class=modules.main_parameter_class,
+        )
+        new_runner = RunnerService(
+            project_dir=modules.project_dir,
+            processes=modules.processes,
+            configs=modules.configs,
+            run_store=self._run_store,
+        )
+        with self._lock:
+            self._project_dir = modules.project_dir
+            self._protocol_service = new_protocol
+            self._runner_service = new_runner

chemunited_workflow-0.0.1/chemunited_workflow/api/routers/components.py

@@ -0,0 +1,30 @@
+"""Routes: GET /components."""
+
+from fastapi import APIRouter, Depends
+
+from ..dependencies import get_protocol_service
+from ..schemas import ComponentStatus
+from ..services.protocol import ProtocolService
+
+router = APIRouter(prefix="/components", tags=["components"])
+
+
+@router.get("/ping", response_model=list[ComponentStatus])
+async def ping_components(
+    timeout: float = 2.0,
+    svc: ProtocolService = Depends(get_protocol_service),
+):
+    """Verify that all device URLs in ``associations.json`` are reachable."""
+    return svc.ping_components(timeout=timeout)
+
+
+@router.get("/")
+async def get_components(svc: ProtocolService = Depends(get_protocol_service)):
+    """Return the device connectivity map.
+
+    Returns the full contents of `connectivity/associations.json` — the
+    mapping of component names to their device-server URLs. Entries with an
+    empty `component_url` are included as-is; they represent devices that are
+    physically present but not yet wired to a server endpoint.
+    """
+    return svc.read_components()