📊 SmartPortfolio
Intelligent Portfolio Optimization using Graph Neural Networks, Prophet Forecasting, and Deep Reinforcement Learning
🚀 Overview
SmartPortfolio is a terminal-based portfolio optimization system that combines cutting-edge machine learning techniques to generate intelligent asset allocations:
- 🔗 Graph Neural Networks (GAT) — Model complex asset relationships and correlations
- 📈 Prophet Forecasting — Time series predictions with seasonality awareness
- 🤖 Deep Reinforcement Learning (PPO) — Dynamic allocation via hierarchical agents
- 💻 Neural Terminal TUI — Beautiful, Bloomberg-inspired terminal interface
✨ Features
| Feature | Description |
|---|---|
| PyTorch GAT | Pure PyTorch Graph Attention Network for asset embeddings |
| Correlation Graphs | Dynamic asset relationship visualization |
| Live Prices | Real-time market data via yfinance |
| Portfolio Metrics | Expected return, volatility, Sharpe ratio |
| Plot Export | Save allocation charts (pie, bar, dashboard) |
| 8GB RAM Optimized | Memory-efficient for consumer hardware |
📦 Installation
Prerequisites
- Python 3.10 or higher
- pip package manager
Quick Install
# Clone the repository
git clone https://github.com/yourusername/smartportfolio.git
cd smartportfolio
# Create virtual environment
python -m venv .venv
.venv\Scripts\activate # Windows
source .venv/bin/activate # Linux/Mac
# Install package
pip install -e .
Dependencies
Core dependencies are automatically installed:
torch— PyTorch for neural networksnetworkx— Graph operationsprophet— Time series forecastingstable-baselines3— Reinforcement learningtextual— Terminal user interfaceyfinance— Market data
🎮 Usage
Launch the TUI
# Start with default tickers
smartportfolio
# Start with custom ticker file
smartportfolio --tickers my_tickers.csv
TUI Commands
| Command | Description |
|---|---|
LOAD <file> |
Load tickers from CSV/XLSX file |
LOADWEIGHTS <file> |
Load previous portfolio weights |
RUN |
Execute optimization pipeline |
STATUS |
Show current system status |
EXPORT |
Export weights to CSV |
PLOT |
Save allocation charts |
GRAPH |
Save correlation graph visualization |
HELP |
Display help information |
CLEAR |
Reset all state |
Keyboard Shortcuts
| Key | Action |
|---|---|
q |
Quit application |
r |
Run optimization |
l |
Load tickers |
e |
Export results |
h |
Show help |
Esc |
Focus command bar |
Ticker File Format
ticker
AAPL
MSFT
GOOGL
AMZN
META
📊 Output Files
All outputs are saved to the outputs/ directory with timestamp-UUID naming:
| File Pattern | Description |
|---|---|
*_portfolio_weights.csv |
Asset weights allocation |
*_allocation_pie.png |
Pie chart visualization |
*_allocation_bar.png |
Bar chart visualization |
*_correlation_graph.png |
Asset relationship graph |
*_dashboard.png |
Combined metrics dashboard |
🏗️ Architecture
smartportfolio/
├── __init__.py # Package initialization
├── __main__.py # CLI entry point
├── app.py # Main TUI application
├── config.py # Configuration management
├── visualization.py # Matplotlib plotting
├── data/ # Data handling modules
│ ├── fetcher.py # Yahoo Finance data fetcher
│ ├── features.py # Feature engineering
│ └── storage.py # Local file storage
├── graph/ # Graph neural network modules
│ ├── builder.py # Dynamic graph construction
│ ├── gat.py # NumPy GAT implementation
│ └── torch_gat.py # PyTorch GAT implementation
├── forecasting/ # Time series forecasting
│ └── prophet_model.py # Prophet integration
├── rl/ # Reinforcement learning
│ ├── environment.py # Gymnasium environment
│ └── agent.py # PPO agent
└── components/ # TUI widgets
├── header.py # App header
├── sidebar.py # Watchlist sidebar
└── main_content.py # Portfolio overview
🔧 Configuration
Configuration is managed via smartportfolio/config.py:
# Model parameters
gat_embedding_dim = 32
gat_num_heads = 4
gat_dropout = 0.1
# Data parameters
default_period = "2y"
correlation_threshold = 0.3
# RL parameters
rl_learning_rate = 0.0003
train_episodes = 100
🧪 Development
Setup Development Environment
# Install with dev dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Format code
black smartportfolio/
# Lint code
ruff check smartportfolio/
Running Tests
pytest tests/ -v --cov=smartportfolio
📈 Performance
Tested on consumer hardware (8GB RAM):
| Operation | Time | Memory |
|---|---|---|
| Data fetch (10 tickers) | ~5s | ~200MB |
| Graph construction | <1s | ~50MB |
| GAT embedding | ~2s | ~300MB |
| Full pipeline | ~15s | ~500MB |
🤝 Contributing
We welcome contributions! Please see our Contributing Guide for details.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
📜 License
This project is licensed under the MIT License - see the LICENSE file for details.
🔐 Security
For security concerns, please see our Security Policy.
📞 Support
🙏 Acknowledgments
- Textual — Terminal UI framework
- Prophet — Time series forecasting
- Stable-Baselines3 — RL algorithms
- yfinance — Market data
Made with ❤️ by Anonymous
Metadata
Release files for smartportfolio 2.1.5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| smartportfolio-2.1.5.tar.gz | 53.9 kB | Without provenance | Details for smartportfolio-2.1.5.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| smartportfolio-2.1.5-py3-none-any.whl | Python 3 | none | any | Details for smartportfolio-2.1.5-py3-none-any.whl |
Total release size: 114.8 kB
Release files / smartportfolio-2.1.5.tar.gz
| Download URL | smartportfolio-2.1.5.tar.gz |
|---|---|
| Size | 53.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
46cdfafb292aa7879f8be682ad46f3036ed8fa9ba8faada5e351bda0b4b566ad
|
|
BLAKE2b-256 checksum How to use checksums |
f2f38b0eb17ad9a23d211cecca2fc9ddcdb2f6f066be2e6b36f2cadd17f3f529
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.3
|
Release files / smartportfolio-2.1.5-py3-none-any.whl
| Download URL | smartportfolio-2.1.5-py3-none-any.whl |
|---|---|
| Size | 60.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b745a40240d1abdbb0005d178113b48f6ce1b729643ab473d35ab01623788d88
|
|
BLAKE2b-256 checksum How to use checksums |
9fcd06aa10b4cc56054a3f18f85b57d462058f3a748b7863996308450ddf4c69
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.3
|
Security for smartportfolio 2.1.5
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.