### Quick Start Installation for Linux/macOS

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/README.md

Clone the repository, navigate to the directory, and execute the setup script to automatically install dependencies, build, and launch the application. This method is suitable for Linux and macOS users.

```bash
git clone https://github.com/Fincept-Corporation/FinceptTerminal.git
cd FinceptTerminal
chmod +x setup.sh && ./setup.sh
```

--------------------------------

### Automated Setup Script

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/docs/CONTRIBUTING.md

Use this script for the fastest setup on Linux or macOS. It installs the necessary toolchain and Qt, then builds the project.

```bash
git clone https://github.com/Fincept-Corporation/FinceptTerminal.git
cd FinceptTerminal
./setup.sh      # Linux / macOS — installs toolchain + Qt via aqtinstall, then builds
setup.bat       # Windows — run from a VS 2022 Developer Command Prompt
```

--------------------------------

### Install AkShare Python Package

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/fincept-qt/scripts/CHINA_DATA_SOURCES.md

Use this command to install the AkShare Python package. No additional setup is required.

```bash
pip install akshare
```

--------------------------------

### Generate Cross-Platform Installer

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/fincept-qt/CMakeLists.txt

Command to generate a cross-platform installer with uninstaller using CMake. Ensure Qt Installer Framework is available and configured.

```bash
cmake -B build -DFINCEPT_BUILD_INSTALLER=ON -DDEPLOY_QT=ON \
  && cmake --build build --config Release \
  && cd build && cpack -G IFW -C Release
```

--------------------------------

### Install macOS Application Bundle and Resources

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/fincept-qt/CMakeLists.txt

Installs the .app bundle, requirements files, and the Fincept Notebook library for a plain macOS installation (non-IFW). Resources are placed within the .app bundle.

```cmake
install(TARGETS FinceptTerminal BUNDLE DESTINATION "." COMPONENT core)
install(FILES
        "${CMAKE_CURRENT_SOURCE_DIR}/resources/requirements-numpy1.txt"
        "${CMAKE_CURRENT_SOURCE_DIR}/resources/requirements-numpy2.txt"
        DESTINATION "FinceptTerminal.app/Contents/Resources/resources" COMPONENT core)
install(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/resources/notebooks/"
        DESTINATION "FinceptTerminal.app/Contents/Resources/resources/notebooks" COMPONENT core)
```

--------------------------------

### Install Linux qt.conf for IFW Installer

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/fincept-qt/CMakeLists.txt

Installs the qt.conf file next to the binary for Linux IFW installations. This allows Qt to find bundled plugins and libraries regardless of the installation location.

```cmake
install(FILES "${CMAKE_CURRENT_SOURCE_DIR}/packaging/linux/qt.conf"
            DESTINATION "bin" COMPONENT core)
```

--------------------------------

### Install functime Wrapper

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/fincept-qt/scripts/Analytics/functime_wrapper/README.md

Install the functime wrapper library using pip. Ensure you are using version 0.1.10.

```bash
pip install functime==0.1.10
```

--------------------------------

### Install pypme Wrapper

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/fincept-qt/scripts/Analytics/pypme_wrapper/README.md

Install the pypme library using pip. Ensure you are using version 0.6.2.

```bash
pip install pypme==0.6.2
```

--------------------------------

### Install Fincept Notebook Resources

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/fincept-qt/CMakeLists.txt

Installs prebuilt Fincept Notebook library resources into the application's resource directory.

```cmake
install(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/resources/notebooks/"
        DESTINATION "share/fincept-terminal/resources/notebooks" COMPONENT core)
```

--------------------------------

### Install Desktop Entry File

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/fincept-qt/CMakeLists.txt

Installs the '.desktop' file for Fincept Terminal, which is necessary for application launchers and menus on Linux.

```cmake
install(FILES "${CMAKE_CURRENT_SOURCE_DIR}/packaging/linux/fincept-terminal.desktop"
        DESTINATION "share/applications" COMPONENT core)
```

--------------------------------

### Read Framework Guide

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/fincept-qt/scripts/agents/GeopoliticsAgents/README.md

