🧠 Robo Advisor with Risk, Portfolio, Investment & Trading Agents

This repository implements a complete 5-step intelligent, modular robo-advising platform built on
LLM-powered agents orchestrated with LangGraph.
The system integrates conversational intent detection, questionnaire-based risk profiling,
portfolio optimization, fund selection, trading execution workflows, and a modern Streamlit web interface.

---

🏗 Architecture Overview

User
 └──> Entry Agent (ChatOpenAI)
       ├─ natural conversation
       ├─ manages phase summaries and user intent
       ├─ routes based on intent flags:
       │    ├─ Risk Agent  → equity setting OR questionnaire-based guidance
       │    ├─ Portfolio Agent → mean-variance optimizer
       │    ├─ Investment Agent → fund selection & analysis
       │    ├─ Trading Agent → executable trading requests
       │    └─ Reviewer Agent → when awaiting final input
       ↓
 ├──> Risk Agent (ChatOpenAI + Tool)
 │      ├─ handles direct equity setting commands
 │      ├─ runs 7 risk-profiling questions (when guidance requested)
 │      ├─ produces {"equity": x, "bond": 1-x}
 │      └─ writes recommendation to shared state
 │
 ├──> Portfolio Agent (ChatOpenAI + Tool)
 │      ├─ reads equity/bond split from risk output
 │      ├─ expands into detailed asset-class sleeves via **mean/variance optimization**
 │      ├─ allows user edits to λ (risk-aversion) and cash-reserve inputs
 │      ├─ outputs an **asset-class portfolio dictionary**
 │      └─ routes to Investment Agent for fund selection
 │
 ├──> Investment Agent (ChatOpenAI + Fund Analysis)
 │      ├─ selects ETFs/funds for each asset class
 │      ├─ provides 4 selection criteria (Balanced, Low Cost, High Performance, Low Risk)
 │      ├─ analyzes funds using Yahoo Finance API
 │      ├─ allows user review and editing of selections
 │      └─ outputs **investment portfolio with tickers**
 │
 ├──> Trading Agent (ChatOpenAI + Rebalancing Engine)
 │      ├─ generates executable trading requests
 │      ├─ uses demo scenarios for realistic testing
 │      ├─ implements tax-aware rebalancing optimization
 │      ├─ outputs **simple trading table** (ticker, action, price, shares)
 │      └─ provides execution summary
 │
└──> Reviewer Agent (ChatOpenAI)
       ├─ validates completion of all phases
       ├─ shows final summary when all complete
       ├─ handles "start over" and "finish" options
       ├─ routes back to Entry Agent for next phase
       └─ manages phase transitions and state updates

---

🧩 Key Components

---

⚙️ Setup & Run

1. Environment Setup

# Create conda environment
conda create -n roboadvisor python=3.11
conda activate roboadvisor

# Install dependencies
pip install -r requirements.txt

2. Environment Variables

Create a .env file in the project root:

OPENAI_API_KEY=sk-your-key
OPENAI_MODEL=gpt-4o-mini
OPENAI_TEMPERATURE=0.2

3. Run the Application

Option A: Streamlit Web Interface (Recommended)

streamlit run streamlit_app.py

The app will open in your browser at http://localhost:8501

Option B: Command Line Interface

python app.py

---

🎨 Streamlit Web Interface Features

Interactive Chat Interface

• Real-time back-and-forth communication with the AI robo-advisor
• Clean message input with automatic form submission
• Displays latest AI response prominently

Real-time Data Visualization

• Risk Assessment: Bar charts for equity/bond allocation + collapsible questionnaire answers
• Portfolio: Interactive pie charts + detailed allocation tables with weights
• Investment: Comprehensive fund selection table with tickers, weights, and selection criteria
• Trading: Clean table format for trading requests with execution details

Process Status Tracking

• Visual progress indicators for each of the 4 main phases
• Color-coded status indicators (complete/pending/not started)
• Progress bar in sidebar showing completion percentage

