Spaces:

MCP-1st-Birthday
/

Finance-Portfolio-Intelligence-Platform

Running on Zero

App Files Files Community

Finance-Portfolio-Intelligence-Platform / README.md

BrianIsaac

docs: add demo video and LinkedIn post links to README

52179de 12 days ago

preview code

raw

history blame contribute delete

35.5 kB

A newer version of the Gradio SDK is available: 6.0.2

Upgrade

metadata

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

📊 Financial Portfolio Intelligence Platform

AI-Powered Portfolio Analysis with Multi-Agent MCP Orchestration

Features • Demo • Installation • Architecture • Usage

🏆 Hackathon Submission

Track: MCP in Action - Consumer | MCP in Action - Enterprise
Solo Submission: BrianIsaac
Demo Video: Watch on YouTube
Social Media Post: LinkedIn Post

🎯 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

LangGraph Workflow Orchestration: Multi-phase state machine with parallel execution and custom reducers for agent state management
ReAct Agent: Dynamic tool-calling loop for goal-based portfolio construction with real-time streaming
Advisory Council: Multi-agent debate system with specialist analysts, bull/bear researchers, and score-based consensus
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

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

Demo Video

🎥 Watch Demo Video (1-5 minutes)

🏗️ 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:

{
  "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

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

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

🚀 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:

Fork this repository to your Hugging Face account
Add your API keys as Space Secrets (Settings → Variables and secrets)
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)
uv package manager (Install)
Anthropic API Key (Get Key)

Quick Start

# 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:

# 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
ElevenLabs	Audio narration	Optional	Get Key
FMP	Financial data	Optional	Get Key
FRED	Economic data	Optional	Get Key
Finnhub	News data	Optional	Get Key
Supabase	Database	Optional	Get Key
Upstash	Redis cache	Optional	Get Key
Sentry	Error monitoring	Optional	Get Key

📖 Usage

Portfolio Input Formats

The platform accepts multiple input formats for flexibility:

# 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

Tech Growth Portfolio

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

Conservative Income Portfolio

VOO 40
VTI 30
SCHD 20
BND 10

Balanced Portfolio

VTI 35
VXUS 25
BND 25
GLD 10
VNQ 5

Crypto Portfolio

BTC 50
ETH 30
SOL 10
AVAX 5
LINK 5

📁 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:

# 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:

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:

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:

# 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

# 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

Common Issues

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

📄 License

This project is licensed under the MIT License - see the 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

📊 Financial Portfolio Intelligence Platform

AI-Powered Portfolio Analysis with Multi-Agent MCP Orchestration

🏆 Hackathon Submission

🎯 Motivation

What's Missing in Current Agentic Workflows

Our Solution

Consumer Value

Enterprise Value

✨ Features

🎙️ Audio Intelligence (NEW)

🤖 Autonomous Agent Behaviour

📊 Comprehensive Analysis

🎯 Four Workflow Tasks

Demo Video

🏗️ Architecture

Five-Phase Workflow

MCP Server Integration

Backend MCP Servers

Technology Stack

🚀 Installation

Deployment Options

Option 1: Hugging Face Spaces (Recommended)

Option 2: Local Development

Prerequisites

Quick Start

Environment Configuration

API Keys Guide

📖 Usage

Portfolio Input Formats

Example Workflows

1. Analyse Existing Portfolio

2. Build New Portfolio from Goals

3. Compare Investment Strategies

Example Portfolios

📁 Project Structure

🔧 Advanced Configuration

Market Data Providers

Caching Strategy

Rate Limiting

Logging Control

🤝 Contributing

Development Setup

Areas for Contribution

🐛 Troubleshooting

Audio Not Playing

Rate Limiting Errors

yfinance Data Errors

Slow Performance

Too Many Logs / Verbose Output

📄 License

🙏 Acknowledgements

📞 Contact & Support