Lumen (pre-release V1.0.0-alpha)

Quantum-Enhanced Edge Reasoning Engine for Portfolio Optimization

Lumen is an open-source edge reasoning engine that brings AI to financial portfolio optimization. Unlike statistical machine learning approaches, Lumen uses explicit constraint-based reasoning to solve optimization problems with mathematical rigor and full explainability.

About The Author

Lumen is a creation of OA Quantum Labs and its CTO Danny Wall. If you'd like to work with us on your AI or quantum enhanced projects, let us know. Contact Danny at [email protected]

Visit us on the web at https://oaqlabs.com

Key Features

• Explainable AI - Every recommendation traceable to specific constraints
• Edge-First Computation - Runs on personal computers without cloud dependency
• Hybrid Classical-Quantum - Optional quantum enhancement for complex scenarios
• Tax-Aware Optimization - Tax-loss harvesting with wash sale compliance
• Open Source Core - MIT licensed for transparency and trust

Quick Start

Prerequisites

• C++17 compatible compiler (GCC 9+, Clang 10+, MSVC 2019+)
• CMake 3.16 or higher
• vcpkg package manager (recommended)

Installation

Using vcpkg (Recommended)

# Clone the repository
git clone https://github.com/oaqlabs/lumen.git
cd lumen/lumen

# Install dependencies via vcpkg
vcpkg install

# Configure and build
cmake -B build -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake
cmake --build build --config Release

# Run tests
cd build && ctest --output-on-failure

Manual Build

# Install system dependencies (Ubuntu/Debian)
sudo apt-get install -y cmake ninja-build libsqlite3-dev libeigen3-dev

# Clone and build
git clone https://github.com/oaqlabs/lumen.git
cd lumen/lumen

cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build

# Install
sudo cmake --install build

Basic Usage

# Optimize a portfolio
lumen optimize --portfolio portfolio.csv --target 60-40-stocks-bonds

# Find tax-loss harvesting opportunities
lumen tax-harvest --portfolio portfolio.csv --tax-rate 0.22

# View configuration
lumen config --show

Documentation

• CLI Usage Guide
• API Reference
• Architecture Overview
• Tax Optimization Guide
• Quantum Integration

Project Structure

lumen/
├── include/lumen/       # Public header files
│   ├── core/            # Portfolio, constraints, solver dispatcher
│   ├── solvers/         # HiGHS wrapper, quantum clients
│   ├── data/            # Market data, tax lots
│   ├── explain/         # Provenance, explainability
│   └── utils/           # Logging, configuration
├── src/                 # Implementation files
├── apps/
│   ├── cli/             # Command-line interface
│   ├── server/          # REST API server
│   └── gui/             # Qt desktop application
├── test/                # Test suite
│   ├── unit/            # Unit tests
│   ├── integration/     # Integration tests
│   └── benchmarks/      # Performance benchmarks
└── docs/                # Documentation

Technology Stack

Component	Technology	Purpose
Language	C++17	Performance, cross-platform
Build	CMake	Cross-platform builds
Optimization	HiGHS	LP/MILP/QP solving
Linear Algebra	Eigen	Matrix operations
Database	SQLite	Local persistence
JSON	nlohmann/json	Data serialization
HTTP	cpp-httplib	API client/server
CLI	CLI11	Command-line parsing
Testing	Google Test	Unit testing

Configuration

Create ~/.lumen/config.yaml:

solver:
  classical:
    default: highs
    timeout_ms: 30000
  quantum:
    enabled: false
    providers:
      - name: dwave
        api_key_env: DWAVE_API_KEY

market_data:
  providers:
    - name: alpha_vantage
      api_key_env: ALPHA_VANTAGE_API_KEY
  cache_ttl_minutes: 60

persistence:
  database_path: ~/.lumen/data/lumen.db

Environment Variables

# Market data
export ALPHA_VANTAGE_API_KEY=your_key_here

# Quantum providers (optional)
export DWAVE_API_KEY=your_dwave_key
export IBM_QUANTUM_API_KEY=your_ibm_key

Build Options

Option	Default	Description
BUILD_TESTS	ON	Build test suite
BUILD_BENCHMARKS	OFF	Build performance benchmarks
BUILD_CLI	ON	Build command-line interface
BUILD_SERVER	ON	Build REST API server
BUILD_GUI	OFF	Build Qt desktop application
ENABLE_QUANTUM	ON	Enable quantum solver support
ENABLE_PYFLARE	ON	Enable telemetry integration

Example:

cmake -B build \
  -DBUILD_GUI=ON \
  -DENABLE_QUANTUM=OFF \
  -DCMAKE_BUILD_TYPE=Release

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Setup

# Clone with submodules
git clone --recursive https://github.com/oaqlabs/lumen.git
cd lumen/lumen

# Install development dependencies
vcpkg install

# Build with tests
cmake -B build -DBUILD_TESTS=ON -DCMAKE_BUILD_TYPE=Debug
cmake --build build

# Run tests
cd build && ctest --output-on-failure

# Format code
find include src apps test -name '*.cpp' -o -name '*.hpp' | xargs clang-format -i

Roadmap

• Phase 0: Project setup
• Phase 1: Core infrastructure (Weeks 1-4)
• Phase 2: MVP portfolio optimizer (Weeks 5-8)
• Phase 3: Tax optimization (Weeks 9-12)
• Phase 4: Quantum integration (Weeks 13-16)
• Phase 5: Desktop GUI (Weeks 17-20)
• Phase 6: Public launch (Weeks 21-24)

See Lumen_Project_Plan.md for detailed implementation plan.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Disclaimer

Lumen is a decision support tool for portfolio analysis. It does not provide investment advice. Always consult with a qualified financial advisor before making investment decisions.

Contact

• Organization: OA Quantum Labs
• Project Lead: Danny
• Email: [email protected]
• GitHub: https://github.com/oaqlabs/lumen

---

Built with quantum in mind, powered by classical performance.