Consensus & Debate Logic

The trading system employs a multi-agent consensus architecture to minimize individual model bias and simulate a professional investment committee. By separating concerns into specialized domains—Technical, Sentiment, Fundamental, and Risk Management—the system ensures that no single indicator or market narrative can trigger a trade without cross-verification.

The Consensus Workflow

The TradingOrchestrator manages the lifecycle of a trade decision through four distinct phases. This process is designed to move from specialized data analysis to a unified execution command.

Phase 1: Specialized Analysis

Each specialized agent receives the market context and retrieves relevant data from its specific tools (e.g., technical indicators, news RSS feeds via NewsAPIConnector, or on-chain data). Every agent must return a structured response following the AgentRecommendation schema:

• Recommendation: BUY, SELL, or HOLD.
• Confidence: A score from 0–100.
• Reasoning: Detailed justification for the decision.

Phase 2: Conflict Detection

The Supervisor agent aggregates the individual recommendations. A conflict is identified if there is a significant discrepancy between agents (e.g., the Technical agent suggests a BUY while the Risk agent suggests a SELL).

If all agents agree (Consensus), the system skips directly to the Final Decision. If they disagree, the Debate Logic is triggered.

Phase 3: The Debate Mechanism

When enable_debate=True is passed to the orchestrator, conflicting agents engage in a secondary reasoning round.

1. Rebuttal: Agents are presented with the opposing reasoning from their peers.
2. Contextual Weighting: The Supervisor evaluates which agent's data is more critical given current market conditions (e.g., in high volatility, Risk Management recommendations may carry more weight).
3. Synthesis: The "Debater" logic attempts to find a middle ground or determines if one agent's reasoning invalidates another's.

Phase 4: Final Decision

The system calculates a final recommendation based on the weighted votes and the outcome of the debate.

# Example of the final decision structure returned by the Orchestrator
{
    "decision": "BUY",
    "confidence": 82,
    "vote_count": {
        "BUY": 3,
        "HOLD": 1,
        "SELL": 0
    },
    "metadata": {
        "average_confidence": 78,
        "debate_held": True,
        "dominant_agent": "Technical"
    }
}

Implementation via TradingOrchestrator

The TradingOrchestrator is the primary entry point for executing this logic. It abstracts the complexity of agent communication and schema validation.

Usage Example

from orchestrator import TradingOrchestrator

# Initialize the orchestrator (supports 'groq', 'openai', or 'ollama')
orchestrator = TradingOrchestrator(backend="groq")

# Execute a full analysis with debate logic enabled
market_query = "Bitcoin is at $65k, RSI is 72, news sentiment is highly positive."
result = orchestrator.analyze(market_query, enable_debate=True)

# Access individual agent thoughts
tech_analysis = result["phase_1_analyses"]["technical"]
print(f"Technical Agent says: {tech_analysis.recommendation} ({tech_analysis.confidence}%)")

# View final consensus
print(f"Final Decision: {result['phase_4_decision']['decision']}")

Recommendation Schemas

To ensure the debate logic is programmable and consistent, all agents use Pydantic models defined in agents/schemas.py. This prevents "hallucinated" formats during the consensus phase.

| Component | Type | Description | | :--- | :--- | :--- | | recommendation | Literal["BUY", "SELL", "HOLD"] | The core action suggested by the agent. | | confidence | int (0-100) | Numerical certainty of the agent's analysis. | | key_factors | List[str] | Top 5 data points used in the decision. | | metadata | BaseModel | Domain-specific data (e.g., rsi_signal for Technical, valuation_status for Fundamental). |

Conflict Resolution Logic

The system follows a hierarchy of resolution:

1. Risk Overrule: If the Risk Management agent returns a SELL or HOLD with a confidence > 90% due to volatility or stop-loss concerns, it can overrule BUY signals from other agents.
2. Confidence Weighting: Decisions are not just "one agent, one vote." An agent with 95% confidence has a higher mathematical weight in the final consensus than an agent with 55% confidence.
3. The "Hold" Default: If a clear consensus cannot be reached after a debate, the system defaults to HOLD to preserve capital.