quantred 2.4.0__py3-none-any.whl

quantred/risk/sample.py

@@ -0,0 +1,89 @@
+"""Sample-covariance estimators: raw, and Ledoit–Wolf shrinkage.
+
+The raw sample covariance ``S`` over ``N`` names from ``T`` observations needs
+``N(N+1)/2`` parameters; when ``T`` is not far greater than ``N`` it is noisy and
+often **non-invertible** - fatal, because the optimizer needs ``Σ⁻¹``.
+Ledoit–Wolf shrinks ``S`` toward a structured target ``F`` by the analytically
+optimal intensity ``δ``:
+
+    Σ̂ = δ·F + (1 − δ)·S
+
+Here ``F`` is the **constant-correlation** target (every pairwise correlation = the
+average sample correlation, variances kept), which is the right structure for
+equity returns. The closed form is vendored in pure numpy (Ledoit & Wolf, 2004,
+"Honey, I Shrunk the Sample Covariance Matrix") so the risk module needs no
+compiled or sklearn dependency.
+"""
+
+from typing import Optional, Tuple
+
+import numpy as np
+import pandas as pd
+
+from quantred.risk.base import RiskModel
+
+
+class SampleCovariance(RiskModel):
+    """The raw sample covariance. Honest, but ill-conditioned when ``T ≲ N``."""
+
+    def estimate(self, returns: pd.DataFrame) -> Tuple[np.ndarray, Optional[float]]:
+        x = returns.to_numpy(dtype=float)
+        x = x - x.mean(axis=0)
+        t = x.shape[0]
+        if t < 2:
+            n = x.shape[1]
+            return np.zeros((n, n)), None
+        return (x.T @ x) / t, None
+
+
+class LedoitWolfCovariance(RiskModel):
+    """Ledoit–Wolf shrinkage toward a constant-correlation target (well-conditioned)."""
+
+    def estimate(self, returns: pd.DataFrame) -> Tuple[np.ndarray, float]:
+        x = returns.to_numpy(dtype=float)
+        x = x - x.mean(axis=0)
+        t, n = x.shape
+        if t < 2 or n == 0:
+            return np.zeros((n, n)), 0.0
+
+        sample = (x.T @ x) / t  # MLE sample covariance
+        var = np.diag(sample)
+        std = np.sqrt(var)
+        if n == 1 or np.any(std == 0):
+            # No correlation structure to shrink (or a dead name); S is the answer.
+            return sample, 0.0
+
+        # Constant-correlation target F: average off-diagonal correlation, variances kept.
+        outer_std = np.outer(std, std)
+        corr = sample / outer_std
+        r_bar = (corr.sum() - n) / (n * (n - 1))
+        target = r_bar * outer_std
+        np.fill_diagonal(target, var)
+
+        # π̂ — sum of asymptotic variances of the sample-covariance entries.
+        x2 = x**2
+        pi_mat = (x2.T @ x2) / t - sample**2
+        pi_hat = pi_mat.sum()
+
+        # ρ̂ — asymptotic covariances; diagonal terms plus the constant-correlation
+        # off-diagonal adjustment (the θ terms).
+        rho_diag = np.trace(pi_mat)
+        cubed = (x**3).T @ x / t  # A[i,j] = E[x_i^3 x_j]
+        theta_ii = cubed - var[:, None] * sample  # θ_{ii,ij}
+        theta_jj = cubed.T - var[None, :] * sample  # θ_{jj,ij}
+        ratio = np.outer(std, 1.0 / std)  # ratio[i,j] = std_i / std_j
+        off = (r_bar / 2.0) * (ratio.T * theta_ii + ratio * theta_jj)
+        np.fill_diagonal(off, 0.0)
+        rho_hat = rho_diag + off.sum()
+
+        # γ̂ — misfit of the target to the sample covariance.
+        gamma_hat = float(((target - sample) ** 2).sum())
+
+        if gamma_hat == 0:
+            delta = 0.0
+        else:
+            kappa = (pi_hat - rho_hat) / gamma_hat
+            delta = max(0.0, min(1.0, kappa / t))
+
+        sigma = delta * target + (1.0 - delta) * sample
+        return sigma, float(delta)

