# 24mlight/a_share_investment_agent architecture

> Architecture diagram of the GitHub repository 24mlight/a_share_investment_agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/24mlight/a_share_investment_agent
- Repository: https://github.com/24mlight/a_share_investment_agent

## Overview

Step 1: Identify the Project Type and Purpose
- This project is an AI-driven investment platform designed specifically for analyzing and making decisions on A-share (Chinese market) stocks. It acts as a proof-of-concept for using multiple “agent” modules (each with its own analysis like market-data, technicals, fundamentals, sentiment, valuation, and risk management) to form a consolidated trading decision.
- The README clearly details that the system is educational and experimental, featuring backtesting and live decision-making processes; it also highlights a recent enhancement around a “debate room” module, where multi-agent opinions are debated and combined using both traditional signals and third-party LLM analysis.

Step 2: Analyze the File Structure for Architectural Clues
- Top-level directories/files include:
- A configuration file (.env and .env.example) for environment/credentials.
- A pyproject.toml and poetry.lock indicating dependency and build management via Poetry.
- The src directory organized into:
– agents: contains individual agent modules (e.g., fundamentals, market_data, portfolio_manager, risk_manager, sentiment, technicals, valuation, and debate_room).
– tools: includes API interfacing, data analyzers (news crawlers, API tests, etc).
– utils: contains logging configuration and LLM clients (for Gemini and OpenAI APIs).
– main.py (which serves as the entry point) and backtester.py for backtesting.

Step 3: Examine the README for Additional Insights
- The README outlines the “System Architecture” and describes the flow as:
Market Data Agent → [Technical/Fundamentals/Sentiment/Valuation Analysts + Debate Room] → Risk Manager → Portfolio Manager → Final Trading Decision.
- It offers descriptions of each agent’s responsibilities, data flows, and even touches upon aspects like multi-LLM support, logging, and backtesting.
- It emphasizes the modular, message-driven (state sharing) structure, as well as the main feedback mechanisms (logs, caching, and API calls).

- a. Identify the Main Components:
– Data Input Layer: API/data retrieval via Market Data Agent and news crawler (src/tools/api.py, src/data, etc).
– Analysis Agents Layer: Include individual agents for:
- Technical Analysis (src/agents/technicals.py)
- Fundamentals Analysis (src/agents/fundamentals.py)
- Sentiment Analysis (src/agents/sentiment.py)
- Valuation Analysis (src/agents/valuation.py)
- (Also include multi-view agents like researcher_bull.py and researcher_bear.py representing diverse outlooks)
- Debate Room (src/agents/debate_room.py) to aggregate/minimize bias through debate.
– Risk & Portfolio Management Layer: Risk Manager (src/agents/risk_manager.py) and Portfolio Manager (src/agents/portfolio_manager.py) aggregate signals into final order.
– Data Storage/Cache and Logging Components: Indicate use of logs (logs/) and sentiment_cache.json for data caching.
– Supporting Utilities: LLM Clients (src/utils/llm_clients.py), Logging configs (src/utils/logging_config.py), and additional tools for market data analysis.

- b. Relationships and Interactions:
– Data flows from the external API (and internally between modules) must be clearly shown:
→ The Market Data Agent collects market and news data.
→ Data moves into the individual analysis agents, each producing a signal (with confidence scores).
→ Signals are then fed into the Risk Manager to perform risk assessment.
→ Subsequently, the Portfolio Manager consolidates inputs and makes the final trading decision.

- c. Architectural Patterns/Design Principles:
– Modular Design: Each analysis module (agent) is self-contained, making it easy to extend.
– Layered Architecture: Separate data retrieval, analysis, risk management, and decision-making.
– Message or State Sharing: Show how agents communicate via the shared state (src/agents/state.py).
– Extendibility via plug-in components: For future addition of more agents or data sources.
– Use of test and log modules for tracking decisions.

- d. Relevant Technologies and Frameworks:
– Python with Poetry for dependency management.
– API integration libraries (akshare, news crawlers).
– LLM APIs (Gemini and OpenAI-Compatible) as part of sentiment/enhanced debate.
– Logging mechanism for debugging and traceability.

