ghosalquant 0.1.0__tar.gz

ghosalquant-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Ghosal Quants
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ghosalquant-0.1.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: ghosalquant
+Version: 0.1.0
+Summary: Event-driven quantitative trading research framework
+Author: Ghosal Quants
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Ghosal-Quants/GhosalQuant
+Project-URL: Documentation, https://github.com/Ghosal-Quants/GhosalQuant/blob/main/design/user_guide.md
+Project-URL: Repository, https://github.com/Ghosal-Quants/GhosalQuant
+Project-URL: Issues, https://github.com/Ghosal-Quants/GhosalQuant/issues
+Keywords: quant,trading,backtesting,algorithmic-trading,finance
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: pytz
+Requires-Dist: requests
+Requires-Dist: yfinance
+Requires-Dist: PyYAML
+Requires-Dist: python-dotenv
+Requires-Dist: pyarrow
+Requires-Dist: fastparquet
+Requires-Dist: ib_insync
+Requires-Dist: websockets
+Provides-Extra: alpaca
+Requires-Dist: alpaca-py; extra == "alpaca"
+Provides-Extra: plotting
+Requires-Dist: matplotlib; extra == "plotting"
+Requires-Dist: plotly; extra == "plotting"
+Provides-Extra: ui
+Requires-Dist: customtkinter; extra == "ui"
+Requires-Dist: matplotlib; extra == "ui"
+Dynamic: license-file
+
+# GhosalQuant
+Ghosal Fund | Quantitative Trading Team Repository
+
+A modular Python framework for developing, backtesting, and executing quantitative trading strategies.
+
+## Documentation
+- [System Overview](https://github.com/Ghosal-Quants/GhosalQuant/blob/main/design/system-overview.md) - architecture + data flow
+- [User Guide](https://github.com/Ghosal-Quants/GhosalQuant/blob/main/design/user_guide.md) - getting started + quick reference
+
+## Installation
+```bash
+pip install ghosalquant
+```
+Optional extras: `ghosalquant[alpaca]` (Alpaca market data), `ghosalquant[plotting]` (matplotlib and plotly charts),
+`ghosalquant[ui]` (the prototype backtest GUI, launched with `ghosalquant-ui`).
+
+To work on the framework itself, install from source in editable mode:
+```bash
+git clone https://github.com/Ghosal-Quants/GhosalQuant.git
+cd GhosalQuant
+pip install -e .
+```
+
+## Quick Start
+1. **Write a strategy** — subclass `Strategy`, implement `on_market_data(bar) -> Signal | None`
+2. **Create a config** — see `examples/config.yaml`
+3. **Run a backtest**:
+```python
+from ghosalquant.backtester.backtester_base import Backtester
+from my_strategy import MyStrategy
+
+kpms = Backtester.from_config(strategy=MyStrategy(), config_path="config.yaml").run()
+print(kpms)
+```
+
+See `examples/` for more examples for: DataFrame backtesting, strategy comparison, IBKR paper trading, and live data.
+
+## Project Structure
+```
+src/ghosalquant/
+  core/           # Bar, Signal, Order, Fill, Trade types
+  execution/      # Strategy base, ExecutionSystem, signal sinks, benchmarks
+  data_layer/     # DataSource implementations (yfinance, Polygon, DataFrame, list)
+  backtester/     # Backtester, DataFrameBacktester
+  risk/           # RiskManager, rules (MaxOpenPositions, ConfidenceSizer)
+  portfolio/      # Portfolio protocol, BasicPortfolio
+  brokerage/      # Broker base, SimBroker, IBKRBroker
+  util/           # Config, visualisation, helpers
+  backtest_ui/    # Prototype GUI (the [ui] extra)
+examples/         # Ready-to-run scripts and sample config
+```
+
+## Tom's Notes
+
+### What are we actually trying to do?
+- Find ideas for interesting strategies for a given asset class
+- Implement the mathematical theory algorithmically
+- Provide quantitative evidence that they work, over a period of time
+- Execute the orders
+
+### Some existing open source frameworks
+- https://amor71.github.io/LiuAlgoTrader/
+- https://www.backtrader.com/
+- https://github.com/gbeced/basana (crypto orientated)
+- https://github.com/panpanpandas/ultrafinance
+- https://github.com/ematvey/pybacktest
+- https://github.com/mhallsmoore/qstrader

ghosalquant-0.1.0/README.md

@@ -0,0 +1,67 @@
+# GhosalQuant
+Ghosal Fund | Quantitative Trading Team Repository
+
+A modular Python framework for developing, backtesting, and executing quantitative trading strategies.
+
+## Documentation
+- [System Overview](https://github.com/Ghosal-Quants/GhosalQuant/blob/main/design/system-overview.md) - architecture + data flow
+- [User Guide](https://github.com/Ghosal-Quants/GhosalQuant/blob/main/design/user_guide.md) - getting started + quick reference
+
+## Installation
+```bash
+pip install ghosalquant
+```
+Optional extras: `ghosalquant[alpaca]` (Alpaca market data), `ghosalquant[plotting]` (matplotlib and plotly charts),
+`ghosalquant[ui]` (the prototype backtest GUI, launched with `ghosalquant-ui`).
+
+To work on the framework itself, install from source in editable mode:
+```bash
+git clone https://github.com/Ghosal-Quants/GhosalQuant.git
+cd GhosalQuant
+pip install -e .
+```
+
+## Quick Start
+1. **Write a strategy** — subclass `Strategy`, implement `on_market_data(bar) -> Signal | None`
+2. **Create a config** — see `examples/config.yaml`
+3. **Run a backtest**:
+```python
+from ghosalquant.backtester.backtester_base import Backtester
+from my_strategy import MyStrategy
+
+kpms = Backtester.from_config(strategy=MyStrategy(), config_path="config.yaml").run()
+print(kpms)
+```
+
+See `examples/` for more examples for: DataFrame backtesting, strategy comparison, IBKR paper trading, and live data.
+
+## Project Structure
+```
+src/ghosalquant/
+  core/           # Bar, Signal, Order, Fill, Trade types
+  execution/      # Strategy base, ExecutionSystem, signal sinks, benchmarks
+  data_layer/     # DataSource implementations (yfinance, Polygon, DataFrame, list)
+  backtester/     # Backtester, DataFrameBacktester
+  risk/           # RiskManager, rules (MaxOpenPositions, ConfidenceSizer)
+  portfolio/      # Portfolio protocol, BasicPortfolio
+  brokerage/      # Broker base, SimBroker, IBKRBroker
+  util/           # Config, visualisation, helpers
+  backtest_ui/    # Prototype GUI (the [ui] extra)
+examples/         # Ready-to-run scripts and sample config
+```
+
+## Tom's Notes
+
+### What are we actually trying to do?
+- Find ideas for interesting strategies for a given asset class
+- Implement the mathematical theory algorithmically
+- Provide quantitative evidence that they work, over a period of time
+- Execute the orders
+
+### Some existing open source frameworks
+- https://amor71.github.io/LiuAlgoTrader/
+- https://www.backtrader.com/
+- https://github.com/gbeced/basana (crypto orientated)
+- https://github.com/panpanpandas/ultrafinance
+- https://github.com/ematvey/pybacktest
+- https://github.com/mhallsmoore/qstrader

ghosalquant-0.1.0/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["setuptools>=77.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ghosalquant"
+dynamic = ["version"]
+description = "Event-driven quantitative trading research framework"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Ghosal Quants" }]
+requires-python = ">=3.10"
+keywords = ["quant", "trading", "backtesting", "algorithmic-trading", "finance"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Financial and Insurance Industry",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business :: Financial :: Investment",
+]
+
+dependencies = [
+    "numpy",
+    "pandas",
+    "pytz",
+    "requests",
+    "yfinance",
+    "PyYAML",
+    "python-dotenv",
+    "pyarrow",
+    "fastparquet",
+    "ib_insync",
+    "websockets"
+]
+
+[project.optional-dependencies]
+alpaca = ["alpaca-py"]
+plotting = ["matplotlib", "plotly"]
+ui = ["customtkinter", "matplotlib"]
+
+[project.gui-scripts]
+ghosalquant-ui = "ghosalquant.backtest_ui.app:main"
+
+[project.urls]
+Homepage = "https://github.com/Ghosal-Quants/GhosalQuant"
+Documentation = "https://github.com/Ghosal-Quants/GhosalQuant/blob/main/design/user_guide.md"
+Repository = "https://github.com/Ghosal-Quants/GhosalQuant"
+Issues = "https://github.com/Ghosal-Quants/GhosalQuant/issues"
+
+[tool.setuptools.dynamic]
+version = { attr = "ghosalquant.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["ghosalquant*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

ghosalquant-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ghosalquant-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/ghosalquant/backtester/__init__.py

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