palmengine 0.7.4__py3-none-any.whl

palm/app/resolvers.py

@@ -0,0 +1,43 @@
+"""
+Definition reference resolution — shared by library and CLI callers.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from palm.common.exceptions import DefinitionNotFoundError
+from palm.definitions.flow import FlowDefinition
+from palm.definitions.process import ProcessDefinition
+
+if TYPE_CHECKING:
+    from palm.app.app import PalmApp
+    from palm.common.persistence.definition_repository import DefinitionRepository
+
+
+def resolve_flow(repository: DefinitionRepository, ref: str) -> FlowDefinition:
+    """Resolve a flow by display name, falling back to definition id."""
+    try:
+        return repository.get_flow(ref)
+    except DefinitionNotFoundError:
+        return repository.get_flow(ref, by_id=True)
+
+
+def resolve_process(repository: DefinitionRepository, ref: str) -> ProcessDefinition:
+    """Resolve a process by display name, falling back to definition id."""
+    try:
+        return repository.get_process(ref)
+    except DefinitionNotFoundError:
+        return repository.get_process(ref, by_id=True)
+
+
+def resolve_flow_for_app(app: PalmApp, ref: str, *, runtime_name: str | None = None) -> FlowDefinition:
+    """Resolve a flow via a :class:`~palm.app.app.PalmApp` runtime repository."""
+    return resolve_flow(app.repository(runtime_name=runtime_name), ref)
+
+
+def resolve_process_for_app(
+    app: PalmApp, ref: str, *, runtime_name: str | None = None
+) -> ProcessDefinition:
+    """Resolve a process via a :class:`~palm.app.app.PalmApp` runtime repository."""
+    return resolve_process(app.repository(runtime_name=runtime_name), ref)

palm/app/session.py

@@ -0,0 +1,67 @@
+"""
+CLI session bootstrap — thin PalmApp client for terminal entrypoints.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from palm.app.app import PalmApp
+from palm.app.bootstrap import runtime_start_options
+from palm.app.cli_settings import resolve_cli_settings
+from palm.app.settings import PalmSettings
+from palm.core.storage import StorageEngine
+
+
+def create_console() -> Any:
+    """Build a Rich console for CLI output."""
+    try:
+        from rich.console import Console
+
+        return Console(highlight=False)
+    except ImportError as exc:
+        raise SystemExit(
+            "Rich is required for the Palm CLI. Install with: pip install palmengine[cli]"
+        ) from exc
+
+
+def create_cli_app(
+    *,
+    storage_backend: str | None = None,
+    data_dir: Path | None = None,
+    storage: StorageEngine | None = None,
+    settings: PalmSettings | None = None,
+) -> PalmApp:
+    """
+    Construct a fully bootstrapped :class:`~palm.app.app.PalmApp` for the CLI.
+
+    Settings resolve from ``PALM_*`` environment variables, with optional CLI flag
+    overrides. ``bootstrap_cli`` wires the embedded runtime, ``InstanceManager``,
+    persistence hooks, and definition catalog — no manual runtime assembly.
+
+    Shared ``storage`` enables resume across separate CLI invocations (daemon +
+    terminal) when both use the same engine instance or durable backend + data dir.
+    """
+    if settings is not None:
+        cfg = settings
+        if storage_backend is not None:
+            cfg = resolve_cli_settings(storage_backend=storage_backend, settings=cfg)
+        if data_dir is not None:
+            cfg = resolve_cli_settings(data_dir=data_dir, settings=cfg)
+    else:
+        shared_backend = (
+            storage.backend_name
+            if storage is not None and storage.is_initialized and storage.backend_name
+            else None
+        )
+        cfg = resolve_cli_settings(
+            storage_backend=storage_backend,
+            data_dir=data_dir,
+            align_shared_storage=shared_backend if storage_backend is None else None,
+        )
+
+    app = PalmApp(cfg, storage=storage)
+    app.bootstrap()
+    app.bootstrap_cli(**runtime_start_options(cfg))
+    return app

palm/app/settings.py

@@ -0,0 +1,61 @@
+"""
+PalmSettings — central configuration for Palm applications.
+
+Loaded from environment variables (``PALM_*``) and optional ``.env`` files via
+``pydantic-settings``.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+SchedulerPolicy = Literal["inline", "queued"]
+
+
+class PalmSettings(BaseSettings):
+    """
+    Application-wide Palm configuration.
+
+    Environment prefix: ``PALM_`` (e.g. ``PALM_STORAGE_BACKEND=postgres``).
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix="PALM_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    storage_backend: str = "memory"
+    data_dir: Path | None = None
+    observability: bool = False
+    auth_enforce: bool = False
+    auth_roles: list[str] = Field(default_factory=lambda: ["user"])
+    load_example_definitions: bool = True
+    default_scheduler: SchedulerPolicy = "inline"
+    max_concurrent_jobs: int | None = None
+    enable_state_snapshot: bool = False
+    snapshot_on_status: list[str] = Field(
+        default_factory=lambda: ["WAITING_FOR_INPUT", "SUCCEEDED", "FAILED"]
+    )
+    max_snapshots_per_instance: int = 10
+    max_loaded_instances: int = 128
+    max_concurrent_active: int = 32
+    reconcile_instances_on_startup: bool = True
+
+    def definition_roots(self) -> list[Path]:
+        """Directories scanned for ``register_definitions`` modules."""
+        roots: list[Path] = []
+        if self.data_dir is not None:
+            roots.append(self.data_dir / "definitions")
+        roots.extend(
+            [
+                Path.cwd() / "examples" / "definitions",
+            ]
+        )
+        return roots
+

