Architecture Overview
=====================

OpenClaw Trading uses a multi-agent architecture with LangGraph workflow orchestration. The system is designed to simulate a realistic trading environment where agents must pay for their decisions and compete for survival.

System Architecture
-------------------

High-Level Components
~~~~~~~~~~~~~~~~~~~~~

.. code-block:: text

    ┌─────────────────────────────────────────────────────────────┐
    │                    Trading Workflow                          │
    │                  (LangGraph Orchestration)                   │
    └──────────────┬──────────────────────────────────┬───────────┘
                   │                                  │
       ┌───────────▼──────────┐        ┌──────────────▼────────────┐
       │   Analysis Phase     │        │     Decision Phase        │
       ├──────────────────────┤        ├───────────────────────────┤
       │ • Market Analyst     │        │ • Bull-Bear Debate        │
       │ • Sentiment Analyst  │───────▶│ • Decision Fusion         │
       │ • Fundamental Analyst│        │ • Risk Assessment         │
       └──────────────────────┘        └──────────────┬────────────┘
                                                      │
                               ┌──────────────────────▼──────────────────┐
                               │           Trading Execution              │
                               │  ┌──────────┐  ┌──────────┐  ┌────────┐│
                               │  │  Trader  │  │ Portfolio│  │Exchange││
                               │  │  Agent   │  │ Manager  │  │Adapter ││
                               │  └──────────┘  └──────────┘  └────────┘│
                               └──────────────────────────────────────────┘

Agent Hierarchy
~~~~~~~~~~~~~~~

All agents inherit from :class:`openclaw.agents.base.BaseAgent`:

.. code-block:: text

    BaseAgent (abstract)
        │
        ├── MarketAnalyst
        ├── SentimentAnalyst
        ├── FundamentalAnalyst
        ├── BullResearcher
        ├── BearResearcher
        ├── RiskManager
        └── Trader

Each agent has:

* **Economic Tracker**: Tracks balance, costs, and survival status
* **State**: Skill level, win rate, unlocked factors
* **Event Hooks**: Callback system for lifecycle events

Economic Model
--------------

The economic model creates a survival-of-the-fittest environment:

Costs
~~~~~

Agents pay for every action:

* **Token Costs**: $2.50 per 1M input tokens, $10.00 per 1M output tokens
* **Data Costs**: $0.01 per market data API call
* **Trading Fees**: 0.1% of trade value

Survival Status
~~~~~~~~~~~~~~~

Agents are classified based on balance relative to initial capital:

* **🚀 Thriving**: 150%+ of initial capital (50%+ profit)
* **💪 Stable**: 110-150% of initial capital
* **⚠️ Struggling**: 80-110% of initial capital
* **🔴 Critical**: 30-80% of initial capital
* **💀 Bankrupt**: Below 30% of initial capital

Work-Trade Balance
~~~~~~~~~~~~~~~~~~

When agents perform poorly, they can work to earn money:

* Trading agents can switch to "work mode" during market downturns
* Work earnings supplement trading capital
* Prevents total bankruptcy and enables recovery

Workflow Graph
--------------

The trading workflow uses LangGraph for state-driven orchestration:

.. code-block:: text

    START
      │
      ▼
┌─────────────┐
│  Market     │────┐
│  Analysis   │    │
└─────────────┘    │
                   ▼
┌─────────────┐  ┌──────────────┐
│ Sentiment   │  │ Fundamental  │
│ Analysis    │  │ Analysis     │
└─────────────┘  └──────────────┘
      │                  │
      └────────┬─────────┘
               ▼
        ┌──────────────┐
        │ Bull-Bear    │
        │ Debate       │
        └──────────────┘
               │
               ▼
        ┌──────────────┐
        │ Decision     │
        │ Fusion       │
        └──────────────┘
               │
               ▼
        ┌──────────────┐
        │ Risk         │
        │ Assessment   │
        └──────────────┘
               │
               ▼
              END

Key Features:

* **Parallel Analysis**: Market, sentiment, and fundamental analysis run in parallel
* **Debate Mechanism**: Bull and bear researchers debate the signals
* **Decision Fusion**: Combines all signals into a unified recommendation
* **Risk Check**: Final risk assessment before trading

Data Flow
---------

1. **Input**: Symbol and initial capital
2. **Analysis**: Multiple agents analyze from different perspectives
3. **Debate**: Bull and bear sides argue for their positions
4. **Fusion**: Weighted decision based on all inputs
5. **Risk Assessment**: Risk manager validates the decision
6. **Execution**: Trader executes the approved trade
7. **Tracking**: Economic tracker updates balances and costs

Module Structure
----------------

Core Modules
~~~~~~~~~~~~

* :mod:`openclaw.core`: Core economic tracking and configuration
* :mod:`openclaw.agents`: Agent implementations
* :mod:`openclaw.workflow`: LangGraph workflow orchestration
* :mod:`openclaw.backtest`: Backtesting engine
* :mod:`openclaw.exchange`: Exchange adapters
* :mod:`openclaw.factor`: Trading factors (basic and advanced)
* :mod:`openclaw.learning`: Course-based learning system
* :mod:`openclaw.portfolio`: Portfolio and risk management
* :mod:`openclaw.monitoring`: System monitoring and alerts

Utility Modules
~~~~~~~~~~~~~~~

* :mod:`openclaw.utils.logging`: Structured logging
* :mod:`openclaw.utils.validation`: Input validation
* :mod:`openclaw.data`: Data sources and caching

Technology Stack
----------------

* **Python 3.10+**: Core language
* **LangGraph**: Workflow orchestration
* **LangChain**: LLM integrations
* **Pydantic**: Data validation
* **FastAPI**: Web dashboard API
* **Pandas/NumPy**: Data processing
* **yfinance**: Market data
* **Loguru**: Logging