quantcore-lite 0.1.0__py3-none-any.whl

quantcore/__init__.py

@@ -0,0 +1,15 @@
+"""QuantCore — open-core backtesting framework for quantitative trading strategies."""
+
+__version__ = "0.1.0"
+
+from quantcore.engine import Backtest
+from quantcore.metrics import compute_metrics
+from quantcore.strategies import MeanReversion, MomentumStrategy, MovingAverageCrossover
+
+__all__ = [
+    "Backtest",
+    "compute_metrics",
+    "MomentumStrategy",
+    "MeanReversion",
+    "MovingAverageCrossover",
+]

quantcore/cli.py

@@ -0,0 +1,208 @@
+"""Command-line interface for QuantCore."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+import pandas as pd
+
+from quantcore.engine import Backtest
+from quantcore.strategies import FREE_STRATEGIES
+
+
+def _get_all_strategies() -> dict:
+    """Return combined dict of free + pro strategies (pro only if licensed)."""
+    all_strats = dict(FREE_STRATEGIES)
+    try:
+        from quantcore.pro.license import validate_license
+
+        if validate_license():
+            from quantcore.pro.strategies import PRO_STRATEGIES
+
+            all_strats.update(PRO_STRATEGIES)
+    except Exception:
+        pass
+    return all_strats
+
+
+def cmd_backtest(args: argparse.Namespace) -> None:
+    """Run a backtest from the CLI."""
+    data_path = Path(args.data)
+    if not data_path.exists():
+        print(f"Error: Data file not found: {data_path}")
+        sys.exit(1)
+
+    data = pd.read_csv(data_path, parse_dates=True, index_col=0)
+
+    all_strategies = _get_all_strategies()
+    strategy_key = args.strategy.lower().replace("-", "_").replace(" ", "_")
+
+    if strategy_key not in all_strategies:
+        # Check if it's a pro strategy that requires license
+        from quantcore.pro.strategies import PRO_STRATEGIES
+
+        if strategy_key in PRO_STRATEGIES:
+            from quantcore.pro.license import require_pro
+
+            if not require_pro():
+                sys.exit(0)
+            all_strategies.update(PRO_STRATEGIES)
+        else:
+            available = ", ".join(sorted(all_strategies.keys()))
+            print(f"Error: Unknown strategy '{args.strategy}'. Available: {available}")
+            sys.exit(1)
+
+    strategy_cls = all_strategies[strategy_key]
+    strategy = strategy_cls()
+
+    bt = Backtest(
+        data,
+        strategy,
+        initial_capital=args.capital,
+        commission=args.commission,
+    )
+    bt.run()
+
+    print(bt.summary())
+    print()
+
+    if args.output:
+        out_path = bt.export_csv(args.output)
+        print(f"Results exported to: {out_path}")
+
+    if args.tearsheet:
+        from quantcore.pro.license import require_pro
+
+        if require_pro():
+            from quantcore.pro.monte_carlo import monte_carlo_simulation
+            from quantcore.pro.tearsheet import generate_tearsheet
+
+            mc = monte_carlo_simulation(bt.results, initial_capital=args.capital)
+            pdf_path = generate_tearsheet(
+                bt.results, bt.metrics, mc, strategy.name, args.tearsheet
+            )
+            print(f"Tearsheet saved to: {pdf_path}")
+
+    if args.monte_carlo:
+        from quantcore.pro.license import require_pro
+
+        if require_pro():
+            from quantcore.pro.monte_carlo import monte_carlo_simulation
+
+            mc = monte_carlo_simulation(
+                bt.results, n_simulations=args.mc_runs, initial_capital=args.capital
+            )
+            ci = mc["confidence_intervals"]
+            print(f"\nMonte Carlo ({mc['n_simulations']} simulations):")
+            print(f"  Median final value: ${mc['median_final']:,.2f}")
+            print(f"  Mean final value:   ${mc['mean_final']:,.2f}")
+            for pct, val in ci.items():
+                print(f"  {pct} percentile:    ${val:,.2f}")
+
+
+def cmd_strategies(args: argparse.Namespace) -> None:
+    """List available strategies."""
+    print("Free strategies:")
+    for name in sorted(FREE_STRATEGIES.keys()):
+        print(f"  - {name}")
+
+    print("\nPro strategies (requires license):")
+    from quantcore.pro.strategies import PRO_STRATEGIES
+
+    for name in sorted(PRO_STRATEGIES.keys()):
+        print(f"  - {name}")
+
+
+def cmd_optimize(args: argparse.Namespace) -> None:
+    """Run parameter grid search optimization."""
+    from quantcore.pro.license import require_pro
+
+    if not require_pro():
+        sys.exit(0)
+
+    from quantcore.pro.optimizer import grid_search
+
+    data = pd.read_csv(args.data, parse_dates=True, index_col=0)
+
+    all_strategies = dict(FREE_STRATEGIES)
+    from quantcore.pro.strategies import PRO_STRATEGIES
+
+    all_strategies.update(PRO_STRATEGIES)
+
+    strategy_key = args.strategy.lower().replace("-", "_").replace(" ", "_")
+    if strategy_key not in all_strategies:
+        print(f"Error: Unknown strategy '{args.strategy}'")
+        sys.exit(1)
+
+    # Default param grids per strategy
+    default_grids = {
+        "momentum": {"lookback": [10, 20, 30, 50]},
+        "mean_reversion": {"window": [10, 20, 30], "threshold": [1.0, 1.5, 2.0]},
+        "moving_average": {"short_window": [10, 20], "long_window": [30, 50, 100]},
+        "rsi": {"period": [7, 14, 21], "oversold": [20, 30], "overbought": [70, 80]},
+        "bollinger_bands": {"window": [10, 20, 30], "num_std": [1.5, 2.0, 2.5]},
+        "macd": {"fast": [8, 12], "slow": [21, 26], "signal": [7, 9]},
+    }
+
+    param_grid = default_grids.get(strategy_key, {"lookback": [10, 20, 30]})
+    results = grid_search(data, all_strategies[strategy_key], param_grid, metric=args.metric)
+
+    print(f"\nGrid search results for {strategy_key} (optimizing {args.metric}):\n")
+    for i, r in enumerate(results[:10]):
+        print(f"  #{i + 1}: {r['params']} -> {args.metric}={r['score']:.4f}")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the CLI argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="quantcore",
+        description="QuantCore — backtesting framework for quantitative trading strategies",
+    )
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    # backtest
+    bt_parser = subparsers.add_parser("backtest", help="Run a backtest")
+    bt_parser.add_argument("--data", "-d", required=True, help="Path to OHLCV CSV file")
+    bt_parser.add_argument(
+        "--strategy", "-s", required=True, help="Strategy name (e.g. momentum, mean_reversion)"
+    )
+    bt_parser.add_argument("--capital", "-c", type=float, default=100_000, help="Initial capital")
+    bt_parser.add_argument("--commission", type=float, default=0.001, help="Commission rate")
+    bt_parser.add_argument("--output", "-o", help="Output CSV path for results")
+    bt_parser.add_argument("--tearsheet", help="Output PDF path for tearsheet (Pro)")
+    bt_parser.add_argument("--monte-carlo", action="store_true", help="Run Monte Carlo sim (Pro)")
+    bt_parser.add_argument("--mc-runs", type=int, default=1000, help="Number of MC simulations")
+
+    # strategies
+    subparsers.add_parser("strategies", help="List available strategies")
+
+    # optimize
+    opt_parser = subparsers.add_parser("optimize", help="Grid search optimization (Pro)")
+    opt_parser.add_argument("--data", "-d", required=True, help="Path to OHLCV CSV file")
+    opt_parser.add_argument("--strategy", "-s", required=True, help="Strategy to optimize")
+    opt_parser.add_argument("--metric", "-m", default="sharpe_ratio", help="Metric to optimize")
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    """Entry point for the quantcore CLI."""
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command is None:
+        parser.print_help()
+        sys.exit(0)
+
+    commands = {
+        "backtest": cmd_backtest,
+        "strategies": cmd_strategies,
+        "optimize": cmd_optimize,
+    }
+    commands[args.command](args)
+
+
+if __name__ == "__main__":
+    main()

quantcore/engine.py

@@ -0,0 +1,142 @@
+"""Core backtesting engine that processes OHLCV data through trading strategies."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional, Union
+
+import numpy as np
+import pandas as pd
+
+from quantcore.metrics import compute_metrics
+
+
+class Backtest:
+    """Run a strategy against historical OHLCV data and collect results.
+
+    Parameters
+    ----------
+    data : pd.DataFrame
+        OHLCV DataFrame with columns: open, high, low, close, volume.
+        Index should be datetime or integer.
+    strategy : object
+        A strategy instance implementing ``generate_signals(data) -> pd.Series``.
+    initial_capital : float
+        Starting portfolio value (default 100_000).
+    commission : float
+        Per-trade commission as a fraction (default 0.001 = 0.1%).
+    """
+
+    def __init__(
+        self,
+        data: pd.DataFrame,
+        strategy,
+        initial_capital: float = 100_000,
+        commission: float = 0.001,
+    ):
+        self.data = self._validate_data(data)
+        self.strategy = strategy
+        self.initial_capital = initial_capital
+        self.commission = commission
+        self.results: Optional[pd.DataFrame] = None
+        self.metrics: Optional[dict] = None
+
+    @staticmethod
+    def _validate_data(data: pd.DataFrame) -> pd.DataFrame:
+        required = {"open", "high", "low", "close", "volume"}
+        columns_lower = {c.lower() for c in data.columns}
+        missing = required - columns_lower
+        if missing:
+            raise ValueError(f"Missing required OHLCV columns: {missing}")
+        data.columns = [c.lower() for c in data.columns]
+        return data
+
+    def run(self) -> pd.DataFrame:
+        """Execute the backtest and return a results DataFrame."""
+        signals = self.strategy.generate_signals(self.data)
+        results = self._simulate(signals)
+        self.results = results
+        self.metrics = compute_metrics(results, self.initial_capital)
+        return results
+
+    def _simulate(self, signals: pd.Series) -> pd.DataFrame:
+        """Simulate trades based on signals (+1 buy, -1 sell, 0 hold)."""
+        prices = self.data["close"].values
+        n = len(prices)
+
+        positions = np.zeros(n)
+        cash = np.full(n, self.initial_capital, dtype=float)
+        holdings = np.zeros(n)
+        portfolio = np.zeros(n)
+        trades = np.zeros(n)
+
+        sig = signals.values if hasattr(signals, "values") else np.asarray(signals)
+
+        position = 0.0
+        current_cash = self.initial_capital
+
+        for i in range(n):
+            price = prices[i]
+            signal = sig[i] if i < len(sig) else 0
+
+            if signal == 1 and position == 0:
+                shares = int(current_cash * 0.95 / price)
+                cost = shares * price * (1 + self.commission)
+                if cost <= current_cash and shares > 0:
+                    position = shares
+                    current_cash -= cost
+                    trades[i] = 1
+            elif signal == -1 and position > 0:
+                proceeds = position * price * (1 - self.commission)
+                current_cash += proceeds
+                trades[i] = -1
+                position = 0
+
+            positions[i] = position
+            cash[i] = current_cash
+            holdings[i] = position * price
+            portfolio[i] = current_cash + position * price
+
+        results = pd.DataFrame(
+            {
+                "close": prices,
+                "signal": sig[:n] if len(sig) >= n else np.pad(sig, (0, n - len(sig))),
+                "position": positions,
+                "cash": cash,
+                "holdings": holdings,
+                "portfolio": portfolio,
+                "trades": trades,
+            },
+            index=self.data.index,
+        )
+        return results
+
+    def get_metrics(self) -> dict:
+        """Return performance metrics. Runs backtest first if needed."""
+        if self.metrics is None:
+            self.run()
+        return self.metrics
+
+    def export_csv(self, path: Union[str, Path] = "backtest_results.csv") -> Path:
+        """Export results to CSV."""
+        if self.results is None:
+            self.run()
+        path = Path(path)
+        self.results.to_csv(path)
+        return path
+
+    def summary(self) -> str:
+        """Return a formatted summary of backtest metrics."""
+        m = self.get_metrics()
+        lines = [
+            f"Strategy: {self.strategy.name}",
+            f"Initial Capital: ${self.initial_capital:,.2f}",
+            f"Final Value: ${m['final_value']:,.2f}",
+            f"Total Return: {m['total_return']:.2%}",
+            f"CAGR: {m['cagr']:.2%}",
+            f"Sharpe Ratio: {m['sharpe_ratio']:.4f}",
+            f"Max Drawdown: {m['max_drawdown']:.2%}",
+            f"Win Rate: {m['win_rate']:.2%}",
+            f"Total Trades: {m['total_trades']}",
+        ]
+        return "\n".join(lines)

