perago 0.1.0__py3-none-any.whl

perago/__init__.py

@@ -0,0 +1,144 @@
+from perago.attempt import assert_current_attempt_snapshot
+from perago.config import ConductorConfig, LakeFSConfig, RuntimeConfig, load_runtime_config
+from perago.errors import (
+    GuardrailViolation,
+    PostGuardrailViolation,
+    PublishBudgetError,
+    PublishFenceError,
+    PreGuardrailViolation,
+    RuntimeConfigError,
+    StaleAttemptError,
+    TaskDefinitionError,
+    TaskInputError,
+)
+from perago.execution import (
+    StagedWorkspace,
+    build_workspace_free_task_output,
+    build_workspace_task_output,
+    invoke_workspace_free_task,
+    invoke_workspace_task_body,
+    run_workspace_free_task_attempt,
+    run_workspace_task_attempt,
+)
+from perago.guards import (
+    check_guardrails,
+    forbid_glob,
+    require_dir,
+    require_file,
+    require_glob,
+)
+from perago.metadata import (
+    WorkspacePublicationPlan,
+    build_workspace_publication_plan,
+    choose_publish_base,
+    confirm_metadata_extra,
+    find_matching_publication_commit,
+    logical_task_key,
+    metadata_value,
+    perago_metadata,
+    staging_branch_name,
+)
+from perago.models import (
+    ExecutionLimits,
+    PublishBudget,
+    RetryPolicy,
+    TaskControls,
+    TimeoutPolicy,
+    WorkspaceInput,
+    WorkspaceOutput,
+    WorkspaceSpec,
+)
+from perago.task import TaskDefinition, load_module_task, task
+from perago.taskdef import build_taskdef, write_taskdef
+from perago.result import (
+    RuntimeTaskResult,
+    completed_result,
+    failed_result,
+    result_for_exception,
+    terminal_failed_result,
+)
+from perago.supervisor import WorkerChildSpec, restart_backoff_seconds, worker_child_specs
+from perago.worker_runtime import WorkerRuntime, prepare_worker_runtime
+from perago.workspace import (
+    WorkspaceDownloadFile,
+    WorkspaceSyncPlan,
+    WorkspaceUploadFile,
+    assert_workspace_sync_plan_within_budget,
+    build_budgeted_workspace_sync_plan,
+    build_workspace_sync_plan,
+    workspace_delete_object_paths,
+    workspace_download_files,
+    workspace_local_path,
+    workspace_upload_files,
+)
+
+__all__ = [
+    "ExecutionLimits",
+    "ConductorConfig",
+    "GuardrailViolation",
+    "PostGuardrailViolation",
+    "PublishBudgetError",
+    "PublishFenceError",
+    "PreGuardrailViolation",
+    "PublishBudget",
+    "RetryPolicy",
+    "LakeFSConfig",
+    "RuntimeConfig",
+    "RuntimeConfigError",
+    "RuntimeTaskResult",
+    "StagedWorkspace",
+    "StaleAttemptError",
+    "TaskControls",
+    "TaskDefinition",
+    "TaskDefinitionError",
+    "TaskInputError",
+    "TimeoutPolicy",
+    "WorkerChildSpec",
+    "WorkerRuntime",
+    "WorkspaceInput",
+    "WorkspaceOutput",
+    "WorkspacePublicationPlan",
+    "WorkspaceSpec",
+    "WorkspaceDownloadFile",
+    "WorkspaceSyncPlan",
+    "WorkspaceUploadFile",
+    "assert_current_attempt_snapshot",
+    "assert_workspace_sync_plan_within_budget",
+    "build_budgeted_workspace_sync_plan",
+    "build_taskdef",
+    "build_workspace_free_task_output",
+    "build_workspace_publication_plan",
+    "build_workspace_sync_plan",
+    "build_workspace_task_output",
+    "check_guardrails",
+    "choose_publish_base",
+    "confirm_metadata_extra",
+    "completed_result",
+    "failed_result",
+    "find_matching_publication_commit",
+    "forbid_glob",
+    "invoke_workspace_free_task",
+    "invoke_workspace_task_body",
+    "load_module_task",
+    "load_runtime_config",
+    "logical_task_key",
+    "metadata_value",
+    "perago_metadata",
+    "prepare_worker_runtime",
+    "require_dir",
+    "require_file",
+    "require_glob",
+    "result_for_exception",
+    "run_workspace_free_task_attempt",
+    "run_workspace_task_attempt",
+    "restart_backoff_seconds",
+    "staging_branch_name",
+    "task",
+    "terminal_failed_result",
+    "worker_child_specs",
+    "workspace_delete_object_paths",
+    "workspace_download_files",
+    "workspace_local_path",
+    "workspace_upload_files",
+    "write_taskdef",
+]