quantred/risk/streaming.py

@@ -0,0 +1,214 @@
+"""Out-of-core risk estimation — stream the return panel instead of materializing it.
+
+:func:`quantred.risk.base.build_risk_matrix` (and the factor model that shares its
+:func:`build_return_panel`) is the only genuinely **panel-wide** (``T×N``) pandas
+materialization in the stack: it builds an aligned returns DataFrame for the whole
+history and hands it to an estimator. For a broad universe over many years that ``T×N``
+panel is the thing that does not fit in RAM.
+
+This module is the out-of-core counterpart: it estimates the *same*
+quantities by **streaming** the return panel out of a
+:class:`~quantred.data.store.ParquetBarStore` in date-chunks and accumulating sufficient
+statistics. It never holds the ``T×N`` panel: peak working memory is one chunk
+(``chunk_obs × N``) plus the small accumulators (``N×N`` / ``K×K`` / ``N``) plus a 1-D
+``O(T)`` index of complete-case timestamps — so on a long, wide history it peaks well
+below the eager path (the dominant ``T×N`` matrix is never materialized), growing in
+``T`` only as a thin timestamp vector.
+
+Two estimators, both reproducing their eager oracle to machine epsilon for the
+well-sampled names:
+
+- :func:`streaming_sample_covariance` ↔ :func:`build_risk_matrix` with
+  :class:`~quantred.risk.sample.SampleCovariance`.
+- :func:`streaming_factor_risk_matrix` ↔ :func:`quantred.risk.factor.estimate_factor_model`
+  (the structural ``Σ = X F Xᵀ + Δ``). Exposures stay a small ``N×K`` leaf computed by
+  :func:`quantred.risk.exposures.build_factor_exposures`.
+
+Ledoit–Wolf shrinkage needs higher moments and stays on the eager path for now — noted,
+not faked. Requires the ``store`` extra (``polars``).
+"""
+
+from datetime import datetime
+from typing import TYPE_CHECKING, Callable, Iterable, List, Optional, Tuple
+
+import numpy as np
+import pandas as pd
+
+from quantred.marketdata.client import TimeframeLike
+from quantred.risk.base import RiskMatrix
+from quantred.risk.factor import FactorRiskMatrix
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from quantred.data.store import ParquetBarStore
+
+
+def _kept_and_blocks(
+    store: "ParquetBarStore",
+    universe: List[str],
+    timeframe: TimeframeLike,
+    as_of: datetime,
+    lookback_days: int,
+    min_obs: int,
+    chunk_obs: int,
+) -> Optional[Tuple[List[str], Callable[[], Iterable[np.ndarray]]]]:
+    """The shared streaming spine: the complete-case return panel, never materialized.
+
+    Reproduces :func:`build_return_panel` exactly: keep names with ≥ ``min_obs`` finite
+    returns (in ``universe`` order), take the timestamps where **every** kept name has a
+    finite return (the lazy analogue of ``returns[kept].dropna()``), and return a factory
+    that streams that complete-case panel in ``chunk_obs``-row blocks (columns in ``kept``
+    order). Returns ``(kept, blocks)`` or ``None`` if fewer than two complete-case rows.
+    """
+    import polars as pl
+
+    from quantred.data import compute
+
+    lf = compute.with_returns(store.scan_lazy(universe, timeframe, as_of, lookback_days), src="close")
+    # Present == finite return: mirror pandas' notna/dropna (null and NaN are missing).
+    nn = lf.filter(pl.col("ret").is_not_null() & pl.col("ret").is_not_nan())
+
+    counts = nn.group_by("symbol").agg(pl.len().alias("n")).collect(engine="streaming")
+    count_map = dict(zip(counts["symbol"].to_list(), counts["n"].to_list()))
+    kept: List[str] = []
+    seen = set()
+    for sym in universe:
+        if sym in seen:
+            continue
+        seen.add(sym)
+        if count_map.get(sym, 0) >= min_obs:
+            kept.append(sym)
+    if not kept:
+        return None
+
+    k = len(kept)
+    complete = (
+        nn.filter(pl.col("symbol").is_in(kept))
+        .group_by("ts")
+        .agg(pl.len().alias("c"))
+        .filter(pl.col("c") == k)
+        .select("ts")
+        .collect(engine="streaming")
+        .sort("ts")["ts"]
+        .to_list()
+    )
+    if len(complete) < 2:
+        return None
+
+    def blocks() -> Iterable[np.ndarray]:
+        for i in range(0, len(complete), chunk_obs):
+            ts_chunk = complete[i : i + chunk_obs]
+            block = (
+                nn.filter(pl.col("symbol").is_in(kept) & pl.col("ts").is_in(ts_chunk))
+                .select(["ts", "symbol", "ret"])
+                .collect(engine="streaming")
+                .pivot(values="ret", index="ts", on="symbol")
+                .sort("ts")
+            )
+            yield block.select(kept).to_numpy()  # rows × N, columns in kept order
+
+    return kept, blocks
+
+
+def streaming_sample_covariance(
+    store: "ParquetBarStore",
+    universe: List[str],
+    timeframe: TimeframeLike,
+    as_of: datetime,
+    *,
+    lookback_days: int = 365,
+    periods_per_year: float = 252.0,
+    min_obs: int = 60,
+    chunk_obs: int = 1024,
+) -> Optional[RiskMatrix]:
+    """Annualized sample :class:`RiskMatrix` by streaming the return panel.
+
+    Mirrors :func:`build_risk_matrix` with :class:`~quantred.risk.sample.SampleCovariance`
+    (population covariance), accumulating cross-products chunk-by-chunk via
+    :func:`quantred.data.compute.streaming_covariance`. Returns ``None`` when no name clears
+    ``min_obs`` or fewer than two complete-case rows exist; ``shrinkage`` is ``None``.
+    Kept names are returned in ``universe`` order.
+    """
+    from quantred.data import compute
+
+    prepared = _kept_and_blocks(store, universe, timeframe, as_of, lookback_days, min_obs, chunk_obs)
+    if prepared is None:
+        return None
+    kept, blocks = prepared
+
+    sigma_bar, n_obs = compute.streaming_covariance(blocks())
+    if n_obs < 2:
+        return None
+    return RiskMatrix(symbols=kept, sigma=sigma_bar * periods_per_year, shrinkage=None)
+
+
+def streaming_factor_risk_matrix(
+    store: "ParquetBarStore",
+    universe: List[str],
+    timeframe: TimeframeLike,
+    as_of: datetime,
+    exposures: pd.DataFrame,
+    *,
+    lookback_days: int = 365,
+    periods_per_year: float = 252.0,
+    min_obs: int = 60,
+    chunk_obs: int = 1024,
+) -> Optional[FactorRiskMatrix]:
+    """Structural factor :class:`FactorRiskMatrix` ``Σ = X F Xᵀ + Δ`` by streaming returns.
+
+    Mirrors :func:`quantred.risk.factor.estimate_factor_model`: factor returns are recovered
+    per period by the cross-sectional OLS ``f_t = (XᵀX)⁻¹Xᵀ r_t``, ``F`` is their
+    covariance (``ddof=1``, as ``np.cov``) and ``Δ`` the per-name residual variance
+    (``ddof=1``) — both annualized. The ``N×K`` ``exposures`` (a small cross-sectional
+    leaf from :func:`quantred.risk.build_factor_exposures`) stay pandas; only the panel-wide
+    ``T×N`` returns are streamed. Each chunk is projected to factor returns and residuals
+    and folded into ``K×K`` / ``N`` accumulators, so the ``T×N`` panel is never held.
+
+    Names are the well-sampled set ∩ ``exposures.index`` (the eager path's selection),
+    in ``universe`` order. Returns ``None`` if fewer than two names/periods survive.
+    """
+    prepared = _kept_and_blocks(store, universe, timeframe, as_of, lookback_days, min_obs, chunk_obs)
+    if prepared is None:
+        return None
+    kept, blocks = prepared
+
+    names = [s for s in kept if s in exposures.index]
+    if len(names) < 2:
+        return None
+    col = [kept.index(s) for s in names]  # pick the `names` columns out of each kept-ordered block
+    x = exposures.loc[names].to_numpy(dtype=float)  # N×K
+    proj = x @ np.linalg.pinv(x.T @ x)  # N×K; factor returns of a chunk R are R @ proj
+
+    n_obs = 0
+    k = x.shape[1]
+    sf = np.zeros(k)  # Σ f_t
+    sff = np.zeros((k, k))  # Σ f_t f_tᵀ
+    sr = np.zeros(len(names))  # Σ residual_t (per name)
+    srr = np.zeros(len(names))  # Σ residual_t² (per name)
+    for block in blocks():
+        r = block[:, col]  # rows × N (names columns)
+        f = r @ proj  # rows × K factor returns
+        resid = r - f @ x.T  # rows × N residuals
+        sf += f.sum(axis=0)
+        sff += f.T @ f
+        sr += resid.sum(axis=0)
+        srr += (resid * resid).sum(axis=0)
+        n_obs += r.shape[0]
+
+    if n_obs < 2:
+        return None
+    # ddof=1 sample stats from the streamed sums, to match np.cov / Series.var(ddof=1).
+    mean_f = sf / n_obs
+    factor_cov = (sff / n_obs - np.outer(mean_f, mean_f)) * (n_obs / (n_obs - 1)) * periods_per_year
+    factor_cov = np.atleast_2d(factor_cov)
+    specific_var = (srr - sr * sr / n_obs) / (n_obs - 1) * periods_per_year
+    sigma = x @ factor_cov @ x.T + np.diag(specific_var)
+
+    return FactorRiskMatrix(
+        symbols=names,
+        sigma=sigma,
+        shrinkage=None,
+        exposures=exposures.loc[names],
+        factor_cov=factor_cov,
+        specific_var=specific_var,
+        factor_names=list(exposures.columns),
+    )

