orca-auto 6.0.0__py3-none-any.whl

orca_auto/__init__.py

@@ -0,0 +1,11 @@
+"""Shared namespace package for the chemistry automation monorepo."""
+
+from pkgutil import extend_path
+
+# Core owns this initializer; separately installed extensions own subpackages.
+# Never discover sibling checkout sources unless they were explicitly installed.
+__path__ = extend_path(__path__, __name__)
+
+from ._version import __version__
+
+__all__ = ["__version__"]

orca_auto/_process_evidence.py

@@ -0,0 +1,60 @@
+"""Process-local provenance used by the systemd freshness check."""
+
+from __future__ import annotations
+
+import os
+import sys
+from importlib import import_module
+from pathlib import Path
+
+PROCESS_IMPORT_SOURCE_ENV = "ORCA_AUTO_PROCESS_IMPORT_SOURCE"
+PROCESS_WORKFLOW_IMPORT_SOURCE_ENV = "ORCA_AUTO_PROCESS_WORKFLOW_IMPORT_SOURCE"
+
+
+def _workflow_worker_requested(argv: list[str]) -> bool:
+    return "--app=workflow" in argv or any(
+        flag == "--app" and value == "workflow" for flag, value in zip(argv, argv[1:], strict=False)
+    )
+
+
+def exec_with_import_source_evidence() -> None:
+    """Re-exec the module CLI once with its actual imported source in environ.
+
+    ``/proc/<pid>/environ`` exposes only the environment installed by ``exec``;
+    mutating ``os.environ`` after Python starts is not reliable process evidence.
+    Re-exec preserves the systemd MainPID and kernel process start identity while
+    making the source path observable without a sidecar state file.
+    """
+
+    if sys.argv[1:3] != ["queue", "worker"]:
+        return
+    import_source = str(Path(__file__).resolve(strict=False))
+    environment = os.environ.copy()
+    environment[PROCESS_IMPORT_SOURCE_ENV] = import_source
+    if _workflow_worker_requested(sys.argv[3:]):
+        from orca_auto.core.extensions import require_workflows
+
+        require_workflows()
+        workflow_module = import_module("orca_auto.flow")
+        workflow_source = workflow_module.__file__
+        if workflow_source is None:
+            raise ValueError("workflow import source is unavailable")
+        environment[PROCESS_WORKFLOW_IMPORT_SOURCE_ENV] = str(
+            Path(workflow_source).resolve(strict=True)
+        )
+    else:
+        environment.pop(PROCESS_WORKFLOW_IMPORT_SOURCE_ENV, None)
+    if environment == os.environ:
+        return
+    os.execve(
+        sys.executable,
+        [sys.executable, "-m", "orca_auto.cli", *sys.argv[1:]],
+        environment,
+    )
+
+
+__all__ = [
+    "PROCESS_IMPORT_SOURCE_ENV",
+    "PROCESS_WORKFLOW_IMPORT_SOURCE_ENV",
+    "exec_with_import_source_evidence",
+]

orca_auto/_version.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import tomllib
+from importlib import metadata
+from pathlib import Path
+
+
+def package_version() -> str:
+    try:
+        return metadata.version("orca_auto")
+    except metadata.PackageNotFoundError:
+        return "0.0.0+unknown"
+
+
+def _source_pyproject_version(source_root: Path) -> str | None:
+    try:
+        with open(source_root / "pyproject.toml", "rb") as fh:
+            project = tomllib.load(fh)["project"]
+        if project["name"] != "orca_auto":
+            return None
+        return str(project["version"])
+    except (OSError, tomllib.TOMLDecodeError, KeyError, TypeError):
+        return None
+
+
+def installed_version_drift(source_root: Path | None = None) -> tuple[str, str] | None:
+    """Report `(installed, source)` when the two disagree, else `None`.
+
+    An editable install freezes its distribution metadata at install time while
+    the interpreter keeps importing the checkout, so a live deployment can run
+    one version's code and declare another until someone reruns the install.
+    Returns `None` when there is no source `pyproject.toml` to compare against,
+    which is the normal shape of a wheel install rather than a drift verdict.
+    """
+    root = source_root if source_root is not None else Path(__file__).resolve().parents[2]
+    source = _source_pyproject_version(root)
+    if source is None:
+        return None
+    installed = package_version()
+    return None if installed == source else (installed, source)
+
+
+__version__ = package_version()
+
+__all__ = ["__version__", "installed_version_drift", "package_version"]

