stock_analysis_telegram_agent

# Stock Analysis Telegram Agent 📈

A multi-agent autonomous trading analysis system that provides real-time stock recommendations via Telegram. Built with **AutoGen**, **TwelveData**, and **NewsAPI**.

## 🚀 Overview

This agent leverages a "Chain of Thought" approach to stock analysis. When a user sends a stock symbol (e.g., `AAPL`, `NVDA`), the system orchestrates multiple agents to fetch technical data and market news, perform sentiment analysis, and generate a unified trade recommendation.

## 🧠 Program Logic & Architecture

The system follows a structured pipeline designed to mimic a professional day trader's workflow:

### 1. Parallel Data Fetching
Upon receiving a symbol, the system triggers parallel requests to:
- **TwelveData API**: Fetches OHLCV (Open, High, Low, Close, Volume) data for three timeframes: `1m`, `15m`, and `1h`.
- **NewsAPI**: Fetches the most recent and relevant news articles from the past 24 hours.

### 2. Sentiment Analysis (SentimentAnalyzer Agent)
The news articles are passed to the `SentimentAnalyzer` agent. This agent:
- Evaluates market reaction and news impact.
- Determines a category (`Positive`, `Neutral`, `Negative`).
- Calculates a sentiment score (`-1` to `1`).
- Provides a rationale with key headlines.

### 3. Trade Recommendation (TradeDecisionAgent)
The `TradeDecisionAgent` aggregates the multi-timeframe candle data and the sentiment report. It follows these steps:
- **Trend Confirmation**: Uses `1h` data to identify the primary trend.
- **Entry Signals**: Analyzes `1m` and `15m` action for optimal entry levels.
- **Sentiment Integration**: Weighs the technical signals against real-time market sentiment.
- **Output Generation**: Produces a structured recommendation including Buy/Sell/Hold, Entry Price, Stop-Loss, Target Price, and a detailed Rationale.

## 📦 Installation (using `uv`)

This project uses [uv](https://github.com/astral-sh/uv), an extremely fast Python package manager.

### 1. Install `uv`
If you haven't installed `uv` yet, run:
```bash
# macOS/Linux
curl -lsSf https://astral.sh/uv/install.sh | sh
```

### 2. Clone the Repository
```bash
git clone https://github.com/alfredang/stock_analysis_telegram_agent.git
cd stock_analysis_telegram_agent
```

### 3. Setup Environment
Initialize the project and install dependencies:
```bash
uv sync
```
This will automatically create a virtual environment in `.venv` and install all required packages.

### 4. Configuration
Create a `.env` file in the root directory and add your API keys:
```env
OPENAI_API_KEY=your_openai_key
TWELVEDATA_API_KEY=your_twelvedata_key
NEWSAPI_API_KEY=your_newsapi_key
TELEGRAM_BOT_TOKEN=your_telegram_bot_token
```

## 🛠 Usage

### Run the Telegram Bot
```bash
uv run stock_agent.py
```

### Run the Logic Test Script (Interactive)
To verify the analysis logic without Telegram, you can run the interactive test script:
```bash
uv run test_analysis.py
```
When prompted, enter a stock ticker (e.g., `AAPL`, `NVDA`). The script will fetch the multi-timeframe candle data, perform sentiment analysis, and display the final unified trade recommendation with rationale directly in your terminal.

## 📝 License
MIT