agent_hypervisor 3.1.0__py3-none-any.whl

hypervisor/saga/checkpoint.py

@@ -0,0 +1,110 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+# Public Preview — basic implementation
+"""
+Execution Checkpoints — stub implementation.
+
+Public Preview: checkpoints are recorded but replay/skip logic is removed.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import uuid
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import Any
+
+
+@dataclass
+class SemanticCheckpoint:
+    """A checkpoint record (Public Preview: stored but not used for replay)."""
+
+    checkpoint_id: str = field(default_factory=lambda: f"ckpt:{uuid.uuid4().hex[:8]}")
+    saga_id: str = ""
+    step_id: str = ""
+    goal_description: str = ""
+    goal_hash: str = ""
+    achieved_at: datetime = field(default_factory=lambda: datetime.now(UTC))
+    state_snapshot: dict[str, Any] = field(default_factory=dict)
+    is_valid: bool = True
+    invalidated_reason: str | None = None
+
+    @staticmethod
+    def compute_goal_hash(goal: str, step_id: str) -> str:
+        """Compute deterministic hash for a goal."""
+        content = f"{goal}:{step_id}"
+        return hashlib.sha256(content.encode()).hexdigest()[:16]
+
+
+class CheckpointManager:
+    """
+    Checkpoint stub (Public Preview: saves checkpoints but no replay logic).
+    """
+
+    def __init__(self) -> None:
+        self._checkpoints: dict[str, list[SemanticCheckpoint]] = {}
+        self._by_goal_hash: dict[str, SemanticCheckpoint] = {}
+
+    def save(
+        self,
+        saga_id: str,
+        step_id: str,
+        goal_description: str,
+        state_snapshot: dict | None = None,
+    ) -> SemanticCheckpoint:
+        """Save a checkpoint record."""
+        goal_hash = SemanticCheckpoint.compute_goal_hash(goal_description, step_id)
+        checkpoint = SemanticCheckpoint(
+            saga_id=saga_id,
+            step_id=step_id,
+            goal_description=goal_description,
+            goal_hash=goal_hash,
+            state_snapshot=state_snapshot or {},
+        )
+        self._checkpoints.setdefault(saga_id, []).append(checkpoint)
+        self._by_goal_hash[goal_hash] = checkpoint
+        return checkpoint
+
+    def is_achieved(
+        self,
+        saga_id: str,
+        goal_description: str,
+        step_id: str,
+    ) -> bool:
+        """Always returns False (Public Preview: no skip-on-replay)."""
+        return False
+
+    def get_checkpoint(
+        self,
+        saga_id: str,
+        goal_description: str,
+        step_id: str,
+    ) -> SemanticCheckpoint | None:
+        """Returns None (Public Preview: no replay support)."""
+        return None
+
+    def invalidate(
+        self,
+        saga_id: str,
+        step_id: str,
+        reason: str = "",
+    ) -> int:
+        """No-op in Public Preview."""
+        return 0
+
+    def get_saga_checkpoints(self, saga_id: str) -> list[SemanticCheckpoint]:
+        """Get all checkpoints for a saga."""
+        return list(self._checkpoints.get(saga_id, []))
+
+    def get_replay_plan(self, saga_id: str, steps: list[str]) -> list[str]:
+        """All steps need execution (Public Preview: no skip logic)."""
+        return list(steps)
+
+    @property
+    def total_checkpoints(self) -> int:
+        return sum(len(v) for v in self._checkpoints.values())
+
+    @property
+    def valid_checkpoints(self) -> int:
+        return self.total_checkpoints

hypervisor/saga/dsl.py

@@ -0,0 +1,190 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+# Public Preview — basic implementation
+"""
+Declarative Saga DSL — stub implementation.
+
+Public Preview: DSL parsing is retained for basic step definitions only.
+Fan-out groups in DSL are ignored (sequential execution only).
+"""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from typing import Any
+
+from hypervisor.saga.fan_out import FanOutPolicy
+from hypervisor.saga.schema import SagaSchemaValidator
+from hypervisor.saga.state_machine import SagaStep
+
+
+@dataclass
+class SagaDSLStep:
+    """A step parsed from the DSL definition."""
+
+    id: str = ""
+    action_id: str = ""
+    agent: str = ""
+    execute_api: str = ""
+    undo_api: str | None = None
+    timeout: int = 300
+    retries: int = 0
+    checkpoint_goal: str | None = None
+
+
+@dataclass
+class SagaDSLFanOut:
+    """A fan-out group (Public Preview: ignored during execution)."""
+
+    policy: FanOutPolicy = FanOutPolicy.ALL_MUST_SUCCEED
+    branch_step_ids: list[str] = field(default_factory=list)
+
+
+@dataclass
+class SagaDefinition:
+    """A complete saga definition parsed from DSL."""
+
+    name: str = ""
+    session_id: str = ""
+    saga_id: str = field(default_factory=lambda: f"saga:{uuid.uuid4().hex[:8]}")
+    steps: list[SagaDSLStep] = field(default_factory=list)
+    fan_outs: list[SagaDSLFanOut] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def step_ids(self) -> list[str]:
+        return [s.id for s in self.steps]
+
+    @property
+    def fan_out_step_ids(self) -> set[str]:
+        return set()
+
+    @property
+    def sequential_steps(self) -> list[SagaDSLStep]:
+        """All steps are sequential in Public Preview."""
+        return list(self.steps)
+
+
+class SagaDSLParser:
+    """
+    Parses saga definitions from dict.
+
+    Public Preview: fan-out groups are parsed but ignored during execution.
+    """
+
+    def __init__(self, *, schema_validation: bool = False) -> None:
+        self._schema_validator = SagaSchemaValidator() if schema_validation else None
+
+    def parse(self, definition: dict[str, Any]) -> SagaDefinition:
+        """Parse a saga definition dict into a SagaDefinition.
+
+        If schema_validation was enabled at construction, validates against
+        the JSON schema before parsing.
+        """
+        if self._schema_validator is not None:
+            self._schema_validator.validate_or_raise(definition)
+
+        name = definition.get("name", "")
+        if not name:
+            raise SagaDSLError("Saga definition must have a 'name'")
+
+        session_id = definition.get("session_id", "")
+        if not session_id:
+            raise SagaDSLError("Saga definition must have a 'session_id'")
+
+        raw_steps = definition.get("steps", [])
+        if not raw_steps:
+            raise SagaDSLError("Saga must have at least one step")
+
+        steps = []
+        step_ids = set()
+        for raw in raw_steps:
+            step = self._parse_step(raw)
+            if step.id in step_ids:
+                raise SagaDSLError(f"Duplicate step ID: {step.id}")
+            step_ids.add(step.id)
+            steps.append(step)
+
+        return SagaDefinition(
+            name=name,
+            session_id=session_id,
+            saga_id=definition.get("saga_id", f"saga:{uuid.uuid4().hex[:8]}"),
+            steps=steps,
+            fan_outs=[],
+            metadata=definition.get("metadata", {}),
+        )
+
+    def _parse_step(self, raw: dict) -> SagaDSLStep:
+        step_id = raw.get("id", "")
+        if not step_id:
+            raise SagaDSLError("Each step must have an 'id'")
+
+        action_id = raw.get("action_id", "")
+        if not action_id:
+            raise SagaDSLError(f"Step {step_id} must have an 'action_id'")
+
+        agent = raw.get("agent", "")
+        if not agent:
+            raise SagaDSLError(f"Step {step_id} must have an 'agent'")
+
+        return SagaDSLStep(
+            id=step_id,
+            action_id=action_id,
+            agent=agent,
+            execute_api=raw.get("execute_api", ""),
+            undo_api=raw.get("undo_api"),
+            timeout=raw.get("timeout", 300),
+            retries=raw.get("retries", 0),
+            checkpoint_goal=raw.get("checkpoint_goal"),
+        )
+
+    def _parse_fan_out(self, raw: dict, valid_step_ids: set[str]) -> SagaDSLFanOut:
+        """Parse fan-out definition (Public Preview: retained for API compat)."""
+        return SagaDSLFanOut(
+            policy=FanOutPolicy.ALL_MUST_SUCCEED,
+            branch_step_ids=raw.get("branches", []),
+        )
+
+    def to_saga_steps(self, definition: SagaDefinition) -> list[SagaStep]:
+        """Convert a SagaDefinition into SagaStep objects."""
+        return [
+            SagaStep(
+                step_id=s.id,
+                action_id=s.action_id,
+                agent_did=s.agent,
+                execute_api=s.execute_api,
+                undo_api=s.undo_api,
+                timeout_seconds=s.timeout,
+                max_retries=s.retries,
+            )
+            for s in definition.steps
+        ]
+
+    def validate(self, definition: dict[str, Any]) -> list[str]:
+        """Validate a definition and return list of errors (empty = valid)."""
+        errors = []
+        if not definition.get("name"):
+            errors.append("Missing 'name'")
+        if not definition.get("session_id"):
+            errors.append("Missing 'session_id'")
+        if not definition.get("steps"):
+            errors.append("Missing 'steps'")
+        else:
+            step_ids = set()
+            for i, step in enumerate(definition["steps"]):
+                if not step.get("id"):
+                    errors.append(f"Step {i} missing 'id'")
+                elif step["id"] in step_ids:
+                    errors.append(f"Duplicate step ID: {step['id']}")
+                else:
+                    step_ids.add(step["id"])
+                if not step.get("action_id"):
+                    errors.append(f"Step {step.get('id', i)} missing 'action_id'")
+                if not step.get("agent"):
+                    errors.append(f"Step {step.get('id', i)} missing 'agent'")
+        return errors
+
+
+class SagaDSLError(Exception):
+    """Raised for invalid saga DSL definitions."""

hypervisor/saga/fan_out.py

@@ -0,0 +1,126 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+# Public Preview — basic implementation
+"""
+Parallel Saga Fan-Out — stub implementation.
+
+Public Preview: only sequential ALL_MUST_SUCCEED execution.
+Fan-out groups execute branches one at a time.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import uuid
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+from hypervisor.saga.state_machine import SagaStep, StepState
+
+
+class FanOutPolicy(str, Enum):
+    ALL_MUST_SUCCEED = "all_must_succeed"
+    MAJORITY_MUST_SUCCEED = "majority_must_succeed"
+    ANY_MUST_SUCCEED = "any_must_succeed"
+
+
+@dataclass
+class FanOutBranch:
+    branch_id: str = field(default_factory=lambda: f"branch:{uuid.uuid4().hex[:8]}")
+    step: SagaStep | None = None
+    result: Any = None
+    error: str | None = None
+    succeeded: bool = False
+
+
+@dataclass
+class FanOutGroup:
+    group_id: str = field(default_factory=lambda: f"fanout:{uuid.uuid4().hex[:8]}")
+    saga_id: str = ""
+    policy: FanOutPolicy = FanOutPolicy.ALL_MUST_SUCCEED
+    branches: list[FanOutBranch] = field(default_factory=list)
+    resolved: bool = False
+    policy_satisfied: bool = False
+    compensation_needed: list[str] = field(default_factory=list)
+
+    @property
+    def success_count(self) -> int:
+        return sum(1 for b in self.branches if b.succeeded)
+
+    @property
+    def failure_count(self) -> int:
+        return sum(1 for b in self.branches if not b.succeeded and b.error)
+
+    @property
+    def total_branches(self) -> int:
+        return len(self.branches)
+
+    def check_policy(self) -> bool:
+        """Public Preview: only ALL_MUST_SUCCEED is enforced."""
+        return self.success_count == self.total_branches
+
+
+class FanOutOrchestrator:
+    """Fan-out stub (Public Preview: sequential execution, ALL_MUST_SUCCEED only)."""
+
+    def __init__(self) -> None:
+        self._groups: dict[str, FanOutGroup] = {}
+
+    def create_group(self, saga_id: str, policy: FanOutPolicy = FanOutPolicy.ALL_MUST_SUCCEED) -> FanOutGroup:
+        group = FanOutGroup(saga_id=saga_id, policy=FanOutPolicy.ALL_MUST_SUCCEED)
+        self._groups[group.group_id] = group
+        return group
+
+    def add_branch(self, group_id: str, step: SagaStep) -> FanOutBranch:
+        group = self._get_group(group_id)
+        branch = FanOutBranch(step=step)
+        group.branches.append(branch)
+        return branch
+
+    async def execute(
+        self, group_id: str, executors: dict[str, Callable[..., Any]], timeout_seconds: int = 300,
+    ) -> FanOutGroup:
+        """Execute branches sequentially (Public Preview)."""
+        group = self._get_group(group_id)
+
+        for branch in group.branches:
+            if not branch.step:
+                branch.error = "No step assigned"
+                continue
+            executor = executors.get(branch.step.step_id)
+            if not executor:
+                branch.error = f"No executor for step {branch.step.step_id}"
+                continue
+            try:
+                branch.step.transition(StepState.EXECUTING)
+                result = await asyncio.wait_for(executor(), timeout=branch.step.timeout_seconds)
+                branch.result = result
+                branch.succeeded = True
+                branch.step.execute_result = result
+                branch.step.transition(StepState.COMMITTED)
+            except Exception as e:
+                branch.error = str(e)
+                branch.step.error = str(e)
+                branch.step.transition(StepState.FAILED)
+                break  # ALL_MUST_SUCCEED: stop on first failure
+
+        group.policy_satisfied = group.check_policy()
+        group.resolved = True
+        if not group.policy_satisfied:
+            group.compensation_needed = [b.step.step_id for b in group.branches if b.succeeded and b.step]
+        return group
+
+    def get_group(self, group_id: str) -> FanOutGroup | None:
+        return self._groups.get(group_id)
+
+    def _get_group(self, group_id: str) -> FanOutGroup:
+        group = self._groups.get(group_id)
+        if not group:
+            raise ValueError(f"Fan-out group {group_id} not found")
+        return group
+
+    @property
+    def active_groups(self) -> list[FanOutGroup]:
+        return [g for g in self._groups.values() if not g.resolved]