perago/_segments.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+import re
+
+
+def safe_segment(value: object) -> str:
+    text = str(value)
+    return re.sub(r"[^A-Za-z0-9_.=-]+", "_", text).strip("._") or "unknown"

perago/attempt.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from typing import Any
+
+from perago.errors import StaleAttemptError
+
+
+def assert_current_attempt_snapshot(task: object, fresh: object) -> None:
+    if (
+        _task_attr(fresh, "status") != "IN_PROGRESS"
+        or _task_attr(fresh, "workflow_instance_id") != _task_attr(task, "workflow_instance_id")
+        or _task_attr(fresh, "task_id") != _task_attr(task, "task_id")
+        or _task_attr(fresh, "retry_count") != _task_attr(task, "retry_count")
+    ):
+        raise StaleAttemptError(_task_attr(task, "task_id"))
+
+
+def _task_attr(task: object, name: str) -> Any:
+    try:
+        return getattr(task, name)
+    except AttributeError as exc:
+        raise AttributeError(f"task is missing required attribute {name}") from exc

perago/cli.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from pydantic import ValidationError
+from pydantic.errors import PydanticInvalidForJsonSchema
+
+from perago.conductor_runtime import OrkesConductorRuntimeClient
+from perago.config import load_runtime_config
+from perago.errors import RuntimeConfigError, TaskDefinitionError
+from perago.supervisor import run_worker_supervisor
+from perago.task import load_module_task
+from perago.taskdef import build_taskdef, write_taskdef
+
+
+app = typer.Typer(no_args_is_help=True)
+
+
+@app.command()
+def check(module_target: str) -> None:
+    """Validate one Perago task module and local runtime config."""
+    try:
+        config = load_runtime_config(module_target)
+        task = load_module_task(module_target)
+        build_taskdef(task)
+    except (TaskDefinitionError, RuntimeConfigError, ValidationError, PydanticInvalidForJsonSchema) as exc:
+        _fail(str(exc))
+    typer.echo(f"ok: {task.name}")
+    typer.echo(f"workspace_root: {config.workspace_root}")
+    typer.echo(f"log_root: {config.log_root}")
+    typer.echo(f"worker_id_prefix: {config.worker_id_prefix}")
+    typer.echo(f"conductor: {_configured(config.conductor is not None)}")
+    typer.echo(f"lakefs: {_configured(config.lakefs is not None)}")
+
+
+@app.command()
+def extract(module_target: str, output: Path = typer.Option(..., "--output", "-o")) -> None:
+    """Write generated Conductor TaskDef JSON for one task module."""
+    try:
+        load_runtime_config(module_target)
+        task = load_module_task(module_target)
+        path = write_taskdef(task, output)
+    except (TaskDefinitionError, RuntimeConfigError, ValidationError, PydanticInvalidForJsonSchema, ValueError) as exc:
+        _fail(str(exc))
+    typer.echo(str(path))
+
+
+@app.command()
+def start(module_target: str, j: int = typer.Option(1, "-j", min=1)) -> None:
+    """Start Conductor worker processes for one Perago task module."""
+    try:
+        config = load_runtime_config(module_target)
+        if config.conductor is None:
+            raise RuntimeConfigError("CONDUCTOR_SERVER_URL is required for perago start")
+        if config.lakefs is None:
+            raise RuntimeConfigError("LakeFS config is required for perago start")
+        task = load_module_task(module_target)
+        build_taskdef(task)
+        conductor = OrkesConductorRuntimeClient.from_config(config.conductor)
+        if not conductor.taskdef_exists(task.name):
+            raise RuntimeConfigError(
+                f"Conductor TaskDef {task.name!r} is not registered; run perago extract and register it before start"
+            )
+    except (TaskDefinitionError, RuntimeConfigError, ValidationError, PydanticInvalidForJsonSchema) as exc:
+        _fail(str(exc))
+    except Exception as exc:  # noqa: BLE001
+        _fail(f"failed to validate Conductor TaskDef: {exc}")
+    run_worker_supervisor(config=config, module_target=module_target, process_count=j)
+
+
+def _fail(message: str) -> None:
+    typer.echo(f"error: {message}", err=True)
+    raise typer.Exit(code=1)
+
+
+def _configured(value: bool) -> str:
+    return "configured" if value else "not configured"
+
+
+if __name__ == "__main__":
+    app()