orca_auto/activity/__init__.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from orca_auto.core.activity import (
+    ActivityCancelRequest,
+    ActivityListRequest,
+    ActivityRecord,
+    ActivitySourceRequest,
+    ResolvedActivitySources,
+)
+from orca_auto.core.statuses import WORKFLOW_TERMINAL_STATUSES
+
+from . import _cancel as _activity_cancel
+from . import _clear as _activity_clear
+from . import _collectors as _activity_collectors
+from . import _list as _activity_list
+from . import _sources as _activity_sources
+
+_ACTIVITY_CLEARABLE_TERMINAL_STATUSES = WORKFLOW_TERMINAL_STATUSES
+
+
+def list_activities(
+    *,
+    workflow_root: str | Path | None = None,
+    shared_config: str | None = None,
+    refresh: bool = False,
+    limit: int = 0,
+    crest_config: str | None = None,
+    xtb_config: str | None = None,
+    orca_config: str | None = None,
+) -> dict[str, Any]:
+    return _activity_list.list_activities(
+        workflow_root=workflow_root,
+        shared_config=shared_config,
+        refresh=refresh,
+        limit=limit,
+        crest_config=crest_config,
+        xtb_config=xtb_config,
+        orca_config=orca_config,
+    )
+
+
+def clear_activities(
+    *,
+    workflow_root: str | Path | None = None,
+    shared_config: str | None = None,
+    crest_config: str | None = None,
+    xtb_config: str | None = None,
+    orca_config: str | None = None,
+) -> dict[str, Any]:
+    return _activity_clear.clear_activities(
+        workflow_root=workflow_root,
+        shared_config=shared_config,
+        crest_config=crest_config,
+        xtb_config=xtb_config,
+        orca_config=orca_config,
+        clearable_terminal_statuses=_ACTIVITY_CLEARABLE_TERMINAL_STATUSES,
+    )
+
+
+def cancel_activity(
+    *,
+    target: str,
+    workflow_root: str | Path | None = None,
+    shared_config: str | None = None,
+    crest_config: str | None = None,
+    xtb_config: str | None = None,
+    orca_config: str | None = None,
+) -> dict[str, Any]:
+    request = ActivityCancelRequest(
+        target=target,
+        sources=ActivitySourceRequest(
+            workflow_root=workflow_root,
+            shared_config=shared_config,
+            crest_config=crest_config,
+            xtb_config=xtb_config,
+            orca_config=orca_config,
+        ),
+    )
+    resolved = _activity_sources.resolve_activity_source_request(request.sources)
+    record = _activity_cancel.match_activity_record(
+        _activity_collectors.collect_activity_records(
+            workflow_root=resolved.workflow_root,
+            refresh=False,
+            crest_config=resolved.crest_config,
+            xtb_config=resolved.xtb_config,
+            orca_config=resolved.orca_config,
+        ),
+        request.target,
+    )
+
+    if record.kind == "workflow":
+        result = _activity_cancel.cancel_workflow_activity(record, resolved, request)
+        return _activity_cancel.cancel_activity_payload(
+            record,
+            result,
+            fallback_status="cancelled",
+        )
+
+    result = _activity_cancel.cancel_non_workflow_activity(record, resolved, request)
+    return _activity_cancel.cancel_activity_payload(record, result, fallback_status="failed")
+
+
+__all__ = [
+    "ActivityCancelRequest",
+    "ActivityListRequest",
+    "ActivityRecord",
+    "ActivitySourceRequest",
+    "ResolvedActivitySources",
+    "cancel_activity",
+    "clear_activities",
+    "list_activities",
+]

