liurenchaxin/docs/custom_modules_tutorial.md

Developer Tutorial: Creating Custom Modules

Welcome, contributor! This guide will show you how to extend the "太公心易" system by creating your own custom MythologyEngine and CycleModel.

The system is built on the principle of decoupling, using Abstract Base Classes (ABCs) to separate the core logic of the MarketFSM from the specific cultural or analytical models it uses. By creating new classes that inherit from these ABCs, you can fundamentally change the system's narrative and analytical framework without touching the core FSM logic.

Part 1: Creating a Custom Mythology Engine

A MythologyEngine is responsible for providing the narrative flavor to the system. It maps technical components to mythological figures and processes. Let's create a GreekMythologyEngine as an example.

Step 1: Create a New Python File

Create a new file, for example, greek_mythology.py.

Step 2: Import the MythologyEngine ABC

In your new file, import the abstract base class from mythology.py:

# greek_mythology.py
from mythology import MythologyEngine

Step 3: Implement the MythologyEngine Interface

Create a new class that inherits from MythologyEngine and implements all its abstract methods: get_actor_name, get_process_metaphor, and get_system_narrative.

class GreekMythologyEngine(MythologyEngine):
    """
    An implementation of the MythologyEngine based on Greek mythology.
    """
    def __init__(self):
        self._actor_map = {
            'collector': 'The Muses',
            'refiner': 'Hephaestus',
            'verifier': 'Apollo',
            'synthesizer': 'Zeus',
        }
        self._process_map = {
            'multi_agent_debate': 'Symposium',
            'refinement_process': 'Forging in Aetna',
            'external_verification': 'Consulting the Oracle of Delphi',
            'final_decision': 'Judgment from Olympus',
        }
        self._narrative = "This system views the market as a pantheon of competing gods and heroes, striving for dominance on Mount Olympus."

    def get_actor_name(self, component: str) -> str:
        return self._actor_map.get(component, "An Unknown Titan")

    def get_process_metaphor(self, process: str) -> str:
        return self._process_map.get(process, "A Herculean Task")

    def get_system_narrative(self) -> str:
        return self._narrative

Step 4: Integrate with the FSM

Now, you can instantiate your new engine and inject it into the MarketFSM. The FSM will work seamlessly with your new narrative layer.

# In your main application file
from market_fsm import MarketFSM
from greek_mythology import GreekMythologyEngine
from cycle_models import TwelveStagesOfLifeCycleModel # We can reuse the old cycle model

# Instantiate your custom engine
greek_engine = GreekMythologyEngine()
cycle_model = TwelveStagesOfLifeCycleModel()

# Inject it into the FSM
fsm = MarketFSM(
    mythology_engine=greek_engine,
    cycle_model=cycle_model
)

# Run the analysis
fsm.run_analysis({"mock_score": 8}) 
# The output will now be framed in the language of Greek mythology!

Part 2: Creating a Custom Cycle Model

A CycleModel is responsible for analyzing market data and determining the current stage of a given cycle. Let's create a simple MarketSentimentCycleModel based on four stages: Greed, Fear, Hope, and Despair.

Step 1: Create a New Python File

Create a file named sentiment_cycle.py.

Step 2: Import the CycleModel ABC

# sentiment_cycle.py
from cycle_models import CycleModel
from typing import Dict, Any, List

Step 3: Implement the CycleModel Interface

Create a new class that inherits from CycleModel and implements get_current_stage, get_stage_characteristics, and get_all_stages.

class MarketSentimentCycleModel(CycleModel):
    """
    A cycle model based on the four stages of market sentiment.
    """
    def __init__(self):
        self._stages = ["Hope", "Greed", "Fear", "Despair"]
        self._characteristics = {
            "Hope": {"description": "The market is cautiously optimistic.", "strategy": "Accumulate"},
            "Greed": {"description": "Euphoria and high expectations dominate.", "strategy": "Take profits"},
            "Fear": {"description": "Panic and uncertainty are widespread.", "strategy": "Reduce risk"},
            "Despair": {"description": "Capitulation, the market has given up hope.", "strategy": "Look for bargains"},
        }

    def get_current_stage(self, data: Dict[str, Any]) -> str:
        # A real implementation would analyze news sentiment, VIX, etc.
        # Here, we'll use a mock sentiment score from 0 to 1.
        sentiment_score = data.get("sentiment", 0.5)
        if sentiment_score > 0.75:
            return "Greed"
        elif sentiment_score > 0.5:
            return "Hope"
        elif sentiment_score > 0.25:
            return "Fear"
        else:
            return "Despair"

    def get_stage_characteristics(self, stage: str) -> Dict[str, Any]:
        return self._characteristics.get(stage, {})

    def get_all_stages(self) -> List[str]:
        return self._stages

Step 4: Integrate with the FSM

You can now use your new cycle model in the FSM, even combining it with a different mythology engine.

# In your main application file
from market_fsm import MarketFSM
from mythology import DaoistMythologyEngine
from sentiment_cycle import MarketSentimentCycleModel

# Instantiate your custom cycle model
sentiment_model = MarketSentimentCycleModel()
daoist_engine = DaoistMythologyEngine()

# Inject it into the FSM
fsm = MarketFSM(
    mythology_engine=daoist_engine,
    cycle_model=sentiment_model
)

# Run the analysis with data your new model understands
fsm.run_analysis({"sentiment": 0.2}) 
# The FSM will now report the market is in a state of "Despair".

Congratulations! You have successfully extended the "太公心易" system.