---
title: Financial Portfolio Intelligence Platform
emoji: 📊
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 5.49.1
app_file: app.py
pinned: true
license: mit
short_description: AI portfolio analysis with multi-agent MCP orchestration
suggested_hardware: cpu-upgrade
startup_duration_timeout: 30m
tags:
  - building-mcp-track-enterprise
  - building-mcp-track-customer
  - building-mcp-track-consumer
  - agents
  - mcp
  - portfolio-analysis
  - finance
  - langgraph
  - gradio
---

<div align="center">

# 📊 Financial Portfolio Intelligence Platform

### AI-Powered Portfolio Analysis with Multi-Agent MCP Orchestration

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![Gradio 5.49.1](https://img.shields.io/badge/gradio-5.49.1-orange.svg)](https://gradio.app/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Claude Sonnet 4.5](https://img.shields.io/badge/Claude-Sonnet%204.5-purple.svg)](https://www.anthropic.com/)
[![MCP Protocol](https://img.shields.io/badge/MCP-Protocol-green.svg)](https://modelcontextprotocol.io/)
[![LangGraph](https://img.shields.io/badge/LangGraph-Agents-red.svg)](https://github.com/langchain-ai/langgraph)

[Features](#-features) • [Demo](#-demo) • [Installation](#-installation) • [Architecture](#-architecture) • [Usage](#-usage)

</div>

---

## 🏆 Hackathon Submission

**Track**: MCP in Action - Consumer | MCP in Action - Enterprise <br>
**Solo Submission**: BrianIsaac <br>
**Demo Video**: [Watch on YouTube](https://www.youtube.com/watch?v=LGl1_E_jaeA) <br>
**Social Media Post**: [LinkedIn Post](https://www.linkedin.com/posts/brianisaac220_financial-portfolio-intelligence-platform-activity-7399478945223729152-9wH9)

---

## 🎯 Motivation

Most agentic AI applications today follow a simple pattern: **fetch data → send to LLM → return response**. This approach works for general tasks but falls short for domains requiring quantitative rigour.

### What's Missing in Current Agentic Workflows

- **Feature Engineering Layer**: Raw data is sent directly to LLMs without transformation into meaningful signals (momentum indicators, factor exposures, correlation structures)
- **Quantitative Model Layer**: No integration of established mathematical models (portfolio optimisation, risk decomposition, statistical forecasting)
- **ML Prediction Layer**: LLMs are used for everything, even tasks better suited to specialised ML models (time-series forecasting, volatility prediction)
- **Multi-Phase Orchestration**: Sequential tool calls rather than parallel execution with proper state management and conflict resolution

### Our Solution

The Portfolio Intelligence Platform addresses these gaps by implementing a **5-phase architecture** that separates concerns: data collection, feature engineering, quantitative computation, ML predictions, and LLM synthesis. Each phase uses the right tool for the job—statistical models for optimisation, foundation models for forecasting, and Claude for reasoning and recommendations.

**9 Specialised MCP Servers** provide structured data and computations:

| Server | What It Does |
|--------|--------------|
| **Yahoo Finance MCP** | Real-time quotes, historical OHLCV data, dividend history, stock metadata |
| **FMP MCP** | Company fundamentals, financial ratios, income statements, balance sheets |
| **Trading MCP** | Technical indicators (RSI, MACD, Bollinger Bands, moving averages, ATR) |
| **FRED MCP** | Economic data (GDP growth, unemployment rate, Fed funds rate, CPI) |
| **Portfolio Optimiser MCP** | HRP, Black-Litterman, and Mean-Variance allocation strategies |
| **Risk Analyser MCP** | VaR, CVaR, GARCH volatility, Sharpe ratio, max drawdown analysis |
| **Ensemble Predictor MCP** | 30-day forecasts using Chronos-Bolt, TTM, and N-HiTS models |
| **News Sentiment MCP** | VADER sentiment analysis on recent financial news articles |
| **Feature Extraction MCP** | Technical and fundamental feature vectors for ML pipelines |

**Application Features** beyond data retrieval:

- **LangGraph Workflow**: 5-phase state machine with parallel execution, custom reducers, and conflict resolution
- **ReAct Agent**: Dynamic tool-calling loop that reasons about which MCP tools to invoke for goal-based portfolio construction
- **Advisory Council**: Multi-agent debate with bull/bear researchers scoring investment theses (0-100 confidence)
- **Persona Agents**: Analysis through Warren Buffett (value), Cathie Wood (growth), and Ray Dalio (macro) lenses
- **Portfolio Rehearsal**: Simulate proposed changes before execution with projected impact analysis
- **Audio Intelligence**: ElevenLabs TTS for narrated analysis and multi-speaker debate playback

This architecture demonstrates that **agentic systems can be both transparent and rigorous**, combining the interpretability of traditional quantitative finance with the flexibility of LLM-based analysis.

### Consumer Value

For **individual investors and retail traders**:

- **Democratised Institutional Analysis**: Access the same quantitative techniques (HRP, Black-Litterman, GARCH) previously available only to hedge funds
- **Plain-English Explanations**: Complex metrics like VaR and Sharpe ratio explained in understandable terms with actionable recommendations
- **Persona-Based Perspectives**: Get analysis through the lens of legendary investors (Buffett, Wood, Dalio) to understand different investment philosophies
- **Audio Accessibility**: Listen to portfolio analysis while commuting or multitasking via natural TTS narration
- **What-If Simulation**: Test proposed portfolio changes before committing real capital with the rehearsal engine

### Enterprise Value

For **wealth managers, RIAs, and financial institutions**:

- **MCP Integration**: 22 tools exposed via standard MCP protocol for integration into existing Claude Desktop or custom LLM workflows
- **Audit Trail**: Complete transparency into data sources, model outputs, and recommendation logic for compliance requirements
- **White-Label Ready**: Modular architecture allows embedding specific MCP servers into proprietary platforms
- **Scalable Infrastructure**: Redis caching, rate limiting, and Supabase PostgreSQL for multi-tenant deployments
- **Multi-Model Ensemble**: Reduce single-model risk with 3 independent foundation models (Chronos-Bolt, TTM, N-HiTS) for forecasting

---

## ✨ Features

### 🎙️ Audio Intelligence (NEW)
- **Text-to-Speech Narration**: All analysis results can be listened to via on-demand audio generation
- **Multi-Speaker Debate Simulation**: Advisory Council debates with distinct voices for bull/bear/consensus perspectives
- **ElevenLabs Integration**: High-quality, natural-sounding voice synthesis
- **Three Audio Features**:
  - 🔊 **Listen to Analysis**: Portfolio analysis summary with recommendations
  - 🔊 **Listen to Portfolio**: Built portfolio summary with holdings
  - 🎭 **Listen to Debate**: Full advisory council debate with multiple speakers

### 🤖 Autonomous Agent Behaviour

1. **LangGraph Workflow Orchestration**: Multi-phase state machine with parallel execution and custom reducers for agent state management
2. **ReAct Agent**: Dynamic tool-calling loop for goal-based portfolio construction with real-time streaming
3. **Advisory Council**: Multi-agent debate system with specialist analysts, bull/bear researchers, and score-based consensus
4. **Persona Agents**: Investment analysis from different perspectives (Warren Buffett value investing, Cathie Wood growth, Ray Dalio macro)

### 📊 Comprehensive Analysis

- **9 MCP Servers**: Yahoo Finance, FMP, Trading-MCP, FRED, Portfolio Optimiser, Risk Analyser, Ensemble Predictor, News Sentiment, Feature Extraction
- **Advanced Risk Metrics**: VaR, CVaR, Monte Carlo simulation, Sharpe ratio, Information Ratio, Calmar Ratio, Ulcer Index, GARCH volatility forecasting
- **ML Forecasting**: Ensemble of 3 foundation models (Chronos-Bolt, TTM, N-HiTS) for 30-day price predictions
- **Quantitative Models**: Hierarchical Risk Parity (HRP), Black-Litterman, Mean-Variance optimisation
- **Real-time Visualisations**: Interactive Plotly charts for allocations, risk, performance, correlations

### 🎯 Four Workflow Tasks

1. **Analyse Portfolio**: Comprehensive analysis with visualisations, risk metrics, and AI recommendations
2. **Build Portfolio**: Goal-based portfolio construction using ReAct agent with dynamic tool selection
3. **Compare Strategies**: Advisory council debate with bull/bear cases and confidence scoring
4. **Test Changes**: Portfolio rehearsal engine simulating proposed modifications

---

### Demo Video

[🎥 Watch Demo Video (1-5 minutes)](https://www.youtube.com/watch?v=LGl1_E_jaeA)

---

## 🏗️ Architecture

### Five-Phase Workflow

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                              User Portfolio Input                            │
└──────────────────────────────────┬──────────────────────────────────────────┘
                                   │
                                   ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│  Phase 1: Data Layer (Parallel Execution)                                   │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌────────────┐           │
│  │  Yahoo     │  │    FMP     │  │ Trading    │  │   FRED     │           │
│  │  Finance   │  │ Financials │  │   MCP      │  │  Economic  │           │
│  └────────────┘  └────────────┘  └────────────┘  └────────────┘           │
│  ┌────────────┐                                                             │
│  │   News     │  Real-time quotes, fundamentals, technical indicators,     │
│  │ Sentiment  │  economic data, sentiment scores                           │
│  └────────────┘                                                             │
└──────────────────────────────────┬──────────────────────────────────────────┘
                                   │
                                   ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│  Phase 1.5: Feature Engineering                                             │
│  ┌────────────────────────────────────────────────────────────┐            │
│  │  Feature Extraction MCP                                     │            │
│  │  Transform raw data into ML-ready technical and            │            │
│  │  fundamental features (momentum, factors, correlations)    │            │
│  └────────────────────────────────────────────────────────────┘            │
└──────────────────────────────────┬──────────────────────────────────────────┘
                                   │
                                   ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│  Phase 2: Computation Layer (Parallel Execution)                            │
│  ┌────────────────────────┐     ┌────────────────────────┐                │
│  │ Portfolio Optimiser    │     │   Risk Analyser        │                │
│  │ • HRP                  │     │ • VaR / CVaR           │                │
│  │ • Black-Litterman      │     │ • Monte Carlo          │                │
│  │ • Mean-Variance        │     │ • GARCH Volatility     │                │
│  └────────────────────────┘     └────────────────────────┘                │
└──────────────────────────────────┬──────────────────────────────────────────┘
                                   │
                                   ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│  Phase 2.5: ML Predictions                                                  │
│  ┌────────────────────────────────────────────────────────────┐            │
│  │  Ensemble Predictor MCP                                     │            │
│  │  3 Foundation Models: Chronos-Bolt + TTM + N-HiTS          │            │
│  │  30-day price forecasts with confidence intervals          │            │
│  └────────────────────────────────────────────────────────────┘            │
└──────────────────────────────────┬──────────────────────────────────────────┘
                                   │
                                   ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│  Phase 3: LLM Synthesis                                                     │
│  ┌────────────────────────────────────────────────────────────┐            │
│  │  Claude Sonnet 4.5                                          │            │
│  │  Synthesise quantitative results into actionable insights  │            │
│  │  with transparent reasoning and recommendations            │            │
│  └────────────────────────────────────────────────────────────┘            │
└──────────────────────────────────┬──────────────────────────────────────────┘
                                   │
                                   ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                          Results & Outputs                                   │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐                     │
│  │    Text      │  │    Audio     │  │    Visual    │                     │
│  │   Results    │  │  Narration   │  │    Charts    │                     │
│  │  Analysis    │  │  (ElevenLabs)│  │   (Plotly)   │                     │
│  └──────────────┘  └──────────────┘  └──────────────┘                     │
└─────────────────────────────────────────────────────────────────────────────┘
```

### MCP Server Integration

The platform exposes **22 MCP tools** via Gradio's native MCP server at `/gradio_api/mcp/`. These tools are organised into namespaced categories:

| Category | Tools | Purpose |
|----------|-------|---------|
| **market_*** | 10 tools | Quotes, historical data, fundamentals, financials, economic data |
| **technical_*** | 5 tools | Indicators, feature extraction, normalisation, selection |
| **portfolio_*** | 3 tools | HRP, Black-Litterman, Mean-Variance optimisation |
| **risk_*** | 2 tools | VaR/CVaR analysis, GARCH volatility forecasting |
| **ml_*** | 1 tool | Ensemble forecasting (Chronos-Bolt + statistical models) |
| **sentiment_*** | 1 tool | News sentiment analysis |

**MCP Client Configuration:**
```json
{
  "mcpServers": {
    "portfolio-intelligence": {
      "url": "https://mcp-1st-birthday-finance-portfolio-intelligence-platform.hf.space/gradio_api/mcp/"
    }
  }
}
```

#### Backend MCP Servers

| MCP Server | Purpose | Data Provided | API Provider |
|------------|---------|---------------|--------------|
| **Yahoo Finance** | Market data | Real-time quotes, historical prices, dividends | yfinance |
| **FMP** | Fundamentals | Financial ratios, company profiles, key metrics | financialmodelingprep.com |
| **Trading-MCP** | Technical analysis | RSI, MACD, Bollinger Bands, moving averages | Internal |
| **FRED** | Economic data | GDP, unemployment, Fed funds rate | Federal Reserve |
| **Portfolio Optimiser** | Allocation | HRP, Black-Litterman, Mean-Variance weights | PyPortfolioOpt |
| **Risk Analyser** | Risk metrics | VaR, CVaR, Sharpe, Sortino, max drawdown | riskfolio-lib |
| **Ensemble Predictor** | ML forecasts | 30-day price predictions with confidence | Chronos-Bolt + TTM + N-HiTS |
| **News Sentiment** | Sentiment analysis | VADER sentiment scores on recent news | VADER + Finnhub |
| **Feature Extraction** | ML features | Technical and fundamental feature vectors | Internal |

### Technology Stack

<table>
<tr>
<td valign="top" width="50%">

**Frontend & UI**
- Gradio 5.49.1
- Plotly for visualisations
- Responsive bento grid layout

**Agent Orchestration**
- LangGraph for workflow
- PydanticAI for structured outputs
- Custom ReAct implementation

**LLM & AI**
- Claude Sonnet 4.5 (Anthropic)
- ElevenLabs TTS for audio
- Pydantic for validation

</td>
<td valign="top" width="50%">

**Quantitative Finance**
- PyPortfolioOpt
- riskfolio-lib
- arch (GARCH models)
- QuantStats

**ML & Forecasting**
- Amazon Chronos-Bolt (9M params)
- IBM Tiny Time Mixers (TTM)
- Nixtla N-HiTS
- scikit-learn

**Infrastructure**
- FastMCP 2.9.1 + Native Gradio MCP
- Supabase PostgreSQL
- Redis (Upstash) with in-memory fallback
- Sentry error monitoring

</td>
</tr>
</table>

---

## 🚀 Installation

### Deployment Options

The platform supports two deployment methods:

| Method | Use Case | SDK | Configuration |
|--------|----------|-----|---------------|
| **Hugging Face Spaces** | Production hosting | Gradio SDK 5.49.1 | `requirements.txt` + `packages.txt` |
| **Local Development** | Development & testing | uv + pyproject.toml | `uv sync` |

### Option 1: Hugging Face Spaces (Recommended)

The easiest way to deploy is via Hugging Face Spaces with the Gradio SDK:

1. Fork this repository to your Hugging Face account
2. Add your API keys as Space Secrets (Settings → Variables and secrets)
3. The Space will automatically build and deploy

**Required Secrets:**
- `ANTHROPIC_API_KEY` - Claude API access

**Optional Secrets:**
- `ELEVENLABS_API_KEY` - Audio narration
- `FMP_API_KEY` - Financial data
- `SUPABASE_URL`, `SUPABASE_KEY` - Database
- `SENTRY_DSN` - Error monitoring

### Option 2: Local Development

#### Prerequisites

- **Python 3.10+** ([Download](https://www.python.org/downloads/))
- **uv package manager** ([Install](https://github.com/astral-sh/uv))
- **Anthropic API Key** ([Get Key](https://console.anthropic.com/))

#### Quick Start

```bash
# 1. Clone the repository
git clone https://github.com/yourusername/Portfolio-Intelligence-Platform.git
cd Portfolio-Intelligence-Platform

# 2. Install dependencies with uv
uv sync

# 3. Set up environment variables
cp .env.example .env
# Edit .env with your API keys

# 4. Run the application
uv run python app.py

# 5. Open your browser
# Navigate to http://localhost:7860
# MCP endpoint at http://localhost:7860/gradio_api/mcp/
```

### Environment Configuration

Create a `.env` file with the following variables:

```bash
# Required - Core LLM
ANTHROPIC_API_KEY=your_anthropic_key_here

# Optional - Audio Features (NEW)
ELEVENLABS_API_KEY=your_elevenlabs_key_here  # For audio narration
ELEVENLABS_ENABLED=true

# Optional - Enhanced Data Sources
FMP_API_KEY=your_fmp_key_here                 # Financial Modeling Prep
FRED_API_KEY=your_fred_key_here               # Federal Reserve data
FINNHUB_API_KEY=your_finnhub_key_here         # News sentiment

# Optional - Database & Caching
SUPABASE_URL=your_supabase_url
SUPABASE_KEY=your_supabase_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_service_key
UPSTASH_REDIS_URL=your_redis_url
UPSTASH_REDIS_TOKEN=your_redis_token

# Optional - Monitoring
SENTRY_DSN=your_sentry_dsn                     # Error tracking
SENTRY_TIER=free                               # free, hobby, or professional

# Optional - Configuration
MARKET_DATA_PROVIDER=yfinance                  # or 'fmp'
CACHE_ENABLED=true
RATE_LIMIT_ENABLED=true

# Optional - Logging Control
LOG_LEVEL=INFO                                 # DEBUG, INFO, WARNING, ERROR, CRITICAL, OFF
LOGGING_ENABLED=true                           # true/false to enable/disable all logging
```

### API Keys Guide

| Service | Purpose | Tier | Link |
|---------|---------|------|------|
| **Anthropic** | Claude LLM | Required | [Get Key](https://console.anthropic.com/) |
| **ElevenLabs** | Audio narration | Optional | [Get Key](https://elevenlabs.io/) |
| **FMP** | Financial data | Optional | [Get Key](https://financialmodelingprep.com/) |
| **FRED** | Economic data | Optional | [Get Key](https://fred.stlouisfed.org/docs/api/) |
| **Finnhub** | News data | Optional | [Get Key](https://finnhub.io/) |
| **Supabase** | Database | Optional | [Get Key](https://supabase.com/) |
| **Upstash** | Redis cache | Optional | [Get Key](https://upstash.com/) |
| **Sentry** | Error monitoring | Optional | [Get Key](https://sentry.io/) |

---

## 📖 Usage

### Portfolio Input Formats

The platform accepts multiple input formats for flexibility:

```python
# Format 1: Ticker and percentage
AAPL 40
MSFT 30
GOOGL 30

# Format 2: Ticker and shares
TSLA 25 shares
NVDA 15 shares

# Format 3: Ticker and dollar amount
BTC $5000
ETH $3000

# Format 4: Crypto with decimals
BTC 0.5
ETH 2.3
```

### Example Workflows

#### 1. Analyse Existing Portfolio

```
1. Navigate to "Analyse Portfolio" tab
2. Enter your holdings:
   AAPL 40
   MSFT 30
   GOOGL 20
   NVDA 10
3. (Optional) Select a persona: Warren Buffett, Cathie Wood, Ray Dalio
4. Click "Analyse"
5. Review comprehensive analysis with charts
6. Click "🔊 Listen to Analysis" for audio summary
```

#### 2. Build New Portfolio from Goals

```
1. Navigate to "Build Portfolio" tab
2. Select investment goals:
   ☑ Growth
   ☑ Income
3. Set risk tolerance: 7/10
4. Add constraints: "Focus on tech sector, avoid China"
5. Click "Submit"
6. Watch ReAct agent work in real-time
7. Click "🔊 Listen to Portfolio" for audio summary
```

#### 3. Compare Investment Strategies

```
1. Navigate to "Compare Strategies" tab
2. Enter portfolio to debate:
   TSLA 100
3. Click "Submit"
4. Watch Advisory Council debate:
   - 5 specialist analysts run in parallel
   - Bull case with confidence score
   - Bear case with confidence score
   - Consensus recommendation
5. Click "🎭 Listen to Debate" for multi-speaker audio
```

### Example Portfolios

<details>
<summary>Tech Growth Portfolio</summary>

```
AAPL 25
MSFT 20
GOOGL 20
NVDA 15
TSLA 10
AMZN 10
```

</details>

<details>
<summary>Conservative Income Portfolio</summary>

```
VOO 40
VTI 30
SCHD 20
BND 10
```

</details>

<details>
<summary>Balanced Portfolio</summary>

```
VTI 35
VXUS 25
BND 25
GLD 10
VNQ 5
```

</details>

<details>
<summary>Crypto Portfolio</summary>

```
BTC 50
ETH 30
SOL 10
AVAX 5
LINK 5
```

</details>

---

## 📁 Project Structure

```
Portfolio-Intelligence-Platform/
│
├── app.py                          # Main Gradio interface (~4,950 lines)
│
├── backend/
│   ├── agents/
│   │   ├── council/
│   │   │   └── advisory_council.py # Bull/bear debate system
│   │   ├── base_agent.py           # Base agent class with PydanticAI
│   │   ├── workflow.py             # LangGraph 5-phase workflow
│   │   ├── workflow_router.py      # Workflow routing logic
│   │   ├── react_agent.py          # ReAct portfolio builder
│   │   ├── portfolio_analyst.py    # LLM synthesis agent
│   │   ├── personas.py             # Investor personas (Buffett, Wood, Dalio)
│   │   └── rehearsal.py            # Change simulation engine
│   │
│   ├── audio/
│   │   └── tts_service.py          # ElevenLabs TTS integration
│   │
│   ├── mcp_servers/                # 9 MCP server implementations
│   │   ├── yahoo_finance_mcp.py    # Market data (yfinance)
│   │   ├── fmp_mcp.py              # Fundamentals (FMP API)
│   │   ├── trading_mcp.py          # Technical indicators
│   │   ├── fred_mcp.py             # Economic data (FRED API)
│   │   ├── portfolio_optimizer_mcp.py  # HRP, Black-Litterman, Mean-Variance
│   │   ├── risk_analyzer_mcp.py    # VaR, CVaR, GARCH, risk metrics
│   │   ├── ensemble_predictor_mcp.py   # Chronos-Bolt + TTM + N-HiTS
│   │   ├── news_sentiment_mcp.py   # VADER sentiment (Finnhub)
│   │   └── feature_extraction_mcp.py   # Technical/fundamental features
│   │
│   ├── models/
│   │   ├── agent_state.py          # LangGraph state with reducers
│   │   └── portfolio.py            # Pydantic data models
│   │
│   ├── data_providers/
│   │   ├── base.py                 # Base provider interface
│   │   ├── factory.py              # Provider factory pattern
│   │   ├── yfinance_provider.py    # Yahoo Finance implementation
│   │   └── fmp_provider.py         # FMP implementation
│   │
│   ├── visualizations/
│   │   └── plotly_charts.py        # Interactive Plotly charts
│   │
│   ├── caching/
│   │   ├── redis_cache.py          # Redis/Upstash implementation
│   │   ├── decorators.py           # Cache decorators
│   │   └── factory.py              # Cache factory
│   │
│   ├── rate_limiting/
│   │   ├── fixed_window.py         # Fixed window algorithm
│   │   └── limiter.py              # Rate limiter interface
│   │
│   ├── stress_testing/
│   │   ├── scenarios.py            # Market stress scenarios
│   │   ├── simulator.py            # Monte Carlo simulation
│   │   └── visualizations.py       # Stress test charts
│   │
│   ├── tax/
│   │   ├── calculator.py           # Tax calculations
│   │   ├── optimizer.py            # Tax-loss harvesting
│   │   ├── interface.py            # Tax interfaces
│   │   ├── models.py               # Tax data models
│   │   └── tests/                  # Tax calculation tests
│   │
│   ├── monitoring/
│   │   └── sentry.py               # Sentry error tracking
│   │
│   ├── utils/
│   │   ├── serialisation.py        # JSON/Decimal serialisation
│   │   └── uuid_generator.py       # UUID generation
│   │
│   ├── mcp_tools.py                # Unified MCP tools (22 namespaced functions)
│   ├── mcp_router.py               # MCP orchestration (compatibility layer)
│   ├── auth.py                     # Supabase authentication
│   ├── database.py                 # PostgreSQL client
│   ├── config.py                   # Configuration management
│   ├── logging_config.py           # Centralised logging control
│   ├── export.py                   # PDF/CSV export utilities
│   └── theme.py                    # UI theme configuration
│
├── database/
│   ├── schema.sql                  # PostgreSQL schema
│   └── setup_database.py           # Database initialisation script
│
├── tests/
│   ├── conftest.py                 # Pytest configuration
│   ├── test_advisory_council.py    # Advisory council tests
│   ├── test_integration.py         # Integration tests
│   ├── test_mcp_servers.py         # MCP server tests
│   ├── test_mcp_tools.py           # MCP tools tests
│   ├── test_p1_features.py         # P1 feature tests
│   ├── test_rehearsal.py           # Rehearsal engine tests
│   └── test_single_asset_portfolio.py  # Single asset tests
│
├── pyproject.toml                  # uv dependencies (local development)
├── requirements.txt                # pip dependencies (HF Spaces)
├── packages.txt                    # System dependencies (HF Spaces)
├── uv.lock                         # Locked dependencies
├── Dockerfile                      # Docker deployment (optional)
└── README.md                       # This file
```

---

## 🔧 Advanced Configuration

### Market Data Providers

Switch between data providers:

```bash
# yfinance (free, educational use only)
MARKET_DATA_PROVIDER=yfinance

# Financial Modeling Prep (recommended for production)
MARKET_DATA_PROVIDER=fmp
FMP_API_KEY=your_key_here
FMP_TIER=free  # or 'starter', 'professional'
```

### Caching Strategy

Configure Redis caching for performance:

```bash
CACHE_ENABLED=true
CACHE_FALLBACK_ENABLED=true
CACHE_TTL_QUOTES=60          # 1 minute
CACHE_TTL_HISTORICAL=14400   # 4 hours
CACHE_TTL_FUNDAMENTALS=86400 # 24 hours
```

### Rate Limiting

Tiered rate limiting with fixed daily windows:

```bash
RATE_LIMIT_ENABLED=true
RATE_LIMIT_ANONYMOUS_CAPACITY=1      # 1 analysis/day
RATE_LIMIT_AUTHENTICATED_CAPACITY=3  # 3 analyses/day
RATE_LIMIT_PREMIUM_CAPACITY=200      # 200 analyses/day
```

### Logging Control

Control logging verbosity via environment variables:

```bash
# Set logging level (default: INFO)
LOG_LEVEL=INFO          # Options: DEBUG, INFO, WARNING, ERROR, CRITICAL, OFF

# Completely disable all logging (default: true)
LOGGING_ENABLED=true    # Set to 'false' to silence all logs

# Examples:
LOG_LEVEL=DEBUG         # Verbose debugging output
LOG_LEVEL=ERROR         # Only errors and above
LOG_LEVEL=OFF           # Disable all logging
LOGGING_ENABLED=false   # Alternative way to disable logging
```

**Note**: On HuggingFace Spaces, set these in Settings → Variables and secrets.

---

## 🤝 Contributing

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

### Development Setup

```bash
# Install dev dependencies
uv sync --all-extras

# Run tests
uv run pytest

# Format code
uv run ruff format .

# Lint
uv run ruff check .
```

### Areas for Contribution

- 🌍 Additional market data providers (Alpha Vantage, EODHD)
- 📊 New visualisation types
- 🎯 Additional persona agents
- 🔊 More voice options for audio features
- 🌐 Internationalisation (i18n)
- 📚 Documentation improvements

---

## 🐛 Troubleshooting

<details>
<summary>Common Issues</summary>

### Audio Not Playing

**Issue**: Audio button appears but no audio plays

**Solution**:
- Check `ELEVENLABS_API_KEY` is set in `.env`
- Verify API key is valid at https://elevenlabs.io/
- Check browser console for errors

### Rate Limiting Errors

**Issue**: "Rate limit exceeded" message

**Solution**:
- Wait until daily reset (midnight UTC)
- Authenticate for higher limits
- Disable rate limiting in development: `RATE_LIMIT_ENABLED=false`

### yfinance Data Errors

**Issue**: "No data found for ticker"

**Solution**:
- Use correct ticker format (e.g., `BTC-USD` for crypto)
- Switch to FMP provider: `MARKET_DATA_PROVIDER=fmp`
- Check ticker exists on Yahoo Finance

### Slow Performance

**Issue**: Analysis takes too long

**Solution**:
- Enable Redis caching
- Use FMP instead of yfinance
- Reduce number of holdings in portfolio
- Check internet connection

### Too Many Logs / Verbose Output

**Issue**: Console flooded with log messages

**Solution**:
- Set `LOG_LEVEL=WARNING` or `LOG_LEVEL=ERROR` for quieter output
- Set `LOGGING_ENABLED=false` to completely disable logging
- On HuggingFace Spaces, add these in Settings → Variables and secrets

</details>

---

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

## 🙏 Acknowledgements

- Built for **MCP 1st Birthday Hackathon** by Anthropic & Gradio
- Powered by **Claude Sonnet 4.5** from Anthropic
- Quantitative models from **PyPortfolioOpt** and **riskfolio-lib**
- ML forecasting with **Amazon Chronos-Bolt**
- Audio synthesis by **ElevenLabs**
- MCP Protocol specification by Anthropic
- UI framework by Gradio

---

## 📞 Contact & Support

- **Discussions**: [Ask questions or share ideas](https://huggingface.co/spaces/MCP-1st-Birthday/Finance-Portfolio-Intelligence-Platform/discussions)

---

<div align="center">

**⭐ Star this repo if you find it useful!**

Made with ❤️ for the MCP 1st Birthday Hackathon

[⬆ Back to Top](#-portfolio-intelligence-platform)

</div>