Advanced UI Features

• Collapsible Message History: Expandable conversation log (shows last 15 messages)
• Reset Functionality: One-click reset button to clear state and restart
• Reactive Design: Sections only appear when relevant data exists
• Modern Styling: Professional interface with custom CSS and responsive layout

---

🧠 Agent Behaviors

Entry Agent

• Central orchestrator for the entire user flow
• Shows welcome message and phase summaries for each completed stage
• Manages user intent classification (proceed, learn_more)
• Routes to specific agents based on intent flags:
  • → Risk Agent when intent_to_risk=True
  • → Portfolio Agent when intent_to_portfolio=True
  • → Investment Agent when intent_to_investment=True
  • → Trading Agent when intent_to_trading=True
  • → Reviewer Agent when reviewer is awaiting input
• Uses LLM structured output for intent classification
• Provides phase summaries before transitioning to next phase

Risk Agent

• Handles all risk-related functionality including:
  • Direct equity setting commands: "set equity 0.6", "set equity to 60%"
  • Risk guidance through 7-question questionnaire
  • Equity reset commands: "reset equity", "clear equity"
• Conducts a comprehensive 7-question risk-profiling interview when guidance requested
• Supports "why" clarifications per question
• On completion:
  • Writes equity/bond mix into state["risk"]
  • Sets done=True and awaiting_input=False
  • Routes to Reviewer Agent for next steps

Portfolio Agent ✅

• Reads mean/covariance data from portfolio/config/asset_stats.xlsx
• Runs a mean-variance optimizer producing 12 asset classes:
  • Equity sleeves (large/small growth/value, developed/emerging)
  • Bond sleeves (short/mid/long-term treasuries, corporates, TIPS, cash)
• Lets user adjust λ (5–20 typical) and cash reserve (3–6%)
• Outputs asset-class portfolio dictionary
• Routes to Reviewer Agent for next steps

Investment Agent ✅

• Presents 4 fund selection criteria:
  • Balanced: Best Sharpe ratio
  • Low Cost: Lowest expense ratio
  • High Performance: Highest returns
  • Low Risk: Lowest volatility
• Analyzes funds using Yahoo Finance API:
  • Performance metrics (returns, volatility, Sharpe ratio, beta)
  • Management metrics (expense ratio, AUM, fund family)
• Allows user review and editing of fund selections
• Excludes cash from fund analysis (uses "sweep_cash")
• Outputs investment portfolio with tickers
• Routes to Reviewer Agent when user says "proceed"

Trading Agent ✅

• Generates executable trading requests from investment portfolio
• Uses demo scenarios for realistic testing:
  • 6 predefined scenarios with different account values and holdings
  • Conservative, Balanced, Growth, Young Professional, Wealthy Conservative, Active Trader
• Implements sophisticated rebalancing:
  • Tax-aware optimization (short/long-term capital gains)
  • Full covariance risk model
  • Soft tax cap with increasing penalties
  • Cash sweep band management
  • Two-stage integerization for whole shares
• Outputs simple trading table:

  | Ticker | Action | Unit Price | Shares |
  |--------|--------|------------|--------|
  | VUG    | BUY    | $245.50    | 100    |
  | VTV    | SELL   | $180.25    | 50     |
  

Reviewer Agent ✅

• Validates completion of all phases
• Updates next_phase field to guide Entry Agent routing
• Shows final summary when all phases are complete
• Handles user options:
  • "start over" → Resets all state and begins fresh flow
  • "finish" → Shows thank you message and ends session
• Routes back to Entry Agent (never directly to other agents)
• Uses LLM structured output for intent classification

---

🧭 Complete User Flow

