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.

11.5 KB
Raw Blame
// src/python/PythonSetupManager.h
//
// First-run Python environment bootstrapping (uv-first) and background sync.
//
// The pipeline is driven from the GUI thread by async QProcess / QNetworkReply
// signals — nothing here ever blocks the GUI thread:
//
//   RUNTIME   uv (verified, pinned 0.7.12, SHA-256 checked) → `uv python install`
//   then two INDEPENDENT lanes, no barrier between them:
//   TRADING   venv-numpy1: venv → compile requirements-numpy1.txt to a lock → install lock
//   ANALYTICS venv-numpy2: venv → compile requirements-numpy2.txt to a lock
//             → install the CORE subset (requirements-numpy2-core.txt, versions from
//               the lock) → core_ready()  ← the terminal can launch here
//             → install the rest of the lock in the background
//
// A lane failure never discards the other lane; markers are written per lane,
// only after an install from exactly that requirements content succeeded.
#pragma once

#include <QHash>
#include <QList>
#include <QMutex>
#include <QObject>
#include <QPointer>
#include <QProcessEnvironment>
#include <QString>
#include <QStringList>

#include <array>
#include <atomic>
#include <functional>
#include <memory>

class QNetworkAccessManager;
class QNetworkReply;
class QProcess;
class QTimer;

namespace fincept::python {

/// Result of the cheap, filesystem-only check_status().
struct SetupStatus {
    bool uv_installed = false;        // uv binary present (not executed)
    bool python_installed = false;    // managed CPython <kPythonVersion> present
    bool venv_numpy1_created = false; // venv python + pyvenv.cfg present
    bool venv_numpy2_created = false;
    bool venv_numpy1_ready = false; // created AND marker matches requirements + python + uv
    bool venv_numpy2_ready = false;
    bool core_ready = false;         // venv-numpy2 can serve the first-run experience
    bool needs_setup = true;         // no usable venv-numpy2 → show the first-run screen
    bool needs_package_sync = false; // terminal usable now; finish / verify installs in background
};

/// The four rows the setup UI shows.
enum class SetupStage : int { Runtime = 0, Trading = 1, AnalyticsCore = 2, AnalyticsFull = 3 };
inline constexpr int kSetupStageCount = 4;

enum class SetupStageState : int { Waiting, Running, Done, Failed, Skipped };

struct SetupStageInfo {
    SetupStageState state = SetupStageState::Waiting;
    int percent = -1;    // 0..100 when a REAL fraction is known; -1 = indeterminate (busy)
    QString detail;      // last meaningful live line, e.g. "Downloading numpy (12.0 MiB)"
    QString error;       // set when state == Failed
    qint64 started_ms = 0;
    qint64 finished_ms = 0;
};

/// Point-in-time copy of the pipeline state. Safe to take from any thread.
struct SetupSnapshot {
    bool running = false;
    bool core_ready = false;
    bool finished = false;  // a run has ended (see succeeded / error)
    bool succeeded = false;
    bool cancelled = false; // the run ended through cancel()
    bool background = false; // the UI moved on (early launch / sync) — failures surface on the status chip
    int overall_percent = 0;
    qint64 started_ms = 0;
    QString error;
    std::array<SetupStageInfo, kSetupStageCount> stages{};

    const SetupStageInfo& stage(SetupStage s) const { return stages[static_cast<std::size_t>(s)]; }
};

/// Progress event. `step` keeps the legacy keys ("uv", "python", "venv",
/// "packages-numpy1", "packages-numpy2-core", "packages-numpy2", "complete");
/// the remaining fields carry the per-stage state the UI renders.
struct SetupProgress {
    QString step;
    int progress = 0; // 0-100 for the stage (0 while indeterminate)
    QString message;
    bool is_error = false;
    SetupStage stage = SetupStage::Runtime;
    SetupStageState state = SetupStageState::Waiting;
    bool busy = false; // no real fraction available — render an indeterminate bar
    QString detail;
    qint64 bytes_done = 0; // uv download only
    qint64 bytes_total = 0;
    int overall = 0;
};

class PythonSetupManager : public QObject {
    Q_OBJECT
  public:
    static PythonSetupManager& instance();

    /// Cheap filesystem-only status (no process is spawned). Thread-safe and fast
    /// enough for the GUI thread. Inconclusive states resolve to needs_setup /
    /// needs_package_sync and the pipeline verifies them for real.
    SetupStatus check_status() const;

    /// Start (or resume) the pipeline. Returns immediately; a call while a run is
    /// in progress is a no-op. GUI thread.
    void run_setup();

    /// Abort the running pipeline: kills every uv / curl / tar child (and their
    /// children) and emits setup_complete(false, ...). `wait_for_exit` blocks up
    /// to ~2 s for the children to die — only for application teardown.
    void cancel(bool wait_for_exit = false);

    bool is_running() const { return running_.load(); }
    /// True once venv-numpy2 holds the core packages (this run or on disk).
    bool is_core_ready() const { return core_ready_.load(); }
    /// Weighted overall progress of the current / last run (0-100).
    int overall_percent() const { return overall_percent_.load(); }
    SetupSnapshot snapshot() const;

    /// The UI has moved on (early launch / background sync): post one in-app +
    /// desktop notification when the current run finishes, and let the status
    /// chip own failure reporting.
    void set_background_mode();

