workload-profile-controller 0.1.0__py3-none-any.whl

workload_profile_controller/cli.py

@@ -0,0 +1,154 @@
+import argparse
+
+from .application import create_controller
+from .config_loader import load_config
+
+
+def create_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="wpc",
+        description="Safe and configurable workload profile controller.",
+    )
+
+    parser.add_argument(
+        "--config",
+        required=True,
+        help="Path to the profile configuration file.",
+    )
+
+    subparsers = parser.add_subparsers(
+        dest="command",
+        required=True,
+    )
+
+    subparsers.add_parser(
+        "profiles",
+        help="List configured profiles.",
+    )
+
+    subparsers.add_parser(
+        "status",
+        help="Show the current resource status.",
+    )
+
+    plan_parser = subparsers.add_parser(
+    "plan",
+    help="Plan a transition without changing resources.",
+    )
+
+    plan_parser.add_argument(
+    "target_profile",
+    help="Target profile to plan.",
+    )
+
+    transition_parser = subparsers.add_parser(
+        "transition",
+        help="Transition to a configured profile.",
+    )
+
+    transition_parser.add_argument(
+        "target_profile",
+        help="Target profile to transition to.",
+    )
+
+    return parser
+
+
+def main(argv=None) -> int:
+    parser = create_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "profiles":
+        config = load_config(args.config)
+
+        for profile in config.profiles.values():
+            print(
+                f"{profile.name}\t{profile.description}"
+            )
+
+        return 0
+
+    if args.command == "status":
+        controller = create_controller(args.config)
+        statuses = controller.get_resource_statuses()
+
+        for resource_id, status in statuses.items():
+            print(
+                f"{resource_id}\t{status.value}"
+            )
+
+        return 0
+
+    if args.command == "plan":
+        controller = create_controller(args.config)
+
+        current_profile = controller.reconcile()
+        target_profile = args.target_profile
+
+        if not controller.has_profile(target_profile):
+            parser.error(
+                f"Unknown profile: {target_profile}"
+            )
+
+        plan = controller.build_transition_plan(
+            current_profile,
+            target_profile,
+        )
+
+        print(f"Current profile: {current_profile}")
+        print(f"Target profile: {target_profile}")
+        print()
+        print("Plan:")
+
+        if not plan.actions:
+            print("  no changes required")
+        else:
+            for action in plan.actions:
+                print(
+                    f"  {action.action.value} "
+                    f"{action.resource_id}"
+                )
+
+        print()
+        print("No changes were made.")
+
+        return 0
+
+    if args.command == "transition":
+        controller = create_controller(args.config)
+
+        current_profile = controller.reconcile()
+        target_profile = args.target_profile
+
+        if not controller.has_profile(target_profile):
+            parser.error(
+                f"Unknown profile: {target_profile}"
+            )
+
+        if current_profile == target_profile:
+            print(
+                f"Already in profile: {target_profile}"
+            )
+            return 0
+
+        print(
+            f"Transitioning from "
+            f"{current_profile} to {target_profile}..."
+        )
+
+        controller.transition(
+            current_profile,
+            target_profile,
+        )
+
+        print(
+            f"Transition completed: {target_profile}"
+        )
+
+        return 0
+
+    parser.error(f"Unknown command: {args.command}")
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

workload_profile_controller/config.py

@@ -0,0 +1,21 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ResourceConfig:
+    name: str
+    description: str
+
+
+@dataclass(frozen=True)
+class ProfileConfig:
+    name: str
+    description: str
+    running: tuple[str, ...]
+    stopped: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class Config:
+    resources: dict[str, ResourceConfig]
+    profiles: dict[str, ProfileConfig]

workload_profile_controller/config_loader.py

@@ -0,0 +1,40 @@
+from pathlib import Path
+
+import yaml
+
+from .config import Config, ProfileConfig, ResourceConfig
+from .config_validator import validate_config
+
+
+def load_config(path: str | Path) -> Config:
+    config_path = Path(path)
+
+    with config_path.open("r", encoding="utf-8") as file:
+        data = yaml.safe_load(file)
+
+    resources = {
+        resource_id: ResourceConfig(
+            name=resource_id,
+            description=resource_data.get("description", ""),
+        )
+        for resource_id, resource_data in data["resources"].items()
+    }
+
+    profiles = {
+        name: ProfileConfig(
+            name=name,
+            description=profile_data.get("description", ""),
+            running=tuple(profile_data.get("running", [])),
+            stopped=tuple(profile_data.get("stopped", [])),
+        )
+        for name, profile_data in data["profiles"].items()
+    }
+
+    config = Config(
+        resources=resources,
+        profiles=profiles,
+    )
+
+    validate_config(config)
+
+    return config

workload_profile_controller/config_validator.py