hypervisor/saga/orchestrator.py

@@ -0,0 +1,229 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+# Public Preview — basic implementation
+"""
+Semantic Saga Orchestrator
+
+Sequential step execution with reverse-order compensation on failure.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import uuid
+from collections.abc import Callable
+from typing import Any
+
+from hypervisor.constants import (
+    SAGA_DEFAULT_MAX_RETRIES,
+    SAGA_DEFAULT_RETRY_DELAY_SECONDS,
+    SAGA_DEFAULT_STEP_TIMEOUT_SECONDS,
+)
+from hypervisor.saga.state_machine import (
+    Saga,
+    SagaState,
+    SagaStateError,
+    SagaStep,
+    StepState,
+)
+
+
+class SagaTimeoutError(Exception):
+    """Raised when a saga step exceeds its timeout."""
+
+
+class SagaOrchestrator:
+    """
+    Orchestrates multi-step agent transactions with saga semantics.
+
+    Forward execution records each step. On failure, the orchestrator
+    iterates the Reversibility Registry in reverse order, calling
+    Undo_API for each committed step. If any Undo_API fails,
+    Joint Liability penalty is triggered.
+    """
+
+    DEFAULT_MAX_RETRIES = SAGA_DEFAULT_MAX_RETRIES
+    DEFAULT_RETRY_DELAY_SECONDS = SAGA_DEFAULT_RETRY_DELAY_SECONDS
+
+    def __init__(self) -> None:
+        self._sagas: dict[str, Saga] = {}
+
+    def create_saga(self, session_id: str) -> Saga:
+        """Create a new saga for a session."""
+        saga = Saga(
+            saga_id=f"saga:{uuid.uuid4()}",
+            session_id=session_id,
+        )
+        self._sagas[saga.saga_id] = saga
+        return saga
+
+    def add_step(
+        self,
+        saga_id: str,
+        action_id: str,
+        agent_did: str,
+        execute_api: str,
+        undo_api: str | None = None,
+        timeout_seconds: int = SAGA_DEFAULT_STEP_TIMEOUT_SECONDS,
+        max_retries: int = 0,
+    ) -> SagaStep:
+        """Add a step to a saga."""
+        saga = self._get_saga(saga_id)
+        step = SagaStep(
+            step_id=f"step:{uuid.uuid4()}",
+            action_id=action_id,
+            agent_did=agent_did,
+            execute_api=execute_api,
+            undo_api=undo_api,
+            timeout_seconds=timeout_seconds,
+            max_retries=max_retries,
+        )
+        saga.steps.append(step)
+        return step
+
+    async def execute_step(
+        self,
+        saga_id: str,
+        step_id: str,
+        executor: Callable[..., Any],
+    ) -> Any:
+        """
+        Execute a single saga step with timeout and retry support.
+
+        Args:
+            saga_id: Saga identifier
+            step_id: Step identifier
+            executor: Async callable that performs the action
+
+        Returns:
+            Result from the executor
+
+        Raises:
+            SagaStateError: If step is not in PENDING state
+            SagaTimeoutError: If step exceeds its timeout
+        """
+        saga = self._get_saga(saga_id)
+        step = self._get_step(saga, step_id)
+
+        last_error: Exception | None = None
+        attempts = 1 + step.max_retries
+
+        for attempt in range(attempts):
+            step.retry_count = attempt
+            step.transition(StepState.EXECUTING)
+            try:
+                result = await asyncio.wait_for(
+                    executor(),
+                    timeout=step.timeout_seconds,
+                )
+                step.execute_result = result
+                step.transition(StepState.COMMITTED)
+                return result
+            except TimeoutError:
+                last_error = SagaTimeoutError(
+                    f"Step {step_id} timed out after {step.timeout_seconds}s "
+                    f"(attempt {attempt + 1}/{attempts})"
+                )
+                step.error = str(last_error)
+                step.transition(StepState.FAILED)
+                if attempt < attempts - 1:
+                    # Reset to PENDING for retry
+                    step.state = StepState.PENDING
+                    step.error = None
+                    await asyncio.sleep(
+                        self.DEFAULT_RETRY_DELAY_SECONDS * (attempt + 1)
+                    )
+            except Exception as e:
+                last_error = e
+                step.error = str(e)
+                step.transition(StepState.FAILED)
+                if attempt < attempts - 1:
+                    step.state = StepState.PENDING
+                    step.error = None
+                    await asyncio.sleep(
+                        self.DEFAULT_RETRY_DELAY_SECONDS * (attempt + 1)
+                    )
+
+        # All retries exhausted
+        if last_error:
+            raise last_error
+        raise SagaStateError("Step execution failed with no error captured")
+
+    async def compensate(
+        self,
+        saga_id: str,
+        compensator: Callable[[SagaStep], Any],
+    ) -> list[SagaStep]:
+        """
+        Run compensation (rollback) for all committed steps in reverse order.
+
+        Args:
+            saga_id: Saga identifier
+            compensator: Async callable that takes a SagaStep and calls its Undo_API
+
+        Returns:
+            List of steps that failed compensation (empty = full success)
+        """
+        saga = self._get_saga(saga_id)
+        saga.transition(SagaState.COMPENSATING)
+
+        failed_compensations: list[SagaStep] = []
+
+        for step in saga.committed_steps_reversed:
+            if not step.undo_api:
+                step.state = StepState.COMPENSATION_FAILED
+                step.error = "No Undo_API available"
+                failed_compensations.append(step)
+                continue
+
+            step.transition(StepState.COMPENSATING)
+            try:
+                result = await asyncio.wait_for(
+                    compensator(step),
+                    timeout=step.timeout_seconds,
+                )
+                step.compensation_result = result
+                step.transition(StepState.COMPENSATED)
+            except TimeoutError:
+                step.error = f"Compensation timed out after {step.timeout_seconds}s"
+                step.transition(StepState.COMPENSATION_FAILED)
+                failed_compensations.append(step)
+            except Exception as e:
+                step.error = f"Compensation failed: {e}"
+                step.transition(StepState.COMPENSATION_FAILED)
+                failed_compensations.append(step)
+
+        if failed_compensations:
+            saga.transition(SagaState.ESCALATED)
+            saga.error = (
+                f"{len(failed_compensations)} step(s) failed compensation — "
+                "Joint Liability penalty triggered"
+            )
+        else:
+            saga.transition(SagaState.COMPLETED)
+
+        return failed_compensations
+
+    def get_saga(self, saga_id: str) -> Saga | None:
+        """Get a saga by ID."""
+        return self._sagas.get(saga_id)
+
+    @property
+    def active_sagas(self) -> list[Saga]:
+        """Get all non-terminal sagas."""
+        return [
+            s for s in self._sagas.values()
+            if s.state in (SagaState.RUNNING, SagaState.COMPENSATING)
+        ]
+
+    def _get_saga(self, saga_id: str) -> Saga:
+        saga = self._sagas.get(saga_id)
+        if not saga:
+            raise SagaStateError(f"Saga {saga_id} not found")
+        return saga
+
+    def _get_step(self, saga: Saga, step_id: str) -> SagaStep:
+        for step in saga.steps:
+            if step.step_id == step_id:
+                return step
+        raise SagaStateError(f"Step {step_id} not found in saga {saga.saga_id}")