palm/backends/__init__.py

@@ -0,0 +1,5 @@
+"""Concrete job runners for Palm orchestration (modular apps)."""
+
+from palm.backends.behavior_tree import BehaviorTreeRunner
+
+__all__ = ["BehaviorTreeRunner"]

palm/backends/behavior_tree/__init__.py

@@ -0,0 +1,7 @@
+"""
+Behavior-tree job runner app — default ``JobRunner`` for pattern executables.
+"""
+
+from palm.backends.behavior_tree.runner import BehaviorTreeRunner
+
+__all__ = ["BehaviorTreeRunner"]

palm/backends/behavior_tree/runner.py

@@ -0,0 +1,68 @@
+"""
+BehaviorTreeRunner — runs ``BasePattern`` executables against job state.
+"""
+
+from __future__ import annotations
+
+from palm.core.behavior_tree import BasePattern, PatternStatus
+from palm.core.orchestration.execution.base_runner import JobRunner
+from palm.core.orchestration.execution_context import ExecutionContext
+from palm.core.orchestration.job import JobStatus
+from palm.core.orchestration.run_result import RunResult
+
+
+class BehaviorTreeRunner(JobRunner):
+    """Advances a ``BasePattern`` stored in ``job.executable`` using ``job.state``."""
+
+    def run(self, ctx: ExecutionContext, *, budget: int | None = None) -> RunResult:
+        job = ctx.job
+        if job.is_terminal:
+            return RunResult(status=job.status, result=job.result)
+
+        pattern = job.executable
+        if not isinstance(pattern, BasePattern):
+            return RunResult(
+                status=JobStatus.FAILED,
+                error=TypeError("BehaviorTreeRunner requires a BasePattern executable"),
+                propagate=True,
+            )
+
+        ticks = budget if budget is not None else 10_000
+        if ticks < 1:
+            raise ValueError("budget must be >= 1")
+
+        logical_status = job.status
+        if logical_status == JobStatus.PENDING:
+            logical_status = JobStatus.RUNNING
+
+        for _ in range(ticks):
+            try:
+                status = pattern.tick(job.state)
+            except Exception as exc:
+                return RunResult(status=JobStatus.FAILED, error=exc, propagate=True)
+
+            if status == PatternStatus.WAITING_FOR_INPUT:
+                return RunResult(status=JobStatus.WAITING_FOR_INPUT)
+
+            if status == PatternStatus.SUCCESS:
+                return RunResult(
+                    status=JobStatus.SUCCEEDED,
+                    result=job.state.get("__result__"),
+                )
+
+            if status == PatternStatus.FAILURE:
+                err = job.state.get("__error__")
+                return RunResult(
+                    status=JobStatus.FAILED,
+                    error=err if isinstance(err, BaseException) else RuntimeError("pattern failed"),
+                )
+
+            logical_status = JobStatus.RUNNING
+
+        if logical_status == JobStatus.RUNNING:
+            return RunResult(status=JobStatus.RUNNING)
+
+        return RunResult(
+            status=JobStatus.FAILED,
+            error=RuntimeError("pattern did not reach a terminal status"),
+        )

palm/common/__init__.py