@@ -0,0 +1,106 @@
+from .config import Config
+
+
+def validate_config(config: Config) -> None:
+    # R-01 — At least one resource
+    if not config.resources:
+        raise ValueError("At least one resource is required")
+
+    # R-02 — Resource identity
+    for resource_id, resource in config.resources.items():
+        if not isinstance(resource_id, str) or not resource_id.strip():
+            raise ValueError("Resource ID must not be empty")
+
+        if not isinstance(resource.name, str) or not resource.name.strip():
+            raise ValueError(
+                f"Resource name must not be empty: {resource_id}"
+            )
+
+    # At least one profile
+    if not config.profiles:
+        raise ValueError("At least one profile is required")
+
+    managed_resources = set(config.resources)
+
+    # Validate every profile
+    for profile_name, profile in config.profiles.items():
+        # R-03 — Profile name must match dictionary key
+        if profile.name != profile_name:
+            raise ValueError(
+                f"Profile name mismatch: key={profile_name}, "
+                f"name={profile.name}"
+            )
+
+        running = profile.running
+        stopped = profile.stopped
+
+        # R-04 — All referenced resources must exist
+        referenced_resources = set(running) | set(stopped)
+
+        unknown_resources = referenced_resources - managed_resources
+
+        if unknown_resources:
+            raise ValueError(
+                f"Profile {profile_name} references unknown resources: "
+                f"{sorted(unknown_resources)}"
+            )
+
+        # R-05 — Mutual exclusivity
+        conflicting_resources = set(running) & set(stopped)
+
+        if conflicting_resources:
+            raise ValueError(
+                f"Profile {profile_name} has resources in both states: "
+                f"{sorted(conflicting_resources)}"
+            )
+
+        # R-06 — No duplicates
+        if len(running) != len(set(running)):
+            raise ValueError(
+                f"Profile {profile_name} contains duplicate resources in running"
+            )
+
+        if len(stopped) != len(set(stopped)):
+            raise ValueError(
+                f"Profile {profile_name} contains duplicate resources in stopped"
+            )
+
+        # R-07 — Exactly one state per managed resource
+        if referenced_resources != managed_resources:
+            missing_resources = managed_resources - referenced_resources
+
+            if missing_resources:
+                raise ValueError(
+                    f"Profile {profile_name} does not define a state "
+                    f"for resources: {sorted(missing_resources)}"
+                )
+
+        # R-10 — No empty profile
+        if not running and not stopped:
+            raise ValueError(
+                f"Profile {profile_name} cannot be empty"
+            )
+
+    # R-08 — Same resource universe across all profiles
+    profile_universes = {
+        profile_name: set(profile.running) | set(profile.stopped)
+        for profile_name, profile in config.profiles.items()
+    }
+
+    universes = list(profile_universes.values())
+    reference_universe = universes[0]
+
+    for profile_name, universe in profile_universes.items():
+        if universe != reference_universe:
+            raise ValueError(
+                f"Profile {profile_name} manages a different resource universe"
+            )
+
+    # R-09 — Complete deterministic state
+    for profile_name, profile in config.profiles.items():
+        universe = set(profile.running) | set(profile.stopped)
+
+        if universe != managed_resources:
+            raise ValueError(
+                f"Profile {profile_name} does not define a complete state"
+            )

workload_profile_controller/controller.py

