README.md

---
title: Multi Agent Finance Assistant
emoji: 🚀
colorFrom: blue
colorTo: red
sdk: gradio
sdk_version: 5.31.0
app_file: app.py
pinned: false
---

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

# 🚀 Multi-Agent Finance Assistant

A sophisticated AI-powered financial analysis system that delivers spoken market briefs through an intuitive Gradio interface. Built with multiple specialized agents and powered by Google's Gemini 2.0 Flash.

## 🏗️ Architecture Overview

### Agent Ecosystem
```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   API Agent     │    │ Scraping Agent  │    │ Retriever Agent │
│ Real-time Data  │    │ News & Filings  │    │ Vector Search   │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
                    ┌─────────────────┐
                    │  Orchestrator   │
                    │   (FastAPI)     │
                    └─────────────────┘
                                 │
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│ Analysis Agent  │    │ Language Agent  │    │  Voice Agent    │
│ Risk Metrics    │    │ Gemini 2.0 Flash│    │ STT/TTS Pipeline│
└─────────────────┘    └─────────────────┘    └─────────────────┘
```

## 🎯 Key Features

- **🤖 Multi-Agent Architecture**: Six specialized agents working in harmony
- **🎤 Voice Interface**: Speech-to-text and text-to-speech capabilities  
- **📊 Real-time Data**: Live market data via Yahoo Finance API
- **🔍 Smart Retrieval**: Vector search with FAISS embeddings
- **🧠 Advanced AI**: Powered by Google Gemini 2.0 Flash
- **📱 Modern UI**: Attractive Gradio interface with dark mode support
- **☁️ Cloud Ready**: Deployable on Hugging Face Spaces

## 🚀 Quick Start

### Local Development

1. **Clone the repository**
```bash
git clone <your-repo-url>
cd multi-agent-finance-assistant
```

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

3. **Set environment variables**
```bash
export GEMINI_API_KEY="your-gemini-api-key"
export ALPHA_VANTAGE_KEY="your-alphavantage-key"  # Optional
```

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

### Hugging Face Spaces Deployment

1. **Create a new Space** on Hugging Face
2. **Upload all files** to your Space repository
3. **Add secrets** in Space settings:
   - `GEMINI_API_KEY`: Your Google AI Studio API key
4. **Set Space to Gradio** framework
5. **Deploy** and share!

## 📋 Use Case Example

**Morning Market Brief Query:**
> "What's our risk exposure in Asia tech stocks today, and highlight any earnings surprises?"

**AI Response:**
> "Today, your Asia tech allocation is 22% of AUM, up from 18% yesterday. TSMC beat estimates by 4%, Samsung missed by 2%. Regional sentiment is neutral with a cautionary tilt due to rising yields