- Since this is a full-stack analytical tool (with a core backend engine), emphasize separation between:
– Data Collection and Ingestion (integration with external market data/news APIs)
– Analytical Agents (each agent’s functionality: technical, fundamentals, sentiment, valuation)
– Decision Aggregation (risk management and portfolio decisioning)
– Utility components (e.g., tools and utils could be shaded differently)
– Final output modules (Portfolio Manager and Trading Decision)

– Start with data ingestion (market data/news) flowing into each agent module.

## Diagram (Mermaid)

```mermaid
graph TD
    A["API Interface"]:::data
    B["News Crawler"]:::data
    C["Market Data Agent"]:::analysis
    D["Technical Analysis Agent"]:::analysis
    E["Fundamentals Analysis Agent"]:::analysis
    F["Sentiment Analysis Agent"]:::analysis
    G["Valuation Analysis Agent"]:::analysis
    H["Debate Room Module"]:::analysis
    I["Researcher Bull"]:::analysis
    J["Researcher Bear"]:::analysis
    K["Shared State"]:::utility
    L["Risk Manager"]:::risk
    M["Portfolio Manager"]:::decision
    N["Trading Decision"]:::decision
    O["Backtesting Module"]:::utility
    P["LLM Client Utilities"]:::utility
    Q["Logging Configuration"]:::utility

    %% Data Ingestion Layer
    A --> C
    B --> C

    %% Propagation from Market Data Agent to Analysis Agents
    C --> D
    C --> E
    C --> F
    C --> G
    C --> H
    C --> I
    C --> J

    %% Shared State connections (dashed)
    D --- K
    E --- K
    F --- K
    G --- K
    H --- K
    I --- K
    J --- K

    %% Analysis Agents feed into Risk Manager
    D --> L
    E --> L
    F --> L
    G --> L
    H --> L
    I --> L
    J --> L

    %% Decision Flow
    L --> M
    M --> N

    %% Auxiliary and Utility Connections
    P -.-> H
    Q -.-> M
    M -.-> O

    %% Styles
    classDef data fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef analysis fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef risk fill:#FF7F7F,stroke:#000,stroke-width:2px;
    classDef decision fill:#DDA0DD,stroke:#000,stroke-width:2px;
    classDef utility fill:#F4A460,stroke:#000,stroke-width:2px;

    %% Click Events
    click A "https://github.com/24mlight/a_share_investment_agent/blob/main/src/tools/api.py"
    click B "https://github.com/24mlight/a_share_investment_agent/blob/main/src/tools/news_crawler.py"
    click C "https://github.com/24mlight/a_share_investment_agent/blob/main/src/agents/market_data.py"
    click D "https://github.com/24mlight/a_share_investment_agent/blob/main/src/agents/technicals.py"
    click E "https://github.com/24mlight/a_share_investment_agent/blob/main/src/agents/fundamentals.py"
    click F "https://github.com/24mlight/a_share_investment_agent/blob/main/src/agents/sentiment.py"
    click G "https://github.com/24mlight/a_share_investment_agent/blob/main/src/agents/valuation.py"
    click H "https://github.com/24mlight/a_share_investment_agent/blob/main/src/agents/debate_room.py"
    click I "https://github.com/24mlight/a_share_investment_agent/blob/main/src/agents/researcher_bull.py"
    click J "https://github.com/24mlight/a_share_investment_agent/blob/main/src/agents/researcher_bear.py"
    click K "https://github.com/24mlight/a_share_investment_agent/blob/main/src/agents/state.py"
    click L "https://github.com/24mlight/a_share_investment_agent/blob/main/src/agents/risk_manager.py"
    click M "https://github.com/24mlight/a_share_investment_agent/blob/main/src/agents/portfolio_manager.py"
    click O "https://github.com/24mlight/a_share_investment_agent/blob/main/src/backtester.py"
    click P "https://github.com/24mlight/a_share_investment_agent/blob/main/src/utils/llm_clients.py"
    click Q "https://github.com/24mlight/a_share_investment_agent/blob/main/src/utils/logging_config.py"
```