perago/conductor_runtime.py

@@ -0,0 +1,238 @@
+from __future__ import annotations
+
+import time
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+from conductor.client.configuration.configuration import Configuration
+from conductor.client.http.models.task_result import TaskResult
+from conductor.client.http.models.task_result_status import TaskResultStatus
+from conductor.client.orkes.orkes_metadata_client import OrkesMetadataClient
+from conductor.client.orkes.orkes_task_client import OrkesTaskClient
+from loguru import logger
+
+from perago.config import ConductorConfig
+from perago.execution import (
+    CleanupStaging,
+    DownloadWorkspace,
+    LoadCurrentAttempt,
+    PublishWorkspace,
+    StageWorkspace,
+    run_workspace_free_task_attempt,
+    run_workspace_task_attempt,
+)
+from perago.result import RuntimeTaskResult
+from perago.task import TaskDefinition
+
+
+POLL_EMPTY_SLEEP_SECONDS = 1.0
+POLL_ERROR_BACKOFF_SECONDS = 5.0
+
+
+@dataclass(frozen=True)
+class ConductorTaskAttempt:
+    workflow_instance_id: str
+    task_id: str
+    retry_count: int
+    task_def_name: str
+    reference_task_name: str
+    seq: int
+    iteration: int
+    status: str
+    input_data: Mapping[str, Any]
+    retried_task_id: str | None = None
+
+
+class ConductorRuntimeClient(Protocol):
+    def taskdef_exists(self, task_name: str) -> bool: ...
+
+    def poll_task(self, task_name: str, *, worker_id: str) -> ConductorTaskAttempt | None: ...
+
+    def get_task(self, task_id: str) -> ConductorTaskAttempt: ...
+
+    def update_task(self, attempt: ConductorTaskAttempt, result: RuntimeTaskResult, *, worker_id: str) -> None: ...
+
+
+class OrkesConductorRuntimeClient:
+    def __init__(
+        self,
+        *,
+        task_client: OrkesTaskClient,
+        metadata_client: OrkesMetadataClient,
+    ) -> None:
+        self._task_client = task_client
+        self._metadata_client = metadata_client
+
+    @classmethod
+    def from_config(cls, config: ConductorConfig) -> OrkesConductorRuntimeClient:
+        sdk_config = Configuration(server_api_url=config.server_url)
+        return cls(
+            task_client=OrkesTaskClient(sdk_config),
+            metadata_client=OrkesMetadataClient(sdk_config),
+        )
+
+    def taskdef_exists(self, task_name: str) -> bool:
+        try:
+            self._metadata_client.get_task_def(task_name)
+        except Exception as exc:  # noqa: BLE001
+            if _looks_like_not_found(exc):
+                return False
+            raise
+        return True
+
+    def poll_task(self, task_name: str, *, worker_id: str) -> ConductorTaskAttempt | None:
+        task = self._task_client.poll_task(task_name, worker_id=worker_id)
+        if task is None or getattr(task, "task_id", None) in {None, ""}:
+            return None
+        return conductor_task_to_attempt(task)
+
+    def get_task(self, task_id: str) -> ConductorTaskAttempt:
+        return conductor_task_to_attempt(self._task_client.get_task(task_id))
+
+    def update_task(self, attempt: ConductorTaskAttempt, result: RuntimeTaskResult, *, worker_id: str) -> None:
+        self._task_client.update_task(runtime_result_to_sdk_task_result(attempt, result, worker_id=worker_id))
+
+
+def conductor_task_to_attempt(task: object) -> ConductorTaskAttempt:
+    return ConductorTaskAttempt(
+        workflow_instance_id=str(_required_task_attr(task, "workflow_instance_id")),
+        task_id=str(_required_task_attr(task, "task_id")),
+        retry_count=int(_required_task_attr(task, "retry_count")),
+        task_def_name=str(_required_task_attr(task, "task_def_name")),
+        reference_task_name=str(_required_task_attr(task, "reference_task_name")),
+        seq=int(_required_task_attr(task, "seq")),
+        iteration=int(_task_attr(task, "iteration", 0) or 0),
+        status=str(_required_task_attr(task, "status")),
+        input_data=_mapping_attr(task, "input_data"),
+        retried_task_id=_optional_str(_task_attr(task, "retried_task_id", None)),
+    )
+
+
+def runtime_result_to_sdk_task_result(
+    attempt: ConductorTaskAttempt,
+    result: RuntimeTaskResult,
+    *,
+    worker_id: str,
+) -> TaskResult:
+    task_result = TaskResult(
+        workflow_instance_id=attempt.workflow_instance_id,
+        task_id=attempt.task_id,
+        worker_id=worker_id,
+        status=TaskResultStatus(result.status),
+    )
+    if result.status == "COMPLETED":
+        task_result.output_data = result.output
+    else:
+        task_result.reason_for_incompletion = result.reason_for_incompletion
+    return task_result
+
+
+def run_worker_poll_loop(
+    *,
+    task: TaskDefinition,
+    client: ConductorRuntimeClient,
+    worker_id: str,
+    workspace_root: Any,
+    should_stop: Any,
+    download_workspace: DownloadWorkspace,
+    stage_workspace: StageWorkspace,
+    publish_workspace: PublishWorkspace,
+    cleanup_staging: CleanupStaging,
+    poll_empty_sleep_seconds: float = POLL_EMPTY_SLEEP_SECONDS,
+    poll_error_backoff_seconds: float = POLL_ERROR_BACKOFF_SECONDS,
+) -> None:
+    while not should_stop():
+        try:
+            attempt = client.poll_task(task.name, worker_id=worker_id)
+        except Exception as exc:  # noqa: BLE001
+            logger.opt(exception=exc).error("failed to poll Conductor task")
+            _sleep_until_stop(poll_error_backoff_seconds, should_stop)
+            continue
+
+        if attempt is None:
+            _sleep_until_stop(poll_empty_sleep_seconds, should_stop)
+            continue
+
+        result = execute_polled_task(
+            task=task,
+            attempt=attempt,
+            workspace_root=workspace_root,
+            download_workspace=download_workspace,
+            load_current_attempt=lambda current_attempt: client.get_task(current_attempt.task_id),
+            stage_workspace=stage_workspace,
+            publish_workspace=publish_workspace,
+            cleanup_staging=cleanup_staging,
+        )
+        try:
+            client.update_task(attempt, result, worker_id=worker_id)
+        except Exception as exc:  # noqa: BLE001
+            logger.bind(task_id=attempt.task_id, workflow_instance_id=attempt.workflow_instance_id).opt(
+                exception=exc
+            ).error("failed to update Conductor task result")
+            _sleep_until_stop(poll_error_backoff_seconds, should_stop)
+
+
+def execute_polled_task(
+    *,
+    task: TaskDefinition,
+    attempt: ConductorTaskAttempt,
+    workspace_root: Any,
+    download_workspace: DownloadWorkspace,
+    load_current_attempt: LoadCurrentAttempt,
+    stage_workspace: StageWorkspace,
+    publish_workspace: PublishWorkspace,
+    cleanup_staging: CleanupStaging,
+) -> RuntimeTaskResult:
+    if task.has_workspace:
+        return run_workspace_task_attempt(
+            task,
+            attempt.input_data,
+            attempt,
+            workspace_root,
+            download_workspace=download_workspace,
+            load_current_attempt=load_current_attempt,
+            stage_workspace=stage_workspace,
+            publish_workspace=publish_workspace,
+            cleanup_staging=cleanup_staging,
+        )
+    return run_workspace_free_task_attempt(task, attempt.input_data)
+
+
+def _sleep_until_stop(seconds: float, should_stop: Any) -> None:
+    deadline = time.monotonic() + seconds
+    while not should_stop() and time.monotonic() < deadline:
+        time.sleep(min(0.1, deadline - time.monotonic()))
+
+
+def _required_task_attr(task: object, name: str) -> Any:
+    value = _task_attr(task, name, None)
+    if value is None:
+        raise AttributeError(f"Conductor task is missing required field {name}")
+    return value
+
+
+def _task_attr(task: object, name: str, default: Any) -> Any:
+    if isinstance(task, Mapping):
+        return task.get(name, default)
+    return getattr(task, name, default)
+
+
+def _mapping_attr(task: object, name: str) -> Mapping[str, Any]:
+    value = _required_task_attr(task, name)
+    if not isinstance(value, Mapping):
+        raise TypeError(f"Conductor task field {name} must be a mapping")
+    return value
+
+
+def _optional_str(value: object) -> str | None:
+    if value is None:
+        return None
+    return str(value)
+
+
+def _looks_like_not_found(exc: Exception) -> bool:
+    status = getattr(exc, "status", None) or getattr(exc, "status_code", None)
+    if status == 404:
+        return True
+    return "404" in str(exc) and "not" in str(exc).lower()