orca_auto/activity/_cancel.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from importlib import import_module
+from typing import Any
+
+from orca_auto.core.activity import ActivityCancelRequest, ActivityRecord, ResolvedActivitySources
+from orca_auto.core.engine_catalog import (
+    EngineCatalogEntry,
+    find_engine_catalog_entry_by_source_id,
+)
+from orca_auto.core.extensions import require_workflows
+from orca_auto.core.utils import normalize_text
+from orca_auto.orca.direct_cancel import cancel_target as cancel_orca_target
+
+_CANCEL_ENGINE_TARGETS: dict[str, str | Callable[..., dict[str, Any]]] = {
+    "crest": "orca_auto.flow.submitters.crest",
+    "xtb": "orca_auto.flow.submitters.xtb",
+}
+
+
+def match_activity_record(records: list[ActivityRecord], target: str) -> ActivityRecord:
+    normalized_target = normalize_text(target)
+    if not normalized_target:
+        raise ValueError("Cancel target is empty.")
+
+    exact_matches = [
+        record
+        for record in records
+        if normalized_target in {record.activity_id, record.cancel_target}
+    ]
+    if len(exact_matches) == 1:
+        return exact_matches[0]
+    if len(exact_matches) > 1:
+        raise ValueError(
+            f"Ambiguous activity target: {normalized_target}. Matches: "
+            + ", ".join(sorted(record.activity_id for record in exact_matches))
+        )
+
+    alias_matches = [record for record in records if normalized_target in set(record.aliases)]
+    if len(alias_matches) == 1:
+        return alias_matches[0]
+    if len(alias_matches) > 1:
+        raise ValueError(
+            f"Ambiguous activity target: {normalized_target}. Matches: "
+            + ", ".join(sorted(record.activity_id for record in alias_matches))
+        )
+    raise LookupError(f"Activity target not found: {normalized_target}")
+
+
+def cancel_activity_payload(
+    record: ActivityRecord,
+    result: dict[str, Any],
+    *,
+    fallback_status: str,
+) -> dict[str, Any]:
+    return {
+        "activity_id": record.activity_id,
+        "kind": record.kind,
+        "engine": record.engine,
+        "source": record.source,
+        "label": record.label,
+        "status": normalize_text(result.get("status")) or fallback_status,
+        "cancel_target": record.cancel_target,
+        "result": result,
+    }
+
+
+def cancel_workflow_activity(
+    record: ActivityRecord,
+    resolved: ResolvedActivitySources,
+    request: ActivityCancelRequest,
+) -> dict[str, Any]:
+    require_workflows()
+    from orca_auto.flow.orchestration import cancel_materialized_workflow
+
+    return cancel_materialized_workflow(
+        target=record.cancel_target,
+        workflow_root=resolved.workflow_root or "",
+        crest_config=resolved.crest_config,
+        orca_config=resolved.orca_config,
+    )
+
+
+def cancel_workflow_stage_engine_activity(
+    entry: EngineCatalogEntry,
+    record: ActivityRecord,
+    resolved: ResolvedActivitySources,
+    request: ActivityCancelRequest,
+) -> dict[str, Any]:
+    del request
+    config_path = normalize_text(resolved.config_for_engine(entry.engine_id))
+    if not config_path:
+        raise ValueError(
+            f"{entry.engine_id}_config is required to cancel {entry.engine_id} activities."
+        )
+    cancel_target = _CANCEL_ENGINE_TARGETS.get(entry.engine_id)
+    if cancel_target is None:
+        raise ValueError(f"No cancellation handler for catalog engine: {entry.engine_id}")
+    require_workflows()
+    if isinstance(cancel_target, str):
+        cancel_target = import_module(cancel_target).cancel_target
+    return cancel_target(
+        target=record.cancel_target,
+        config_path=config_path,
+    )
+
+
+def cancel_orca_activity(
+    record: ActivityRecord,
+    resolved: ResolvedActivitySources,
+    request: ActivityCancelRequest,
+) -> dict[str, Any]:
+    config_path = normalize_text(resolved.orca_config)
+    if not config_path:
+        raise ValueError("orca_auto_config is required to cancel orca_auto ORCA activities.")
+    return cancel_orca_target(
+        target=record.cancel_target,
+        config_path=config_path,
+    )
+
+
+def cancel_non_workflow_activity(
+    record: ActivityRecord,
+    resolved: ResolvedActivitySources,
+    request: ActivityCancelRequest,
+) -> dict[str, Any]:
+    entry = find_engine_catalog_entry_by_source_id(record.source)
+    if entry is None:
+        raise ValueError(f"Unsupported activity source: {record.source}")
+    if entry.workflow_stage_role == "workflow-stage":
+        return cancel_workflow_stage_engine_activity(
+            entry,
+            record,
+            resolved,
+            request,
+        )
+    if entry.activity_role == "orca-run":
+        return cancel_orca_activity(record, resolved, request)
+    raise ValueError(f"Unsupported activity role for source {record.source}: {entry.activity_role}")

