ghosalquant 0.1.0__py3-none-any.whl

ghosalquant/__init__.py

@@ -0,0 +1,10 @@
+from ghosalquant.execution.strategy_base import OrderBookStrategy, Strategy
+import ghosalquant.core.types as types
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "OrderBookStrategy",
+    "Strategy",
+    "types"
+]

ghosalquant/backtest_ui/__init__.py

@@ -0,0 +1,7 @@
+from pathlib import Path
+
+
+def project_root() -> Path:
+    """The source checkout when run from one, otherwise the directory the UI was started in."""
+    root = Path(__file__).resolve().parents[3]
+    return root if (root / "pyproject.toml").exists() else Path.cwd()

ghosalquant/backtest_ui/__main__.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+import sys
+
+from .runner import run_from_config
+
+if __name__ == "__main__":
+    if len(sys.argv) < 3:
+        print("Usage: python -m ghosalquant.backtest_ui <config.yaml> <strategy.py>")
+        raise SystemExit(2)
+    raise SystemExit(run_from_config(sys.argv[1], sys.argv[2]))

ghosalquant/backtest_ui/app.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+import sys
+import threading
+import subprocess
+from pathlib import Path
+from queue import Queue, Empty
+
+import customtkinter as ctk
+from tkinter import filedialog, messagebox
+
+from . import project_root
+
+"""
+WARNING: VIBED because I hate UI development and this is a prototype for now
+
+This is a rough experimental prototype of a UI to abstract backtesting from QRs.
+"""
+
+
+class App(ctk.CTk):
+    def __init__(self) -> None:
+        super().__init__()
+        self.title("GhosalQuant Backtest (Prototype)")
+        self.geometry("900x600")
+
+        self.root = project_root()
+        self.default_cfg = self.root / "examples" / "config.yaml"
+
+        self.cfg_var = ctk.StringVar(value=str(self.default_cfg) if self.default_cfg.exists() else "")
+
+        self.log_q: Queue[str] = Queue()
+
+        top = ctk.CTkFrame(self)
+        top.pack(fill="x", padx=12, pady=12)
+
+        row1 = ctk.CTkFrame(top)
+        row1.pack(fill="x")
+
+        row2 = ctk.CTkFrame(top)
+        row2.pack(fill="x")
+
+        # Config + Run
+        ctk.CTkLabel(row1, text="Config:").pack(side="left", padx=(10, 8), pady=10)
+        self.cfg_entry = ctk.CTkEntry(row1, textvariable=self.cfg_var, width=560)
+        self.cfg_entry.pack(side="left", padx=8, pady=10)
+        ctk.CTkButton(row1, text="Browse…", command=self.browse).pack(side="left", padx=8, pady=10)
+        self.run_btn = ctk.CTkButton(row1, text="Run", command=self.run)
+        self.run_btn.pack(side="left", padx=8, pady=10)
+
+        # Strategy
+        self.strategy_var = ctk.StringVar(value="")
+        ctk.CTkLabel(row2, text="Strategy:").pack(side="left", padx=(10, 8), pady=10)
+        self.strategy_entry = ctk.CTkEntry(row2, textvariable=self.strategy_var, width=560)
+        self.strategy_entry.pack(side="left", padx=8, pady=10)
+        ctk.CTkButton(row2, text="Browse…", command=self.browse_strategy).pack(side="left", padx=8, pady=10)
+
+        self.log = ctk.CTkTextbox(self, wrap="none")
+        self.log.pack(fill="both", expand=True, padx=12, pady=(0, 12))
+
+        self.after(100, self.drain_logs)
+
+    def browse(self) -> None:
+        p = filedialog.askopenfilename(
+            title="Select config.yaml",
+            filetypes=[("YAML files", "*.yaml *.yml"), ("All files", "*.*")]
+        )
+        if p:
+            self.cfg_var.set(p)
+
+    def browse_strategy(self) -> None:
+        p = filedialog.askopenfilename(
+            title="Select strategy .py",
+            filetypes=[("Python files", "*.py"), ("All files", "*.*")]
+        )
+        if p:
+            self.strategy_var.set(p)
+
+    def append(self, line: str) -> None:
+        self.log.insert("end", line + "\n")
+        self.log.see("end")
+
+    def drain_logs(self) -> None:
+        try:
+            while True:
+                self.append(self.log_q.get_nowait())
+        except Empty:
+            pass
+        self.after(100, self.drain_logs)
+
+    def run(self) -> None:
+        cfg = Path(self.cfg_var.get().strip())
+        if not cfg.exists():
+            messagebox.showerror("Missing config", f"Config not found:\n{cfg}")
+            return
+
+        strategy = Path(self.strategy_var.get().strip())
+        if not strategy.exists():
+            messagebox.showerror("Missing strategy", f"Strategy not found:\n{strategy}")
+            self.run_btn.configure(state="normal")
+            return
+
+        self.run_btn.configure(state="disabled")
+        self.append(f"Running with config: {cfg}")
+
+        strategy = Path(self.strategy_var.get().strip())  # add a strategy picker var in UI
+        cmd = [sys.executable, "-m", "ghosalquant.backtest_ui", str(cfg), str(strategy)]
+
+        def worker() -> None:
+            try:
+                proc = subprocess.Popen(
+                    cmd,
+                    cwd=str(self.root),
+                    stdout=subprocess.PIPE,
+                    stderr=subprocess.STDOUT,
+                    text=True,
+                )
+                assert proc.stdout is not None
+                for line in proc.stdout:
+                    self.log_q.put(line.rstrip("\n"))
+                rc = proc.wait()
+                self.log_q.put(f"[done] exit code = {rc}")
+            except Exception as e:
+                self.log_q.put(f"[error] {e}")
+            finally:
+                self.log_q.put("__enable__")
+
+        def enable_later() -> None:
+            # wait for the marker then re-enable the button in UI thread
+            while True:
+                msg = self.log_q.get()
+                if msg == "__enable__":
+                    self.run_btn.configure(state="normal")
+                    break
+                else:
+                    self.append(msg)
+
+        threading.Thread(target=worker, daemon=True).start()
+        threading.Thread(target=enable_later, daemon=True).start()
+
+
+def main() -> None:
+    ctk.set_appearance_mode("System")
+    App().mainloop()
+
+
+if __name__ == "__main__":
+    main()

