"""
StateStore - 状态类的配置存储抽象

包含 Conversation, Message, Action, ReActRound, ToolCallRecord, JobTask（运行时状态）等状态类。
来自 schema/states.py
"""

from abc import ABC, abstractmethod
from typing import Optional, List
from datetime import datetime
from turbo_agent_core.schema.states import (
    Conversation,
    Message,
    Action,
    ReActRound,
    ToolCallRecord,
    JobTask,
)


class StateStore(ABC):
    """
    状态类的配置存储抽象类。
    
    所有方法均支持 **kwargs 参数，用于实现侧传入鉴权信息。
    状态类通常具有时间序列特性，支持按时间范围查询。
    """

    # ========== Conversation CRUD ==========
    @abstractmethod
    async def get_conversation(
        self, 
        conversation_id: str, 
        **kwargs
    ) -> Optional[Conversation]:
        """
        根据 ID 获取 Conversation（包含完整的 Message 列表）。

        Args:
            conversation_id: Conversation 唯一标识
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass

    @abstractmethod
    async def save_conversation(
        self, 
        conversation: Conversation, 
        **kwargs
    ) -> str:
        """
        保存 Conversation，返回 Conversation ID。

        Args:
            conversation: Conversation 实例
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass

    @abstractmethod
    async def list_conversations(
        self, 
        assistant_id: Optional[str] = None,
        workset_id: Optional[str] = None,
        status: Optional[str] = None,
        skip: int = 0, 
        limit: int = 20, 
        **kwargs
    ) -> List[Conversation]:
        """
        列出 Conversations。

        Args:
            assistant_id: 可选的 Assistant ID 过滤
            workset_id: 可选的 Workset ID 过滤
            status: 可选的状态过滤
            skip: 跳过的记录数
            limit: 返回的最大记录数
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass

    @abstractmethod
    async def delete_conversation(
        self, 
        conversation_id: str, 
        **kwargs
    ) -> bool:
        """
        删除 Conversation。

        Args:
            conversation_id: Conversation 唯一标识
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass

    # ========== Message CRUD ==========
    @abstractmethod
    async def get_message(
        self, 
        message_id: str, 
        **kwargs
    ) -> Optional[Message]:
        """
        根据 ID 获取 Message（包含完整的 Action 列表）。

        Args:
            message_id: Message 唯一标识
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass

    @abstractmethod
    async def save_message(
        self, 
        message: Message, 
        conversation_id: str,
        **kwargs
    ) -> str:
        """
        保存 Message，返回 Message ID。

        Args:
            message: Message 实例
            conversation_id: 所属 Conversation ID
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass

    @abstractmethod
    async def list_messages(
        self, 
        conversation_id: str,
        skip: int = 0, 
        limit: int = 100, 
        **kwargs
    ) -> List[Message]:
        """
        列出指定 Conversation 下的 Messages。

        Args:
            conversation_id: Conversation ID
            skip: 跳过的记录数
            limit: 返回的最大记录数
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass

    @abstractmethod
    async def delete_message(
        self, 
        message_id: str, 
        **kwargs
    ) -> bool:
        """
        删除 Message。

        Args:
            message_id: Message 唯一标识
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass

    # ========== Action CRUD ==========
    @abstractmethod
    async def get_action(
        self, 
        action_id: str, 
        **kwargs
    ) -> Optional[Action]:
        """
        根据 ID 获取 Action（包含完整的 ToolCallRecord 列表）。

        Args:
            action_id: Action 唯一标识
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass

    @abstractmethod
    async def save_action(
        self, 
        action: Action, 
        message_id: str,
        **kwargs
    ) -> str:
        """
        保存 Action，返回 Action ID。

        Args:
            action: Action 实例
            message_id: 所属 Message ID
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass

    @abstractmethod
    async def list_actions(
        self, 
        message_id: str,
        skip: int = 0, 
        limit: int = 100, 
        **kwargs
    ) -> List[Action]:
        """
        列出指定 Message 下的 Actions。

        Args:
            message_id: Message ID
            skip: 跳过的记录数
            limit: 返回的最大记录数
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass

    @abstractmethod
    async def update_action_status(
        self, 
        action_id: str, 
        status: str,
        **kwargs
    ) -> bool:
        """
        更新 Action 的状态。

        Args:
            action_id: Action 唯一标识
            status: 新状态
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass

    # ========== ReActRound CRUD ==========
    @abstractmethod
    async def get_react_round(
        self, 
        round_id: str, 
        **kwargs
    ) -> Optional[ReActRound]:
        """
        根据 ID 获取 ReActRound。

        Args:
            round_id: ReActRound 唯一标识
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass

    @abstractmethod
    async def save_react_round(
        self, 
        react_round: ReActRound, 
        message_id: str,
        **kwargs
    ) -> str:
        """
        保存 ReActRound，返回 Round ID。

        Args:
            react_round: ReActRound 实例
            message_id: 所属 Message ID
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass

    @abstractmethod
    async def list_react_rounds(
        self, 
        message_id: str,
        skip: int = 0, 
        limit: int = 100, 
        **kwargs
    ) -> List[ReActRound]:
        """
        列出指定 Message 下的 ReActRounds。

        Args:
            message_id: Message ID
            skip: 跳过的记录数
            limit: 返回的最大记录数
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass

    # ========== ToolCallRecord CRUD ==========
    @abstractmethod
    async def get_tool_call_record(
        self, 
        record_id: str, 
        **kwargs
    ) -> Optional[ToolCallRecord]:
        """
        根据 ID 获取 ToolCallRecord。

        Args:
            record_id: ToolCallRecord 唯一标识
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass

    @abstractmethod
    async def save_tool_call_record(
        self, 
        record: ToolCallRecord, 
        **kwargs
    ) -> str:
        """
        保存 ToolCallRecord，返回 Record ID。

        Args:
            record: ToolCallRecord 实例
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass

    @abstractmethod
    async def list_tool_call_records(
        self, 
        action_id: Optional[str] = None,
        tool_project_id: Optional[str] = None,
        tool_name_id: Optional[str] = None,
        skip: int = 0, 
        limit: int = 100, 
        **kwargs
    ) -> List[ToolCallRecord]:
        """
        列出 ToolCallRecords。

        Args:
            action_id: 可选的 Action ID 过滤
            tool_project_id: 可选的工具项目ID过滤
            tool_name_id: 可选的工具 name_id 过滤
            skip: 跳过的记录数
            limit: 返回的最大记录数
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass

    # ========== JobTask 运行时状态（来自 states.py）==========
    @abstractmethod
    async def get_job_task_state(
        self, 
        task_id: str, 
        **kwargs
    ) -> Optional[JobTask]:
        """
        根据 ID 获取 JobTask 的运行时状态。

        Args:
            task_id: Task 唯一标识
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass

    @abstractmethod
    async def save_job_task_state(
        self, 
        task: JobTask, 
        **kwargs
    ) -> str:
        """
        保存 JobTask 的运行时状态，返回 Task ID。

        Args:
            task: JobTask 实例
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass

    @abstractmethod
    async def update_job_task_state(
        self, 
        task_id: str,
        status: Optional[str] = None,
        execution_time: Optional[datetime] = None,
        end_time: Optional[datetime] = None,
        token_cost: Optional[int] = None,
        money_cost: Optional[float] = None,
        **kwargs
    ) -> bool:
        """
        更新 JobTask 的运行时状态字段。

        Args:
            task_id: Task 唯一标识
            status: 可选的新状态
            execution_time: 可选的实际开始时间
            end_time: 可选的结束时间
            token_cost: 可选的 Token 消耗
            money_cost: 可选的费用消耗
            **kwargs: 实现侧可传入 user_id, org_id 等鉴权信息
        """
        pass