Command to display the content of the implementation guide for a specific geopolitical framework.

```bash
# Read relevant guide for framework specifics
cat PRISONERS_OF_GEOGRAPHY_AGENT_GUIDE.md    # Marshall framework
cat WORLD_ORDER_AGENT_GUIDE.md              # Kissinger framework
```

--------------------------------

### Enable Installer Generation

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/fincept-qt/CMakeLists.txt

CMake option to enable the generation of the QtIFW installer via CPack.

```cmake
option(FINCEPT_BUILD_INSTALLER "Generate QtIFW installer via CPack" OFF)
```

--------------------------------

### Build and Configure C++ Project with CMake Presets

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/docs/CPP_CONTRIBUTOR_GUIDE.md

Use CMake presets to configure and build the project for release on Windows, Linux, or macOS. Ensure you have the correct toolchain versions installed as specified in the guide.

```bash
cmake --preset <win-release|linux-release|macos-release>
cmake --build --preset <same-preset>
```

--------------------------------

### Set Build Examples Option

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/fincept-qt/CMakeLists.txt

Disables the building of examples for the project. This is set to OFF and forced.

```cmake
set(BUILD_EXAMPLES OFF CACHE BOOL "" FORCE)
```

--------------------------------

### Install Flatpak Metainfo on Linux

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/fincept-qt/CMakeLists.txt

Installs the Flatpak metainfo XML file for Fincept Terminal on Linux systems.

```cmake
install(FILES packaging/flatpak/in.fincept.FinceptTerminal.metainfo.xml
    DESTINATION ${CMAKE_INSTALL_DATADIR}/metainfo)
```

--------------------------------

### Define Core Install Component

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/fincept-qt/CMakeLists.txt

Defines the 'core' component for the installer, which includes the main application executable and Qt runtime libraries. This component is required.

```cmake
cpack_add_component(core
        DISPLAY_NAME "Fincept Terminal"
        DESCRIPTION  "Core application executable and Qt runtime libraries"
        REQUIRED)
```

--------------------------------

### Install pmdarima

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/fincept-qt/scripts/Analytics/pmdarima_wrapper/README.md

Install the pmdarima library using pip. Ensure you use the specified version for compatibility.

```bash
pip install pmdarima==2.1.1
```

--------------------------------

### Install Qt Development Packages on Linux

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/docs/GETTING_STARTED.md

Installs essential Qt 6 development packages and libraries on Debian-based Linux systems.

```bash
sudo apt install -y \
  qt6-base-dev qt6-charts-dev qt6-tools-dev qt6-base-private-dev \
  libqt6sql6-sqlite libqt6websockets6-dev \
  libgl1-mesa-dev libglu1-mesa-dev
```

--------------------------------

### Install Flatpak Desktop Entry on Linux

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/fincept-qt/CMakeLists.txt

Installs the Flatpak desktop entry file for Fincept Terminal on Linux systems. The application ID is in.fincept.FinceptTerminal.

```cmake
install(FILES packaging/flatpak/in.fincept.FinceptTerminal.desktop
    DESTINATION ${CMAKE_INSTALL_DATADIR}/applications)
```

--------------------------------

### Install Windows Executable and Scripts

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/fincept-qt/CMakeLists.txt

Installs the main executable and associated scripts for Windows. Excludes specific temporary or backup files from script directory deployment.

```cmake
install(TARGETS FinceptTerminal RUNTIME DESTINATION "." COMPONENT core)
install(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/scripts/"
        DESTINATION "scripts" COMPONENT scripts
        REGEX "(\\.deleted\\.|\\.pytest_cache|__pycache__|\\.pyc$|\\.db$|\\.sqlite$|\\.sqlite3$|\\.bak$|\\.orig$)" EXCLUDE)
```

--------------------------------

### Install Application Icon

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/fincept-qt/CMakeLists.txt

Installs the application icon (PNG format) to the hicolor icon theme directory for desktop integration. It renames the icon to 'fincept-terminal.png'.