ghosalquant/backtest_ui/runner.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Type
+import importlib.util
+
+import yaml
+import yfinance as yf
+from matplotlib import pyplot as plt
+
+from ghosalquant.backtester.dataframe_backtester import DataFrameBacktester
+from ghosalquant.execution.strategy_base import Strategy
+from ghosalquant.util.visualisation import plot_equity_curve
+
+from . import project_root
+
+def _safe_stem(s: str) -> str:
+    # sanitiser
+    chars: list[str] = []
+    for ch in s:
+        if ch.isalnum() or ch in ("-", "_"):
+            chars.append(ch)
+        else:
+            chars.append("_")
+
+    stem = "".join(chars).strip("_")
+    return stem or "run"
+
+
+def _load_strategy_from_file(path: Path) -> Strategy:
+    spec = importlib.util.spec_from_file_location(path.stem, str(path))
+    if spec is None or spec.loader is None:
+        raise RuntimeError(f"Could not import strategy file: {path}")
+
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)  # type: ignore[assignment]
+
+    # Explicit export as STRATEGY_CLASS
+    if hasattr(mod, "STRATEGY_CLASS"):
+        cls = getattr(mod, "STRATEGY_CLASS")
+        if isinstance(cls, type) and issubclass(cls, Strategy):
+            return cls()
+        raise TypeError("STRATEGY_CLASS exists but is not a Strategy subclass.")
+
+    # As a fallback, find first Strategy subclass in module
+    for obj in mod.__dict__.values():
+        if isinstance(obj, type) and issubclass(obj, Strategy) and obj is not Strategy:
+            return obj()
+
+    raise ValueError(
+        "No strategy found. Define STRATEGY_CLASS = YourStrategy, "
+        "or include a Strategy subclass in the file."
+    )
+
+
+def run_from_config(config_path: str | Path, strategy_path: str | Path) -> int:
+    cfg_path = Path(config_path).resolve()
+    strat_path = Path(strategy_path).resolve()
+
+    if not cfg_path.exists():
+        print(f"Config not found: {cfg_path}")
+        return 2
+    if not strat_path.exists():
+        print(f"Strategy not found: {strat_path}")
+        return 2
+
+    cfg: dict[str, Any] = yaml.safe_load(cfg_path.read_text(encoding="utf-8")) or {}
+    system = cfg.get("SYSTEM", {}) or {}
+    tr = cfg.get("TIME_RANGE", {}) or {}
+
+    symbols = system.get("symbols", ["AAPL"]) or ["AAPL"]
+    symbol = symbols[0]  # prototype: single symbol
+
+    start_date = tr.get("start_date", "2024-01-01")
+    end_date = tr.get("end_date", "2025-12-31")
+
+    print("UI Runner: DataFrameBacktester")
+    print(f"Config:   {cfg_path}")
+    print(f"Strategy: {strat_path}")
+    print(f"Symbol:   {symbol}")
+    print(f"Range:    {start_date} -> {end_date}")
+
+    df = yf.download(symbol, start=start_date, end=end_date, auto_adjust=True, progress=False)
+
+    strategy = _load_strategy_from_file(strat_path)
+    backtester = DataFrameBacktester(strategy=strategy, dataframe=df, config_path=str(cfg_path))
+
+    kpms = backtester.run()
+    print("\nKEY PERFORMANCE METRICS:\n" + str(kpms))
+    print("REALISED PNL:", backtester.realised_pnl)
+
+    # Plot and save to file
+    plot_equity_curve(backtester.equity_curve, show_realised_unrealised=True)
+
+    out_dir = project_root() / "ui_outputs"
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    strategy_name = _safe_stem(strat_path.stem)
+    symbol_name = _safe_stem(symbol)
+    now = datetime.now().strftime("%Y-%m-%d_%H-%M-%S")
+    out_path = out_dir / f"equity_curve_{now}_{symbol_name}_{strategy_name}.png"
+
+    plt.savefig(out_path, dpi=150, bbox_inches="tight")
+    plt.close()
+
+    print(f"Saved plot: {out_path}")
+
+    return 0