quantcore/metrics.py

@@ -0,0 +1,75 @@
+"""Performance metrics for backtest results."""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+
+def compute_metrics(results: pd.DataFrame, initial_capital: float = 100_000) -> dict:
+    """Compute standard performance metrics from backtest results.
+
+    Parameters
+    ----------
+    results : pd.DataFrame
+        Backtest results with at least ``portfolio`` and ``trades`` columns.
+    initial_capital : float
+        The starting portfolio value.
+
+    Returns
+    -------
+    dict
+        Dictionary with sharpe_ratio, max_drawdown, cagr, win_rate, and more.
+    """
+    portfolio = results["portfolio"].values
+    final_value = portfolio[-1]
+    total_return = (final_value - initial_capital) / initial_capital
+
+    # Daily returns
+    daily_returns = np.diff(portfolio) / portfolio[:-1]
+    daily_returns = daily_returns[np.isfinite(daily_returns)]
+
+    # Sharpe ratio (annualized, assuming 252 trading days)
+    if len(daily_returns) > 1 and np.std(daily_returns) > 0:
+        sharpe_ratio = (np.mean(daily_returns) / np.std(daily_returns)) * np.sqrt(252)
+    else:
+        sharpe_ratio = 0.0
+
+    # Max drawdown
+    cumulative_max = np.maximum.accumulate(portfolio)
+    drawdowns = (portfolio - cumulative_max) / cumulative_max
+    max_drawdown = float(np.min(drawdowns))
+
+    # CAGR
+    n_days = len(portfolio)
+    n_years = n_days / 252 if n_days > 0 else 1
+    if initial_capital > 0 and final_value > 0 and n_years > 0:
+        cagr = (final_value / initial_capital) ** (1 / n_years) - 1
+    else:
+        cagr = 0.0
+
+    # Win rate
+    trades = results["trades"].values
+    buy_indices = np.where(trades == 1)[0]
+    sell_indices = np.where(trades == -1)[0]
+    n_trades = min(len(buy_indices), len(sell_indices))
+    wins = 0
+    for i in range(n_trades):
+        buy_price = results["close"].iloc[buy_indices[i]]
+        sell_price = results["close"].iloc[sell_indices[i]]
+        if sell_price > buy_price:
+            wins += 1
+    win_rate = wins / n_trades if n_trades > 0 else 0.0
+
+    return {
+        "initial_capital": initial_capital,
+        "final_value": final_value,
+        "total_return": total_return,
+        "sharpe_ratio": sharpe_ratio,
+        "max_drawdown": max_drawdown,
+        "cagr": cagr,
+        "win_rate": win_rate,
+        "total_trades": n_trades,
+        "winning_trades": wins,
+        "losing_trades": n_trades - wins,
+    }

