Kairos: Multi-Agent LLM Stock Alerting Framework

Project Overview

Kairos is an automated financial intelligence system designed to address the latency and manual overhead inherent in retail investing. While average investors often react late to market-moving news and must manually review financial context, Kairos automates the ingestion, analysis, and decision-making process.

The system functions as a fully autonomous agent that scrapes real-time news, enriches it with financial data, and utilizes a multi-agent Large Language Model (LLM) architecture to simulate a dialectical debate regarding the market impact. This approach prioritizes custom agent conversations over basic sentiment analysis to generate high-conviction trading signals.

System Architecture

The pipeline is structured into three primary stages: Data Ingestion, Agent Analysis, and Decision Execution.

1. Data Ingestion

The system monitors high-velocity information streams to identify relevant market events:

• Yahoo Finance: Scraped using Playwright for breaking news articles.
• Stocktwits: Accessed via API to track trending sentiment.
• Reddit (Stocks Sub): Accessed via API to track trending sentiment.
• Truth Social: Monitored for geopolitical commentary affecting specific equities.

2. Analysis Engine (The War Room)

Upon detecting news, the system executes a multi-step analytical workflow:

• Contextual Enrichment: A Stock Ticker Agent identifies relevant companies and utilizes yfinance to fetch real-time financial metrics (price, P/E, volatility) to ground the analysis in hard data.
• Dialectical Debate: Two distinct agents, a "Bull Analyzer" and a "Bear Analyzer," engage in a two-round debate to assess the news from opposing viewpoints (opportunity vs. risk).
• Model Specification: The system utilizes gpt-5-mini for agent inference to balance performance and cost.

3. Decision and Notification

• Portfolio Manager: A "Decision Maker" agent synthesizes the Bull/Bear arguments and financial data to render a final verdict: Buy, Sell, or Hold.
• Alerting: Actionable recommendations are formatted into a concise summary and delivered via Twilio SMS.

Sample Kairos Input/Output

• Note: Actual LLM reasoning/conversation examples can be found in the "Sample Output" folder.

Key Features & Differentiators

• Agentic Reasoning: Unlike simple sentiment analysis, Kairos employs a conversational framework where agents challenge each other's theses to reduce bias.
• Cost Efficiency: The system operates at approximately $0.02 per processed article, offering a low-cost alternative to institutional tools.
• Automation: The pipeline is fully autonomous, moving from raw news scraping to SMS alert without human intervention.

Performance and Limitations

• Latency: The process from news scraping to message delivery occurs in minutes.
• Computation: While faster than manual analysis, the system faces computational limits compared to high-frequency trading (HFT) infrastructure.
• Accuracy: Users should be aware that LLM agents may occasionally hallucinate arguments or financial context.

Technical Stack

• Language: Python
• Deployment: Docker
• AI/ML: OpenAI API (gpt-5-mini)
• Web Scraping: Playwright, Requests
• Financial Data: yfinance
• Notifications: Twilio

Setup

Docker (Recommended)

1. Create .env file:

   OPENAI_API_KEY=your_key
   TWILIO_SID=your_sid
   TWILIO_TOKEN=your_token
   TWILIO_FROM_NUMBER=+1234567890
   TWILIO_TO_NUMBER=+1234567890
   

2. Build and run:

   docker build -t kairos .
   docker run --env-file .env kairos

Local Setup

1. Install dependencies:

   pip install -r requirements.txt
   playwright install chromium

2. Configure .env (same as Docker)

3. Run:

   python orchestrator.py