quantred/scanners/base.py

@@ -0,0 +1,141 @@
+"""Base class for universe scanners - the bouncers deciding which symbols are even
+worth a strategy's attention today.
+
+A scanner answers a different question than a strategy: *which symbols are worth
+trading right now?* It scores each symbol's recent bars and emits a per-symbol
+scan signal (``SCANNER_BUY`` / ``SCANNER_SELL`` / ``SCANNER_HOLD``).
+
+Scanners operate on a single symbol's OHLCV frame at a time (the
+:class:`~quantred.scanners.symbol_scanner.SymbolScanner` iterates the universe), which
+keeps the interface simple and avoids MultiIndex bookkeeping.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List
+
+import pandas as pd
+
+from quantred.analytics import metrics
+
+# Scan-signal vocabulary (distinct from trade signals so the two never mix).
+SCANNER_BUY = "SCANNER_BUY"
+SCANNER_SELL = "SCANNER_SELL"
+SCANNER_HOLD = "SCANNER_HOLD"
+
+_ACTIONABLE = frozenset({SCANNER_BUY, SCANNER_SELL})
+
+
+class ScannerStrategy(ABC):
+    """Abstract base for scanner strategies."""
+
+    SCANNER_BUY = SCANNER_BUY
+    SCANNER_SELL = SCANNER_SELL
+
+    #: Tunable parameters (with min/max/step) for the optimizer.
+    PARAM_RANGES: Dict[str, Dict[str, Any]] = {}
+
+    def __init__(self, config: Dict[str, Any]):
+        self.config = self._validate_config(config)
+
+    # ------------------------------------------------------------------ #
+    # Abstract hooks
+    # ------------------------------------------------------------------ #
+    @abstractmethod
+    def initialize(self) -> None:
+        """Optional setup before scanning."""
+
+    @abstractmethod
+    def process_data(self, data: pd.DataFrame) -> pd.DataFrame:
+        """Return one symbol's OHLCV frame enriched with scan indicators."""
+
+    @abstractmethod
+    def generate_signals_df(self, data: pd.DataFrame) -> pd.DataFrame:
+        """Return a frame aligned to ``data.index`` with a ``signal`` column.
+
+        Should also include a numeric ``signal_strength`` column for ranking.
+        """
+
+    # ------------------------------------------------------------------ #
+    # Shared behavior
+    # ------------------------------------------------------------------ #
+    def latest_signal(self, signals_df: pd.DataFrame) -> str:
+        """The most recent scan signal, or ``SCANNER_HOLD`` if none/empty."""
+        if signals_df.empty or "signal" not in signals_df:
+            return SCANNER_HOLD
+        signal = signals_df["signal"].iloc[-1]
+        return signal if signal in _ACTIONABLE else SCANNER_HOLD
+
+    def required_data_points(self) -> int:
+        """Bars needed for a valid scan (lookback + current bar)."""
+        return self.config.get("lookback_periods", 20) + 1
+
+    def is_hit(self, returns: float, price_change: float) -> bool:
+        """Whether a forward outcome counts as a successful signal (override per scanner)."""
+        return returns > 0
+
+    def evaluate_forward(
+        self, signals_df: pd.DataFrame, forward: pd.DataFrame, hold_bars: int
+    ) -> Dict[str, float]:
+        """Score a symbol's signals against subsequent price action.
+
+        Used by the optimizer to tune scanner parameters. Returns hit rate,
+        average return, Sharpe and profit factor over the realized signals.
+        """
+        empty = {
+            "hit_rate": 0.0,
+            "avg_return": 0.0,
+            "total_signals": 0,
+            "sharpe_ratio": 0.0,
+            "profit_factor": 0.0,
+        }
+        if signals_df.empty or forward.empty:
+            return empty
+
+        closes = forward["close"]
+        trade_returns: List[float] = []
+        hits = 0
+
+        for timestamp, row in signals_df.iterrows():
+            if row["signal"] not in _ACTIONABLE:
+                continue
+            future = closes[closes.index > timestamp].head(hold_bars)
+            if future.empty or timestamp not in closes.index:
+                continue
+
+            entry = closes.loc[timestamp]
+            exit_price = future.iloc[-1]
+            ret = (exit_price / entry - 1) * 100
+            if row["signal"] == SCANNER_SELL:
+                ret = -ret
+            trade_returns.append(ret)
+            if self.is_hit(ret, abs(ret)):
+                hits += 1
+
+        if not trade_returns:
+            return empty
+
+        series = pd.Series(trade_returns)
+        return {
+            "hit_rate": hits / len(trade_returns) * 100,
+            "avg_return": float(series.mean()),
+            "total_signals": len(trade_returns),
+            "sharpe_ratio": metrics.sharpe_ratio(series),
+            "profit_factor": metrics.profit_factor(series),
+        }
+
+    def _validate_config(self, config: Dict[str, Any]) -> Dict[str, Any]:
+        """Fill defaults and range-check values against ``PARAM_RANGES``."""
+        validated = dict(config)
+        for param, spec in self.PARAM_RANGES.items():
+            if param not in validated:
+                validated[param] = spec["default"]
+                continue
+            value = validated[param]
+            if spec["type"] in ("int", "float"):
+                value = int(value) if spec["type"] == "int" else float(value)
+                if not (spec["min"] <= value <= spec["max"]):
+                    raise ValueError(
+                        f"Scanner parameter '{param}' value {value} outside [{spec['min']}, {spec['max']}]"
+                    )
+                validated[param] = value
+        return validated

