quantred 2.4.0__py3-none-any.whl

quantred/services/data.py

@@ -0,0 +1,172 @@
+"""Data-client construction and universe resolution (the read-only data path).
+
+The MCP server and research agent must be *structurally* incapable
+of trading, so this builds **only** a :class:`MarketDataClient` over Alpaca's
+historical-data client - never a ``TradingClient`` or broker. That absence is the
+safety model.
+"""
+
+import logging
+from datetime import datetime
+from typing import Any, List, Optional, Tuple
+
+from quantred.marketdata.base import MarketDataProvider
+from quantred.marketdata.client import MarketDataClient
+
+logger = logging.getLogger(__name__)
+
+
+def build_data_client(
+    cache: bool = False,
+    offline: bool = False,
+    cache_dir: Optional[Any] = None,
+    feed: Optional[str] = None,
+) -> MarketDataClient:
+    """Construct the Alpaca-backed historical data client from settings.
+
+    Deliberately constructs no trading client / broker: the
+    process that calls this cannot place orders.
+
+    ``cache``/``offline`` opt into the persistent bar cache
+    (:class:`~quantred.store.bars.CachedMarketData`): ``cache`` wraps the Alpaca
+    provider so repeated requests reuse previously-fetched bars; ``offline``
+    additionally forbids any network call (a request touching an uncached range
+    raises rather than falling through to Alpaca), and implies ``cache`` on its
+    own and needs no credentials. Default behavior (neither flag) is a plain Alpaca
+    provider.
+
+    ``feed`` pins the Alpaca market-data feed; ``None`` (the default) resolves from
+    ``ALPACA_DATA_FEED`` and otherwise leaves the SDK's defaults alone.
+    """
+    from quantred.brokers.alpaca.factory import build_market_data
+    from quantred.settings import data_feed, load_settings
+
+    if offline:
+        from quantred.store.bars import CachedMarketData
+
+        # A cache-only run never reaches the vendor, so it needs no keys: demanding
+        # them hid "these bars are not cached" behind a credentials wall, and a
+        # warmed cache was unusable on a machine without them.
+        return MarketDataClient(CachedMarketData(_NoVendor(), cache_dir=cache_dir, offline=True))
+    settings = load_settings()
+    provider = build_market_data(settings.alpaca_key, settings.alpaca_secret, feed=feed or data_feed())
+    if cache:
+        from quantred.store.bars import CachedMarketData
+
+        provider = CachedMarketData(provider, cache_dir=cache_dir)
+    return MarketDataClient(provider)
+
+
+class _NoVendor(MarketDataProvider):
+    """The upstream of a cache-only client: there is no vendor behind it.
+
+    ``CachedMarketData(offline=True)`` refuses an uncached read before it would ask its
+    upstream, so nothing should reach this; if something does, it fails loudly rather
+    than becoming a network call nobody asked for.
+    """
+
+    def get_bars(self, symbols, timeframe, start, end):
+        raise RuntimeError("--offline: an uncached read reached the vendor")
+
+    async def stream_bars(self, symbols, handler):
+        raise RuntimeError("--offline: live streaming needs a network connection")
+
+    def supports_streaming(self) -> bool:
+        return False
+
+
+def vintage_stamp(data_client, universe: List[str], timeframe: Any, start: Any, end: Any) -> Optional[str]:
+    """The bar cache's data-vintage stamp for this exact fetch, or ``None`` when the
+    client is not cache-backed.
+
+    Part of a run's dedup identity whenever the cache is in play, so a run over bars
+    that have since changed is not answered from the old result. One definition for
+    both surfaces: the CLI folded it and the service did not, so once the MCP server
+    could read the cache (`mcp --offline`) the same run over the two surfaces could never
+    match and journaled twice. Calling it ensures the window is cached (it warms the
+    cache as a side effect), which is why callers compute it once, up front.
+    """
+    from quantred.store.bars import CachedMarketData
+
+    provider = getattr(data_client, "provider", None)
+    if not isinstance(provider, CachedMarketData):
+        return None
+    return provider.vintage_stamp(universe, timeframe, start, end)
+
+
+#: ``(symbols, timeframe, start, end)``: the arguments of one ``get_bars`` call.
+BarRead = Tuple[List[str], Any, datetime, datetime]
+
+
+def resolve_universe(
+    data_client: MarketDataClient,
+    scanner_name: Optional[str],
+    candidates: List[str],
+    as_of: Optional[datetime] = None,
+    *,
+    then_reads: Optional[List[BarRead]] = None,
+) -> List[str]:
+    """Filter ``candidates`` through a scanner, falling back to them if none flag.
+
+    ``then_reads`` lists the reads the caller makes next, written as if the scanner kept
+    every candidate. Offline, when the scan itself cannot run from the cache, the miss
+    covers that read too, so one warm fixes the command rather than one for the scan
+    and a second for the run.
+    """
+    if not scanner_name or scanner_name == "none":
+        return candidates
+
+    from quantred.scanners.symbol_scanner import SymbolScanner
+
+    scanner = SymbolScanner(data_client, scanner_name)
+    if then_reads is not None:
+        scan_tf, scan_start, scan_end = scanner.scan_window(as_of)
+        refuse_uncached_together(
+            data_client,
+            (candidates, scan_tf, scan_start, scan_end),
+            list(then_reads),
+            why=(
+                "The scanner picks the universe from these bars, so which names the run keeps "
+                "is not known yet; the command covers the scan and the run for every candidate."
+            ),
+        )
+    flagged = scanner.scan(candidates, as_of=as_of)
+    universe = [symbol for symbol, _ in flagged]
+    if not universe:
+        logger.warning("Scanner flagged no symbols; falling back to the candidate list")
+        return candidates
+    logger.info("Trading universe from scanner: %s", universe)
+    return universe
+
+
+def refuse_uncached_together(
+    data_client: MarketDataClient, first: BarRead, rest: List[BarRead], *, why: Optional[str] = None
+) -> None:
+    """Offline, when ``first`` cannot be served from the cache, raise one miss for it and ``rest``.
+
+    A command that reads in stages otherwise learns of each stage only after warming
+    the one before, a rerun per stage. Nothing is raised while ``first`` is cached,
+    because whether the later reads happen at all can turn on it — a scan picks the
+    names, a memoized result reads nothing more — and asking for them then would warm
+    data the run may never touch; their own read refuses if it comes to that. ``why``
+    is printed only when ``rest`` widened the miss.
+    """
+    from quantred.marketdata.timeframe import Timeframe
+    from quantred.store.bars import CachedMarketData
+
+    provider = getattr(data_client, "provider", None)
+    if not isinstance(provider, CachedMarketData) or not provider.offline:
+        return
+    if provider.is_cached(*first):
+        return
+
+    def key(timeframe: Any) -> str:
+        return str(Timeframe.parse(timeframe) if isinstance(timeframe, str) else timeframe)
+
+    def adds(read: BarRead) -> bool:
+        symbols, _, start, end = read
+        return bool(set(symbols) - set(first[0])) or start < first[2] or end > first[3]
+
+    # A warm command takes one timeframe, so a read on another is left to its own miss.
+    widened = [r for r in rest if key(r[1]) == key(first[1]) and adds(r) and not provider.is_cached(*r)]
+    provider.refuse_uncached_reads([first, *widened], why=why if widened else None)