```cmake
set(_ICON_PNG "${CMAKE_CURRENT_SOURCE_DIR}/resources/fincept.png")
if(EXISTS "${_ICON_PNG}")
    install(FILES "${_ICON_PNG}"
            DESTINATION "share/icons/hicolor/256x256/apps"
            RENAME "fincept-terminal.png" COMPONENT core)
else()
    message(STATUS "Linux icon not found at ${_ICON_PNG} — "
                   "convert resources/fincept.ico to fincept.png for proper desktop integration")
endif()
```

--------------------------------

### Install Wayland Qt Platform Plugin

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/fincept-qt/CMakeLists.txt

Installs the Qt Wayland QPA plugin if Wayland support is detected and Qt6 is available. This ensures the application renders correctly on Wayland sessions.

```cmake
if(HAS_WAYLAND AND Qt6_DIR)
    get_filename_component(_fincept_qt_prefix "${Qt6_DIR}/../../.." ABSOLUTE)
    set(_fincept_wayland_plugin "${_fincept_qt_prefix}/plugins/platforms/libqwayland-generic.so")
    if(EXISTS "${_fincept_wayland_plugin}")
        install(FILES "${_fincept_wayland_plugin}"
                DESTINATION "share/fincept-terminal/plugins/platforms"
                COMPONENT core)
    endif()
    # Also bundle wayland-decoration-client and wayland shell integration plugins.
    foreach(_dir wayland-decoration-client wayland-shell-integration wayland-graphics-integration-client)
        if(EXISTS "${_fincept_qt_prefix}/plugins/${_dir}")
            install(DIRECTORY "${_fincept_qt_prefix}/plugins/${_dir}"
                    DESTINATION "share/fincept-terminal/plugins"
                    COMPONENT core)
        endif()
    endforeach()
endif()
```

--------------------------------

### Clone Repository and Navigate

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/README.md

Clone the FinceptTerminal repository and navigate to the fincept-qt directory. This is the initial step before configuring the build.

```bash
git clone https://github.com/Fincept-Corporation/FinceptTerminal.git
cd FinceptTerminal/fincept-qt
```

--------------------------------

### Get Bond Yields

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/fincept-qt/scripts/CHINA_DATA_SOURCES.md

Retrieves bond yield data. Specify the type of bond, for example, 'china_treasury'.

```python
from akshare_bonds import get_bond_yields
yields = get_bond_yields(bond_type='china_treasury')
```

--------------------------------

### Environment Setup Commands

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/fincept-qt/scripts/agents/GeopoliticsAgents/GrandChessboardAgents/README.md

Set up the necessary environment variables for API keys required by the agents. Ensure you replace 'your-key-here' with your actual API credentials.

```bash
# Required environment variables
export OPENAI_API_KEY="your-key-here"
export ANTHROPIC_API_KEY="your-key-here"
export GEOPOLITICAL_API_KEY="your-geopolitical-data-key"
```

--------------------------------

### Manual Setup with CMake Presets

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/docs/CONTRIBUTING.md

Configure and build the project manually using CMake presets. This method is recommended for day-to-day development.

```bash
cd fincept-qt

# Configure (one-time, or after CMakeLists.txt changes)
cmake --preset win-release        # Windows
cmake --preset linux-release      # Linux
cmake --preset macos-release      # macOS

# Build (run after every code change — incremental)
cmake --build --preset win-release        # Windows
cmake --build --preset linux-release      # Linux
cmake --build --preset macos-release      # macOS
```

--------------------------------

### Get Weather Satellites by Category

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/fincept-qt/scripts/SATELLITE_GEO_DATA_SOURCES.md

Retrieves satellite data filtered by a specific category. Ensure the 'n2yo_satellite_data' library is installed.

```python
from n2yo_satellite_data import get_category_satellites
weather_sats = get_category_satellites(category='weather')
```

--------------------------------

### Set Up Environment and Test Agents

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/fincept-qt/scripts/agents/GeopoliticsAgents/README.md

Configure API keys for LLM providers and run test scripts for Geography and World Order agents.

```bash
# Set up environment
export OPENAI_API_KEY="your-key-here"
export ANTHROPIC_API_KEY="your-key-here"

# Test Geography agents (Marshall framework)
python test_agents/russia_geography_test.py

# Test World Order agents (Kissinger framework)
python test_agents/westphalian_order_test.py
```

