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.

10.5 KB
Raw Blame
// PythonTools.cpp — Run Python analytics scripts (Qt port)

#include "mcp/tools/PythonTools.h"

#include "core/logging/Logger.h"
#include "mcp/AsyncDispatch.h"
#include "mcp/ToolSchemaBuilder.h"
#include "python/PythonRunner.h"

#include <QDir>
#include <QJsonDocument>
#include <QPromise>
#include <QRegularExpression>

#include <algorithm>
#include <memory>

namespace fincept::mcp::tools {

static constexpr const char* TAG = "PythonTools";

std::vector<ToolDef> get_python_tools() {
    std::vector<ToolDef> tools;

    // ── run_python_script ──────────────────────────────────────────────
    // Phase 4: async exemplar. Previously used run_script_sync (which
    // blocked the worker thread for the entire script run via
    // QMutex+QWaitCondition). Now the handler returns immediately; the
    // promise resolves when PythonRunner's QProcess::finished signal
    // fires. Provider's timeout watchdog covers runaway scripts.
    {
        ToolDef t;
        t.name = "run_python_script";
        t.description = "Execute a Python analytics script by name. IMPORTANT: only pass script names returned by "
                        "list_python_scripts — do not invent or guess script names. For market data prefer "
                        "get_quote / get_candles / edgar_* tools rather than Python scripts.";
        t.category = "analytics";
        t.input_schema =
            ToolSchemaBuilder()
                .string("script", "Script name (without .py) — must be returned by list_python_scripts")
                .required()
                .pattern("^[a-zA-Z0-9_-]+$")
                .length(1, 128)
                .array("args", "Array of string arguments to pass to the script", QJsonObject{{"type", "string"}})
                .build();
        // Match PythonRunner's 5-minute watchdog for top-level scripts (the only
        // ones this tool can run): a shorter budget gave up on scripts that were
        // still working. Over 30 s with an async handler, so long calls become a
        // background job instead of holding the turn open (M1).
        t.default_timeout_ms = 300000;
        // Phase 6.3: arbitrary script execution must be gated. Even with the
        // regex pattern check on script name, the script can read/write
        // files, hit the network, etc. Always confirm.
        t.auth_required = AuthLevel::Authenticated;
        t.is_destructive = true;
        t.async_handler = [](const QJsonObject& args_obj, ToolContext ctx,
                             std::shared_ptr<QPromise<ToolResult>> promise) {
            QString script = args_obj["script"].toString().trimmed();
            // Schema + list_python_scripts expose bare names (no .py), but
            // PythonRunner::run() resolves scripts_dir_ + "/" + script with an
            // exact existence check and never appends .py — normalize here.
            if (!script.endsWith(".py"))
                script += ".py";
            QStringList script_args;
            if (args_obj.contains("args") && args_obj["args"].isArray()) {
                for (const auto& a : args_obj["args"].toArray()) {
                    // The schema says "array of strings" but items are not type-checked,
                    // and models pass numbers/booleans all the time. Numbers and bools
                    // used to fall into the object branch, where `toObject()` of a scalar
                    // is an empty object — the script silently received "{}" instead of
                    // the value. Convert each JSON type to the argv text it stands for.
                    if (a.isString())
                        script_args.append(a.toString());
                    else if (a.isBool())
                        script_args.append(a.toBool() ? QStringLiteral("true") : QStringLiteral("false"));
                    else if (a.isDouble())
                        script_args.append(QString::number(a.toDouble(), 'g', 15));
                    else if (a.isObject())
                        script_args.append(QString::fromUtf8(QJsonDocument(a.toObject()).toJson(QJsonDocument::Compact)));
                    else if (a.isArray())
                        script_args.append(QString::fromUtf8(QJsonDocument(a.toArray()).toJson(QJsonDocument::Compact)));
                    // null / undefined: no argv text to pass
                }
            }

            if (!python::PythonRunner::instance().is_available()) {
                // Resolve through the shared single-winner guard (ctx.resolve_guard), not a
                // bare addResult(): the provider's watchdog races the same flag.
                AsyncDispatch::callback_to_promise(nullptr, ctx, promise, [](auto resolve) {
                    resolve(ToolResult::fail("Python is not available — run setup first"));
                });
                return;
            }

            LOG_INFO(TAG, QString("Running script: %1 with %2 args").arg(script).arg(script_args.size()));

            auto* runner = &python::PythonRunner::instance();
            AsyncDispatch::callback_to_promise(runner, ctx, promise, [runner, script, script_args, ctx](auto resolve) {
                // Forward the script's own output as job progress. Under a job
                // this is the only thing that separates "still working" from
                // "hung": the tool is one opaque call, so its stdout is the
                // sole evidence anything is happening.
                runner->run(script, script_args, [resolve, ctx](python::PythonResult result) {
                    if (ctx.cancelled()) {
                        resolve(ToolResult::fail("cancelled"));
                        return;
                    }
                    if (!result.success) {
                        resolve(ToolResult::fail("Script failed: " + result.error));
                        return;
                    }
                    QString json_text = python::extract_json(result.output);
                    if (json_text.isEmpty())
                        json_text = result.output;

                    QJsonDocument doc = QJsonDocument::fromJson(json_text.toUtf8());
                    if (!doc.isNull()) {
                        if (doc.isObject())
                            resolve(ToolResult::ok_data(doc.object()));
                        else if (doc.isArray())
                            resolve(ToolResult::ok_data(doc.array()));
                        else
                            resolve(ToolResult::ok(result.output));
                    } else {
                        resolve(ToolResult::ok(result.output));
                    }
                }, AsyncDispatch::line_progress_bridge(ctx));
            });
        };
        tools.push_back(std::move(t));
    }

    // ── list_python_scripts ────────────────────────────────────────────
    {
        ToolDef t;
        t.name = "list_python_scripts";
        t.description = "List the runnable Python analytics scripts in the scripts/ directory (there are hundreds — "
                        "pass `query` to filter by name; results are capped by `limit`).";
        t.category = "analytics";
        t.input_schema = ToolSchemaBuilder()
                             .string("query", "Case-insensitive substring to filter script names (e.g. 'yfinance')")
                             .default_str("")
                             .length(0, 64)
                             .integer("limit", "Max scripts to return")
                             .default_int(100)
                             .between(1, 500)
                             .build();
        t.handler = [](const QJsonObject& args) -> ToolResult {
            QString scripts_dir = python::PythonRunner::instance().scripts_dir();
            QDir dir(scripts_dir);

            if (!dir.exists())
                return ToolResult::fail("Scripts directory not found: " + scripts_dir);

            const QString needle = args["query"].toString().trimmed().toLower();
            const int limit = std::clamp(args["limit"].toInt(100), 1, 500);

            // Only offer names run_python_script will accept (its `script` pattern), so
            // the model is never handed a script the validator then refuses.
            static const QRegularExpression runnable(QStringLiteral("^[a-zA-Z0-9_-]+$"));

            QStringList py_files = dir.entryList({"*.py"}, QDir::Files, QDir::Name);
            QJsonArray result;
            int matched = 0;
            for (const auto& f : py_files) {
                QString name = f;
                name.chop(3); // remove .py
                if (!runnable.match(name).hasMatch())
                    continue;
                if (!needle.isEmpty() && !name.toLower().contains(needle))
                    continue;
                ++matched;
                if (result.size() < limit)
                    result.append(QJsonObject{{"name", name}, {"filename", f}});
            }
            // The unfiltered list is ~365 names — far over the result budget, and the
            // overflow shaper keeps the alphabetically-first ones. Say so, and tell the
            // model how to see the rest, rather than letting a clipped list read as complete.
            if (matched > result.size())
                return ToolResult::ok(QStringLiteral("Showing %1 of %2 matching scripts — pass `query` to narrow the "
                                                     "list or raise `limit` (max 500).")
                                          .arg(result.size())
                                          .arg(matched),
                                      result);
            return ToolResult::ok_data(result);
        };
        tools.push_back(std::move(t));
    }

    // ── check_python_status ────────────────────────────────────────────
    {
        ToolDef t;
        t.name = "check_python_status";
        t.description = "Check if Python is available and what scripts directory is in use.";
        t.category = "analytics";
        t.handler = [](const QJsonObject&) -> ToolResult {
            auto& runner = python::PythonRunner::instance();
            return ToolResult::ok_data(QJsonObject{{"python_available", runner.is_available()},
                                                   {"python_path", runner.python_path()},
                                                   {"scripts_dir", runner.scripts_dir()}});
        };
        tools.push_back(std::move(t));
    }

    return tools;
}

} // namespace fincept::mcp::tools