orca_auto/activity/_clear.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from orca_auto.core.activity import ActivitySourceRequest, ResolvedActivitySources
+from orca_auto.core.engine_catalog import (
+    activity_engine_entries,
+    get_engine_catalog_entry,
+    workflow_stage_engine_entries,
+)
+from orca_auto.core.engine_runtime import engine_runtime_paths
+from orca_auto.core.engines import own_engine_accept_entry
+from orca_auto.core.extensions import workflows_available
+from orca_auto.core.queue import clear_terminal as clear_queue_terminal
+from orca_auto.core.utils import normalize_text
+
+from . import _sources
+from ._queue_records import engine_queue_roots
+
+_ENGINE_QUEUE_CLEAR_SOURCES = tuple(
+    (entry.engine_id, f"{entry.engine_id}_queue_entries")
+    for entry in workflow_stage_engine_entries()
+)
+
+
+def _clear_counts() -> dict[str, int]:
+    cleared = {"workflows": 0}
+    for entry in activity_engine_entries():
+        cleared[f"{entry.engine_id}_queue_entries"] = 0
+    cleared["orca_run_states"] = 0
+    return cleared
+
+
+def _clear_engine_queue(
+    resolved: ResolvedActivitySources,
+    *,
+    engine: str,
+) -> int:
+    config_path = normalize_text(resolved.config_for_engine(engine))
+    if not config_path:
+        return 0
+    entry = get_engine_catalog_entry(engine)
+    if entry.workflow_stage_role == "workflow-stage" and not normalize_text(resolved.workflow_root):
+        return 0
+    return sum(
+        clear_queue_terminal(
+            root,
+            select_entry_fn=own_engine_accept_entry(engine),
+        )
+        for root in engine_queue_roots(config_path, engine=engine)
+    )
+
+
+def _clear_workflow_registry(
+    resolved: ResolvedActivitySources,
+    *,
+    clearable_terminal_statuses: frozenset[str],
+) -> int:
+    if not workflows_available() or not normalize_text(resolved.workflow_root):
+        return 0
+    from orca_auto.flow.registry import clear_terminal_workflow_registry
+
+    return clear_terminal_workflow_registry(
+        str(resolved.workflow_root),
+        statuses=clearable_terminal_statuses,
+    )
+
+
+def _clear_engine_queues(
+    resolved: ResolvedActivitySources,
+) -> dict[str, int]:
+    cleared = {cleared_key: 0 for _, cleared_key in _ENGINE_QUEUE_CLEAR_SOURCES}
+    for engine, cleared_key in _ENGINE_QUEUE_CLEAR_SOURCES:
+        cleared[cleared_key] += _clear_engine_queue(
+            resolved,
+            engine=engine,
+        )
+    return cleared
+
+
+def _clear_orca_terminal_entries(
+    resolved: ResolvedActivitySources,
+) -> tuple[int, int]:
+    if not normalize_text(resolved.orca_config):
+        return 0, 0
+    from orca_auto.orca.run_cleanup import (
+        clear_terminal_entries as clear_orca_terminal_entries,
+    )
+
+    allowed_root = engine_runtime_paths(str(resolved.orca_config), engine="orca")["allowed_root"]
+    return clear_orca_terminal_entries(allowed_root)
+
+
+def _clear_sources_payload(resolved: ResolvedActivitySources) -> dict[str, str]:
+    workflow_root_text = normalize_text(resolved.workflow_root)
+    return {
+        "workflow_root": str(Path(workflow_root_text).expanduser().resolve())
+        if workflow_root_text
+        else "",
+        **{
+            f"{entry.engine_id}_config": normalize_text(resolved.config_for_engine(entry.engine_id))
+            for entry in activity_engine_entries()
+        },
+    }
+
+
+def clear_activities(
+    *,
+    workflow_root: str | Path | None = None,
+    shared_config: str | None = None,
+    crest_config: str | None = None,
+    xtb_config: str | None = None,
+    orca_config: str | None = None,
+    clearable_terminal_statuses: frozenset[str],
+) -> dict[str, Any]:
+    source_request = ActivitySourceRequest(
+        workflow_root=workflow_root,
+        shared_config=shared_config,
+        crest_config=crest_config,
+        xtb_config=xtb_config,
+        orca_config=orca_config,
+    )
+    resolved = _sources.resolve_activity_source_request(source_request)
+    _sources.require_activity_support(resolved)
+
+    cleared = _clear_counts()
+    cleared["workflows"] = _clear_workflow_registry(
+        resolved,
+        clearable_terminal_statuses=clearable_terminal_statuses,
+    )
+    for key, count in _clear_engine_queues(resolved).items():
+        cleared[key] += count
+    queue_count, run_count = _clear_orca_terminal_entries(resolved)
+    cleared["orca_queue_entries"] += queue_count
+    cleared["orca_run_states"] += run_count
+
+    return {
+        "total_cleared": sum(int(value) for value in cleared.values()),
+        "cleared": cleared,
+        "sources": _clear_sources_payload(resolved),
+    }