ghosalquant/backtester/__init__.py

@@ -0,0 +1,7 @@
+from .backtester_base import Backtester
+from .dataframe_backtester import DataFrameBacktester
+
+__all__ = [
+    "Backtester",
+    "DataFrameBacktester",
+]

ghosalquant/backtester/backtester_base.py

@@ -0,0 +1,129 @@
+import asyncio
+from typing import final, Iterable
+
+from ..data_layer.datasource_factory import datasource_from_config
+from ..brokerage.builder import build_broker
+from ..execution.strategy_base import Strategy
+from ..execution.execution_system import ExecutionSystem
+from ..data_layer.datasource_base import DataSource
+from ..execution.sinks import SignalSink
+from ..core.contracts import ContractRegistry
+from ..core.types import Order, BacktestKPMs, EquityPoint
+from ..portfolio.basic_portfolio import BasicPortfolio
+from ..portfolio.portfolio_base import Portfolio
+from ..brokerage.broker_base import Broker
+from ..risk.builder import build_risk_manager
+from ..risk.risk_manager import RiskManager
+from ..util.backtester_utils import calculate_kpms
+from ..util.config import Config, load_config
+
+
+class Backtester:
+    def __init__(
+            self,
+            *,
+            strategy: Strategy,
+            data_src: DataSource,
+            signal_destination: SignalSink | None = None,
+            portfolio: Portfolio | None = None,
+            risk_manager: RiskManager | None = None,
+            broker: Broker | None = None,
+            config: Config | None = None,
+            contracts: ContractRegistry | None = None,
+    ) -> None:
+        self.config = config
+
+        if portfolio is None:
+            portfolio = BasicPortfolio(init_capital=10_000.0, contracts=contracts)
+
+        if risk_manager is None and config is not None and config.system.use_risk_manager:
+            risk_manager = build_risk_manager(config.risk)
+
+        self.execution_system = ExecutionSystem(
+            data_src = data_src,
+            strategy = strategy,
+            signal_destination = signal_destination,
+            risk_manager = risk_manager,
+            portfolio = portfolio,
+            broker = broker,
+            contracts = contracts,
+        )
+
+        self._portfolio = self.execution_system.portfolio
+
+    @classmethod
+    def from_config(cls,
+                    *,
+                    strategy: Strategy,
+                    config_path: str,
+
+                    # Optional overrides
+                    signal_destination: SignalSink | None = None,
+                    portfolio: Portfolio | None = None,
+                    risk_manager: RiskManager | None = None,
+                    init_capital: float = 10_000.0,
+                    contracts: ContractRegistry | None = None,
+        ) -> "Backtester":
+
+            cfg = load_config(config_path)
+            data_src = datasource_from_config(cfg, contracts=contracts)
+
+            if portfolio is None:
+                portfolio = BasicPortfolio(init_capital=float(init_capital), contracts=contracts)
+
+            if risk_manager is None and cfg.system.use_risk_manager:
+                risk_manager = build_risk_manager(cfg.risk)
+
+            return cls(
+                strategy=strategy,
+                data_src=data_src,
+                signal_destination=signal_destination,
+                portfolio=portfolio,
+                risk_manager=risk_manager,
+                broker=build_broker(cfg.broker, contracts=contracts),
+                config=cfg,
+                contracts=contracts,
+            )
+
+    # ----- Properties ----- #
+    @property
+    def equity_curve(self) -> Iterable[EquityPoint]:
+        return self._portfolio.equity_curve
+
+    @property
+    def realised_pnl(self) -> float:
+        return self._portfolio.realised_pnl
+
+    @property
+    def unrealised_pnl(self) -> float:
+        return self._portfolio.unrealised_pnl
+
+    @property
+    def total_pnl(self) -> float:
+        return self.realised_pnl + self.unrealised_pnl
+
+    @property
+    def kpms(self) -> BacktestKPMs:
+        if not self._portfolio:
+            raise ValueError("Cannot produce KPMs without an initialised Portfolio")
+
+        """Calculate and return key performance metrics after completing a backtest."""
+        return calculate_kpms(self._portfolio)
+
+    @final
+    async def run_async(self) -> BacktestKPMs:
+        await self.execution_system.run()
+
+        if not self._portfolio:
+            raise ValueError("Cannot produce KPMs without an initialised Portfolio")
+
+        return calculate_kpms(self._portfolio)
+
+    @final
+    def run(self) -> BacktestKPMs:
+        try:
+            asyncio.get_running_loop()
+        except RuntimeError:
+            return asyncio.run(self.run_async())
+
+        raise RuntimeError("Cannot run backtest synchronously within an existing event loop. Please use run_async() instead.")

