System Architecture

The system architecture is built on a Modular Multi-Agent System (MAS) designed to simulate a professional trading desk. It decouples data acquisition, analytical reasoning, and performance visualization, allowing for high extensibility and robust decision-making.

High-Level Component Overview

The architecture consists of four primary layers:

1. Orchestration Layer: Managed by the TradingOrchestrator, which directs the flow of information and coordinates the multi-phase analysis.
2. Intelligence Layer (Agents): Specialized LLM-powered agents (Technical, Sentiment, Fundamental, and Risk) that perform domain-specific analysis.
3. Data & Knowledge Layer: Connectors for real-time market data (NewsAPI, RSS) and a RAG (Retrieval-Augmented Generation) system for indexing institutional knowledge.
4. Presentation & Evaluation Layer: A FastAPI/React dashboard for monitoring and a backtesting engine for historical verification.

1. The Trading Orchestrator

The TradingOrchestrator is the central gateway of the system. It abstracts the complexity of agent communication and state management.

Public Interface

To interact with the system, you primarily use the analyze method.

from orchestrator import TradingOrchestrator

# Initialize with desired LLM backend (e.g., "groq" or "ollama")
orchestrator = TradingOrchestrator(backend="groq")

# Execute a full multi-agent analysis
result = orchestrator.analyze(
    query="Bitcoin analysis at $45,000",
    enable_debate=True
)

Analysis Phases

The Orchestrator executes a four-phase workflow:

1. Phase 1: Parallel Analysis: All specialized agents receive the market context and generate independent reports.
2. Phase 2: Conflict Detection: The Supervisor agent compares recommendations (BUY/SELL/HOLD) to identify significant disagreements.
3. Phase 3: Agent Debate (Optional): If conflicts exist and debate is enabled, agents defend their positions in a second iteration.
4. Phase 4: Final Synthesis: The Supervisor aggregates all viewpoints and confidence scores into a structured final decision.

2. Specialized Agents & Schemas

Each agent is defined by a strict Pydantic schema (found in agents/schemas.py). This ensures that the LLM outputs are structured, type-safe, and ready for programmatic execution or dashboard rendering.

Agent Roles

• Technical Agent: Analyzes RSI, MACD, and price action metadata.
• Sentiment Agent: Processes news feeds and the Fear & Greed Index.
• Fundamental Agent: Evaluates network health, valuation status, and market cycle phases.
• Risk Agent: Calculates position sizing, ATR-based stop-losses, and take-profit levels using mathematical tools.

Structured Output Usage

The system enforces the AgentRecommendation base model for all responses:

| Field | Type | Description | | :--- | :--- | :--- | | recommendation | Enum | BUY, SELL, or HOLD. | | confidence | Integer | 0-100 score of the agent's certainty. | | reasoning | String | Qualitative explanation of the data points. | | metadata | Object | Specialized fields (e.g., rsi_signal for Technical). |

3. Data Connectors & Knowledge Base

Real-Time Data Flow

The system utilizes NewsAPIConnector to aggregate market intelligence. It features a failover mechanism:

1. Attempts to fetch high-quality data from NewsAPI.
2. Falls back to Google News RSS or specific crypto-feeds (e.g., CoinTelegraph) if API limits are reached.

RAG (Retrieval-Augmented Generation)

The KnowledgeIndexer allows the agents to access static research papers and trading strategies stored in the /knowledge directory.

• Format Support: Markdown, Text, and PDF (via conversion).
• Vector Store: Chunks and indexes documents into domain-specific namespaces (e.g., "technical", "risk").

4. Presentation Layer (Dashboard)

The system includes a full-stack dashboard for analyzing agent decisions and backtest performance.

Backend (FastAPI)

Located in dashboard/backend/main.py, the API provides:

• REST Endpoints: For retrieving historical trade logs and agent reasoning.
• WebSockets: For real-time updates during live trading sessions.

Frontend (React)

A modern UI (Vite-powered) that visualizes:

• Equity Curves: Comparison of system performance vs. Buy & Hold.
• Trade Log: A detailed audit trail including the "Reasoning" provided by the agents for every transaction.
• Metrics Panel: Real-time calculation of Sharpe Ratio, Max Drawdown, and Win Rate.

5. Execution Flow Example

When a query is processed, the system follows this architectural path:

1. Input: User query or automated price trigger.
2. Retrieval: The KnowledgeIndexer fetches relevant strategy snippets.
3. Context Construction: The Orchestrator gathers news via NewsAPIConnector and technical indicators.
4. Inference: Agents generate structured JSON responses via the Intelligence Layer.
5. Persistence: Results are saved to a local SQLite/PostgreSQL database via database.py.
6. Visualization: The React dashboard fetches the update via the FastAPI backend.