264 lines
6.8 KiB
Markdown
264 lines
6.8 KiB
Markdown
# Portfolio Analysis Feature
|
|
|
|
## Overview
|
|
|
|
The Portfolio Analysis feature extends TradingAgents to analyze entire portfolios of stocks, providing comprehensive insights on diversification, risk, correlation, and rebalancing recommendations.
|
|
|
|
## Features
|
|
|
|
### Core Capabilities
|
|
- **Multi-stock parallel analysis**: Analyze multiple stocks concurrently for faster results
|
|
- **Portfolio-level metrics**: Calculate correlation, beta, volatility, Sharpe ratio, and diversification scores
|
|
- **Risk assessment**: Identify concentration risks, sector exposure, and correlation risks
|
|
- **Rebalancing suggestions**: AI-powered recommendations for portfolio optimization
|
|
- **Comprehensive PDF reports**: Visual charts including allocation pie charts, correlation heatmaps, sector breakdown, and performance graphs
|
|
|
|
### Analysis Components
|
|
|
|
#### Individual Stock Analysis
|
|
Each position in your portfolio is analyzed using the full TradingAgents framework:
|
|
- Market Analyst
|
|
- Sentiment Analyst (optional)
|
|
- News Analyst (optional)
|
|
- Fundamentals Analyst (optional)
|
|
- Research Team debate
|
|
- Trading recommendations
|
|
- Risk management review
|
|
|
|
#### Portfolio-Level Analysis
|
|
- **Correlation Matrix**: Understand how your positions move together
|
|
- **Sector Diversification**: See your exposure across different sectors
|
|
- **Position Weights**: Identify over/under-weighted positions
|
|
- **Performance Metrics**: Beta, volatility, Sharpe ratio, max drawdown
|
|
- **Risk Concentration**: Warnings for concentrated positions or sectors
|
|
|
|
## Usage
|
|
|
|
### Command Line Interface
|
|
|
|
#### Option 1: Interactive CLI
|
|
```bash
|
|
python -m cli.main analyze-portfolio
|
|
```
|
|
|
|
The CLI will prompt you to enter:
|
|
1. Portfolio name
|
|
2. Analysis date
|
|
3. Your positions (ticker, shares, average cost)
|
|
4. Analyst selection
|
|
5. Research depth
|
|
6. LLM settings
|
|
|
|
#### Option 2: Programmatic Usage
|
|
```python
|
|
from tradingagents.portfolio.models import Portfolio, Position
|
|
from tradingagents.portfolio.portfolio_graph import PortfolioAnalysisGraph
|
|
from tradingagents.default_config import DEFAULT_CONFIG
|
|
|
|
# Define your positions
|
|
positions = {
|
|
"AAPL": Position(ticker="AAPL", shares=100, avg_cost=150.00),
|
|
"MSFT": Position(ticker="MSFT", shares=50, avg_cost=300.00),
|
|
"NVDA": Position(ticker="NVDA", shares=75, avg_cost=450.00),
|
|
}
|
|
|
|
# Create portfolio
|
|
portfolio = Portfolio(
|
|
positions=positions,
|
|
analysis_date="2024-12-01",
|
|
name="My Portfolio"
|
|
)
|
|
|
|
# Configure analysis
|
|
config = DEFAULT_CONFIG.copy()
|
|
config["max_debate_rounds"] = 1
|
|
config["quick_think_llm"] = "gpt-4o-mini"
|
|
config["deep_think_llm"] = "gpt-4o-mini"
|
|
|
|
# Initialize and run analysis
|
|
portfolio_graph = PortfolioAnalysisGraph(
|
|
selected_analysts=["market", "fundamentals"],
|
|
debug=True,
|
|
config=config
|
|
)
|
|
|
|
result = portfolio_graph.analyze_portfolio(portfolio)
|
|
|
|
# Access results
|
|
print(result.portfolio_recommendation)
|
|
print(result.risk_assessment)
|
|
print(result.rebalancing_suggestions)
|
|
```
|
|
|
|
### Test the Feature
|
|
|
|
Run the included test script:
|
|
```bash
|
|
python test_portfolio_analysis.py
|
|
```
|
|
|
|
## Output
|
|
|
|
### Console Output
|
|
- Real-time progress updates for each stock analysis
|
|
- Portfolio summary (value, P/L, allocations)
|
|
- Portfolio metrics (beta, volatility, Sharpe ratio)
|
|
- Risk assessment
|
|
- Rebalancing suggestions
|
|
|
|
### Saved Files
|
|
|
|
Results are saved in `results/portfolio/{analysis_date}/`:
|
|
- `portfolio_analysis.json`: Complete analysis results in JSON format
|
|
- `portfolio_analysis_{date}.pdf`: Comprehensive PDF report with charts
|
|
|
|
### PDF Report Sections
|
|
|
|
1. **Cover Page**: Portfolio summary, total value, P/L
|
|
2. **Portfolio Visualizations**:
|
|
- Allocation pie chart
|
|
- Position performance bar chart
|
|
- Sector allocation bar chart
|
|
- Correlation heatmap
|
|
3. **Portfolio Overview**: Summary and recommendations
|
|
4. **Risk Assessment**: Detailed risk analysis
|
|
5. **Rebalancing Suggestions**: Specific recommendations
|
|
6. **Individual Stock Analyses**: Detailed breakdown for each position
|
|
|
|
## Configuration
|
|
|
|
### Performance Optimization
|
|
|
|
Adjust `max_workers` for parallel processing:
|
|
```python
|
|
result = portfolio_graph.analyze_portfolio(portfolio, max_workers=3)
|
|
```
|
|
- Higher values = faster but more API calls
|
|
- Recommended: 2-4 workers
|
|
|
|
### Cost Optimization
|
|
|
|
Use cheaper LLMs for testing:
|
|
```python
|
|
config["quick_think_llm"] = "gpt-4o-mini"
|
|
config["deep_think_llm"] = "gpt-4o-mini"
|
|
config["max_debate_rounds"] = 1
|
|
```
|
|
|
|
Select fewer analysts:
|
|
```python
|
|
selected_analysts=["market", "fundamentals"] # Instead of all 4
|
|
```
|
|
|
|
## Requirements
|
|
|
|
### Python Packages
|
|
```bash
|
|
pip install reportlab matplotlib seaborn
|
|
```
|
|
|
|
All requirements are in `requirements.txt`.
|
|
|
|
### API Keys
|
|
- OpenAI API key (or Anthropic/Google)
|
|
- Alpha Vantage API key (for fundamental/news data)
|
|
|
|
## Metrics Explained
|
|
|
|
### Portfolio Beta
|
|
- Measures portfolio volatility relative to the market (SPY)
|
|
- Beta > 1: More volatile than market
|
|
- Beta < 1: Less volatile than market
|
|
|
|
### Sharpe Ratio
|
|
- Risk-adjusted return metric
|
|
- Higher is better (>1 is good)
|
|
- Negative means returns below risk-free rate
|
|
|
|
### Diversification Score
|
|
- 0 to 1 scale (1 = best diversification)
|
|
- Based on correlation between positions
|
|
- <0.5 = high correlation, poor diversification
|
|
|
|
### Max Drawdown
|
|
- Largest peak-to-trough decline
|
|
- Measures downside risk
|
|
- Lower is better
|
|
|
|
## Backward Compatibility
|
|
|
|
The portfolio analysis feature is **completely separate** from single-stock analysis:
|
|
- Single stock: `python -m cli.main analyze`
|
|
- Portfolio: `python -m cli.main analyze-portfolio`
|
|
|
|
All existing functionality remains unchanged.
|
|
|
|
## Limitations
|
|
|
|
- Requires historical price data (uses yfinance)
|
|
- Analysis date cannot be in the future
|
|
- Parallel analysis increases API costs
|
|
- Correlation analysis requires at least 60 days of overlapping price data
|
|
- Sector data may not be available for all tickers
|
|
|
|
## Examples
|
|
|
|
### Example Portfolio Input
|
|
```
|
|
Portfolio name: Tech Holdings
|
|
Analysis date: 2024-12-01
|
|
|
|
Position #1
|
|
Ticker: AAPL
|
|
Shares: 100
|
|
Average cost: $150.00
|
|
|
|
Position #2
|
|
Ticker: MSFT
|
|
Shares: 50
|
|
Average cost: $300.00
|
|
|
|
Position #3
|
|
Ticker: GOOGL
|
|
Shares: 25
|
|
Average cost: $120.00
|
|
```
|
|
|
|
### Example Output
|
|
```
|
|
Portfolio Summary:
|
|
Total Cost Basis: $36,000.00
|
|
Total Market Value: $42,500.00
|
|
Unrealized P/L: $6,500.00 (+18.06%)
|
|
|
|
Portfolio Metrics:
|
|
Beta: 1.15
|
|
Volatility: 22.3% (annualized)
|
|
Sharpe Ratio: 1.42
|
|
Diversification Score: 0.68/1.00
|
|
|
|
Sector Allocation:
|
|
- Technology: 85.0%
|
|
- Communication: 15.0%
|
|
|
|
⚠️ High concentration in Technology sector (85.0%) - consider diversifying
|
|
```
|
|
|
|
## Support
|
|
|
|
For issues or questions:
|
|
1. Check the main README.md
|
|
2. Review PORTFOLIO_ANALYSIS.md (this file)
|
|
3. Run test_portfolio_analysis.py to verify setup
|
|
4. Open an issue on GitHub
|
|
|
|
## Future Enhancements
|
|
|
|
Potential future features:
|
|
- Portfolio optimization suggestions
|
|
- Historical portfolio performance tracking
|
|
- Tax-loss harvesting recommendations
|
|
- Monte Carlo simulation for risk projections
|
|
- Factor analysis (value, growth, momentum)
|
|
- ESG scoring
|