quantred/scanners/symbol_scanner.py

@@ -0,0 +1,148 @@
+"""Universe scanner.
+
+Runs a chosen :class:`ScannerStrategy` across a candidate symbol list and returns
+those flagged at a specific research clock - the universe the trading
+strategy/engine then operates on. Only TA-Lib-free scanners are registered, in
+keeping with the no-compiled-deps goal.
+"""
+
+import logging
+from datetime import datetime
+from typing import Dict, List, Optional, Tuple, Type
+
+from quantred.data.scan import slice_to_as_of
+from quantred.marketdata.client import MarketDataClient
+from quantred.marketdata.timeframe import Timeframe
+from quantred.scanners.base import ScannerStrategy
+from quantred.utils.timeutils import NEW_YORK, shift_days
+
+logger = logging.getLogger(__name__)
+
+# Extra calendar days fetched per required bar, to absorb weekends/holidays.
+_LOOKBACK_DAY_BUFFER = 3
+
+
+#: Scanner names this package reserves for classes it defines *in this module*.
+#: Empty, and deliberately so: the example scanner moved to ``quantred.demo`` and
+#: arrives by entry point like any other pack's, so the engine discovers its own
+#: demonstration the way it discovers yours. Adding a public scanner means shipping
+#: it from ``quantred.demo`` with an entry point in ``pyproject.toml``, not
+#: extending this literal - see ``docs/content/engineering/extending.md``.
+#:
+#: Kept as a distinct name from :attr:`SymbolScanner.SCANNERS`, which discovery
+#: overwrites with the reserved set *plus* whatever installed packages contribute:
+#: deriving the reserved set from that live attribute meant a module reload absorbed
+#: third-party scanners into it, and the names an extension may not override then
+#: silently included names that came from an extension.
+BUILTIN_SCANNERS: Dict[str, Type[ScannerStrategy]] = {}
+
+
+def resolve_scan_clock(as_of: Optional[datetime] = None) -> datetime:
+    """The exchange-zone instant a scan is resolved at, from an optional request.
+
+    One rule, so the clock a scan *runs* at and the clock it *reports* cannot differ.
+    The payload used to echo the caller's own argument, so a naive ``2024-06-01`` was
+    reported as a bare date while the scan actually ran at ``2024-06-01`` New York,
+    and an omitted ``as_of`` was reported as nothing at all rather than as the
+    wall-clock now it resolved to. A selection clock reported differently from the one
+    applied is worse than no clock, because it reads as provenance.
+    """
+    end = as_of or datetime.now(NEW_YORK)
+    if end.tzinfo is None:
+        return NEW_YORK.localize(end)
+    return end.astimezone(NEW_YORK)
+
+
+class SymbolScanner:
+    """Filters a candidate universe down to scanner-signaled symbols."""
+
+    #: Scanners resolvable by name, kept in step with
+    #: :data:`quantred.services.registry.SCANNERS` by ``refresh_registries()``.
+    #:
+    #: Empty until discovery has run, which is why every read goes through
+    #: :meth:`_registry` rather than touching this directly. Nothing is defined in
+    #: this module any more, so the seed that used to make a bare
+    #: ``import symbol_scanner`` usable is gone: without the lazy resolve, importing
+    #: this module alone gave ``available() == []`` and every name raised.
+    SCANNERS: Dict[str, Type[ScannerStrategy]] = dict(BUILTIN_SCANNERS)
+
+    @classmethod
+    def _registry(cls) -> Dict[str, Type[ScannerStrategy]]:
+        """The resolvable scanners, running discovery first if nothing has yet.
+
+        Delegates to the service registry rather than keeping a second answer. The
+        import is deferred because ``registry`` imports *this* module; during that
+        import ``registry.SCANNERS`` is already seeded with the reserved names, so a
+        pack that scans while being discovered sees those rather than nothing.
+
+        This is also the fallback the guard around import-time discovery exists for:
+        if ``refresh_registries()`` raises before its final line, ``registry.SCANNERS``
+        still holds its seed and every scan path keeps working, where a stale empty
+        class attribute would have failed every name the CLI still advertised.
+        """
+        if not cls.SCANNERS:
+            from quantred.services import registry
+
+            cls.SCANNERS = dict(registry.SCANNERS)
+        return cls.SCANNERS
+
+    def __init__(
+        self,
+        data_client: MarketDataClient,
+        # Required. There is no built-in to fall back to - every scanner, the demo
+        # one included, arrives by entry point, so a default here could only name
+        # something that may not be installed and raise one frame further in.
+        strategy_name: str,
+        config: Optional[dict] = None,
+    ):
+        registry = self._registry()
+        if strategy_name not in registry:
+            raise ValueError(f"Unknown scanner '{strategy_name}'. Available: {self.available()}")
+        scanner_cls = registry[strategy_name]
+        defaults = {p: spec["default"] for p, spec in scanner_cls.PARAM_RANGES.items()}
+        defaults.update(config or {})
+
+        self.data_client = data_client
+        self.strategy = scanner_cls(defaults)
+        self.strategy.initialize()
+        self.timeframe: str = getattr(scanner_cls, "TIMEFRAME", "1Day")
+
+    @classmethod
+    def available(cls) -> List[str]:
+        return list(cls._registry())
+
+    def scan(
+        self, symbols: List[str], timeframe: Optional[str] = None, as_of: Optional[datetime] = None
+    ) -> List[Tuple[str, str]]:
+        """Return ``(symbol, scan_signal)`` for every flagged symbol in ``symbols``."""
+        timeframe = timeframe or self.timeframe
+        start, end = self._scan_window(timeframe, as_of=as_of)
+        bars = self.data_client.get_bars(symbols, timeframe, start, end)
+
+        flagged: List[Tuple[str, str]] = []
+        for symbol, frame in bars.items():
+            if frame.empty:
+                continue
+            frame = slice_to_as_of(frame, end)
+            if frame.empty:
+                continue
+            processed = self.strategy.process_data(frame)
+            signal = self.strategy.latest_signal(self.strategy.generate_signals_df(processed))
+            if signal in (self.strategy.SCANNER_BUY, self.strategy.SCANNER_SELL):
+                flagged.append((symbol, signal))
+
+        logger.info("Scanner flagged %d/%d symbols", len(flagged), len(symbols))
+        return flagged
+
+    def scan_window(self, as_of: Optional[datetime] = None) -> Tuple[str, datetime, datetime]:
+        """The ``(timeframe, start, end)`` a default :meth:`scan` at ``as_of`` reads."""
+        start, end = self._scan_window(self.timeframe, as_of=as_of)
+        return self.timeframe, start, end
+
+    def _scan_window(self, timeframe: str, as_of: Optional[datetime] = None) -> Tuple[datetime, datetime]:
+        """A lookback window large enough for the scanner's indicators."""
+        tf = Timeframe.parse(timeframe)
+        required = self.strategy.required_data_points()
+        days = max(required * tf.amount * _LOOKBACK_DAY_BUFFER, 30)
+        end = resolve_scan_clock(as_of)
+        return shift_days(end, -days), end