@@ -0,0 +1,154 @@
+from enum import Enum
+
+from .backend import ResourceStatus
+from .policy import Policy
+
+
+class ControllerState(Enum):
+    IDLE = "idle"
+    TRANSITIONING = "transitioning"
+    LOCKED = "locked"
+
+
+class Controller:
+    def __init__(self, config, backend):
+        self._config = config
+        self._backend = backend
+        self._policy = Policy(config)
+        self.state = ControllerState.IDLE
+
+    def get_profile(self, name):
+        return self._policy.get_profile(name)
+
+    def has_profile(self, name):
+        return self._policy.has_profile(name)
+
+    def build_transition_plan(self, source_profile, target_profile):
+        return self._policy.build_transition_plan(
+            source_profile,
+            target_profile,
+        )
+
+    def transition(self, source_profile, target_profile):
+        if self.state == ControllerState.LOCKED:
+            raise RuntimeError("Controller is locked")
+
+        self._validate_profile_state(source_profile)
+        self._validate_profile_resources(target_profile)
+
+        self.state = ControllerState.TRANSITIONING
+
+        try:
+            plan = self.build_transition_plan(
+                source_profile,
+                target_profile,
+            )
+
+            for action in plan.actions:
+                if action.action.value == "stop":
+                    self._backend.stop(action.resource_id)
+
+                    status = self._backend.get_status(action.resource_id)
+
+                    if status != ResourceStatus.STOPPED:
+                        raise RuntimeError(
+                            f"Resource did not stop: {action.resource_id}"
+                        )
+
+                elif action.action.value == "start":
+                    self._backend.start(action.resource_id)
+
+                    status = self._backend.get_status(action.resource_id)
+
+                    if status != ResourceStatus.RUNNING:
+                        raise RuntimeError(
+                            f"Resource did not start: {action.resource_id}"
+                        )
+
+            self._validate_target_profile_state(target_profile)
+
+            self.state = ControllerState.IDLE
+
+        except Exception:
+            self.state = ControllerState.LOCKED
+            raise
+
+    def _validate_profile_resources(self, profile_name):
+        profile = self._policy.get_profile(profile_name)
+
+        for resource_id in profile.running:
+            self._backend.get_status(resource_id)
+
+        for resource_id in profile.stopped:
+            self._backend.get_status(resource_id)
+
+    def _validate_profile_state(self, profile_name):
+        profile = self._policy.get_profile(profile_name)
+
+        for resource_id in profile.running:
+            status = self._backend.get_status(resource_id)
+
+            if status != ResourceStatus.RUNNING:
+                raise RuntimeError("Source profile is not active")
+
+        for resource_id in profile.stopped:
+            status = self._backend.get_status(resource_id)
+
+            if status != ResourceStatus.STOPPED:
+                raise RuntimeError("Source profile is not active")
+
+    def _validate_target_profile_state(self, profile_name):
+        profile = self._policy.get_profile(profile_name)
+
+        for resource_id in profile.running:
+            status = self._backend.get_status(resource_id)
+
+            if status != ResourceStatus.RUNNING:
+                raise RuntimeError("Target profile is not active")
+
+        for resource_id in profile.stopped:
+            status = self._backend.get_status(resource_id)
+
+            if status != ResourceStatus.STOPPED:
+                raise RuntimeError("Target profile is not active")
+
+    def get_resource_statuses(self):
+        statuses = {}
+
+        for resource_id in self._config.resources:
+            statuses[resource_id] = self._backend.get_status(resource_id)
+
+        return statuses
+
+    def reconcile(self):
+        for profile_name in self._policy.list_profiles():
+            profile = self._policy.get_profile(profile_name)
+
+            matches = True
+
+            for resource_id in profile.running:
+                status = self._backend.get_status(resource_id)
+
+                if status != ResourceStatus.RUNNING:
+                    matches = False
+                    break
+
+            if not matches:
+                continue
+
+            for resource_id in profile.stopped:
+                status = self._backend.get_status(resource_id)
+
+                if status != ResourceStatus.STOPPED:
+                    matches = False
+                    break
+
+            if matches:
+                self.state = ControllerState.IDLE
+                return profile_name
+
+        self.state = ControllerState.LOCKED
+
+        raise RuntimeError(
+            "Current resource state does not match any profile"
+        )

workload_profile_controller/errors.py

@@ -0,0 +1,26 @@
+class BackendError(Exception):
+    """Base exception for backend failures."""
+
+
+class ResourceNotFoundError(BackendError):
+    """Raised when a resource cannot be resolved."""
+
+
+class ResourceAmbiguousError(BackendError):
+    """Raised when a resource resolves to multiple infrastructure resources."""
+
+
+class BackendUnavailableError(BackendError):
+    """Raised when the backend cannot be reached or used."""
+
+
+class InvalidResourceStateError(BackendError):
+    """Raised when a resource is in an invalid state for an operation."""
+
+
+class TaskTimeoutError(Exception):
+    """Raised when a backend task does not finish before the timeout."""
+
+
+class TaskFailedError(Exception):
+    """Raised when a backend task finishes unsuccessfully."""

workload_profile_controller/policy.py

@@ -0,0 +1,67 @@
+from dataclasses import dataclass
+from enum import Enum
+
+from .config import Config, ProfileConfig
+
+
+class ActionType(Enum):
+    STOP = "stop"
+    START = "start"
+
+
+@dataclass(frozen=True)
+class TransitionAction:
+    action: ActionType
+    resource_id: str
+
+
+@dataclass(frozen=True)
+class TransitionPlan:
+    actions: tuple[TransitionAction, ...]
+
+
+class Policy:
+    def __init__(self, config: Config):
+        self._config = config
+
+    def get_profile(self, name: str) -> ProfileConfig:
+        if name not in self._config.profiles:
+            raise ValueError(f"Unknown profile: {name}")
+
+        return self._config.profiles[name]
+
+    def list_profiles(self) -> tuple[str, ...]:
+        return tuple(self._config.profiles.keys())
+
+    def has_profile(self, name: str) -> bool:
+        return name in self._config.profiles
+
+    def build_transition_plan(
+        self,
+        source_profile: str,
+        target_profile: str,
+    ) -> TransitionPlan:
+        source = self.get_profile(source_profile)
+        target = self.get_profile(target_profile)
+
+        source_running = set(source.running)
+        target_running = set(target.running)
+
+        stop = tuple(
+            resource_id
+            for resource_id in source.running
+            if resource_id not in target_running
+        )
+
+        start = tuple(
+            resource_id
+            for resource_id in target.running
+            if resource_id not in source_running
+        )
+
+        return TransitionPlan(
+            actions=(
+                *(TransitionAction(ActionType.STOP, resource_id) for resource_id in stop),
+                *(TransitionAction(ActionType.START, resource_id) for resource_id in start),
+            )
+        )