ghosalquant/backtester/dataframe_backtester.py

@@ -0,0 +1,95 @@
+import asyncio
+from typing import Iterable
+
+from pandas import DataFrame
+import pandas as pd
+
+from ..backtester.backtester_base import Backtester
+from ..brokerage.builder import build_broker
+from ..core.types import Order, EquityPoint, BacktestKPMs
+from ..execution.strategy_base import Strategy
+from ..data_layer.dataframe_datasource import DataFrameDataSource
+from ..execution.sinks import DataFrameSink
+from ..portfolio.basic_portfolio import BasicPortfolio
+from ..util.backtester_utils import output_to_excel, calculate_kpms
+from ..util.config import load_config
+
+class DataFrameBacktester(Backtester):
+    def __init__(
+            self,
+            strategy: Strategy,
+            dataframe: DataFrame,
+            config_path: str,
+
+            timestamp_col: str | None = None,
+            # DataFrame format:
+            *,
+            symbol: str | None = None,
+            open_col: str   = "Open",
+            high_col: str   = "High",
+            low_col: str    = "Low",
+            close_col: str  = "Close",
+            volume_col: str = "Volume",
+
+            # Additional Columns
+            signal_col: str = "Signal",
+            confidence_col: str = "Confidence",
+            quantity_col: str = "Quantity",
+
+            # Backtesting
+            init_capital: float = 10_000.0
+    ) -> None:
+        config = load_config(config_path)
+
+        df = dataframe.copy()
+
+        if isinstance(df.columns, pd.MultiIndex): # Flatten MultiIndex if present
+            required = {open_col, high_col, low_col, close_col, volume_col}
+
+            levels = [set(map(str, df.columns.get_level_values(i))) for i in range(df.columns.nlevels)]
+            level_with_required = None
+            for i, vals in enumerate(levels):
+                if required.issubset(vals):
+                    level_with_required = i
+                    break
+
+            if level_with_required is not None:
+                df.columns = df.columns.get_level_values(level_with_required)
+
+        # Duplicate the initial DataFrame and initialise signal and confidence columns
+        self._return_df = df
+        self._return_df[signal_col] = pd.NA
+        self._return_df[confidence_col] = 0.0
+        self._return_df[quantity_col] = 0.0
+
+        # Backtesting variables
+        self._symbols: list[str] = config.system.symbols
+        self._portfolio = BasicPortfolio(init_capital=init_capital)
+
+        super().__init__(
+            strategy=strategy,
+            data_src=DataFrameDataSource(
+                dataframe=df,
+                symbol= config.system.symbols[0],
+                timestamp_col= timestamp_col,
+                open_col= open_col,
+                high_col= high_col,
+                low_col= low_col,
+                close_col= close_col,
+                volume_col= volume_col
+            ),
+            signal_destination=DataFrameSink(
+                dataframe= self._return_df,
+                timestamp_col= timestamp_col,
+                signal_col= signal_col,
+                confidence_col= confidence_col,
+                quantity_col= quantity_col
+            ),
+            portfolio= self._portfolio,
+            broker=build_broker(config.broker),
+            config= config,
+        )
+
+    @property
+    def dataframe(self) -> DataFrame:
+        return self._return_df