--------------------------------

### Get Futures Data

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/fincept-qt/scripts/CHINA_DATA_SOURCES.md

Fetches futures contract data for a specified exchange and symbol. For example, gold futures on SHFE.

```python
from akshare_derivatives import get_futures_data
futures = get_futures_data(exchange='SHFE', symbol='AU')  # Gold futures
```

--------------------------------

### Import pandas and numpy with error handling

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/fincept-qt/resources/notebooks/economics_yield_curve.ipynb

Imports the necessary pandas and numpy libraries. Includes error handling to guide the user if the libraries are not installed.

```python
try:
    import numpy as np
    import pandas as pd
except ImportError:
    raise SystemExit("Fincept Notebook needs pandas + numpy — install with: pip install pandas numpy")
```

--------------------------------

### Running the Application

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/docs/CONTRIBUTING.md

Execute the built FinceptTerminal application. The command varies depending on the operating system.

```bash
.\build\win-release\FinceptTerminal.exe                                           # Windows
./build/linux-release/FinceptTerminal                                             # Linux
./build/macos-release/FinceptTerminal.app/Contents/MacOS/FinceptTerminal          # macOS
```

--------------------------------

### Get OSCAR Current Trends

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/fincept-qt/scripts/SATELLITE_GEO_DATA_SOURCES.md

Retrieves current trends from OSCAR data for a specified region and number of years. Ensure the 'oscar_data' library is installed.

```python
from oscar_data import get_current_trends
trends = get_current_trends(region='gulf_stream', years=10)
```

--------------------------------

### Minimal Screen Implementation Template

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/docs/CPP_CONTRIBUTOR_GUIDE.md

Implementation file for a new screen, setting up a basic layout with a label.

```cpp
// YourScreen.cpp
#include "YourScreen.h"
#include "ui/theme/StyleSheets.h"
#include <QVBoxLayout>
#include <QLabel>

namespace fincept {

YourScreen::YourScreen(QWidget* parent) : QWidget(parent) {
    auto* layout = new QVBoxLayout(this);
    layout->addWidget(new QLabel("Your Screen", this));
}

} // namespace fincept
```

--------------------------------

### Load Example Time Series Data with Fortitudo.tech

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/fincept-qt/scripts/Analytics/fortitudo_tech_wrapper/README.md

Utilize `load_example_time_series` to load a sample time series dataset provided by the library. This is useful for testing and demonstration purposes.

```python
from fortitudo_tech_wrapper.data import load_example_time_series

# Load built-in example data
ts = load_example_time_series()
print(f"Loaded {ts.shape[0]} scenarios with {ts.shape[1]} variables")
```

--------------------------------

### Get Fund Rankings

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/fincept-qt/scripts/CHINA_DATA_SOURCES.md

Fetches rankings for funds based on specified criteria such as category and performance period. For example, top equity funds over the last year.

```python
from akshare_funds_expanded import get_fund_rankings
top_funds = get_fund_rankings(category='equity', period='1y')
```

--------------------------------

### Configure and Build Manually (Linux)

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/README.md

Manually configure and build the project on Linux using CMake. Ensure CMAKE_PREFIX_PATH points to the correct Qt installation.

```bash
cmake -B build/linux-release -G Ninja -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_PREFIX_PATH="$HOME/Qt/6.8.3/gcc_64"
cmake --build build/linux-release
```

--------------------------------

### Python Task Management Actions

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/fincept-qt/docs/agentic-research/README.md

Demonstrates the Python actions for managing tasks within the FinceptTerminal system, including starting, resuming, getting, and listing tasks. These are part of the core agentic primitives.

```python
start_task/resume_task/get_task/list_tasks actions (lines 833, 850, 865, 876)
```

--------------------------------

### Install Linux IFW Installer Payload

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/fincept-qt/CMakeLists.txt

For Linux IFW installers, this installs the pre-built application directory payload generated by linuxdeploy. It ensures the application is relocatable and self-contained.

