docs/GETTING_STARTED.md

Getting Started

This guide walks you through installing and running the Quantum Hybrid Portfolio system.

Prerequisites

• Python 3.9+
• Node.js 16+ and npm (for the dashboard)
• Git

Installation

1. Clone the repository

git clone https://github.com/Quantum-Global-Group/quantum-hybrid-portfolio.git
cd quantum-hybrid-portfolio

2. Set up Python backend

python3 -m venv .venv
source .venv/bin/activate   # On Windows: .venv\Scripts\activate
pip install -r requirements.txt
pip install -e .

3. Quick verification

python quick_test.py

Expected output: success message and basic optimization result.

4. Set up the dashboard (optional)

cd frontend
npm install

How it works

Optimization goes through run_optimization in core.portfolio_optimizer (also exposed from services.portfolio_optimizer). It can route to:

1. Hybrid pipeline — Screening, quantum-inspired selection, optimization
2. QUBO + simulated annealing — Discrete selection
3. VQE-style weights — Quantum-inspired variational approach
4. Classical — Markowitz, min variance, HRP, equal weight

Python usage example

from services.portfolio_optimizer import run_optimization
import numpy as np

returns = np.array([0.12, 0.10, 0.15, 0.08, 0.11])
covariance = np.eye(5) * 0.04

result = run_optimization(returns, covariance, objective="hybrid")

print(f"Sharpe Ratio: {result.sharpe_ratio:.3f}")
print(f"Expected Return: {result.expected_return*100:.2f}%")
print(f"Volatility: {result.volatility*100:.2f}%")

Running the System

Backend API only

source .venv/bin/activate
python api.py

The API runs at http://localhost:5000.

• Health check: http://localhost:5000/api/health
• OpenAPI spec: http://localhost:5000/api/docs/openapi

Dashboard (API + Frontend)

Terminal 1 — API:

source .venv/bin/activate
python api.py

Terminal 2 — Frontend:

cd frontend
npm start

The dashboard opens at http://localhost:3000 and proxies API requests to port 5000 (configured in frontend/package.json).

Next.js app (web/) — migration track

Terminal 1 — API (same as above):

source .venv/bin/activate
python api.py

Terminal 2 — Next.js:

cd web
npm install
npm run dev

Open http://localhost:3000. Set NEXT_PUBLIC_API_URL=http://127.0.0.1:5000 in web/.env.local if the app is not using a dev proxy to Flask.

• Proof / smoke page: http://localhost:3000/health-check (API health JSON + optional market-data and optimize buttons).
• Production build: cd web && npm run build && npm run lint
• Unit tests (API error helper): cd web && npm test

Alternatively, from the repo root: ./scripts/dev.sh (starts Flask then Next; see script header for options).

Environment variables

Variable	Default	Description
FLASK_ENV	development	Set to production for production
LOG_LEVEL	INFO	Logging level
CACHE_TTL	3600	Market data cache TTL (seconds)
API_KEY	(none)	Optional API key for X-API-Key header
REACT_APP_API_URL	(empty)	CRA: override API base URL (e.g. http://localhost:5000)
NEXT_PUBLIC_API_URL	(empty)	Next (web/): API base URL for the browser client
NEXT_PUBLIC_API_KEY	(empty)	Next: optional X-API-Key (see .env.example)

Next Steps

1. Public demo — PUBLIC_DEMO.md (hosting, disclaimer, audience)
2. Use the dashboard — See DASHBOARD_GUIDE.md
3. Run an example — python examples/basic_qsw_example.py
4. Call the API — See API_REFERENCE.md
5. Explore notebooks — notebooks/01_qsw_exploration.ipynb

Troubleshooting

API fails to start

• Ensure port 5000 is free
• Check Python version: python --version (3.9+)
• Verify dependencies: pip list | grep -E "flask|numpy"

Dashboard cannot reach API

• Confirm API is running at http://localhost:5000
• Check frontend/package.json has "proxy": "http://localhost:5000"

CORS errors

• The API enables CORS for all origins in development
• For production, configure allowed origins in api.py

---

Last updated: March 2026