chemunited-workflow 0.0.1__py3-none-any.whl

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/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/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/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/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()

chemunited_workflow/api/routers/logs.py

@@ -0,0 +1,60 @@
+"""Routes: GET /logs, GET /logs/{filename}."""
+
+from fastapi import APIRouter, Depends, HTTPException
+
+from ..dependencies import get_protocol_service
+from ..schemas import LogSearchResult
+from ..services.protocol import ProtocolService
+
+router = APIRouter(prefix="/logs", tags=["logs"])
+
+
+@router.get("/")
+async def list_logs(svc: ProtocolService = Depends(get_protocol_service)):
+    """List all execution log files.
+
+    Returns metadata (filename, last-modified timestamp, size) for every
+    `.log` file in the project's `log/` directory, sorted most-recent first.
+    """
+    return svc.list_logs()
+
+
+@router.get("/search", response_model=list[LogSearchResult])
+async def search_logs(
+    query: str,
+    max_results: int = 50,
+    svc: ProtocolService = Depends(get_protocol_service),
+):
+    """Search all active log files for lines containing *query* (case-insensitive)."""
+    return svc.search_logs(query, max_results=max_results)
+
+
+@router.post("/{filename}/archive", status_code=200)
+async def archive_log(
+    filename: str,
+    svc: ProtocolService = Depends(get_protocol_service),
+):
+    """Move a log file from ``log/`` to ``log/archive/``."""
+    try:
+        archived_path = svc.archive_log(filename)
+        return {"archived": archived_path}
+    except FileNotFoundError as exc:
+        raise HTTPException(status_code=404, detail=str(exc))
+
+
+@router.get("/{filename}")
+async def read_log(
+    filename: str,
+    tail: int | None = None,
+    svc: ProtocolService = Depends(get_protocol_service),
+):
+    """Read the contents of a log file.
+
+    Returns the full text of the log. Pass `?tail=N` to return only the last
+    N lines — useful for checking recent activity without loading the entire
+    file.
+    """
+    try:
+        return {"content": svc.read_log(filename, tail=tail)}
+    except FileNotFoundError as exc:
+        raise HTTPException(status_code=404, detail=str(exc))

chemunited_workflow/api/routers/processes.py

@@ -0,0 +1,53 @@
+"""Routes: GET /processes, GET /processes/{name}/schema."""
+
+from fastapi import APIRouter, Depends, HTTPException
+
+from ..dependencies import get_protocol_service
+from ..schemas import ProcessSource
+from ..services.protocol import ProtocolService
+
+router = APIRouter(prefix="/processes", tags=["processes"])
+
+
+@router.get("/")
+async def list_processes(svc: ProtocolService = Depends(get_protocol_service)):
+    """List all registered processes.
+
+    Returns every process available in this experiment together with its
+    human-readable description and the JSON Schema of its configuration model.
+    Call this first to discover what processes can be added to a snapshot.
+    """
+    return svc.list_processes()
+
+
+@router.get("/{name}/source", response_model=ProcessSource)
+async def get_process_source(
+    name: str,
+    svc: ProtocolService = Depends(get_protocol_service),
+):
+    """Return the full source code of a process definition file."""
+    try:
+        source = svc.read_process(name)
+        return ProcessSource(name=name, source=source)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+    except FileNotFoundError as exc:
+        raise HTTPException(status_code=404, detail=str(exc))
+
+
+@router.get("/{name}/schema")
+async def get_process_schema(
+    name: str,
+    svc: ProtocolService = Depends(get_protocol_service),
+):
+    """Return the full parameter schema for a single process.
+
+    Includes the `config_schema` (process-specific parameters) and the
+    `main_parameter_schema` (experiment-level parameters shared across all
+    processes). Each field may carry `group`, `editable`, and `visible` hints
+    inside `json_schema_extra`.
+    """
+    try:
+        return svc.get_process_schema(name)
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail=str(exc))

chemunited_workflow/api/routers/project.py