@@ -0,0 +1,91 @@
+"""
+Shared coordination logic for Palm (non-plugin, non-core).
+
+``palm.common`` holds definition-driven submission, plan staging, persistence
+helpers, orchestration hooks, and pattern materialization — the glue between
+``palm.core`` engines, ``palm.definitions``, and extensible ``palm.patterns``.
+
+Extensible plugins live elsewhere:
+
+- ``palm.patterns`` — register via ``pattern_registry``
+- ``palm.providers`` — register via ``provider_registry``
+- ``palm.storages`` — register via ``storage_registry``
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from palm.common.executions.executor import DefinitionExecutor
+    from palm.common.executions.flow_submission import FlowSubmission
+    from palm.common.hooks.instance_persistence import InstancePersistenceHook
+    from palm.common.patterns.build_context import PatternBuildContext
+    from palm.common.persistence.definition_repository import DefinitionRepository
+    from palm.common.persistence.instance_repository import InstanceRepository
+    from palm.common.plans.execution_plan import ExecutionPlan
+    from palm.common.plans.process_plan import ProcessPlan
+    from palm.common.plans.registry import PlanRegistry, StoredPlan
+    from palm.instances import ProcessInstance, StatusHistoryEntry
+
+__all__ = [
+    "DefinitionBuildError",
+    "DefinitionExecutor",
+    "DefinitionNotFoundError",
+    "DefinitionRepository",
+    "ExecutionError",
+    "ExecutionPlan",
+    "FlowSubmission",
+    "InstanceNotFoundError",
+    "InstancePersistenceHook",
+    "InstanceRepository",
+    "InstanceResumeError",
+    "PatternBuildContext",
+    "PlanNotFoundError",
+    "PlanRegistry",
+    "PlanValidationError",
+    "ProcessInstance",
+    "ProcessPlan",
+    "StatusHistoryEntry",
+    "StoredPlan",
+    "build_pattern",
+    "prepare_flow_submission",
+    "prepare_process_plans",
+]
+
+_LAZY_EXPORTS: dict[str, tuple[str, str]] = {
+    "DefinitionBuildError": ("palm.common.exceptions", "DefinitionBuildError"),
+    "DefinitionNotFoundError": ("palm.common.exceptions", "DefinitionNotFoundError"),
+    "ExecutionError": ("palm.common.exceptions", "ExecutionError"),
+    "InstanceNotFoundError": ("palm.common.exceptions", "InstanceNotFoundError"),
+    "InstanceResumeError": ("palm.common.exceptions", "InstanceResumeError"),
+    "PlanNotFoundError": ("palm.common.exceptions", "PlanNotFoundError"),
+    "PlanValidationError": ("palm.common.exceptions", "PlanValidationError"),
+    "DefinitionExecutor": ("palm.common.executions.executor", "DefinitionExecutor"),
+    "FlowSubmission": ("palm.common.executions.flow_submission", "FlowSubmission"),
+    "prepare_flow_submission": ("palm.common.executions.flow_submission", "prepare_flow_submission"),
+    "prepare_process_plans": ("palm.common.executions.process_submission", "prepare_process_plans"),
+    "InstancePersistenceHook": ("palm.common.hooks.instance_persistence", "InstancePersistenceHook"),
+    "PatternBuildContext": ("palm.common.patterns.build_context", "PatternBuildContext"),
+    "build_pattern": ("palm.common.patterns.builder", "build_pattern"),
+    "DefinitionRepository": ("palm.common.persistence.definition_repository", "DefinitionRepository"),
+    "InstanceRepository": ("palm.common.persistence.instance_repository", "InstanceRepository"),
+    "ExecutionPlan": ("palm.common.plans.execution_plan", "ExecutionPlan"),
+    "ProcessPlan": ("palm.common.plans.process_plan", "ProcessPlan"),
+    "PlanRegistry": ("palm.common.plans.registry", "PlanRegistry"),
+    "StoredPlan": ("palm.common.plans.registry", "StoredPlan"),
+    "ProcessInstance": ("palm.instances", "ProcessInstance"),
+    "StatusHistoryEntry": ("palm.instances", "StatusHistoryEntry"),
+}
+
+
+def __getattr__(name: str):
+    if name not in _LAZY_EXPORTS:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    module_path, attr = _LAZY_EXPORTS[name]
+    import importlib
+
+    module = importlib.import_module(module_path)
+    value = getattr(module, attr)
+    globals()[name] = value
+    return value

palm/common/exceptions.py

@@ -0,0 +1,50 @@
+"""
+Execution-layer exceptions (outside core).
+"""
+
+from __future__ import annotations
+
+
+class ExecutionError(Exception):
+    """Base error for definition-driven execution."""
+
+
+class DefinitionBuildError(ExecutionError):
+    """Raised when a flow or process definition cannot be built."""
+
+
+class DefinitionNotFoundError(ExecutionError):
+    """Raised when a definition name or id cannot be resolved."""
+
+    def __init__(self, kind: str, ref: str) -> None:
+        super().__init__(f"{kind} definition not found: {ref!r}")
+        self.kind = kind
+        self.ref = ref
+
+
+class InstanceNotFoundError(ExecutionError):
+    """Raised when a process instance id cannot be loaded."""
+
+    def __init__(self, instance_id: str) -> None:
+        super().__init__(f"Process instance not found: {instance_id!r}")
+        self.instance_id = instance_id
+
+
+class InstanceResumeError(ExecutionError):
+    """Raised when an instance cannot be resumed (terminal, missing flow, etc.)."""
+
+
+class InstanceActiveLimitError(ExecutionError):
+    """Raised when the active instance limit is exceeded."""
+
+
+class PlanValidationError(ExecutionError):
+    """Raised when an :class:`~palm.common.plans.execution_plan.ExecutionPlan` fails pre-submit checks."""
+
+
+class PlanNotFoundError(ExecutionError):
+    """Raised when a stored plan id cannot be resolved."""
+
+    def __init__(self, plan_id: str) -> None:
+        super().__init__(f"Execution plan not found: {plan_id!r}")
+        self.plan_id = plan_id

palm/common/executions/__init__.py

@@ -0,0 +1,12 @@
+"""Definition-driven submission — prepare and submit orchestration jobs."""
+
+from palm.common.executions.executor import DefinitionExecutor
+from palm.common.executions.flow_submission import FlowSubmission, prepare_flow_submission
+from palm.common.executions.process_submission import prepare_process_plans
+
+__all__ = [
+    "DefinitionExecutor",
+    "FlowSubmission",
+    "prepare_flow_submission",
+    "prepare_process_plans",
+]