quantred 2.4.0__py3-none-any.whl

quantred/demo/scanners.py

@@ -0,0 +1,104 @@
+"""The example scanner: volume and price-move confirmation.
+
+Flags symbols whose latest bar shows unusually high volume *and* a meaningful price
+move - a simple liquidity/attention filter for building a trading universe. Pure
+pandas/numpy; no TA-Lib.
+
+**A demonstration, not a screen to trade on.** It reaches the engine through the
+``quantred.scanners`` entry-point group in this project's ``pyproject.toml``, which is
+the same mechanism a private pack uses. Yours belongs in your own package -
+``quantred init --example-pack ./my-signals`` copies one you own.
+"""
+
+from typing import Any, ClassVar, Dict
+
+import pandas as pd
+
+from quantred.scanners.base import SCANNER_BUY, SCANNER_HOLD, SCANNER_SELL, ScannerStrategy
+
+
+class DemoVolumeScanner(ScannerStrategy):
+    """Select symbols on a volume spike confirmed by price movement."""
+
+    #: A shipped demonstration, not a screen anyone should trade on. Carried on
+    #: the class so it survives being registered by entry point.
+    DEMO = True
+
+    TIMEFRAME = "1Day"
+
+    PARAM_RANGES: ClassVar[Dict[str, Dict[str, Any]]] = {
+        "min_volume": {
+            "type": "float",
+            "min": 50_000,
+            "max": 1_000_000,
+            "step": 50_000,
+            "default": 500_000,
+            "description": "Minimum bar volume to consider a symbol liquid",
+        },
+        "volume_ma_period": {
+            "type": "int",
+            "min": 5,
+            "max": 50,
+            "step": 5,
+            "default": 10,
+            "description": "Lookback for the volume moving-average baseline",
+        },
+        "volume_threshold": {
+            "type": "float",
+            "min": 1.0,
+            "max": 5.0,
+            "step": 0.25,
+            "default": 1.75,
+            "description": "Volume / volume-MA ratio that flags unusual activity",
+        },
+        "price_change_threshold": {
+            "type": "float",
+            "min": 0.5,
+            "max": 5.0,
+            "step": 0.25,
+            "default": 0.5,
+            "description": "Minimum |intrabar price change| (%) to confirm",
+        },
+    }
+
+    def initialize(self) -> None:  # nothing to set up
+        pass
+
+    def required_data_points(self) -> int:
+        return self.config["volume_ma_period"] + 1
+
+    def process_data(self, data: pd.DataFrame) -> pd.DataFrame:
+        if data.empty:
+            return pd.DataFrame()
+
+        enriched = data.copy()
+        volume_ma = data["volume"].rolling(window=self.config["volume_ma_period"]).mean()
+        enriched["volume_ratio"] = data["volume"] / volume_ma
+        enriched["price_change"] = ((data["close"] - data["open"]) / data["open"] * 100).abs()
+        return enriched
+
+    def generate_signals_df(self, data: pd.DataFrame) -> pd.DataFrame:
+        if data.empty:
+            return pd.DataFrame()
+
+        out = pd.DataFrame(index=data.index)
+        out["signal"] = SCANNER_HOLD
+        out["signal_strength"] = 0.0
+
+        qualifies = (
+            (data["volume_ratio"] > self.config["volume_threshold"])
+            & (data["price_change"] > self.config["price_change_threshold"])
+            & (data["volume"] > self.config["min_volume"])
+        )
+        bullish = qualifies & (data["close"] > data["open"])
+        bearish = qualifies & (data["close"] <= data["open"])
+
+        out.loc[bullish, "signal"] = SCANNER_BUY
+        out.loc[bearish, "signal"] = SCANNER_SELL
+        out.loc[qualifies, "signal_strength"] = (
+            data.loc[qualifies, "volume_ratio"] * data.loc[qualifies, "price_change"]
+        )
+        return out
+
+    def is_hit(self, returns: float, price_change: float) -> bool:
+        return price_change > self.config["price_change_threshold"]

quantred/demo/strategies.py