```cmake
install(DIRECTORY "${FINCEPT_IFW_PAYLOAD}/"
            DESTINATION "."
            USE_SOURCE_PERMISSIONS
            COMPONENT core)
```

--------------------------------

### Initialize and Run CoreAgent

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/fincept-qt/scripts/agents/finagent_core/README.md

Instantiate the CoreAgent with API keys and run a query with a specific configuration. Ensure API keys are securely managed.

```python
from finagent_core import CoreAgent

agent = CoreAgent(api_keys={"OPENAI_API_KEY": "sk-..."})

config = {
    "model": {
        "provider": "openai",
        "model_id": "gpt-4-turbo",
        "temperature": 0.7
    },
    "instructions": "You are a portfolio analyst",
    "tools": ["yfinance", "calculator"]
}

response = agent.run("Analyze AAPL", config)
```

--------------------------------

### Configure and Build Manually (macOS)

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/README.md

Manually configure and build the project on macOS using CMake. Ensure CMAKE_PREFIX_PATH points to the correct Qt installation and set the deployment target.

```bash
cmake -B build/macos-release -G Ninja -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_OSX_DEPLOYMENT_TARGET=11.0 \
  -DCMAKE_PREFIX_PATH="$HOME/Qt/6.8.3/macos"
cmake --build build/macos-release
```

--------------------------------

### Install Scripts Directory on Linux

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/fincept-qt/CMakeLists.txt

Installs the scripts directory for Fincept Terminal on Linux. It excludes __pycache__, *.pyc, and .git directories from the installation.

```cmake
install(DIRECTORY scripts/
    DESTINATION ${CMAKE_INSTALL_DATADIR}/fincept-terminal/scripts
    PATTERN "__pycache__" EXCLUDE
    PATTERN "*.pyc"       EXCLUDE
    PATTERN ".git"        EXCLUDE)
```

--------------------------------

### Install Python Dependencies

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/fincept-qt/scripts/Analytics/python_skfolio_lib/README.md

Install required Python packages using pip. Ensure you have pandas, numpy, scipy, scikit-learn, and skfolio installed.

```bash
pip install skfolio pandas numpy scipy scikit-learn
```

--------------------------------

### Install Bundled yt-dlp

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/fincept-qt/CMakeLists.txt

Conditionally installs the yt-dlp executable if the FINCEPT_YTDLP_TO_BUNDLE variable is set and the file exists. It is installed to the binary directory and renamed to 'yt-dlp'.

```cmake
if(FINCEPT_YTDLP_TO_BUNDLE AND EXISTS "${FINCEPT_YTDLP_TO_BUNDLE}")
    install(PROGRAMS "${FINCEPT_YTDLP_TO_BUNDLE}"
            DESTINATION "bin"
            RENAME "yt-dlp" COMPONENT core)
endif()
```

--------------------------------

### Initialize and Optimize Portfolio

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/fincept-qt/scripts/Analytics/pyportfolioopt_wrapper/README.md

Configure and initialize the PyPortfolioOptAnalyticsEngine for portfolio optimization. Load price data and then run the optimization to get portfolio weights and performance metrics.

```python
config = PyPortfolioOptConfig(
    optimization_method="efficient_frontier",
    objective="max_sharpe",
    expected_returns_method="mean_historical_return",
    risk_model_method="sample_cov",
    risk_free_rate=0.02,
    weight_bounds=(0, 1),
    gamma=0.1
)

# Initialize engine
engine = PyPortfolioOptAnalyticsEngine(config)
engine.load_data(prices)

# Optimize
weights = engine.optimize_portfolio()
ret, vol, sharpe = engine.portfolio_performance()
```

--------------------------------

### Install Python Analytics Scripts

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/fincept-qt/CMakeLists.txt

Installs Python analytics scripts from the 'scripts/' directory, excluding cache and temporary files. This component is for the 'scripts' installation.

```cmake
install(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/scripts/"
        DESTINATION "share/fincept-terminal/scripts"
        USE_SOURCE_PERMISSIONS COMPONENT scripts
        REGEX "(\.deleted\.|\.pytest_cache|\.benchmarks|__pycache__|\.pyc$|\.db$|\.sqlite$|\.sqlite3$|\.bak$|\.orig$)" EXCLUDE)
```