┌───────────────────────────────┐
│ User launches conversation    │
└──────────────┬────────────────┘
               ▼
        Entry Agent
         │ Show welcome & phase summary
         │ Orchestrate flow based on intent
         ▼
     User says "proceed"
         ▼
        Entry Agent
         │ Sets intent_to_risk=True
         │ Routes to Risk Agent
         ▼
        Risk Agent
         │ Presents two options:
         │ 1) Set equity directly ("set equity to 0.6")
         │ 2) Use guidance (7-question questionnaire)
         │ User selects option
         │ Computes equity/bond allocation
         │ Sets done=True, routes to Reviewer
         ▼
     Reviewer Agent
         │ Validates risk completion
         │ Updates next_phase="portfolio"
         │ Routes to Entry Agent
         ▼
        Entry Agent
         │ Shows portfolio phase summary
         │ User says "proceed"
         │ Sets intent_to_portfolio=True
         │ Routes to Portfolio Agent
         ▼
     Portfolio Agent
         │ Asks λ & cash reserve parameters
         │ Runs mean-variance optimization
         │ Outputs asset-class portfolio
         │ Sets done=True, routes to Reviewer
         ▼
     Reviewer Agent
         │ Validates portfolio completion
         │ Updates next_phase="investment"
         │ Routes to Entry Agent
         ▼
        Entry Agent
         │ Shows investment phase summary
         │ User says "proceed"
         │ Sets intent_to_investment=True
         │ Routes to Investment Agent
         ▼
     Investment Agent
         │ Presents fund selection criteria
         │ Analyzes funds via Yahoo Finance
         │ Allows review/edit of selections
         │ Outputs investment portfolio
         │ Sets done=True when user says "proceed"
         │ Routes to Reviewer
         ▼
     Reviewer Agent
         │ Validates investment completion
         │ Updates next_phase="trading"
         │ Routes to Entry Agent
         ▼
        Entry Agent
         │ Shows trading phase summary
         │ User says "proceed"
         │ Sets intent_to_trading=True
         │ Routes to Trading Agent
         ▼
     Trading Agent
         │ Shows demo scenarios
         │ User selects scenario
         │ Generates trading requests
         │ Outputs trading table
         │ Sets done=True, routes to Reviewer
         ▼
     Reviewer Agent
         │ Validates all phases complete
         │ Shows final summary with options:
         │   • "start over" → Reset & restart
         │   • "finish" → Complete session
         ▼
      (Ready for execution)

---

🧪 Example Complete Flow

Start: Entry Agent

AI (Entry): Welcome! Let's start with risk assessment...
User: proceed

Risk Phase: Risk Agent

AI (Risk): Choose: 1) Set equity directly (e.g., "set equity to 0.6") or 2) Use guidance (questionnaire)
User: use guidance
AI (Risk): [Shows 7-question questionnaire]
User: [Answers questions]
AI (Risk): Your allocation: 60% equity / 40% bonds
User: proceed
(Risk Agent routes to Reviewer, then Entry shows portfolio summary)

Portfolio Phase: Portfolio Agent

AI (Entry): Portfolio Construction phase...
User: proceed
AI (Portfolio): Defaults λ = 1.0, cash = 0.05...
User: set lambda to 1 and cash to 0.03 run
AI (Portfolio): [Optimization results]

User: proceed
(Entry shows investment summary, then routes to Investment Agent)
AI (Investment): Choose fund selection criteria: Balanced, Low Cost, High Performance, or Low Risk
User: balanced
(Fund analysis and selection)

User: proceed
(Entry shows trading summary, then routes to Trading Agent)
AI (Trading): Select a demo scenario (1-6)...
User: 1
(Trading requests generated)

Total Trades: 3
Buy Orders: 2
Sell Orders: 1
Net Cash Flow: $15,000

User: proceed
(Reviewer validates all phases and shows final summary)

Final Completion: Reviewer Agent

AI (Reviewer): Portfolio Planning Complete! Your plan is ready.
Options: Start over | Finish
User: finish
AI (Reviewer): Thank you for using our robo-advisor!

---

🔮 Implementation Status

---

🧰 Technical Features

Configuration System