ghosalquant/bench/__init__.py

@@ -0,0 +1,7 @@
+from .benchmark_buy_and_hold import BenchmarkBuyAndHold
+from .benchmark_trend_vol_target import BenchmarkTrendVolTarget
+
+__all__ = [
+    "BenchmarkBuyAndHold",
+    "BenchmarkTrendVolTarget",
+]

ghosalquant/bench/benchmark_buy_and_hold.py

@@ -0,0 +1,51 @@
+from ..execution.strategy_base import Strategy
+from ..core.types import Bar, Signal, SignalType
+
+class BenchmarkBuyAndHold(Strategy):
+    """
+    Buy and hold benchmark strategy.
+    - On a bar received with an unseen symbol, sends a BUY signal.
+    - After entering, emits no further signals for that symbol
+    """
+
+    _USE_CATASTROPHIC_SL: bool = True
+    _CATASTROPHIC_SL_PERCENT: float = 0.35  # 35% below entry in case of extreme drawdown
+
+    def __init__(self):
+        super().__init__()
+        self._entered: dict[str, bool] = {}
+        self._entry_price: dict[str, float] = {}
+
+    def on_start(self):
+        ...
+
+    def on_end(self):
+        ...
+
+    def on_market_data(self, bar: Bar) -> Signal | None:
+        symbol = bar.symbol
+
+        if not self._entered.get(symbol, False):
+            self._entered[symbol] = True
+            self._entry_price[symbol] = float(bar.close)
+
+            confidence = 1.0
+            quantity = super().calculate_quantity(confidence=confidence)
+
+            metadata: dict[str, float] = {}
+
+            if self._USE_CATASTROPHIC_SL:
+                sl = bar.close * (1.0 - self._CATASTROPHIC_SL_PERCENT)
+                metadata["stop_loss"] = sl
+
+            return Signal(
+                time_stamp=bar.time_stamp,
+                symbol=symbol,
+                signal_type=SignalType.BUY,
+                ref_price=bar.close,
+                confidence=confidence,
+                quantity=quantity,
+                metadata=metadata if metadata else None,
+            )
+
+        return None