--------------------------------

### Create Trading Engine

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/fincept-qt/scripts/Analytics/vnpy_wrapper/README.md

Initializes a trading engine instance. Use this to set up your trading environment.

```python
from vnpy_wrapper import create_main_engine
result = create_main_engine(engine_id="my_engine")
# Returns: {success: True, engine_id: "my_engine"}
```

--------------------------------

### Install Statsmodels

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/fincept-qt/scripts/Analytics/statsmodels_wrapper/README.md

Installs the statsmodels library. Ensure you are using version 0.14.4 as specified.

```bash
pip install statsmodels==0.14.4
```

--------------------------------

### Fetch and Build QXlsx with CMake

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/fincept-qt/CMakeLists.txt

Fetches the QXlsx library from GitHub using FetchContent and makes it available. This snippet is used when Qt6::GuiPrivate is available.

```cmake
if(FINCEPT_HAS_PRIVATE_HEADERS)
    FetchContent_Declare(
        QXlsx
        GIT_REPOSITORY https://github.com/QtExcel/QXlsx.git
        GIT_TAG        3192b808a283f8eb18c97b9a087bf085054e9bb0  # v1.4.9
        SOURCE_SUBDIR  QXlsx
        GIT_SHALLOW    TRUE
    )
    FetchContent_MakeAvailable(QXlsx)

    # QXlsx uses implicit const char* -> QString conversions which are banned
    # by Qt6's strict cast macros. Undefine them for this target only.
    # Also silence upstream warnings so CI's -Werror doesn't fail on third-party
    # code. /WX- is critical on MSVC: /W0 suppresses warnings but does NOT
    # disable the directory-inherited /WX (warnings-as-errors) that promotes
    # any surviving warning to a build-breaking error.
    if(MSVC)
        target_compile_options(QXlsx PRIVATE
            /UQT_NO_CAST_FROM_ASCII /UQT_NO_CAST_FROM_BYTEARRAY
            /UQT_NO_CAST_TO_ASCII   /UQT_NO_URL_CAST_FROM_STRING
            /W0 /WX-
        )
    else()
        target_compile_options(QXlsx PRIVATE
            -UQT_NO_CAST_FROM_ASCII -UQT_NO_CAST_FROM_BYTEARRAY
            -UQT_NO_CAST_TO_ASCII   -UQT_NO_URL_CAST_FROM_STRING
            -w -Wno-error
        )
    endif()
else()
    # Stub target — satisfies target_link_libraries without pulling in QXlsx
    add_library(QXlsx_stub INTERFACE)
    add_library(QXlsx::QXlsx ALIAS QXlsx_stub)
endif()
```

--------------------------------

### Run Qlib Backtest

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/fincept-qt/scripts/ai_quant_lab/README.md

Executes a backtest for a specified trading strategy. Requires strategy name, universe, date range, and strategy-specific parameters like top_k.

```python
from ai_quant_lab.qlib_service import run_backtest

# Run backtest
results = run_backtest(
    strategy='top_k',
    universe='csi300',
    start_date='2020-01-01',
    end_date='2023-12-31',
    top_k=30
)

print(f"Sharpe Ratio: {results['sharpe']}")
print(f"Annual Return: {results['annual_return']}")
```

--------------------------------

### Commit Message Examples

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/docs/CPP_CONTRIBUTOR_GUIDE.md

Examples of conventional commit messages for various types of changes.

```text
feat: add crypto trading screen
fix: resolve WebSocket reconnection crash
refactor: extract market data service from dashboard
docs: update CONTRIBUTING.md with new architecture
perf: optimize order book rendering
```

--------------------------------

### Install Python 3.11 on Linux

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/docs/GETTING_STARTED.md

Installs Python version 3.11 on Debian-based Linux systems.

```bash
sudo apt install python3.11
```

--------------------------------

### Build Configuration Summary Output

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/fincept-qt/CMakeLists.txt