quantcore/pro/__init__.py

@@ -0,0 +1,6 @@
+"""QuantCore Pro — premium features gated behind Polar.sh license validation."""
+
+from quantcore.pro.license import require_pro
+from quantcore.pro.strategies import PRO_STRATEGIES
+
+__all__ = ["require_pro", "PRO_STRATEGIES"]

quantcore/pro/license.py

@@ -0,0 +1,67 @@
+"""Polar.sh license validation for QuantCore Pro features."""
+
+from __future__ import annotations
+
+import json
+import os
+import uuid
+from functools import lru_cache
+from typing import Optional
+from urllib import request, error as urllib_error
+
+POLAR_VALIDATE_URL = "https://api.polar.sh/v1/licenses/validate"
+POLAR_ORG_ID = "1f3ada33-0e12-48b8-8efe-79e00d29e5e0"
+PRO_UNLOCK_MESSAGE = "\U0001f512 Pro feature \u2014 unlock at https://buy.polar.sh/polar_cl_rA97pLblKd1pRhwXezgssGgCp1NaKlDV0CeG74fP4q4"
+
+
+@lru_cache(maxsize=1)
+def validate_license(license_key: Optional[str] = None) -> bool:
+    """Validate a Polar.sh license key.
+
+    Checks the ``QUANTCORE_LICENSE_KEY`` environment variable if no key is
+    provided directly.
+
+    Returns
+    -------
+    bool
+        True if the license is valid, False otherwise.
+    """
+    key = license_key or os.environ.get("QUANTCORE_LICENSE_KEY", "")
+    if not key:
+        return False
+
+    machine_id = str(uuid.getnode())
+    payload = json.dumps({
+        "key": key,
+        "organization_id": POLAR_ORG_ID,
+        "benefit_id": "quantcore-pro",
+        "machine_id": machine_id,
+    }).encode("utf-8")
+
+    req = request.Request(
+        POLAR_VALIDATE_URL,
+        data=payload,
+        headers={"Content-Type": "application/json"},
+        method="POST",
+    )
+
+    try:
+        with request.urlopen(req, timeout=10) as resp:
+            data = json.loads(resp.read().decode("utf-8"))
+            return data.get("valid", False)
+    except (urllib_error.URLError, json.JSONDecodeError, OSError):
+        return False
+
+
+def require_pro(license_key: Optional[str] = None) -> bool:
+    """Check for a valid Pro license. Prints unlock message if invalid.
+
+    Returns
+    -------
+    bool
+        True if licensed, False otherwise.
+    """
+    if validate_license(license_key):
+        return True
+    print(PRO_UNLOCK_MESSAGE)
+    return False