orca_auto/activity/_collectors.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from orca_auto.core.activity import (
+    ActivityListRequest,
+    ActivityRecord,
+    ActivitySourceRequest,
+    ResolvedActivitySources,
+    sort_key,
+)
+from orca_auto.core.engine_catalog import EngineCatalogEntry, activity_engine_entries
+from orca_auto.core.extensions import workflows_available
+from orca_auto.core.utils import normalize_text
+
+from . import _sources
+from ._queue_records import collect_catalog_engine_activity
+
+
+@dataclass(frozen=True)
+class ActivityListProvider:
+    source: str
+    collect: Callable[[Any, ActivityListRequest], list[ActivityRecord]]
+
+
+def collect_workflow_activity(
+    resolved: ResolvedActivitySources,
+    request: ActivityListRequest,
+) -> list[ActivityRecord]:
+    if not normalize_text(resolved.workflow_root):
+        return []
+    from orca_auto.flow.activity._workflow_records import workflow_records
+
+    return workflow_records(
+        workflow_root=str(resolved.workflow_root),
+        refresh=request.refresh,
+    )
+
+
+def _catalog_activity_provider(entry: EngineCatalogEntry) -> ActivityListProvider:
+    def collect(
+        resolved: ResolvedActivitySources,
+        request: ActivityListRequest,
+    ) -> list[ActivityRecord]:
+        return collect_catalog_engine_activity(entry, resolved, request)
+
+    return ActivityListProvider(entry.source_id, collect)
+
+
+def activity_list_providers() -> tuple[ActivityListProvider, ...]:
+    providers = (
+        [ActivityListProvider("orca_auto_flow", collect_workflow_activity)]
+        if workflows_available()
+        else []
+    )
+    for entry in activity_engine_entries():
+        providers.append(_catalog_activity_provider(entry))
+    return tuple(providers)
+
+
+def collect_activity_records_from_request(
+    request: ActivityListRequest,
+) -> list[ActivityRecord]:
+    resolved = _sources.resolve_activity_source_request(request.sources)
+    _sources.require_activity_support(resolved)
+    rows: list[ActivityRecord] = []
+    for provider in activity_list_providers():
+        rows.extend(provider.collect(resolved, request))
+    return sorted(rows, key=sort_key, reverse=True)
+
+
+def collect_activity_records(
+    *,
+    workflow_root: str | Path | None = None,
+    shared_config: str | None = None,
+    refresh: bool = False,
+    crest_config: str | None = None,
+    xtb_config: str | None = None,
+    orca_config: str | None = None,
+) -> list[ActivityRecord]:
+    return collect_activity_records_from_request(
+        ActivityListRequest(
+            sources=ActivitySourceRequest(
+                workflow_root=workflow_root,
+                shared_config=shared_config,
+                crest_config=crest_config,
+                xtb_config=xtb_config,
+                orca_config=orca_config,
+            ),
+            refresh=refresh,
+        ),
+    )
+
+
+__all__ = [
+    "ActivityListProvider",
+    "activity_list_providers",
+    "collect_activity_records",
+    "collect_activity_records_from_request",
+    "collect_workflow_activity",
+]

orca_auto/activity/_list.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from orca_auto.core.activity import ActivityListRequest, ActivitySourceRequest
+from orca_auto.core.engine_catalog import activity_engine_entries
+from orca_auto.core.utils import normalize_text
+
+from . import _sources
+from ._collectors import collect_activity_records
+
+
+def list_activities(
+    *,
+    workflow_root: str | Path | None = None,
+    shared_config: str | None = None,
+    refresh: bool = False,
+    limit: int = 0,
+    crest_config: str | None = None,
+    xtb_config: str | None = None,
+    orca_config: str | None = None,
+) -> dict[str, Any]:
+    request = ActivityListRequest(
+        sources=ActivitySourceRequest(
+            workflow_root=workflow_root,
+            shared_config=shared_config,
+            crest_config=crest_config,
+            xtb_config=xtb_config,
+            orca_config=orca_config,
+        ),
+        refresh=refresh,
+        limit=limit,
+    )
+    resolved = _sources.resolve_activity_source_request(request.sources)
+    records = collect_activity_records(
+        workflow_root=resolved.workflow_root,
+        refresh=request.refresh,
+        crest_config=resolved.crest_config,
+        xtb_config=resolved.xtb_config,
+        orca_config=resolved.orca_config,
+    )
+    if request.limit > 0:
+        records = records[: request.limit]
+    workflow_root_text = normalize_text(resolved.workflow_root)
+    return {
+        "count": len(records),
+        "activities": [record.to_dict() for record in records],
+        "sources": {
+            "workflow_root": str(Path(workflow_root_text).expanduser().resolve())
+            if workflow_root_text
+            else "",
+            **{
+                f"{entry.engine_id}_config": normalize_text(
+                    resolved.config_for_engine(entry.engine_id)
+                )
+                for entry in activity_engine_entries()
+            },
+        },
+    }
+
+
+__all__ = [
+    "list_activities",
+]