@@ -0,0 +1,53 @@
+"""Routes: GET /project, PUT /project."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from fastapi import APIRouter, Depends, HTTPException
+
+from chemunited_workflow.project_loader import ProjectLoadError, load_project
+
+from ..dependencies import get_project_holder
+from ..project_holder import ProjectHolder
+from ..schemas import ProjectIn, ProjectOut
+
+router = APIRouter(prefix="/project", tags=["project"])
+
+
+@router.get("/", response_model=ProjectOut)
+async def get_project(holder: ProjectHolder = Depends(get_project_holder)):
+    """Return the currently loaded project directory, or null if none is loaded.
+
+    Always returns 200 — use this as a readiness probe.
+    """
+    pd = holder.project_dir
+    return ProjectOut(project_dir=str(pd) if pd is not None else None)
+
+
+@router.put("/", response_model=ProjectOut)
+async def put_project(
+    body: ProjectIn,
+    holder: ProjectHolder = Depends(get_project_holder),
+):
+    """Load or switch the active project.
+
+    Rejects with 409 if a run is currently active. The RunStore (and all
+    historical run records) is preserved across switches.
+    """
+    active = holder.active_run_id()
+    if active is not None:
+        raise HTTPException(
+            status_code=409,
+            detail=f"Cannot switch project while run '{active}' is active.",
+        )
+
+    project_path = Path(body.project_dir).resolve()
+
+    try:
+        modules = load_project(project_path)
+    except ProjectLoadError as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+    holder.load(modules)
+    return ProjectOut(project_dir=str(holder.project_dir))

chemunited_workflow/api/routers/runner.py

@@ -0,0 +1,196 @@
+"""Routes: POST/GET/DELETE /run."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import time
+from collections.abc import AsyncIterator
+
+from fastapi import APIRouter, Depends, HTTPException
+from fastapi.responses import StreamingResponse
+
+from ..dependencies import get_runner_service
+from ..run_store import RunState
+from ..schemas import RunRequest, RunStatus
+from ..services.runner import RunnerService
+
+router = APIRouter(prefix="/run", tags=["run"])
+STREAM_POLL_INTERVAL_SECONDS = 0.1
+STREAM_HEARTBEAT_INTERVAL_SECONDS = 5.0
+
+
+@router.post("/", status_code=202)
+async def start_run(
+    body: RunRequest,
+    svc: RunnerService = Depends(get_runner_service),
+):
+    """Start executing a protocol snapshot.
+
+    Launches execution in a background thread and returns a `run_id`
+    immediately (HTTP 202 Accepted). Pass `dry_run: true` to suppress all
+    HTTP calls to physical devices — the workflow graph and node logic run
+    normally but every device call returns a synthetic `200 OK` with an empty
+    body. `timeout_commands` controls feedback polling timeout. Use the
+    returned `run_id` to poll status or stream events.
+    """
+    run_id = svc.start(
+        body.snapshot,
+        dry_run=body.dry_run,
+        timeout_commands=body.timeout_commands,
+        error_resilient=body.error_resilient,
+    )
+    return {"run_id": run_id}
+
+
+@router.get("/active")
+async def get_active_run(svc: RunnerService = Depends(get_runner_service)):
+    """Return the run_id of the currently running execution, if any.
+
+    Returns `{"run_id": null}` when no execution is in progress.
+    """
+    return {"run_id": svc._run_store.active_run_id}
+
+
+@router.get("/{run_id}/status")
+async def get_run_status(
+    run_id: str,
+    svc: RunnerService = Depends(get_runner_service),
+):
+    """Poll the status of a run.
+
+    Returns the current state (`running`, `finished`, `failed`, or
+    `cancelled`) and all `WorkflowExecutionEvent` objects accumulated since
+    the last call. Events are cleared on each read — call repeatedly until
+    state is terminal. For a continuous feed, use the `/stream` endpoint
+    instead.
+    """
+    rec = svc._run_store.get(run_id)
+    if rec is None:
+        raise HTTPException(status_code=404, detail=f"Run '{run_id}' not found.")
+    events = svc._run_store.pop_events(run_id)
+    return RunStatus(
+        run_id=run_id,
+        state=rec.state.value,
+        events=[e.model_dump() for e in events],
+    )
+
+
+@router.get("/{run_id}/report")
+async def get_run_report(
+    run_id: str,
+    svc: RunnerService = Depends(get_runner_service),
+):
+    """Return the full execution report for a finished run.
+
+    Returns one `WorkflowResult` per process step in execution order,
+    containing node states, results, runtimes, and any errors. Returns
+    HTTP 202 if the run has not finished yet.
+    """
+    rec = svc._run_store.get(run_id)
+    if rec is None:
+        raise HTTPException(status_code=404, detail=f"Run '{run_id}' not found.")
+    if rec.state == RunState.RUNNING:
+        raise HTTPException(status_code=202, detail="Run has not finished yet.")
+    return {
+        "run_id": run_id,
+        "state": rec.state.value,
+        "results": [r.model_dump() for r in rec.results],
+    }
+
+
+@router.get("/{run_id}/stream")
+async def stream_run(
+    run_id: str,
+    svc: RunnerService = Depends(get_runner_service),
+):
+    """Stream execution events as Server-Sent Events (SSE).
+
+    Keeps the connection open while the run is active and pushes each
+    `WorkflowExecutionEvent` as it arrives. Closes with a final
+    `{"state": "finished"|"failed"|"cancelled"}` frame when the run ends.
+    For simple polling without a persistent connection, use `/status` instead.
+    """
+
+    return StreamingResponse(
+        _generate_run_stream(svc, run_id),
+        media_type="text/event-stream",
+    )
+
+
+async def _generate_run_stream(
+    svc: RunnerService,
+    run_id: str,
+    *,
+    poll_interval: float = STREAM_POLL_INTERVAL_SECONDS,
+    heartbeat_interval: float = STREAM_HEARTBEAT_INTERVAL_SECONDS,
+) -> AsyncIterator[str]:
+    rec = svc._run_store.get(run_id)
+    if rec is None:
+        yield 'data: {"error": "run not found"}\n\n'
+        return
+
+    last_sent = time.monotonic()
+    while rec.state == RunState.RUNNING:
+        sent_event = False
+        for event in svc._run_store.pop_events(run_id):
+            yield f"data: {event.model_dump_json()}\n\n"
+            sent_event = True
+
+        now = time.monotonic()
+        if sent_event:
+            last_sent = now
+        elif rec.state == RunState.RUNNING and now - last_sent >= heartbeat_interval:
+            yield ": heartbeat\n\n"
+            last_sent = now
+
+        await asyncio.sleep(poll_interval)
+
+    yield f'data: {{"state": "{rec.state.value}"}}\n\n'
+
+
+@router.get("/pool")
+async def drain_pool(svc: RunnerService = Depends(get_runner_service)):
+    """Return all pending device commands and delete their files.
+
+    Reads every ``*.jsonl`` file under ``log/pool/``, collects every line,
+    deletes the files, and returns the full list. Returns an empty list when
+    no commands have been issued since the last poll.
+
+    Poll this endpoint at a comfortable interval (e.g. every 500 ms) while a
+    run is active to display live device activity in the UI.
+    """
+    pool_dir = svc._project_dir / "log" / "pool"
+    if not pool_dir.exists():
+        return []
+
+    commands = []
+    for f in pool_dir.glob("*.jsonl"):
+        try:
+            for line in f.read_text(encoding="utf-8").splitlines():
+                line = line.strip()
+                if line:
+                    commands.append(json.loads(line))
+            f.unlink()
+        except (OSError, json.JSONDecodeError):
+            pass
+    return commands
+
+
+@router.delete("/{run_id}", status_code=204)
+async def cancel_run(
+    run_id: str,
+    svc: RunnerService = Depends(get_runner_service),
+):
+    """Cancel an active run.
+
+    Sets the run state to `cancelled`. The currently executing process step
+    will run to completion before the runner stops — this is intentional to
+    avoid leaving physical devices in an undefined state mid-operation.
+    Returns 404 if the run does not exist or is already in a terminal state.
+    """
+    if not svc._run_store.cancel(run_id):
+        raise HTTPException(
+            status_code=404,
+            detail=f"Run '{run_id}' not found or not running.",
+        )