quantcore/pro/monte_carlo.py

@@ -0,0 +1,67 @@
+"""Monte Carlo simulation for backtest results."""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+
+def monte_carlo_simulation(
+    results: pd.DataFrame,
+    n_simulations: int = 1000,
+    initial_capital: float = 100_000,
+) -> dict:
+    """Run Monte Carlo simulation by resampling daily returns.
+
+    Parameters
+    ----------
+    results : pd.DataFrame
+        Backtest results with a ``portfolio`` column.
+    n_simulations : int
+        Number of simulation runs (default 1000).
+    initial_capital : float
+        Starting portfolio value.
+
+    Returns
+    -------
+    dict
+        Contains ``simulations`` (array), ``confidence_intervals``, and summary stats.
+    """
+    portfolio = results["portfolio"].values
+    daily_returns = np.diff(portfolio) / portfolio[:-1]
+    daily_returns = daily_returns[np.isfinite(daily_returns)]
+    n_days = len(daily_returns)
+
+    if n_days == 0:
+        return {
+            "simulations": np.full((n_simulations, 1), initial_capital),
+            "confidence_intervals": {},
+            "median_final": initial_capital,
+            "mean_final": initial_capital,
+        }
+
+    simulations = np.zeros((n_simulations, n_days + 1))
+    simulations[:, 0] = initial_capital
+
+    for i in range(n_simulations):
+        sampled = np.random.choice(daily_returns, size=n_days, replace=True)
+        simulations[i, 1:] = initial_capital * np.cumprod(1 + sampled)
+
+    final_values = simulations[:, -1]
+
+    ci = {
+        "5%": float(np.percentile(final_values, 5)),
+        "25%": float(np.percentile(final_values, 25)),
+        "50%": float(np.percentile(final_values, 50)),
+        "75%": float(np.percentile(final_values, 75)),
+        "95%": float(np.percentile(final_values, 95)),
+    }
+
+    return {
+        "simulations": simulations,
+        "confidence_intervals": ci,
+        "median_final": float(np.median(final_values)),
+        "mean_final": float(np.mean(final_values)),
+        "std_final": float(np.std(final_values)),
+        "n_simulations": n_simulations,
+    }

