The Orchestrator

The Orchestrator is the central nervous system of the trading platform. It manages the lifecycle of specialized agents—Technical, Sentiment, Fundamental, and Risk—and coordinates their collaboration through a multi-phase workflow to produce a single, actionable trading decision.

The Orchestrator abstracts the complexity of agent communication, RAG (Retrieval-Augmented Generation) lookups, and consensus logic, providing a simple interface for both backtesting and live trading.

Initialization

The TradingOrchestrator can be configured to use different LLM backends (e.g., Ollama for local execution or Groq for high-speed cloud inference).

from orchestrator import TradingOrchestrator

# Initialize with a local Ollama backend (e.g., using deepseek-r1)
orchestrator = TradingOrchestrator(backend="ollama", model_name="deepseek-r1")

# Or initialize with Groq for production-grade speed
# orchestrator = TradingOrchestrator(backend="groq")

The Analysis Workflow

The Orchestrator executes a structured four-phase process to reach a decision. This ensures that recommendations are not just based on raw data, but are cross-referenced across different market perspectives.

Phase 1: Individual Analysis

Each agent (Technical, Sentiment, Fundamental, Risk) receives the market data and queries their specific RAG domain (e.g., the Technical agent queries knowledge/technical_analysis). They return a structured AgentRecommendation including a vote (BUY/SELL/HOLD), confidence score, and detailed reasoning.

Phase 2: Conflict Check

The Orchestrator aggregates the votes. If the agents are in unanimous agreement, it may bypass the debate phase to save latency. If there is a "split decision" (e.g., Technical says BUY but Risk says HOLD), the system flags a conflict.

Phase 3: Debate (Optional)

When enable_debate=True is passed to the analysis, the Orchestrator initiates a multi-agent conversation. Agents are presented with the conflicting views of their peers and asked to defend or revise their positions based on the collective evidence.

Phase 4: Final Consensus

The Orchestrator compiles the final votes, calculates the average confidence level, and produces a definitive recommendation.

Public Interface

analyze()

The primary method for generating trading decisions.

Parameters:

• query (str): The market context or specific question (e.g., "Analyze BTC at $45k with RSI 65").
• enable_debate (bool): Whether to trigger Phase 3 if agents disagree. Defaults to False.
• context (dict, optional): Raw market data from connectors to supplement the query.

Returns: A dict containing the full lifecycle of the decision:

{
  "phase_1_analyses": {
    "technical": "...", 
    "sentiment": "...",
    "fundamental": "...",
    "risk": "..."
  },
  "phase_2_conflict_check": {
    "individual_votes": {"technical": "BUY", "sentiment": "HOLD", ...},
    "is_conflicting": true
  },
  "phase_3_debate": "The synthesis of the agent discussion...",
  "phase_4_decision": {
    "recommendation": "BUY",
    "vote_count": {"BUY": 3, "HOLD": 1, "SELL": 0},
    "average_confidence": 82,
    "final_reasoning": "..."
  }
}

print_final_decision()

A utility method to output a formatted, human-readable summary of the analysis to the console.

result = orchestrator.analyze(query, enable_debate=True)
orchestrator.print_final_decision(result)

Schema & Data Integrity

The Orchestrator enforces strict output formatting using Pydantic models defined in agents/schemas.py. This ensures that regardless of which LLM backend is used, the system receives predictable data structures:

| Field | Type | Description | | :--- | :--- | :--- | | recommendation | Enum | One of BUY, SELL, or HOLD. | | confidence | int | A score from 0-100. | | reasoning | str | Detailed justification (max 3000 chars). | | metadata | dict | Agent-specific data (e.g., rsi_signal for Technical, stop_loss_level for Risk). |

Integration with Knowledge Base

The Orchestrator automatically links agents to their respective vector stores managed by the KnowledgeIndexer. When an analysis is triggered, the Orchestrator ensures that:

1. The Technical Agent retrieves context from research papers and TA guides.
2. The Risk Agent retrieves position sizing rules and volatility frameworks.
3. The Sentiment Agent analyzes current news via the NewsAPIConnector.