• Centralized config (trading/config.py) with all assumptions and parameters
• Easy toggle between assumed data and real market data
• Comprehensive documentation of all assumptions and production recommendations

State Management

• Clean AgentState with only shared fields
• Internal state for agent-specific data (demo scenarios, preferences)
• Type-safe state management with TypedDict
• Status tracking for each agent phase (done, awaiting_input)

Fund Analysis

• Yahoo Finance integration for real-time fund data
• Performance metrics: returns, volatility, Sharpe ratio, beta, max drawdown
• Management metrics: expense ratio, AUM, fund family, inception date
• Data quality assessment and fallback handling

Trading Optimization

• Tax-aware rebalancing with lot-aware cost calculation
• Full covariance risk model for accurate tracking error
• Soft tax cap with increasing penalty functions
• Cash sweep band management
• Two-stage integerization for whole-share constraints
• Demo scenarios for realistic testing

Web Interface

• Real-time visualization with Plotly charts and tables
• Reactive design that shows/hides sections based on data availability
• Message history with collapsible conversation log
• Status tracking with visual progress indicators
• Reset functionality for easy testing and restart

Error Handling

• Comprehensive error handling with user-friendly messages
• Debug information for development (removed from production output)
• Graceful fallbacks for missing data or API failures
• Unicode encoding fixes for cross-platform compatibility

---

🚀 Production Roadmap

Immediate (Next Steps)

1. Replace synthetic covariance with real market data
2. Implement real-time fund data feeds
3. Add custodian integration for trade execution
4. Implement portfolio monitoring and rebalancing triggers

---

🛠 Developer Notes

• Modular architecture: Each agent is self-contained with clear interfaces
• Easy extension: Add new agents by updating routing in app.py
• Configuration-driven: All assumptions centralized in config files
• Type safety: Full typing with Pydantic models and TypedDict
• Testing: Demo scenarios provide realistic testing without real data
• Documentation: Comprehensive docstrings and configuration notes
• UI/UX: Modern Streamlit interface with real-time updates and visualization

---

📊 Asset Classes Supported

---

🎯 Key Metrics Tracked

Performance Metrics

• Total Return (1Y, 3Y, 5Y)
• Annualized Return
• Volatility (Annualized)
• Sharpe Ratio
• Maximum Drawdown
• Beta (vs S&P 500)

Management Metrics

• Expense Ratio
• Assets Under Management (AUM)
• Fund Family
• Management Company
• Inception Date
• Minimum Investment

Trading Metrics

• Execution Priority
• Tax Implications
• Risk Metrics
• Cash Flow Impact
• Tracking Error

---

🧪 Testing

The repository includes comprehensive testing coverage:

Unit Tests

Test core functions independently:

# Run all unit tests
python test/unittesting/test_suite.py

# Run individual unit tests
python test/unittesting/test_risk_manager.py
python test/unittesting/test_portfolio_manager.py
python test/unittesting/test_fund_analyzer.py
python test/unittesting/test_rebalancer.py

User Flow Tests

Test end-to-end user flows:

# Run all user flow tests
python test/userflowtesting/test_suite.py

# Run individual tests
python test/userflowtesting/test_comprehensive_risk_flow.py
python test/userflowtesting/test_portfolio_to_investment.py
python test/userflowtesting/test_simple_completion.py
python test/userflowtesting/test_start_over.py
python test/userflowtesting/test_trading_completion.py

Test Coverage:

• ✅ Risk Manager: Question management, risk allocation calculation
• ✅ Portfolio Manager: Mean-variance optimization, parameter setting
• ✅ Fund Analyzer: Fund data retrieval and analysis
• ✅ Rebalancer: Tax-aware rebalancing logic
• ✅ User Flows: Complete end-to-end workflows from risk assessment to trading

---

This robo-advisor represents a complete end-to-end wealth management solution, from risk assessment to trade execution, built with modern AI, optimization techniques, and a beautiful web interface.