# mythology.py

from abc import ABC, abstractmethod
from typing import Dict, Any

class MythologyEngine(ABC):
    """
    神话引擎抽象基类 (Abstract Base Class)。

    定义了所有神话体系映射的统一接口，确保上层应用（如FSM）
    可以无差别地调用，实现核心逻辑与文化叙事的解耦。
    """

    @abstractmethod
    def get_actor_name(self, component: str) -> str:
        """
        根据技术组件名称，获取其在神话体系中对应的角色名称。
        :param component: 技术组件的标识符 (e.g., 'refiner', 'verifier').
        :return: 神话角色的名称 (e.g., '太上老君', '灵宝道君').
        """
        pass

    @abstractmethod
    def get_process_metaphor(self, process: str) -> str:
        """
        根据技术流程名称，获取其在神话体系中的隐喻。
        :param process: 技术流程的标识符 (e.g., 'external_fetch').
        :return: 神话流程的隐喻 (e.g., '撒豆成兵').
        """
        pass

    @abstractmethod
    def get_system_narrative(self) -> str:
        """
        获取整个系统的世界观或宏大叙事。
        :return: 描述系统哲学的字符串。
        """
        pass


class DaoistMythologyEngine(MythologyEngine):
    """
    道家“封神”神话引擎的具体实现。

    将“太公心易”系统的组件和流程映射到道家和封神演义的神话体系中。
    """

    def __init__(self):
        self._actor_map: Dict[str, str] = {
            # FSM States / Core Components
            'collector': '聚仙楼',
            'divergence_handler': '白虎观会议',
            'refiner': '太上老君',
            'verifier': '灵宝道君',
            'synthesizer': '元始天尊',
            'actuator': '打神鞭',
            # Agent Roles
            'macro_analyst': '铁拐李',
            'strategist': '汉钟离',
            'sentiment_analyst': '张果老',
            'compliance_checker': '曹国舅',
        }
        self._process_map: Dict[str, str] = {
            'multi_agent_debate': '八仙论道',
            'refinement_process': '兜率宫炼丹',
            'external_verification': '撒豆成兵',
            'final_decision': '元始决断',
            'async_webhook_call': '元神出窍',
        }
        self._narrative = "本系统是一个道法自然、洞察万象的AI智能决策生态，名为“太公心易”。"

    def get_actor_name(self, component: str) -> str:
        """
        获取道家神话体系中的角色名称。
        """
        return self._actor_map.get(component, "未知神祇")

    def get_process_metaphor(self, process: str) -> str:
        """
        获取道家神话体系中的流程隐喻。
        """
        return self._process_map.get(process, "混沌演化")

    def get_system_narrative(self) -> str:
        """
        返回“太公心易”系统的宏大叙事。
        """
        return self._narrative

# --- 示例：如何使用解耦的引擎 ---
if __name__ == '__main__':
    # 上层应用可以声明它需要一个 MythologyEngine，而无需关心具体实现
    def describe_system_component(engine: MythologyEngine, component: str, process: str):
        actor = engine.get_actor_name(component)
        metaphor = engine.get_process_metaphor(process)
        print(f"组件 '{component}' 由 [{actor}] 负责，其核心流程 '{process}' 被称为 [{metaphor}]。")

    # 在运行时，我们可以传入任何一个具体的引擎实例
    daoist_engine = DaoistMythologyEngine()

    print(f"系统世界观: {daoist_engine.get_system_narrative()}")
    print("-" * 50)

    describe_system_component(daoist_engine, 'refiner', 'refinement_process')
    describe_system_component(daoist_engine, 'verifier', 'external_verification')

    # 如果未来要切换到希腊神话，只需实现一个 GreekMythologyEngine 即可，
    # 上层应用 describe_system_component 的代码完全不需要修改。
    # class GreekMythologyEngine(MythologyEngine):
    #     ...
    # greek_engine = GreekMythologyEngine()
    # describe_system_component(greek_engine, 'refiner', 'refinement_process')