quantcore/pro/optimizer.py

@@ -0,0 +1,66 @@
+"""Parameter grid search optimizer for strategy tuning."""
+
+from __future__ import annotations
+
+import itertools
+from typing import Any
+
+import pandas as pd
+
+from quantcore.engine import Backtest
+from quantcore.metrics import compute_metrics
+
+
+def grid_search(
+    data: pd.DataFrame,
+    strategy_class,
+    param_grid: dict[str, list],
+    initial_capital: float = 100_000,
+    metric: str = "sharpe_ratio",
+) -> list[dict[str, Any]]:
+    """Run a grid search over strategy parameters and rank by a metric.
+
+    Parameters
+    ----------
+    data : pd.DataFrame
+        OHLCV data for backtesting.
+    strategy_class : type
+        Strategy class to instantiate with each parameter combination.
+    param_grid : dict
+        Mapping of parameter names to lists of values to try.
+    initial_capital : float
+        Starting portfolio value.
+    metric : str
+        Metric to optimize (default ``sharpe_ratio``).
+
+    Returns
+    -------
+    list[dict]
+        Sorted list of results, best first. Each dict contains ``params``,
+        ``metrics``, and the target ``score``.
+    """
+    keys = list(param_grid.keys())
+    values = list(param_grid.values())
+    results = []
+
+    for combo in itertools.product(*values):
+        params = dict(zip(keys, combo))
+        try:
+            strategy = strategy_class(**params)
+            bt = Backtest(data.copy(), strategy, initial_capital=initial_capital)
+            bt_results = bt.run()
+            m = compute_metrics(bt_results, initial_capital)
+            results.append({
+                "params": params,
+                "metrics": m,
+                "score": m.get(metric, 0),
+            })
+        except Exception:
+            results.append({
+                "params": params,
+                "metrics": {},
+                "score": float("-inf"),
+            })
+
+    results.sort(key=lambda x: x["score"], reverse=True)
+    return results