Balances your portfolio based on holdings, market conditions, and technical signals. Ships with a CLI (portfolio_manager.py) and a desktop GUI (stock_manager_gui.py) featuring charting and a Systematic Momentum Screener.
pip install -r requirements.txt
cp portfolio.example.json portfolio.json # seed your portfolio stateLaunch the GUI with python stock_manager_gui.py, or use the CLI below.
# Add holdings
python portfolio_manager.py add AAPL 50 --cost 175.50
python portfolio_manager.py add MSFT 30 --cost 380.00
python portfolio_manager.py add CASH 0
# Set target allocation (percentages must sum to ~1.0)
python portfolio_manager.py allocation AAPL=0.3 MSFT=0.3 CASH=0.4
# Set risk tolerance (0.0 = conservative, 1.0 = aggressive)
python portfolio_manager.py risk 0.6
# Run full analysis
python portfolio_manager.py analyze
# Check signals for a specific ticker
python portfolio_manager.py signals AAPL
# View current value
python portfolio_manager.py value
# Get rebalance recommendations
python portfolio_manager.py rebalance
# Top stock picks by Recommendation Points (headless, no GUI needed)
python portfolio_manager.py recommend -n 10
python portfolio_manager.py recommend --full # score the full universe- Current Most Recommended Stocks: on every launch the app backtests a universe of large caps and ranks the top 10 by a transparent Recommendation Points score (0-100, where 100 = the best deal imaginable and 0 = guaranteed to tank). The score blends 12-1 momentum, a walk-forward SMA backtest, trend structure, a drawdown guard, MACD, and RSI, then blends in fundamentals (P/E, PEG, ROE, margins, growth, debt, analyst targets — see
fundamentals.py). Seerecommendation_engine.py.
The scoring system is not hand-waved — it is backtested point-in-time with
validate_recommendations.py, which recomputes each score using only data
available at each historical date and measures realized forward returns. Latest
run (38 large caps, 5y, monthly rebalance, 3-month forward horizon, 1,786
samples):
| Metric | Value |
|---|---|
| Top-quintile avg 3-mo forward return | +10.06% |
| Bottom-quintile avg 3-mo forward return | +8.63% |
| Long-top / short-bottom spread | +1.43% |
| Top-quintile hit rate (beat median) | 59% |
Factor weights are tuned toward the inputs with a positive information
coefficient (momentum, strategy backtest). Volatility is reported but not
rewarded — penalizing or chasing it both overfit a single market regime. Full
results in validation_report.json.
- Technical Analysis: RSI, MACD, Moving Averages, Volatility
- Signal Detection: Golden/Death Cross, Overbought/Oversold, MACD crossovers
- Smart Rebalancing: Considers both allocation deviation AND market signals
- Risk-Adjusted: Cash targets adjust based on your risk tolerance
- Local-First: All data stored locally, no cloud dependencies
- Cached Data: Historical data cached for 1 hour to minimize API calls
- Compares current allocation vs target allocation
- Analyzes market signals (RSI, MACD, SMA crossovers)
- Adjusts urgency based on signal strength
- Recommends BUY/SELL with share counts and estimated values
- Factors in your risk tolerance for cash management
portfolio_manager.py— CLI program (analysis, signals, rebalancing)stock_manager_gui.py— Desktop GUI (charts + momentum screener)backtest_strategies.py— Strategy backtestingportfolio.example.json— Template; copy toportfolio.json(gitignored)cache/— Cached historical data (auto-created)