    /// Get the install directory (com.fincept.terminal)
    QString install_dir() const;
    /// uv executable path (may not exist yet)
    QString uv_path() const;
    /// Python executable inside a venv (may not exist yet)
    QString python_path(const QString& venv_name = "venv-numpy2") const;
    /// Managed CPython executable (filesystem scan, never spawns a process). Empty if absent.
    QString base_python_path() const;

    /// The environment every uv invocation must use: app-owned Python + cache dirs,
    /// managed Python only, no user uv.toml, inherited UV_* / VIRTUAL_ENV / CONDA_PREFIX /
    /// PYTHONHOME / PYTHONPATH stripped (network settings such as UV_NATIVE_TLS and
    /// index mirrors are kept), CPU torch on Linux. Thread-safe.
    QProcessEnvironment uv_environment() const;

    /// Locate a bundled requirements file (resources/ beside the exe, macOS
    /// Contents/Resources, FHS share/fincept-terminal/resources, dev tree). Cached; thread-safe.
    QString find_requirements_file(const QString& filename) const;
    /// Requirement specifiers from a requirements file (comments, options and blank lines dropped).
    static QStringList read_requirement_lines(const QString& path);
    /// PEP 503 normalised distribution name ("Scikit_Learn" → "scikit-learn").
    static QString canonical_package_name(const QString& name);
    /// Name part of a requirement specifier ("gluonts[torch]==0.16.2" → "gluonts").
    static QString requirement_name(const QString& spec);

  signals:
    void progress_changed(const fincept::python::SetupProgress& progress);
    void setup_complete(bool success, const QString& error);
    /// venv-numpy2 now holds the core packages — the terminal can launch.
    void core_ready();
    void running_changed(bool running);

  private:
    explicit PythonSetupManager(QObject* parent = nullptr);
    ~PythonSetupManager() override;
    Q_DISABLE_COPY_MOVE(PythonSetupManager)

    struct Run;         // per-run pipeline state (PythonSetupManager.cpp)
    struct StepOptions; // child-process options
    struct StepResult;  // child-process outcome
    using LineFn = std::function<void(const QString& line, bool is_stderr)>;
    using DoneFn = std::function<void(const StepResult& result)>;

    // ── Runtime stage ────────────────────────────────────────────────────────
    void runtime_begin();
    void runtime_download_uv();
    void runtime_download_uv_with_curl(const QString& why);
    void runtime_verify_archive(const QString& part_path);
    void runtime_extract_uv(const QString& archive_path, bool use_powershell);
    void runtime_check_uv_version(bool after_install);
    void runtime_install_python();
    void runtime_done();
    void runtime_failed(const QString& error);

    // ── Package lanes (0 = trading / venv-numpy1, 1 = analytics / venv-numpy2) ─
    void lane_start(int lane);
    void lane_create_venv(int lane);
    void lane_seed_preferences(int lane);
    void lane_compile(int lane);
    void lane_install_core(int lane);
    void lane_install_full(int lane);
    void lane_succeeded(int lane);
    void lane_failed(int lane, const QString& error);
    void open_trading_gate();
    void maybe_finish_run();
    void finish_run(bool success, const QString& error);

    // ── Child processes ──────────────────────────────────────────────────────
    QProcess* start_step(const QString& program, const QStringList& args, const StepOptions& opts, LineFn on_line,
                         DoneFn on_done);
    QString describe_failure(const QString& what, const StepResult& r) const;
    bool retry_with_native_tls(const StepResult& r);
    /// True while the run identified by `generation` is current and not cancelled/finished.
    bool alive(quint64 generation) const;
    /// Runs `fn` once the system-proxy probe has finished (or timed out).
    void when_network_ready(std::function<void()> fn);
    void detect_system_proxy();
    void network_ready();

    // ── Progress ─────────────────────────────────────────────────────────────
    void update_stage(SetupStage s, const std::function<void(SetupStageInfo&)>& fn, bool flush_now = false);
    void set_stage_fraction(SetupStage s, double fraction);
    void flush_progress();

    // ── Status helpers ───────────────────────────────────────────────────────
    QString requirements_hash(const QString& filename) const;
    QString expected_marker(const QString& requirements_filename) const;
    QString lock_path(const QString& venv_name) const;
    bool venv_valid(const QString& venv_name) const;
    QString python_request() const;

    // Pinned to an exact patch so `uv python install <ver>` resolves to the
    // same build on every machine. Bumping either one invalidates every venv
    // marker, so the next launch re-syncs.
    static constexpr const char* kPythonVersion = "3.11.9";
    static constexpr const char* kUvVersion = "0.7.12";

    mutable QMutex mutex_; // guards the caches, snapshot_, stage_fraction_ and system_proxy_
    mutable QHash<QString, QString> req_path_cache_;
    mutable QHash<QString, QString> req_hash_cache_;
    SetupSnapshot snapshot_;
    std::array<double, kSetupStageCount> stage_fraction_{}; // real milestones only — drives overall %
    QString system_proxy_;

    std::atomic<bool> running_{false};
    std::atomic<bool> core_ready_{false};
    std::atomic<int> overall_percent_{0};
    std::atomic<bool> native_tls_{false};
    std::atomic<bool> background_mode_{false};

    std::unique_ptr<Run> run_;
    quint64 generation_ = 0;
    QTimer* progress_timer_ = nullptr;
    std::array<bool, kSetupStageCount> dirty_stages_{};
    QNetworkAccessManager* nam_ = nullptr;
    QPointer<QNetworkReply> download_reply_;
    QList<QPointer<QProcess>> live_procs_;
};

} // namespace fincept::python