@@ -0,0 +1,125 @@
+"""The example strategy: a moving-average crossover, the "hello world" of trend following.
+
+**This ships so the demo has something to run and so there is a smallest complete
+strategy to read. It is not an edge, and it is not where your work goes** — that belongs
+in your own package. ``quantred init --example-pack ./my-signals`` copies a complete one
+you own, with two strategies, a scanner and configs already wired up.
+
+It reaches the engine through the ``quantred.strategies`` entry-point group declared in
+this project's ``pyproject.toml`` — the same mechanism your pack will use, so the path
+is exercised by every install rather than only in tests.
+
+Long-only. Its conviction score is the **normalized EMA gap**
+``(fast - slow) / slow``: positive (and rising) when the fast line leads, negative
+when it lags. The base class derives the trade signal from the score's sign, so a
+golden cross (score crossing above 0) becomes a ``BUY`` and a death cross (crossing
+below 0) a ``CLOSE_BUY`` - the discrete behavior is a consequence of the score, not
+a second code path. Deliberately simple and only five parameters, so it's an honest
+baseline - and a clean example of how little it takes to add a strategy (one file,
+a score, the indicators you already have, register the name).
+"""
+
+from typing import Any, ClassVar, Dict, Tuple
+
+import pandas as pd
+
+from quantred.indicators import indicators
+from quantred.strategies.base import Strategy
+
+
+class DemoTrendStrategy(Strategy):
+    """Long-only EMA trend follower: buy the golden cross, exit the death cross."""
+
+    #: Marks this as a shipped demonstration rather than something to trade. Carried on
+    #: the class rather than inferred from where it was registered, because how a
+    #: strategy was discovered says nothing about what it is for - and after this moved
+    #: to an entry point, registry membership stopped being able to tell.
+    DEMO = True
+
+    #: Bars this strategy is designed to trade.
+    TIMEFRAME = "1Day"
+
+    PARAM_RANGES: ClassVar[Dict[str, Dict[str, Any]]] = {
+        "fast_ema_period": {
+            "type": "int",
+            "min": 5,
+            "max": 20,
+            "step": 1,
+            "default": 10,
+            "description": "Fast EMA period (the responsive line)",
+        },
+        "slow_ema_period": {
+            "type": "int",
+            "min": 21,
+            "max": 60,
+            "step": 1,
+            "default": 30,
+            "description": "Slow EMA period (the trend baseline)",
+        },
+        "risk_per_trade": {
+            "type": "float",
+            "min": 0.01,
+            "max": 0.05,
+            "step": 0.01,
+            "default": 0.02,
+            "description": "Capital fraction risked per trade",
+        },
+        "stop_loss": {
+            "type": "float",
+            "min": 0.01,
+            "max": 0.08,
+            "step": 0.01,
+            "default": 0.03,
+            "description": "Stop-loss distance from entry (fraction)",
+        },
+        "take_profit": {
+            "type": "float",
+            "min": 0.02,
+            "max": 0.15,
+            "step": 0.01,
+            "default": 0.06,
+            "description": "Take-profit distance from entry (fraction)",
+        },
+    }
+
+    #: The fast line has to be faster than the slow one. Declared rather than checked
+    #: in ``initialize`` so a sampler can read it: today's ranges (5-20 against 21-60)
+    #: cannot produce a violation, but narrowed ranges can, and a combination that
+    #: gets evaluated is a journaled trial that raises the deflation bar for every
+    #: future candidate in this family.
+    PARAM_CONSTRAINTS: ClassVar[Tuple[Tuple[str, str, Any], ...]] = (
+        ("fast_ema_period", "<", "slow_ema_period"),
+    )
+
+    def __init__(self, config: Dict[str, Any]):
+        config["timeframe"] = self.TIMEFRAME
+        config.setdefault(
+            "position_limits",
+            {"max_positions": 1, "max_position_size": 100_000.0, "max_total_risk": 0.05},
+        )
+        super().__init__(config)
+
+    def calculate_required_lookback(self) -> int:
+        return self.config["slow_ema_period"] + 1
+
+    def initialize(self) -> None:
+        # The fast/slow ordering is declared in PARAM_CONSTRAINTS and enforced at
+        # construction, so there is nothing left to restate here: a second copy of the
+        # comparison would be the half a sampler cannot read.
+        pass
+
+    def process_data(self, data: pd.DataFrame) -> pd.DataFrame:
+        if data.empty:
+            return pd.DataFrame()
+
+        enriched = data.copy()
+        enriched["fast_ema"] = indicators.calculate_ema(data["close"], self.config["fast_ema_period"])
+        enriched["slow_ema"] = indicators.calculate_ema(data["close"], self.config["slow_ema_period"])
+        return enriched
+
+    def calculate_scores(self, data: pd.DataFrame) -> pd.Series:
+        if data.empty:
+            return pd.Series(dtype=float)
+        # Normalized EMA gap: signed trend strength. Sign crossings are the golden /
+        # death crosses; magnitude is how decisively the fast line leads.
+        return (data["fast_ema"] - data["slow_ema"]) / data["slow_ema"]