quantred/services/__init__.py

@@ -0,0 +1,51 @@
+"""Shared service core.
+
+Plain, side-effect-light functions that wrap the existing engine / optimizer /
+walk-forward / analytics layers and return JSON-serializable dicts. This is the
+*one* orchestration code path: the CLI (``main.py``), the MCP server
+(:mod:`quantred.mcp.server`), and the research agent (:mod:`quantred.research`) all call
+these - no business logic lives in any of those adapters.
+
+Nothing here can place an order: service functions take a
+:class:`~quantred.marketdata.client.MarketDataClient` (data only) and never a broker.
+"""
+
+from quantred.services.analysis import (
+    run_backtest,
+    run_draft_walk_forward,
+    run_optimization,
+    run_scan,
+    run_walk_forward,
+    summarize_bars,
+    validate_draft_scanner_code,
+    validate_draft_strategy_code,
+)
+from quantred.services.configs import list_configs, load_config, save_config
+from quantred.services.glossary import metrics_glossary
+from quantred.services.registry import (
+    SCANNERS,
+    STRATEGIES,
+    get_param_ranges,
+    list_scanners,
+    list_strategies,
+)
+
+__all__ = [
+    "STRATEGIES",
+    "SCANNERS",
+    "list_strategies",
+    "list_scanners",
+    "get_param_ranges",
+    "run_scan",
+    "run_backtest",
+    "run_optimization",
+    "run_walk_forward",
+    "validate_draft_strategy_code",
+    "validate_draft_scanner_code",
+    "run_draft_walk_forward",
+    "summarize_bars",
+    "metrics_glossary",
+    "save_config",
+    "load_config",
+    "list_configs",
+]