# (c) Copyright 2025 Perceptic Technologies Ltd. All rights reserved.
#
# AUTO-GENERATED FILE - DO NOT EDIT
# Generated from: perceptic-workflow.schema.json

from __future__ import annotations

from abc import ABC, abstractmethod
from typing import Any
from perceptic_workflow.definitions import WorkflowEvent


class PercepticWorkflow(ABC):
    """
    Defines the standard Perceptic Workflow control updates that all workflows must support to handle user interaction and interruption. These update names are reserved and invoked directly by the Perceptic Core V3 API.

    This is a mixin class that provides the method signatures and constants for
    the Perceptic workflow interface. Since Temporal's @workflow.defn decorator
    must be applied to concrete classes, implement this mixin in your workflow class
    and apply the appropriate decorators.

    Example:
        @workflow.defn
        class MyWorkflow(PercepticWorkflow):
            @workflow.query(name=PercepticWorkflow.QUERY_GET_EVENTS)
            def get_events(self, after_event_id: int | None = None) -> list[WorkflowEvent]:
                return self._events
    """

    # The reserved update name for handles user input submission.
    UPDATE_SUBMIT_USER_INPUT: str = "submitUserInput"
    # The reserved update name for handles an interrupt signal.
    UPDATE_INTERRUPT: str = "interrupt"
    # The reserved query name for checks if the workflow is currently paused (waiting for user input).
    QUERY_IS_PAUSED: str = "isPaused"
    # The reserved query name for retrieves workflow events, optionally filtered to events after a given event id.
    QUERY_GET_EVENTS: str = "getEvents"

    @abstractmethod
    async def submit_user_input(
        self,
        inputs: dict[str, Any]
    ) -> None:
        """
        Handles user input submission.

        Args:
            inputs: The input data provided by the user (matching the schema requested by the workflow).

        Returns:

        """
        ...

    @abstractmethod
    async def interrupt(
        self,
        reason: str
    ) -> None:
        """
        Handles an interrupt signal.

        Args:
            reason: The reason for the interruption.

        Returns:

        """
        ...

    @abstractmethod
    def is_paused(
        self
    ) -> bool:
        """
        Checks if the workflow is currently paused (waiting for user input).


        Returns:

        """
        ...

    @abstractmethod
    def get_events(
        self,
        after_event_id: int | None = None
    ) -> list[WorkflowEvent]:
        """
        Retrieves workflow events, optionally filtered to events after a given event ID.

        Args:
            after_event_id: If provided, only return events with eventId greater than this value.

        Returns:

        """
        ...