quantred/services/dryrun.py

@@ -0,0 +1,206 @@
+"""What a validated contract would try to do, without trying it.
+
+The decision path and the execution path answer different questions, and running them
+together is what forced a $200-300 position ceiling onto a book that wanted far more:
+fills were needed to observe anything, so the caps were shrunk until fills happened, and
+the resulting sample was biased toward low-priced names. The strategy under observation
+was not the strategy that was validated.
+
+A dry run answers the first question alone. It drives the real decision path - the same
+``LiveTrader``, the same guards, the same sizing - against a stated account, with the
+caps exactly as configured, and reports what *would* have happened. There are no fills,
+no slippage and no fees here, because a broker that cannot trade produces none, and
+inventing them would recreate the confusion this separation exists to end.
+
+**Nothing is journaled.** A dry run measures nothing: no fills, no realized P&L, no
+observed costs, no return series. Recording it would spend a family's statistical budget
+on a rehearsal, which is the same reason a screen journals nothing.
+
+**The vocabulary is deliberate.** ``would_submit``, ``would_skip``, ``would_bind`` -
+never *submitted*, *filled* or *blocked*. A report that borrows execution's words will
+be read as execution's evidence, and the one thing this mode must never be mistaken for
+is the small-real session that produces the real thing.
+"""
+
+from typing import Any, Dict, List, Optional, Sequence
+
+from quantred.brokers.dryrun import BANNER, DryRunBroker
+from quantred.execution import decision as decisions
+
+#: Refusal families that mean *a configured cap bound*, as opposed to some other reason
+#: an order did not go. Only these are reported as ``would_bind``: calling a market-hours
+#: skip a "bind" would attribute to the book a limit that the clock imposed.
+_BINDING_CODES = frozenset(
+    {
+        decisions.BOOK_FULL,
+        decisions.GROSS_EXPOSURE,
+        decisions.NET_EXPOSURE,
+        decisions.RISK_BUDGET,
+        # A declared floor is a configured limit refusing an order, which is what this
+        # bucket means. It reads as one only once the live path actually applies it —
+        # before that the floor was printed by the preflight and enforced by nothing.
+        #
+        # Its sibling, a size rounding to zero, deliberately stays a skip: that is share
+        # granularity rather than a limit anybody configured. Both carry a reason code
+        # so either can be counted, which is what makes a book being traded below the
+        # size it was validated at visible as a number.
+        decisions.BELOW_MIN_NOTIONAL,
+    }
+)
+
+
+def resolve_capital(
+    config_capital: Optional[float] = None, explicit: Optional[float] = None
+) -> "tuple[float, str]":
+    """The capital a dry run reports against, or a refusal.
+
+    Config first, then an explicit override, and **no third source**. There is
+    deliberately no fallback to a broker's equity and no default account size: the caps
+    a dry run reports are only meaningful against the capital they bound, so inventing
+    one would answer a question about a book nobody chose - which is the exact failure
+    this mode exists to remove, arriving by a different route.
+    """
+    capital = explicit if explicit is not None else config_capital
+    source = "--capital" if explicit is not None else "from config"
+    if capital is None:
+        raise ValueError(
+            "a dry run needs a stated capital. Promote a config that records one, or "
+            "pass --capital. There is no default: the caps this reports are only "
+            "meaningful against the capital they bound"
+        )
+    if float(capital) <= 0:
+        raise ValueError(f"a dry run needs a positive capital, not {capital}")
+    # Returned with its source, because a reader judging whether the caps are the right
+    # ones needs to know whether the number came from the validated config or was typed
+    # at the prompt. The two are different claims about what is being rehearsed.
+    return float(capital), source
+
+
+def classify(decision: decisions.Decision, refusal_marker: str) -> str:
+    """Which bucket one decision belongs to.
+
+    ``would_submit`` is a decision that reached the broker and was refused *by the dry
+    run itself* - it got all the way to submission, so it is an order that would have
+    been sent. The plan it carries is what would have been sent, and it exists because
+    ``LiveTrader`` builds the plan before submitting for exactly this reason.
+
+    ``would_bind`` is a configured cap refusing it. ``would_skip`` is everything else:
+    no signal, market closed, a position already open. The distinction matters because
+    only the middle one is a statement about the book's shape.
+    """
+    if decision.allowed:
+        # Unreachable through a dry-run broker, which refuses before any decision can
+        # be allowed. Bucketed anyway rather than dropped: a decision that *was* allowed
+        # in a mode that cannot trade is a defect, and losing it would hide one.
+        return "would_submit"
+    if refusal_marker in (decision.reason or ""):
+        return "would_submit"
+    if decision.reason_code in _BINDING_CODES:
+        return "would_bind"
+    return "would_skip"
+
+
+def dry_run_report(
+    decisions_seen: Sequence[decisions.Decision],
+    *,
+    capital: float,
+    capital_source: str,
+    positions_source: str,
+    universe: Sequence[str],
+    unable_to_evaluate: Optional[Sequence[Dict[str, Any]]] = None,
+    as_of: Optional[Any] = None,
+    refusal_marker: str = "this is a dry run",
+) -> Dict[str, Any]:
+    """The decision path as a report. No fills, no costs, no verdict.
+
+    Every bucket is reported even when empty, because "no signal bound a cap" and "the
+    caps were never reached" are different findings and silence would render them alike.
+    """
+    buckets: Dict[str, List[Dict[str, Any]]] = {
+        "would_submit": [],
+        "would_bind": [],
+        "would_skip": [],
+        # A symbol no decision could be made about is not a skip. A skip is an outcome
+        # the strategy reached; this is the absence of one, and folding the two together
+        # would report a universe as fully evaluated when part of it was never asked.
+        "unable_to_evaluate": list(unable_to_evaluate or []),
+    }
+    for decision in decisions_seen:
+        bucket = classify(decision, refusal_marker)
+        row = {
+            "symbol": decision.symbol,
+            "signal": decision.signal,
+            # A `would_submit` row reached the broker and was refused *by this mode*,
+            # which is the mode working. Reporting "broker refused: this is a dry run"
+            # would describe the mechanism as a failure of the one thing that succeeded,
+            # so the outcome is stated and the mechanism stays internal.
+            "reason": "would submit" if bucket == "would_submit" else decision.reason,
+            "reason_code": None if bucket == "would_submit" else decision.reason_code,
+            "guards_consulted": list(decision.guards_consulted),
+        }
+        plan = decision.plan
+        if plan is not None:
+            # What would have been sent, in full. Named `plan` rather than `order`: an
+            # order is a thing a venue has; this is a thing nobody sent.
+            row["plan"] = {
+                "side": plan.side,
+                "qty": plan.qty,
+                "reference_price": plan.reference_price,
+                "stop_loss": plan.stop_loss,
+                "take_profit": plan.take_profit,
+                "cost_estimate": plan.cost_estimate,
+            }
+        buckets[bucket].append(row)
+
+    evaluated = len(decisions_seen)
+    return {
+        "mode": "dry_run",
+        "banner": BANNER,
+        # Stated rather than discovered, and named as such, so no reader takes it for a
+        # balance read off an account.
+        "capital": capital,
+        "capital_source": capital_source,
+        "starting_positions": positions_source,
+        "universe": list(universe),
+        "as_of": as_of,
+        **buckets,
+        "counts": {name: len(rows) for name, rows in buckets.items()},
+        "n_decisions": evaluated,
+        # Reported beside the universe size so a shortfall is visible in the summary and
+        # not only in a section somebody has to scroll to. A symbol that vanished from
+        # the detail is a symbol nobody notices was never asked.
+        "n_evaluated": evaluated,
+        "n_unable_to_evaluate": len(buckets["unable_to_evaluate"]),
+        # Said explicitly rather than left to be inferred from an absent section. A
+        # reader looking for slippage should find out here that this mode cannot produce
+        # it, not conclude the run was clean.
+        "not_covered": (
+            "fills, slippage, broker fees, queueing, and paper/live account effects. "
+            "A dry run submits nothing, so it observes none of them — that is what a "
+            "small-real session is for"
+        ),
+        "journaled": False,
+    }
+
+
+def build_broker(
+    *,
+    capital: float,
+    positions: Optional[List[Any]] = None,
+    positions_source: Optional[str] = None,
+    tradable: Optional[Dict[str, bool]] = None,
+    market_open: bool = True,
+) -> DryRunBroker:
+    """A dry-run broker, with the source of its starting book recorded.
+
+    ``positions_source`` defaults to describing what was actually supplied, so an empty
+    book is never ambiguous between "start flat" and "nobody said".
+    """
+    source = positions_source or ("adopted" if positions else "flat")
+    return DryRunBroker(
+        capital=capital,
+        positions=positions,
+        positions_source=source,
+        tradable=tradable,
+        market_open=market_open,
+    )

