Skip to content

FinceptTerminal is a modern finance application offering advanced market analytics, investment research, and economic data tools, designed for interactive exploration and data-driven decision-making in a user-friendly environment.

24.6 KB
Raw Blame
// QuantLabTools.cpp — Tools that drive the AI Quant Lab screen.
//
// Module × bespoke commands → 97 module/command-specific tools plus three
// generic discovery/dispatch tools. All execution paths bottom out at
// AIQuantLabService::run_module, which spawns the module's Python script (or,
// for "deep_agent", routes to the deep agent / RD-Agent task registry) and
// emits result_ready / error_occurred when it finishes. We bridge those
// Qt-signal callbacks into an async ToolResult promise via AsyncDispatch.
//
// Tool naming convention: quant_<module>_<command>. The module list and
// command catalogue live in kCatalog below; adding a tool is one line.

#include "mcp/tools/QuantLabTools.h"

#include "core/logging/Logger.h"
#include "mcp/AsyncDispatch.h"
#include "mcp/ToolSchemaBuilder.h"
#include "services/ai_quant_lab/AIQuantLabService.h"
#include "services/ai_quant_lab/AIQuantLabTypes.h"

#include <QJsonArray>
#include <QJsonObject>
#include <QObject>

namespace fincept::mcp::tools {

namespace {

static constexpr const char* TAG = "QuantLabTools";

// Quant Python scripts can run long (full-period backtests, forecasts).
// 5 min default; callers can override per call via _meta.timeout_ms. Anything
// above 30 s with an async handler is job-eligible (CLAUDE.md §M1).
static constexpr int kDefaultTimeoutMs = 300000;
// Model training (qlib models, RL agents) — matches PythonRunner's long-run watchdog.
static constexpr int kTrainingTimeoutMs = 60 * 60 * 1000;
// The LangGraph deep agent: many LLM calls per run.
static constexpr int kDeepAgentTimeoutMs = 20 * 60 * 1000;
// RD-Agent start/status/list/stop/resume, UI/MCP launchers: answered from the
// service's task registry or by a short helper process — never a long wait.
static constexpr int kQuickTimeoutMs = 30000;

struct CatalogEntry {
    const char* module_id;
    const char* command;
    const char* tool_name;
    const char* description;
    // Destructiveness rule: true ONLY when the command writes or deletes
    // persistent state (models / schedules / pipelines / learning state saved to
    // disk), spawns long-lived background work (RD-Agent loops, UI / MCP
    // servers), runs an autonomous LLM agent with filesystem / shell tools, or
    // places orders. Commands that only COMPUTE and return a result are false —
    // flagging them made every agent call refused by default for no safety gain.
    // When adding a row, read the script's command handler before choosing.
    bool destructive;
    int timeout_ms;
};

// Curated from the AIQuantLabService dispatch sites (run_module +
// specialised run_python calls). Adding a new command = one row here.
static const CatalogEntry kCatalog[] = {
    // ── CORE ─────────────────────────────────────────────────────────────
    {"factor_discovery", "get_data", "quant_factor_get_data",
     "Fetch factor data from Qlib for instruments + date range.", false, kDefaultTimeoutMs},
    {"factor_discovery", "get_calendar", "quant_factor_get_calendar", "Get Qlib trading calendar for a date range.",
     false, kDefaultTimeoutMs},
    {"model_library", "train_model", "quant_model_train",
     "Train a Qlib model (LightGBM, XGBoost, LSTM, Transformer, etc).", true, kTrainingTimeoutMs},
    {"model_library", "run_backtest", "quant_model_backtest", "Backtest a trained Qlib model.", false,
     kDefaultTimeoutMs},
    {"backtesting", "run_backtest", "quant_run_backtest", "Multi-strategy backtest with portfolio optimization.", false,
     kDefaultTimeoutMs},
    {"backtesting", "optimize_portfolio", "quant_optimize_portfolio", "Run portfolio optimization across strategies.",
     false, kDefaultTimeoutMs},
    {"live_signals", "get_data", "quant_signals_get_data", "Fetch live trading signal data.", false, kDefaultTimeoutMs},
    {"live_signals", "get_factor_analysis", "quant_signals_factor_analysis", "Factor analysis on live signals.", false,
     kDefaultTimeoutMs},
    {"live_signals", "get_feature_importance", "quant_signals_feature_importance",
     "Feature importance for live signal model.", false, kDefaultTimeoutMs},

    // ── AI_ML ────────────────────────────────────────────────────────────
    {"deep_agent", "execute_task", "quant_deep_agent_execute", "Run an autonomous research task with the deep agent.",
     true, kDeepAgentTimeoutMs},
    {"deep_agent", "check_status", "quant_rd_agent_status", "Check RD-Agent / deep-agent runtime status.", false,
     kQuickTimeoutMs},
    {"deep_agent", "start_factor_mining", "quant_rd_start_factor_mining", "Start an RD-Agent factor mining task.", true,
     kQuickTimeoutMs},
    {"deep_agent", "start_model_optimization", "quant_rd_start_model_opt", "Start an RD-Agent model optimization task.",
     true, kQuickTimeoutMs},
    {"deep_agent", "start_quant_research", "quant_rd_start_quant_research", "Start an RD-Agent quant research task.",
     true, kQuickTimeoutMs},
    {"deep_agent", "get_task_status", "quant_rd_task_status", "Get status of an RD-Agent task by task_id.", false,
     kQuickTimeoutMs},
    {"deep_agent", "get_discovered_factors", "quant_rd_get_factors", "Get factors discovered by an RD-Agent task.",
     false, kQuickTimeoutMs},
    {"deep_agent", "get_optimized_model", "quant_rd_get_model", "Get the optimized model produced by an RD-Agent task.",
     false, kQuickTimeoutMs},
    {"deep_agent", "list_tasks", "quant_rd_list_tasks", "List RD-Agent tasks; optional status filter.", false,
     kQuickTimeoutMs},
    {"deep_agent", "stop_task", "quant_rd_stop_task", "Stop a running RD-Agent task.", true, kQuickTimeoutMs},
    {"deep_agent", "resume_task", "quant_rd_resume_task", "Resume a stopped RD-Agent task; optional config.", true,
     kQuickTimeoutMs},
    {"deep_agent", "start_ui", "quant_rd_start_ui", "Launch the RD-Agent inspection UI.", true, kQuickTimeoutMs},
    {"deep_agent", "start_mcp_server", "quant_rd_start_mcp", "Start the RD-Agent MCP server (default port 18765).",
     true, kQuickTimeoutMs},
    {"deep_agent", "mcp_status", "quant_rd_mcp_status", "Check the RD-Agent MCP server status.", false,
     kQuickTimeoutMs},
    {"rl_trading", "train", "quant_rl_train", "Train an RL trading agent (PPO/DQN/A2C/SAC/TD3). Streaming progress.",
     true, kTrainingTimeoutMs},
    {"rl_trading", "evaluate", "quant_rl_evaluate", "Evaluate a trained RL trading agent.", false, kDefaultTimeoutMs},
    {"online_learning", "create_model", "quant_online_create_model",
     "Create an online-learning model with concept-drift detection.", true, kDefaultTimeoutMs},
    {"online_learning", "train", "quant_online_train", "Incrementally train an online-learning model.", true,
     kDefaultTimeoutMs},
    {"online_learning", "predict", "quant_online_predict", "Get predictions from an online-learning model.", false,
     kDefaultTimeoutMs},
    {"online_learning", "performance", "quant_online_performance",
     "Get performance metrics for an online-learning model.", false, kDefaultTimeoutMs},
    {"meta_learning", "run_selection", "quant_meta_run_selection", "Run meta-learning model selection / AutoML.", true,
     kDefaultTimeoutMs},
    {"meta_learning", "create_ensemble", "quant_meta_create_ensemble", "Build a model ensemble via meta learning.",
     false, kDefaultTimeoutMs},
    {"meta_learning", "tune_hyperparameters", "quant_meta_tune_hyperparams", "Hyperparameter tuning via meta learning.",
     false, kDefaultTimeoutMs},

    // ── ADVANCED ─────────────────────────────────────────────────────────
    {"hft", "fetch_orderbook", "quant_hft_orderbook", "Fetch an order-book snapshot for HFT analysis.", false,
     kDefaultTimeoutMs},
    {"hft", "market_making", "quant_hft_market_making", "Run a market-making strategy step.", false, kDefaultTimeoutMs},
    {"hft", "slippage", "quant_hft_slippage", "Estimate slippage for a trade against the book.", false,
     kDefaultTimeoutMs},
    {"hft", "toxic_flow", "quant_hft_toxic_flow", "Detect toxic order flow on a book.", false, kDefaultTimeoutMs},
    {"hft", "analyze", "quant_hft_analyze", "General HFT order-book analytics.", false, kDefaultTimeoutMs},
    {"rolling_retraining", "create", "quant_rolling_create", "Create a rolling-retraining schedule.", true,
     kDefaultTimeoutMs},
    {"rolling_retraining", "preview", "quant_rolling_preview", "Preview the retrain tasks a schedule would generate.",
     false, kDefaultTimeoutMs},
    {"rolling_retraining", "delete", "quant_rolling_delete", "Delete a rolling-retraining schedule.", true,
     kDefaultTimeoutMs},
    {"advanced_models", "create_model", "quant_adv_create_model",
     "Create an advanced model (lstm/gru/transformer/lstm_attention). Trains on synthetic data; "
     "results carry a 'warning' and are illustrative only.",
     true, kDefaultTimeoutMs},
    {"advanced_models", "train_model", "quant_adv_train_model", "Train an advanced model.", true, kDefaultTimeoutMs},
    {"feature_engineering", "evaluate_expression", "quant_feature_eval_expr", "Evaluate a Qlib feature expression.",
     false, kDefaultTimeoutMs},
    {"feature_engineering", "select_features_by_ic", "quant_feature_select_ic",
     "Select features by Information Coefficient.", false, kDefaultTimeoutMs},
    {"factor_evaluation", "calculate_ic", "quant_eval_ic", "Calculate Information Coefficient metrics for a factor.",
     false, kDefaultTimeoutMs},
    {"factor_evaluation", "calculate_risk_metrics", "quant_eval_risk_metrics",
     "Calculate factor risk metrics (Sharpe, IR, drawdown, etc).", false, kDefaultTimeoutMs},
    {"factor_evaluation", "generate_evaluation_report", "quant_eval_report",
     "Generate a full factor evaluation report.", false, kDefaultTimeoutMs},
    {"strategy_builder", "portfolio_metrics", "quant_strategy_portfolio_metrics",
     "Strategy portfolio metrics (returns, risk, exposure).", false, kDefaultTimeoutMs},
    {"data_processors", "create_pipeline", "quant_dataproc_create_pipeline",
     "Create a Qlib data-processing pipeline (zscore/winsorize/cs_rank/tanh/fillna).", true, kDefaultTimeoutMs},
    {"data_processors", "process_data", "quant_dataproc_process", "Run a Qlib data-processing pipeline on a dataset.",
     false, kDefaultTimeoutMs},

    // ── ANALYTICS ────────────────────────────────────────────────────────
    {"quant_reporting", "check_status", "quant_reporting_status", "Check the quant-reporting service status.", false,
     kDefaultTimeoutMs},
    {"quant_reporting", "ic_analysis", "quant_reporting_ic",
     "Information Coefficient (IC) analysis report — measures a factor's predictive power on forward returns over "
     "time.",
     false, kDefaultTimeoutMs},
    {"quant_reporting", "model_performance", "quant_reporting_model_perf", "Model performance report.", false,
     kDefaultTimeoutMs},
    {"quant_reporting", "cumulative_returns", "quant_reporting_cumret", "Cumulative-returns report.", false,
     kDefaultTimeoutMs},
    {"quant_reporting", "risk_report", "quant_reporting_risk", "Risk-analysis report.", false, kDefaultTimeoutMs},
    {"quant_reporting", "factor_quantiles", "quant_reporting_factor_quantiles", "Factor quantile / decile report.",
     false, kDefaultTimeoutMs},
    {"cfa_quant", "trend_analysis", "quant_cfa_trend", "CFA-style trend analysis on a time series.", false,
     kDefaultTimeoutMs},
    {"cfa_quant", "stationarity_test", "quant_cfa_stationarity", "CFA-style stationarity tests (ADF, KPSS).", false,
     kDefaultTimeoutMs},
    {"cfa_quant", "arima_model", "quant_cfa_arima", "Fit an ARIMA model (CFA wrapper).", false, kDefaultTimeoutMs},
    {"cfa_quant", "supervised_learning", "quant_cfa_supervised", "Supervised-learning prediction (CFA wrapper).", false,
     kDefaultTimeoutMs},
    {"cfa_quant", "unsupervised_learning", "quant_cfa_unsupervised",
     "Unsupervised-learning analysis (PCA, clustering).", false, kDefaultTimeoutMs},
    {"cfa_quant", "resampling_methods", "quant_cfa_resampling", "Bootstrap / resampling-based inference.", false,
     kDefaultTimeoutMs},
    {"cfa_quant", "validate_data", "quant_cfa_validate_data", "Validate input data quality.", false, kDefaultTimeoutMs},
    {"gs_quant", "risk_metrics", "quant_gs_risk_metrics", "GS-Quant risk metrics (VaR, ES, vol, beta, etc).", false,
     kDefaultTimeoutMs},
    {"gs_quant", "portfolio_analytics", "quant_gs_portfolio_analytics", "GS-Quant portfolio analytics.", false,
     kDefaultTimeoutMs},
    {"gs_quant", "greeks", "quant_gs_greeks", "GS-Quant options Greeks.", false, kDefaultTimeoutMs},
    {"gs_quant", "var_analysis", "quant_gs_var_analysis", "GS-Quant VaR analysis.", false, kDefaultTimeoutMs},
    {"gs_quant", "stress_test", "quant_gs_stress_test", "GS-Quant scenario stress test.", false, kDefaultTimeoutMs},
    {"gs_quant", "backtest", "quant_gs_backtest", "GS-Quant backtest engine.", false, kDefaultTimeoutMs},
    {"gs_quant", "statistics", "quant_gs_statistics", "GS-Quant descriptive statistics.", false, kDefaultTimeoutMs},
    {"statsmodels", "check_status", "quant_statsmodels_status", "Statsmodels service status.", false,
     kDefaultTimeoutMs},
    {"statsmodels", "ols", "quant_statsmodels_ols", "Statsmodels OLS regression.", false, kDefaultTimeoutMs},
    {"statsmodels", "arima", "quant_statsmodels_arima", "Statsmodels ARIMA fit.", false, kDefaultTimeoutMs},
    {"statsmodels", "stationarity_tests", "quant_statsmodels_stationarity",
     "Statsmodels stationarity tests (ADF, KPSS, PP).", false, kDefaultTimeoutMs},
    {"statsmodels", "acf_pacf", "quant_statsmodels_acf_pacf", "ACF and PACF computation.", false, kDefaultTimeoutMs},
    {"statsmodels", "granger_causality", "quant_statsmodels_granger", "Granger causality test.", false,
     kDefaultTimeoutMs},
    {"statsmodels", "descriptive", "quant_statsmodels_descriptive", "Descriptive statistics.", false,
     kDefaultTimeoutMs},
    {"functime", "check_status", "quant_functime_status", "Functime service status.", false, kDefaultTimeoutMs},
    {"functime", "forecast", "quant_functime_forecast", "Functime time-series forecast.", false, kDefaultTimeoutMs},
    {"functime", "anomaly_detection", "quant_functime_anomaly", "Functime anomaly detection.", false,
     kDefaultTimeoutMs},
    {"functime", "seasonality", "quant_functime_seasonality", "Functime seasonality decomposition.", false,
     kDefaultTimeoutMs},
    {"functime", "metrics", "quant_functime_metrics", "Functime forecast metrics.", false, kDefaultTimeoutMs},
    {"functime", "confidence_intervals", "quant_functime_intervals", "Functime forecast confidence intervals.", false,
     kDefaultTimeoutMs},
    {"functime", "stationarity", "quant_functime_stationarity", "Functime stationarity tests.", false,
     kDefaultTimeoutMs},
    {"fortitudo", "check_status", "quant_fortitudo_status", "Fortitudo service status.", false, kDefaultTimeoutMs},
    {"fortitudo", "portfolio_metrics", "quant_fortitudo_portfolio_metrics", "Fortitudo portfolio metrics.", false,
     kDefaultTimeoutMs},
    {"fortitudo", "covariance_matrix", "quant_fortitudo_covariance", "Fortitudo covariance matrix.", false,
     kDefaultTimeoutMs},
    {"fortitudo", "mean_variance_optimize", "quant_fortitudo_mv_opt", "Mean-variance portfolio optimization.", false,
     kDefaultTimeoutMs},
    {"fortitudo", "mean_cvar_optimize", "quant_fortitudo_mcvar_opt", "Mean-CVaR portfolio optimization.", false,
     kDefaultTimeoutMs},
    {"fortitudo", "efficient_frontier", "quant_fortitudo_efficient_frontier", "Compute the efficient frontier.", false,
     kDefaultTimeoutMs},
    {"fortitudo", "exp_decay_probabilities", "quant_fortitudo_exp_decay", "Exponential-decay observation weights.",
     false, kDefaultTimeoutMs},
    {"gluonts", "check_status", "quant_gluonts_status", "GluonTS service status.", false, kDefaultTimeoutMs},
    {"gluonts", "probabilistic_forecast", "quant_gluonts_prob_forecast", "GluonTS probabilistic forecast.", false,
     kDefaultTimeoutMs},
    {"gluonts", "quantile_forecast", "quant_gluonts_quantile_forecast", "GluonTS quantile forecast.", false,
     kDefaultTimeoutMs},
    {"gluonts", "distribution_fit", "quant_gluonts_distribution_fit", "Fit a parametric distribution to a series.",
     false, kDefaultTimeoutMs},
    {"gluonts", "evaluate_forecast", "quant_gluonts_evaluate", "Evaluate a forecast against actuals.", false,
     kDefaultTimeoutMs},
    {"gluonts", "seasonal_naive", "quant_gluonts_seasonal_naive", "Seasonal-naive baseline forecast.", false,
     kDefaultTimeoutMs},
};

constexpr std::size_t kCatalogSize = sizeof(kCatalog) / sizeof(kCatalog[0]);

// Async dispatch: post run_module() onto the service thread, wait for the
// first matching result_ready / error_occurred signal, resolve the promise.
//
// Race note: signals are filtered by (module_id, command) for result_ready
// but only by module_id for error_occurred (the service signal only carries
// module_id). Two concurrent calls into the same module CAN have their
// errors crossed. This mirrors the existing screen code's filter; until
// the service grows per-call IDs there's no clean fix.
void dispatch_quant_async(const QString& module_id, const QString& command, const QJsonObject& params, ToolContext ctx,
                          std::shared_ptr<QPromise<ToolResult>> promise) {
    auto* svc = &services::quant::AIQuantLabService::instance();
    // Mark the handoff. Most of these tools declare multi-minute budgets, so under a job the
    // model can be polling for minutes; without this the snapshot says only
    // "running", which cannot distinguish work in flight from a dispatch that
    // never reached the service. The service reports no finer progress than
    // result/error, so this is the whole of the honest signal — one tick, not
    // a fabricated ramp.
    if (ctx.on_progress)
        ctx.on_progress(0.0, QStringLiteral("submitted to %1/%2").arg(module_id, command));
    AsyncDispatch::callback_to_promise(svc, std::move(ctx), promise, [svc, module_id, command, params](auto resolve) {
        auto* holder = new QObject(svc);
        QObject::connect(svc, &services::quant::AIQuantLabService::result_ready, holder,
                         [module_id, command, resolve, holder](QString mid, QString cmd, QJsonObject data) {
                             if (mid != module_id || cmd != command)
                                 return;
                             resolve(ToolResult::ok_data(data));
                             holder->deleteLater();
                         });
        QObject::connect(svc, &services::quant::AIQuantLabService::error_occurred, holder,
                         [module_id, resolve, holder](QString mid, QString msg) {
                             if (mid != module_id)
                                 return;
                             resolve(ToolResult::fail(msg));
                             holder->deleteLater();
                         });
        svc->run_module(module_id, command, params);
    });
}

ToolSchema generic_params_schema(const QString& command_hint = {}) {
    return ToolSchemaBuilder()
        .object("params",
                command_hint.isEmpty()
                    ? QString("Module-specific arguments object (see panel UI for fields).")
                    : QString("Module-specific arguments for '%1'. See panel UI for fields.").arg(command_hint))
        .build();
}

} // namespace

std::vector<ToolDef> get_quant_lab_tools() {
    std::vector<ToolDef> tools;
    tools.reserve(kCatalogSize + 3);

    // ── Generic: list_quant_modules ──────────────────────────────────────
    {
        ToolDef t;
        t.name = "list_quant_modules";
        t.description = "List all AI Quant Lab modules (id, category, description, script).";
        t.category = "quant-lab";
        t.handler = [](const QJsonObject&) -> ToolResult {
            QJsonArray arr;
            for (const auto& m : services::quant::all_quant_modules()) {
                arr.append(QJsonObject{
                    {"id", m.id},
                    {"label", m.label},
                    {"short_label", m.short_label},
                    {"category", m.category},
                    {"description", m.description},
                    {"script", m.script},
                });
            }
            return ToolResult::ok_data(arr);
        };
        tools.push_back(std::move(t));
    }

    // ── Generic: list_quant_module_commands ──────────────────────────────
    {
        ToolDef t;
        t.name = "list_quant_module_commands";
        t.description = "List known commands per AI Quant Lab module, with short descriptions.";
        t.category = "quant-lab";
        t.input_schema = ToolSchemaBuilder()
                             .string("module_id", "Filter by module id (empty = all modules)")
                             .default_str("")
                             .build();
        t.handler = [](const QJsonObject& args) -> ToolResult {
            const QString filter = args["module_id"].toString();
            QJsonObject by_module;
            for (std::size_t i = 0; i < kCatalogSize; ++i) {
                const auto& e = kCatalog[i];
                if (!filter.isEmpty() && filter != QString::fromUtf8(e.module_id))
                    continue;
                QJsonArray cmds = by_module[e.module_id].toArray();
                cmds.append(QJsonObject{
                    {"command", QString::fromUtf8(e.command)},
                    {"tool_name", QString::fromUtf8(e.tool_name)},
                    {"description", QString::fromUtf8(e.description)},
                    {"destructive", e.destructive},
                });
                by_module[QString::fromUtf8(e.module_id)] = cmds;
            }
            return ToolResult::ok_data(by_module);
        };
        tools.push_back(std::move(t));
    }

    // ── Generic: run_quant_module ────────────────────────────────────────
    {
        ToolDef t;
        t.name = "run_quant_module";
        t.description = "Run any AI Quant Lab module/command with custom params (generic dispatcher).";
        t.category = "quant-lab";
        // Stays destructive: it can reach every command, mutating ones included.
        // Prefer the specific quant_* tools, which carry per-command flags.
        t.is_destructive = true;
        t.default_timeout_ms = kDefaultTimeoutMs;
        t.input_schema = ToolSchemaBuilder()
                             .string("module_id", "Module id (use list_quant_modules)")
                             .required()
                             .length(1, 64)
                             .string("command", "Module command (use list_quant_module_commands)")
                             .required()
                             .length(1, 64)
                             .object("params", "Module-specific arguments object")
                             .build();
        t.async_handler = [](const QJsonObject& args, ToolContext ctx, std::shared_ptr<QPromise<ToolResult>> promise) {
            const QString module_id = args["module_id"].toString();
            const QString command = args["command"].toString();
            const QJsonObject params = args["params"].toObject();
            dispatch_quant_async(module_id, command, params, std::move(ctx), promise);
        };
        tools.push_back(std::move(t));
    }

    // ── Catalog-driven specific tools ────────────────────────────────────
    for (std::size_t i = 0; i < kCatalogSize; ++i) {
        const auto& e = kCatalog[i];
        ToolDef t;
        t.name = QString::fromUtf8(e.tool_name);
        t.description = QString::fromUtf8(e.description);
        t.category = "quant-lab";
        t.is_destructive = e.destructive;
        t.default_timeout_ms = e.timeout_ms;
        t.input_schema = generic_params_schema(QString::fromUtf8(e.command));

        const QString module_id = QString::fromUtf8(e.module_id);
        const QString command = QString::fromUtf8(e.command);
        t.async_handler = [module_id, command](const QJsonObject& args, ToolContext ctx,
                                               std::shared_ptr<QPromise<ToolResult>> promise) {
            dispatch_quant_async(module_id, command, args["params"].toObject(), std::move(ctx), promise);
        };
        tools.push_back(std::move(t));
    }

    LOG_INFO(TAG, QString("Defined %1 quant-lab tools").arg(tools.size()));
    return tools;
}

} // namespace fincept::mcp::tools