AltAlpha Lab

Quantitative trading research demo — sentiment signals, ML direction forecasts, backtesting, and strategy optimization in one local stack.

Demo / portfolio project. Run it locally — no cloud deploy required. Market data comes from free public sources (no API keys).

---

What it does

Area	Capability
Dashboard	Price, sentiment, portfolio, drawdown, and Sharpe charts
Strategy	Sentiment + volatility filters, backtests, transaction costs
ML	RandomForest next-day direction with feature importance
Optimizer	Grid search over strategy parameters
Live sim	Day-by-day simulation with trade log
AI report	Structured research-style analysis for a ticker
Compare	Multi-ticker performance, correlation, volatility

---

Quick start

Requirements: Python 3.11+, Node.js 18+, npm

# One-time setup
make setup

# Run API + UI together
make dev

Service	URL
Frontend	http://localhost:5173
API	http://localhost:8000
OpenAPI docs	http://localhost:8000/docs

Manual setup

# Backend
python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -r requirements.txt
uvicorn main:app --reload --port 8000

# Frontend (separate terminal)
cd frontend
npm install
cp .env.example .env.local
npm run dev

Make targets

Command	Description
make setup	Install deps + create frontend/.env.local
make install	Install backend + frontend deps
make dev	Run both servers
make dev-backend	API only (:8000)
make dev-frontend	Vite only (:5173)
make build	Production frontend build
make lint	ESLint
make check	Health check both servers
make clean	Remove venv, node_modules, caches

---

Project structure

AltAlpha-Lab/
├── main.py                 # FastAPI app & routes
├── data.py                 # Price data (yfinance)
├── sentiment.py            # Sentiment series
├── features.py             # Feature engineering
├── strategy.py             # Signal generation
├── backtest.py             # Backtesting engine
├── metrics.py              # Sharpe, drawdown, returns
├── ml_model.py             # RandomForest predictions
├── optimizer.py            # Parameter grid search
├── live_simulator.py       # Day-by-day simulation
├── ai_analyst.py           # Research report generation
├── requirements.txt
├── Makefile
├── LICENSE
├── .github/workflows/ci.yml
└── frontend/
    ├── package.json
    ├── vite.config.js
    ├── .env.example
    └── src/
        ├── App.jsx
        ├── context/              # Currency context
        └── components/
            ├── Dashboard.jsx     # Shell + data orchestration
            ├── views/            # Page views
            ├── layout/           # Sidebar, header
            ├── controls/         # Strategy controls
            ├── comparison/       # Multi-ticker widgets
            ├── insights/         # AI panels
            ├── ui/               # Shared UI primitives
            └── *Chart.jsx        # Recharts visualizations

---

API overview

All analytics endpoints take a ticker query param (e.g. ?ticker=AAPL).

Endpoint	Description
GET /	Health check
GET /price-data	Historical prices + returns
GET /sentiment	Sentiment time series
GET /features	Merged features
GET /strategy	Trading signals
GET /backtest	Full backtest
GET /metrics	Performance metrics
GET /ml-predict	Next-day ML prediction
GET /optimize	Optimal parameters
GET /live-sim	Live simulation
GET /ai-report	AI research report
GET /ai-report/comprehensive	Full AI analysis

curl "http://localhost:8000/price-data?ticker=AAPL"
curl "http://localhost:8000/backtest?ticker=AAPL&initial_capital=10000"
curl "http://localhost:8000/ml-predict?ticker=AAPL"

Interactive docs: http://localhost:8000/docs

---

Configuration

Frontend (frontend/.env.local)

Variable	Default	Description
VITE_API_URL	http://localhost:8000	Backend base URL

cp frontend/.env.example frontend/.env.local

No API keys required for the demo.

Strategy defaults

Parameter	Default	Notes
sentiment_threshold	0.2	Signal threshold
volatility_percentile	50	Volatility filter
initial_capital	10000	Backtest capital
transaction_cost	0.001	Cost fraction (0.1%)

ML model

• Model: RandomForest classifier
• Features: returns, rolling sentiment, volatility, sentiment, 5d avg returns
• Split: 80/20 time-based (no shuffle / leakage)
• Metrics: accuracy, precision, recall, ROC AUC

---

Tech stack

Backend: FastAPI · Pandas · NumPy · yfinance · scikit-learn · VADER

Frontend: React 18 · Vite · Tailwind CSS · Recharts · jsPDF

---

CI

On every push and pull request to main, GitHub Actions:

1. Backend — install deps, import all modules, start API, hit health check
2. Frontend — npm ci, ESLint, production build

Workflow: .github/workflows/ci.yml

---

License

MIT — see LICENSE.

Acknowledgments

• yfinance — market data
• FastAPI — API framework
• Recharts — charts
• VADER Sentiment — sentiment scoring