quantred/services/glossary.py

@@ -0,0 +1,130 @@
+"""Metric glossary.
+
+Definitions + pitfalls for every metric the analytics layer reports, written for
+an LLM reader so it doesn't over-trust in-sample numbers. Surfaces the two traps
+that matter most: the equity-curve fidelity caveat and the
+multiple-testing correction the Deflated Sharpe applies.
+"""
+
+from typing import Any, Dict, Iterable
+
+from quantred.analytics.performance import FLAG_KEYS, METRIC_KEYS
+
+#: Cross-cutting caveats the agent should keep in mind for *all* metrics.
+GLOBAL_CAVEATS = [
+    "The equity basis depends on the result. A backtest, and each walk-forward fold, is "
+    "marked to market at every bar's close, so a loss inside an open position counts - "
+    "but only as of bar closes; a fall and recovery within one bar is not seen. A "
+    "walk-forward's OOS AGGREGATE across folds is rebuilt from CLOSED-trade P&L resampled "
+    "to daily, so its max_drawdown / ulcer_index / volatility UNDERSTATE risk during long "
+    "holds.",
+    "In-sample metrics from run_optimization are NOT evidence of edge - they are the "
+    "by-product of selecting the best of many configs. Validate with run_walk_forward, "
+    "which scores out-of-sample and applies the Deflated Sharpe.",
+    "Any metric computed on fewer than ~30 trades is low-power (see the low_sample flag). "
+    "A great Sharpe on 4 trades is noise.",
+]
+
+_DEFS: Dict[str, str] = {
+    "total_return": "Final/initial capital - 1, in %. Period-dependent; use cagr to compare windows of different length.",
+    "buy_hold_return": "Average % return of holding the *traded universe* over the window (the baseline to beat). "
+    "Not the benchmark - it does not change when --benchmark does; see benchmark_buy_hold_return.",
+    "benchmark_buy_hold_return": "% return of holding the benchmark over the same steps the strategy was measured on. "
+    "0.0 when no benchmark was supplied.",
+    "sharpe_ratio": "Annualized mean/std of returns (rf=0). The headline ratio. Inflated by short samples and fat tails - read probabilistic_sharpe_ratio alongside it.",
+    "sortino_ratio": "Like Sharpe but only penalizes downside deviation.",
+    "calmar_ratio": "CAGR / max drawdown. Reward per unit of worst peak-to-trough loss.",
+    "max_drawdown": "Largest peak-to-trough equity decline, % (positive), at bar-close marks for a backtest "
+    "or a fold; UNDERSTATED for a walk-forward OOS aggregate, which uses the closed-trade curve.",
+    "total_trades": "Number of closed trades. The sample-size guard; <30 => low_sample.",
+    "win_rate": "% of trades with positive P&L. High win rate can still lose money if losers are large (see payoff_ratio).",
+    "profit_factor": "Gross profit / gross loss. >1 is profitable; inf means no losing trades (often a tiny sample).",
+    "avg_win": "Mean P&L of winning trades ($).",
+    "avg_loss": "Mean P&L of losing trades, magnitude ($).",
+    "largest_win": "Best single trade ($).",
+    "largest_loss": "Worst single trade, magnitude ($).",
+    "cagr": "Compound annual growth rate, %. The cross-window comparison number (annualized).",
+    "annualized_volatility": "Std of returns scaled to a year, %.",
+    "max_drawdown_duration": "Longest run of consecutive periods spent underwater (below a prior peak).",
+    "exposure": "% of the window with at least one open position. A Sharpe earned at 5% exposure != one at 95%.",
+    "probabilistic_sharpe_ratio": "P(true Sharpe > 0) given sample length, skew and kurtosis. Corrects the Sharpe for short, fat-tailed samples. 0..1.",
+    "deflated_sharpe_ratio": "Probabilistic Sharpe against the EXPECTED-BEST Sharpe of n_trials configs. The anti-overfitting metric: the more configs tried, the higher the bar. 0..1; >0.5 is encouraging.",
+    "recovery_factor": "Net profit / max drawdown ($). Absolute-dollar cousin of Calmar.",
+    "ulcer_index": "RMS drawdown depth (%) - penalizes deep AND long drawdowns. Lower is better.",
+    "martin_ratio": "CAGR / ulcer index (Ulcer Performance Index).",
+    "sterling_ratio": "CAGR / average drawdown.",
+    "var_95": "Historical 95% Value-at-Risk of period returns (%, positive loss).",
+    "var_99": "Historical 99% Value-at-Risk (%).",
+    "cvar_95": "Expected shortfall: mean loss in the worst 5% tail (%).",
+    "expectancy": "Mean P&L per trade ($).",
+    "payoff_ratio": "Average win / average loss (magnitudes).",
+    "gain_to_pain_ratio": "Sum of P&L / sum of absolute losses.",
+    "kelly_criterion": "Theoretical optimal capital fraction from win rate and payoff. Usually scaled down in practice.",
+    "sqn": "System Quality Number (Van Tharp): sqrt(n)*mean(pnl)/std(pnl). Expectancy quality adjusted for sample size.",
+    "max_consecutive_wins": "Longest winning streak.",
+    "max_consecutive_losses": "Longest losing streak - drives position-sizing survivability.",
+    "avg_trade_duration": "Mean holding period in hours.",
+    "mae_pct": "Average Max Adverse Excursion: worst drawdown DURING the hold, %. Diagnoses stop placement / entry timing.",
+    "mfe_pct": "Average Max Favorable Excursion: best runup during the hold, %. Diagnoses exit timing.",
+    "alpha": "Per-period OLS intercept of strategy vs benchmark returns (0 if no benchmark supplied).",
+    "beta": "OLS slope vs benchmark - market sensitivity (0 if no benchmark).",
+    "r_squared": "Fraction of strategy variance explained by the benchmark.",
+    "treynor_ratio": "Annualized excess return per unit of beta (needs a benchmark). 0.0 when |beta| is too near "
+    "zero to divide by - check treynor_available before reading it as a real zero.",
+    "information_ratio": "Annualized active return / tracking error vs benchmark.",
+    "skew": "Skewness of returns. Negative => occasional large losses.",
+    "kurtosis": "Excess kurtosis. High => fat tails (more extreme moves than normal).",
+    "downside_deviation": "Annualized std of negative returns only (%).",
+    "tail_ratio": "abs(95th pct) / abs(5th pct) of returns. >1 => right tail dominates.",
+    "omega_ratio": "Probability-weighted gains / losses about a threshold.",
+    "best_period": "Best single-period return (%).",
+    "worst_period": "Worst single-period return (%).",
+    "turnover": "Traded notional / capital - a proxy for fee/slippage drag.",
+}
+
+_FLAG_DEFS: Dict[str, str] = {
+    "benchmark_available": "Whether a benchmark series was supplied; if False, alpha/beta/treynor/information_ratio are 0.",
+    "treynor_available": "Whether beta was far enough from zero for Treynor to mean anything. Fails independently of "
+    "benchmark_available: a benchmark can be present and the ratio still meaningless for a market-neutral book.",
+    "low_sample": "True when total_trades < 30 - treat all ratios with caution.",
+}
+
+_PITFALLS: Dict[str, str] = {
+    "sharpe_ratio": "Most likely to mislead: high in-sample after optimization is expected, not impressive. Compare to deflated_sharpe_ratio and OOS.",
+    "profit_factor": "inf / very high usually means too few losing trades to be meaningful.",
+    "max_drawdown": "Bar-close marks miss intrabar lows; a walk-forward OOS aggregate (closed-trade curve) "
+    "misses open-position losses entirely, so its true drawdown is worse.",
+    "calmar_ratio": "Sensitive to a single drawdown event and to window length.",
+    "deflated_sharpe_ratio": "Requires an honest n_trials. The research agent must accumulate trials across the whole session, or this lies.",
+}
+
+
+def metrics_glossary() -> Dict[str, Any]:
+    """Definition + pitfalls of every reported metric, plus global caveats."""
+    metrics = {}
+    for key in METRIC_KEYS:
+        entry: Dict[str, str] = {"definition": _DEFS.get(key, "(no description)")}
+        if key in _PITFALLS:
+            entry["pitfall"] = _PITFALLS[key]
+        metrics[key] = entry
+    flags = {key: {"definition": _FLAG_DEFS.get(key, "")} for key in FLAG_KEYS}
+    return {"metrics": metrics, "flags": flags, "global_caveats": GLOBAL_CAVEATS}
+
+
+def definitions_for(keys: Iterable[str]) -> Dict[str, str]:
+    """The definition (and pitfall, when there is one) for the named metrics.
+
+    Lets another surface — a tool description, a report footer — quote what a
+    metric means instead of restating it in its own words. Two descriptions of one
+    metric will drift; one definition with two readers cannot. Unknown keys are
+    skipped rather than rendered as "(no description)", which would advertise a
+    typo as a metric.
+    """
+    out: Dict[str, str] = {}
+    for key in keys:
+        definition = _DEFS.get(key) or _FLAG_DEFS.get(key)
+        if not definition:
+            continue
+        pitfall = _PITFALLS.get(key)
+        out[key] = f"{definition} Pitfall: {pitfall}" if pitfall else definition
+    return out