README.md

---
title: Financial Advisory Agent
emoji: 🧑‍💼
colorFrom: gray
colorTo: blue
sdk: gradio
sdk_version: 5.33.0
app_file: app.py
tags:
  - mcp-server-track
  - financial-analysis
  - openai
  - tavily
pinned: false
license: apache-2.0
short_description: Financial analysis, investments, budget planning, and more.
---


# AI Financial Advisory Agent

An intelligent financial advisory agent powered by OpenAI's GPT-4.1 and specialized financial tools. This agent provides comprehensive financial analysis, investment recommendations, budget planning, and market insights through an intuitive web interface.

**Watch the demo video:** [Financial Advisory Agent Demo (Hugging Face Hackathon)](https://youtu.be/vGOSAXyrQgM)


[![Watch the demo on YouTube](public/images/image.png)](https://youtu.be/vGOSAXyrQgM)

## 🚀 Features

### Core Financial Tools
- **📊 Investment Analyzer**: Real-time stock analysis with technical indicators, risk assessment, and investment recommendations
- **💰 Budget Planner**: Personalized budget creation using the 50/30/20 rule with optimization suggestions
- **📈 Portfolio Analyzer**: Portfolio diversification analysis and performance optimization
- **📰 Market Trends Analyzer**: Real-time market news, sector analysis, and economic insights

### Advanced Features
- **🎯 Smart Response Type Detection**: Automatically detects if users want short summaries or detailed reports
- **⚡ Real-time LLM Streaming**: Live token-by-token response generation from OpenAI API
- **📋 Interactive Tool Results**: Collapsible sections for clean data presentation
- **🔍 Comprehensive Data Analysis**: Enhanced insights for all financial data

## 🛠️ Installation

1. **Clone the repository**
```bash
git clone https://huggingface.co/spaces/Agents-MCP-Hackathon/Financial-Advisory-Agent.git
cd Financial-Advisory-Agent
```

2. **Install dependencies**
```bash
pip install -r requirements.txt
```

3. **Set up environment variables**
Set environment variables:
```bash
export OPENAI_API_KEY="your-openai-api-key"
export TAVILY_API_KEY="your-tavily-api-key"
```

4. **Run the application**
```bash
python app.py
```

## 🎯 Response Types

The system automatically detects your preference:

### Short Response Keywords
- `quick`, `brief`, `short`, `summary`, `concise`, `simple`, `fast`, `tldr`, `bottom line`

### Detailed Response Keywords  
- `detailed`, `comprehensive`, `thorough`, `in-depth`, `report`, `breakdown`, `explain`, `elaborate`, `deep dive`

### Default Behavior
- **Short responses** are the default (under 200 words)
- **Detailed responses** are triggered by specific keywords (comprehensive analysis)

## 🔧 Technical Architecture

- **Frontend**: Gradio web interface with real-time streaming
- **Backend**: LangChain agents with OpenAI GPT-4.1
- **Data Sources**: 
  - Yahoo Finance API for stock data
  - Tavily Search API for market news
  - Real-time financial calculations
- **Streaming**: Direct LLM token streaming from OpenAI API
- **Tools**: Specialized financial analysis functions

## 📊 Tool Capabilities

### Investment Analyzer
- Real-time stock prices and historical data
- Technical indicators (RSI, MACD, Bollinger Bands, Moving Averages)
- Risk assessment (volatility, VaR, beta analysis)
- Fundamental analysis (P/E, P/B ratios, dividend yield)
- Buy/Hold/Sell recommendations with confidence scores

### Budget Planner
- 50/30/20 rule implementation
- Emergency fund calculations
- Debt-to-income ratio analysis
- Savings optimization recommendations
- Expense category warnings

### Market Trends Analyzer
- Real-time market news via Tavily Search
- Major index tracking (S&P 500, NASDAQ)
- Market sentiment analysis
- Key theme extraction
- Economic trend identification

### Portfolio Analyzer
- Diversification scoring
- Sector allocation analysis
- Concentration risk assessment
- Rebalancing recommendations
- Performance metrics


## 🚀 Recent Updates

- ✅ **Smart Response Detection**: Automatically detects if users want short or detailed responses
- ✅ **Real LLM Streaming**: Genuine token-by-token streaming from OpenAI API
- ✅ **Improved Data Analysis**: Comprehensive insights
- ✅ **Optimized Performance**: Faster tool execution and response times
- ✅ **Collapsible Results**: Clean, organized tool output presentation

## 🔒 API Keys Required

- **OpenAI API Key**: For language model
- **Tavily API Key**: For real-time market news and trends

## Issues to Resolve
The problem is in the current flow:
1. Agent executor runs all tools
2. We collect ALL results
3. Then display everything at once
4. Then stream the final response

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.