chemunited_workflow/api/routers/snapshots.py

@@ -0,0 +1,73 @@
+"""Routes: GET/POST/DELETE /snapshots."""
+
+from fastapi import APIRouter, Depends, HTTPException
+
+from ..dependencies import get_protocol_service
+from ..schemas import SnapshotIn
+from ..services.protocol import ProtocolService
+
+read_router = APIRouter(prefix="/snapshots", tags=["snapshots"])
+write_router = APIRouter(prefix="/snapshots", tags=["snapshots"])
+
+
+@read_router.get("/")
+async def list_snapshots(svc: ProtocolService = Depends(get_protocol_service)):
+    """List all protocol snapshots.
+
+    Returns metadata (filename, last-modified timestamp, size) for every JSON
+    file in `protocols_hystoric/`, sorted most-recent first. Use the filename
+    from this list to start a run or inspect a snapshot's contents.
+    """
+    return svc.list_snapshots()
+
+
+@read_router.get("/{filename}")
+async def get_snapshot(
+    filename: str,
+    svc: ProtocolService = Depends(get_protocol_service),
+):
+    """Read a single snapshot by filename.
+
+    Returns the full JSON content of the snapshot — `main_parameter` plus one
+    key per process step in `{process_name}_{index}` format. The insertion
+    order of the process keys defines the execution sequence.
+    """
+    try:
+        return svc.read_snapshot(filename)
+    except FileNotFoundError as exc:
+        raise HTTPException(status_code=404, detail=str(exc))
+
+
+@write_router.post("/", status_code=201)
+async def create_snapshot(
+    body: SnapshotIn,
+    svc: ProtocolService = Depends(get_protocol_service),
+):
+    """Save a new protocol snapshot.
+
+    Validates all process configs and the `main_parameter` block, then writes
+    a timestamped JSON file to `protocols_hystoric/`. Every call creates a
+    **new** file — snapshots are immutable once written. Returns the generated
+    filename, e.g. `suzuki_batch_14_2026-05-15T10-38-00.json`.
+    """
+    try:
+        filename = svc.write_snapshot(body.name, body.data)
+        return {"filename": filename}
+    except (ValueError, Exception) as exc:
+        raise HTTPException(status_code=422, detail=str(exc))
+
+
+@write_router.delete("/{filename}", status_code=204)
+async def delete_snapshot(
+    filename: str,
+    svc: ProtocolService = Depends(get_protocol_service),
+):
+    """Delete a snapshot file.
+
+    Permanently removes the file from `protocols_hystoric/`. This action is
+    irreversible. Only available in builder mode (`enable_builder=True`).
+    """
+    try:
+        svc.delete_snapshot(filename)
+    except FileNotFoundError as exc:
+        raise HTTPException(status_code=404, detail=str(exc))