AI Supply Chain Momentum Scoring Engine - A systematic approach to momentum-based stock analysis and portfolio management.
AlphaVelocity generates comprehensive momentum scores for stocks using multiple factors:
- Price Momentum (40%): Multi-timeframe returns and moving average signals
- Technical Momentum (25%): RSI, volume confirmation, rate of change
- Fundamental Momentum (25%): P/E ratios, growth metrics, analyst ratings
- Relative Momentum (10%): Performance vs. market benchmarks
- Python 3.11+ installed
- PostgreSQL 13+ installed (optional, for database mode)
- Git for cloning the repository
- Clone the repository:
git clone <repository-url>
cd alpha_velocity- Install dependencies:
pip install -r requirements.txtRun the application with file-based storage:
# Terminal 1: Start the backend server
python -m backend.main
# Terminal 2: Start the frontend server
python frontend_server.py
# Access the application
# Frontend: http://localhost:3000/
# API docs: http://localhost:8000/docsFor full features including portfolio persistence and transaction tracking:
- Install and start PostgreSQL:
# On Ubuntu/Debian
sudo apt update
sudo apt install postgresql postgresql-contrib
# On macOS with Homebrew
brew install postgresql
brew services start postgresql
# On Windows, download from: https://www.postgresql.org/download/windows/- Setup PostgreSQL database:
# Method 1: Use the provided setup script
sudo -u postgres psql -f setup_db.sql
# Method 2: Manual setup
sudo -u postgres psql
# Then run these commands in psql:
# CREATE DATABASE alphavelocity;
# CREATE USER alphavelocity WITH PASSWORD 'alphavelocity_secure_password';
# GRANT ALL PRIVILEGES ON DATABASE alphavelocity TO alphavelocity;
# \q- Verify environment variables (
.envfile should already be configured):
# Check that .env contains:
# DB_HOST=localhost
# DB_PORT=5432
# DB_NAME=alphavelocity
# DB_USER=alphavelocity
# DB_PASSWORD=alphavelocity_secure_password- Test database connection:
python -c "
import sys
sys.path.insert(0, 'backend')
from database.config import db_config
print('Testing connection...')
if db_config.test_connection():
print('✅ Database connection successful')
else:
print('❌ Database connection failed')
"- Run database migration:
python simple_db_migration.py- Populate initial data:
# Setup portfolio categories
python setup_portfolio_categories.py
# Populate market data (optional)
python populate_market_data.py- Start the servers:
# Terminal 1: Start the backend server
python -m backend.main
# Terminal 2: Start the frontend server
python frontend_server.pyOnce both servers are running, you can access:
- Web Interface: http://localhost:3000/
- API Documentation: http://localhost:8000/docs
- Health Check: http://localhost:8000/
- Portfolio Analysis: http://localhost:8000/portfolio/analysis
- Momentum Score: http://localhost:8000/momentum/NVDA
If your app is showing "File Mode" in the header, it means PostgreSQL is not running or not accessible. To switch to database mode:
1. Check if PostgreSQL is running:
# Check PostgreSQL service status
sudo systemctl status postgresql # Linux
brew services list | grep postgresql # macOS
# If not running, start it:
sudo systemctl start postgresql # Linux
brew services start postgresql # macOS2. Test database connection:
python -c "
import sys
sys.path.insert(0, 'backend')
from simple_db_service import get_database_service
db_service = get_database_service()
if db_service.test_connection():
print('✅ Database ready - restart backend to enable database mode')
else:
print('❌ Database connection still failing')
"3. Restart the backend server:
# Stop the current backend (Ctrl+C)
# Then restart:
python -m backend.main4. Refresh the frontend: The frontend will automatically detect database mode and show "Database Mode" in the header.
1. PostgreSQL not running:
# Check if PostgreSQL is running
sudo systemctl status postgresql # Linux
brew services list | grep postgresql # macOS
# Start PostgreSQL
sudo systemctl start postgresql # Linux
brew services start postgresql # macOS2. Connection refused errors:
# Check PostgreSQL is listening on correct port
sudo netstat -plunt | grep 5432
# Edit PostgreSQL config if needed
sudo nano /etc/postgresql/*/main/postgresql.conf
# Ensure: listen_addresses = 'localhost'
# Ensure: port = 54323. Authentication failed:
# Reset PostgreSQL user password
sudo -u postgres psql
# \password alphavelocity
# (enter new password)
# \q
# Update .env file with new password4. Database doesn't exist:
# List databases
sudo -u postgres psql -l
# Recreate database if needed
sudo -u postgres psql -f setup_db.sql5. Permission denied:
# Grant proper permissions
sudo -u postgres psql
# GRANT ALL PRIVILEGES ON DATABASE alphavelocity TO alphavelocity;
# GRANT ALL ON SCHEMA public TO alphavelocity;
# \q# Using uvicorn directly
uvicorn backend.main:app --host 0.0.0.0 --port 8000
# Development mode with auto-reload
uvicorn backend.main:app --host 0.0.0.0 --port 8000 --reloadGET /- Health checkGET /momentum/{ticker}- Get momentum score for a tickerGET /portfolio/analysis- Analyze default portfolioGET /categories- List all portfolio categoriesGET /categories/{name}/analysis- Analyze specific categoryGET /momentum/top/{limit}- Get top momentum stocks
{
"ticker": "NVDA",
"composite_score": 85.2,
"rating": "Strong Buy",
"price_momentum": 92.1,
"technical_momentum": 78.5,
"fundamental_momentum": 85.0,
"relative_momentum": 88.3
}backend/
├── main.py # FastAPI application
├── services/ # Business logic
│ ├── momentum_engine.py
│ └── portfolio_service.py
├── models/ # Pydantic data models
├── utils/ # Data providers
└── api/ # API endpoints (future)
The system organizes investments into 8 strategic categories:
- Large-Cap Anchors (20%) - NVDA, MSFT, META, etc.
- Small-Cap Specialists (15%) - VRT, MOD, BE, etc.
- Data Center Infrastructure (15%) - DLR, SRVR, IRM, etc.
- International Tech/Momentum (12%) - EWJ, EWT, etc.
- Tactical Fixed Income (8%) - SHY, VCIT, etc.
- Sector Momentum Rotation (10%) - XLI, XLE, etc.
- Critical Metals & Mining (7%) - MP, ALB, etc.
- Specialized Materials ETFs (5%) - REMX, LIT, etc.
python -m pytest tests/Original implementation files are preserved in legacy/ directory.
- Implement Alpha Vantage data provider
- Add mobile app (React Native/Flutter)
- Add user authentication
- Implement portfolio persistence
- Add real-time updates
When running the server, visit http://localhost:8000/docs for interactive API documentation.