Prints a summary of the build configuration to the console, including Qt version, build type, platform, compiler, and enabled features like Excel export, WebSockets, Multimedia, Text-to-Speech, Wayland, and code signing status.

```cmake
message(STATUS "")
message(STATUS "============================================================")
message(STATUS "  Fincept Terminal ${CMAKE_PROJECT_VERSION} — build summary")
message(STATUS "============================================================")
message(STATUS "  Qt version        : ${Qt6Core_VERSION}  (pin mode: ${FINCEPT_QT_PIN_MODE})")
message(STATUS "  Build type        : ${CMAKE_BUILD_TYPE}")
message(STATUS "  Platform          : ${CMAKE_SYSTEM_NAME} ${CMAKE_SYSTEM_PROCESSOR}")
message(STATUS "  Compiler          : ${CMAKE_CXX_COMPILER_ID} ${CMAKE_CXX_COMPILER_VERSION}")
if(APPLE AND CMAKE_OSX_ARCHITECTURES)
message(STATUS "  macOS arch        : ${CMAKE_OSX_ARCHITECTURES}")
endif()
message(STATUS "------------------------------------------------------------")
message(STATUS "  Excel export      : ${FINCEPT_HAS_PRIVATE_HEADERS}  (Qt6::GuiPrivate / QXlsx)")
if(DEFINED HAS_WEBSOCKETS)
message(STATUS "  WebSockets        : ${HAS_WEBSOCKETS}")
endif()
if(DEFINED HAS_MULTIMEDIA)
message(STATUS "  Multimedia        : ${HAS_MULTIMEDIA}")
endif()
if(DEFINED HAS_TTS)
message(STATUS "  TextToSpeech      : ${HAS_TTS}")
endif()
if(DEFINED HAS_WAYLAND)
message(STATUS "  Wayland (Linux)   : ${HAS_WAYLAND}")
endif()
if(APPLE AND FINCEPT_MACOS_SIGN_IDENTITY)
message(STATUS "  macOS signing     : ON   (target: sign-macos / notarize-macos)")
endif()
if(WIN32 AND FINCEPT_WIN_SIGN_CERT)
message(STATUS "  Windows signing   : ON   (target: sign-windows)")
endif()
message(STATUS "  Tests             : ${FINCEPT_BUILD_TESTS}")
message(STATUS "============================================================")
message(STATUS "")
```

--------------------------------

### Install Requirements File on Linux

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/fincept-qt/CMakeLists.txt

Installs the requirements-numpy2.txt file to the data directory for Fincept Terminal on Linux.

```cmake
install(FILES
    resources/requirements-numpy2.txt
    DESTINATION ${CMAKE_INSTALL_DATADIR}/fincept-terminal)
```

--------------------------------

### List All MCP Tools

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/fincept-qt/docs/MCP_TOOLS_GUIDE.md

Use `tool.list()` to get a short list of all available tools, including their names and a one-line description.

```shell
tool.list()
```

--------------------------------

### Basic Portfolio Optimization with skfolio API

Source: https://github.com/fincept-corporation/finceptterminal/blob/main/fincept-qt/scripts/Analytics/python_skfolio_lib/README.md

Demonstrates initializing the SkfolioAPI, loading data from a CSV file, and optimizing a portfolio using the mean-risk method. Ensure 'prices.csv' is available in the specified path.

```python
from skfolio_api import SkfolioAPI

# Initialize API
api = SkfolioAPI()

# Load data
data_params = {
    "source_type": "csv",
    "source_path": "prices.csv",
    "date_column": "date",
    "value_columns": ["close"]
}
load_result = api.load_data(data_params)

# Optimize portfolio
params = {
    "optimization_method": "mean_risk",
    "objective_function": "maximize_ratio",
    "risk_measure": "cvar",
    "train_test_split_ratio": 0.8
}

# Sample data format
sample_data = {
    "2020-01-01": [0.01, -0.02, 0.015],
    "2020-01-02": [0.02, 0.01, -0.01],
    "2020-01-03": [-0.01, 0.03, 0.02]
}

result = api.optimize_portfolio(sample_data, params)
```