quantred 2.4.0__py3-none-any.whl

quantred/marketdata/timeframe.py

@@ -0,0 +1,125 @@
+"""Broker-agnostic bar timeframe.
+
+Strategies declare their timeframe as a friendly string (``"5Min"``, ``"1Hour"``,
+``"1Day"``). This module parses that once into a :class:`Timeframe` value object
+so every layer agrees on what ``"5Min"`` means, and each broker adapter maps the
+value object onto its own SDK type.
+"""
+
+import re
+from dataclasses import dataclass
+from datetime import timedelta
+from typing import ClassVar, Dict
+
+# Canonical unit names.
+MINUTE = "min"
+HOUR = "hour"
+DAY = "day"
+WEEK = "week"
+
+# Map the suffixes people actually type onto canonical units.
+_UNIT_ALIASES: Dict[str, str] = {
+    "min": MINUTE,
+    "m": MINUTE,
+    "minute": MINUTE,
+    "h": HOUR,
+    "hr": HOUR,
+    "hour": HOUR,
+    "d": DAY,
+    "day": DAY,
+    "w": WEEK,
+    "wk": WEEK,
+    "week": WEEK,
+}
+
+_PATTERN = re.compile(r"^\s*(\d+)\s*([a-zA-Z]+)\s*$")
+
+
+@dataclass(frozen=True)
+class Timeframe:
+    """An amount + unit, e.g. ``Timeframe(5, "min")``."""
+
+    amount: int
+    unit: str
+
+    #: pandas resample/offset aliases per canonical unit.
+    _PANDAS_OFFSET: ClassVar[Dict[str, str]] = {MINUTE: "min", HOUR: "h", DAY: "D", WEEK: "W"}
+
+    #: US regular-session trading hours per day (09:30-16:00 ET).
+    _TRADING_HOURS_PER_DAY: ClassVar[float] = 6.5
+    #: US trading days per year.
+    _TRADING_DAYS_PER_YEAR: ClassVar[int] = 252
+
+    @classmethod
+    def parse(cls, text: str) -> "Timeframe":
+        """Parse a string like ``"5Min"`` / ``"1Hour"`` / ``"1Day"``."""
+        match = _PATTERN.match(text)
+        if not match:
+            raise ValueError(f"Invalid timeframe: {text!r} (expected e.g. '5Min', '1Hour', '1Day')")
+
+        amount = int(match.group(1))
+        unit = _UNIT_ALIASES.get(match.group(2).lower())
+        if unit is None:
+            raise ValueError(f"Unsupported timeframe unit in {text!r}")
+        if amount < 1:
+            raise ValueError(f"Timeframe amount must be >= 1, got {amount}")
+        return cls(amount=amount, unit=unit)
+
+    def to_pandas_offset(self) -> str:
+        """Return the pandas offset alias, e.g. ``"5min"``, ``"1D"``."""
+        return f"{self.amount}{self._PANDAS_OFFSET[self.unit]}"
+
+    def duration(self) -> timedelta:
+        """The wall-clock length of one bar.
+
+        Deliberately calendar duration, not trading duration: this answers "how long
+        until the next bar should arrive", which is what a staleness check needs. A
+        daily bar is 24 hours here even though the session is 6.5 — the next one
+        genuinely does not arrive for a day.
+        """
+        return {
+            MINUTE: lambda n: timedelta(minutes=n),
+            HOUR: lambda n: timedelta(hours=n),
+            DAY: lambda n: timedelta(days=n),
+            WEEK: lambda n: timedelta(weeks=n),
+        }[self.unit](self.amount)
+
+    def bars_per_trading_day(self) -> float:
+        """How many bars of this timeframe one regular session produces.
+
+        The bridge between a *bar count* and a *wall-clock window*. A strategy asks
+        for "50 bars of warm-up"; only this knows that 50 one-minute bars span part of
+        a single session while 50 daily bars span ten calendar weeks. Converting the
+        two with a plain ``timedelta`` treats the overnight gap as tradeable and
+        under-fetches badly at intraday frequencies.
+
+        Fractional on purpose: a 1Week timeframe yields 0.2 bars per trading day.
+        """
+        if self.unit == DAY:
+            return 1.0 / self.amount
+        if self.unit == WEEK:
+            return 1.0 / (5.0 * self.amount)
+        if self.unit == HOUR:
+            return self._TRADING_HOURS_PER_DAY / self.amount
+        return self._TRADING_HOURS_PER_DAY * 60.0 / self.amount
+
+    def periods_per_year(self) -> float:
+        """How many bars of this timeframe occur in a trading year.
+
+        Used to annualize ratios computed on a *per-bar* return series (a 5-minute
+        bar is **not** 1/252 of a year). Note the backtest equity curve is daily-
+        resampled, so its metrics use ``TRADING_DAYS_PER_YEAR`` directly; this is
+        for callers that work on bar-frequency returns.
+        """
+        days = self._TRADING_DAYS_PER_YEAR
+        if self.unit == DAY:
+            return days / self.amount
+        if self.unit == WEEK:
+            return 52.0 / self.amount
+        if self.unit == HOUR:
+            return days * self._TRADING_HOURS_PER_DAY / self.amount
+        # minutes
+        return days * self._TRADING_HOURS_PER_DAY * 60.0 / self.amount
+
+    def __str__(self) -> str:
+        return f"{self.amount}{self.unit}"

quantred/mcp/__init__.py

@@ -0,0 +1,6 @@
+"""QuantRed MCP server package.
+
+Opt-in: requires the ``mcp`` extra (the command that needs it prints the install line for the copy you
+are running). The ``mcp`` import lives only inside :mod:`quantred.mcp.server` and is imported lazily by the ``mcp``
+subcommand, so the base install and other commands never pull it in.
+"""

quantred/mcp/selftest.py

@@ -0,0 +1,139 @@
+"""Drive the MCP server with the real SDK client, the way a chat client does.
+
+``quantred mcp --self-test`` exists so a user can tell "the server starts and
+answers" apart from "my chat is connected". It launches a *child* copy of the server
+over stdio, initializes, lists the tools and calls the two discovery tools. Going
+through the SDK client matters: the in-process ``call_tool`` shortcut skips the
+output-schema validation a real client performs, which is how a mistyped discovery
+row shipped.
+
+Importable only with the ``mcp`` extra; the CLI imports it lazily.
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+import time
+from typing import Any, Dict, List, Optional
+
+import anyio
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+
+#: Said on every run, pass or fail: a passing self-test is easy to over-read.
+DISCLAIMER = (
+    "This checks that the server starts and answers. It does not connect it to any chat "
+    "- your MCP client launches its own copy from its config."
+)
+
+#: The discovery tools the check calls. Names here are the tool names, not services.
+DISCOVERY_TOOLS = ("list_strategies", "list_scanners")
+
+
+def default_command(*, offline: bool = False, cache_dir: Optional[Any] = None) -> List[str]:
+    """The server command for *this* copy - the one ``init`` tells a reader to configure.
+
+    Delegates to the setup service so the check and the instruction cannot name two
+    different commands (the check passing on one nobody was told to use).
+    """
+    from quantred.services.setup import mcp_launch_command
+
+    return mcp_launch_command(offline=offline, cache_dir=cache_dir)
+
+
+def _rows(result: Any) -> List[Dict[str, Any]]:
+    structured = getattr(result, "structuredContent", None) or {}
+    rows = structured.get("result")
+    return list(rows) if isinstance(rows, list) else []
+
+
+async def _drive(command: List[str], env: Dict[str, str], errlog, report: Dict[str, Any]) -> None:
+    """Fill ``report`` as it goes, so a failure still knows which step it reached."""
+    params = StdioServerParameters(command=command[0], args=command[1:], env=env)
+    async with stdio_client(params, errlog=errlog) as (read, write):
+        async with ClientSession(read, write) as session:
+            report["step"] = "initialize"
+            initialized = await session.initialize()
+            report["server"] = initialized.serverInfo.name
+            report["step"] = "list_tools"
+            report["tools"] = sorted(t.name for t in (await session.list_tools()).tools)
+            for tool in DISCOVERY_TOOLS:
+                report["step"] = tool
+                result = await session.call_tool(tool)
+                if result.isError:
+                    text = " ".join(getattr(c, "text", "") for c in result.content)
+                    raise RuntimeError(f"{tool} returned an error: {text}")
+                rows = _rows(result)
+                if not rows:
+                    raise RuntimeError(
+                        f"{tool} returned no structured rows - the server's MCP SDK may predate "
+                        "structured output (the 'mcp' extra needs >=1.10), or discovery found nothing"
+                    )
+                if not any(r.get("demo") for r in rows):
+                    raise RuntimeError(f"{tool} did not list the built-in demo entries")
+                report[tool] = rows
+    report["step"] = "close"
+
+
+def run_self_test(
+    command: Optional[List[str]] = None,
+    *,
+    timeout: float = 60,
+    env: Optional[Dict[str, str]] = None,
+    offline: bool = False,
+    cache_dir: Optional[Any] = None,
+) -> Dict[str, Any]:
+    """Run the discovery check; never raises for a server-side failure.
+
+    Returns ``{"ok", "step", "elapsed", ...}``. On success it also carries ``tools``,
+    ``list_strategies`` and ``list_scanners`` rows. On failure ``step`` names where it
+    stopped and ``error`` / ``server_stderr`` say why: a server that exits before
+    answering (a missing credential, a missing extra) reaches a client as a closed
+    pipe and nothing else, so what the child printed is the useful part.
+
+    ``env`` defaults to a copy of the caller's environment - the SDK would otherwise
+    hand the child a minimal one, losing ``TRADEFLOW_HOME`` and credentials.
+    """
+    if command:
+        command = list(command)
+    elif offline or cache_dir is not None:
+        command = default_command(offline=offline, cache_dir=cache_dir)
+    else:
+        command = default_command()
+    child_env = dict(os.environ if env is None else env)
+    started = time.monotonic()
+    report: Dict[str, Any] = {"step": "start"}
+
+    async def go() -> Dict[str, Any]:
+        with tempfile.TemporaryFile(mode="w+", encoding="utf-8") as errlog:
+            try:
+                with anyio.fail_after(timeout):
+                    await _drive(command, child_env, errlog, report)
+                return {"ok": True, **report}
+            except BaseException as exc:  # noqa: BLE001 - reported, not raised
+                if isinstance(exc, (KeyboardInterrupt, SystemExit)):
+                    raise
+                errlog.flush()
+                errlog.seek(0)
+                return {
+                    "ok": False,
+                    "step": report["step"],
+                    "error": _describe(exc),
+                    "server_stderr": errlog.read().strip()[-2000:],
+                }
+
+    out = anyio.run(go)
+    out["command"] = command
+    out["elapsed"] = time.monotonic() - started
+    return out
+
+
+def _describe(exc: BaseException) -> str:
+    # Task-group failures arrive wrapped; the first member is the cause worth showing.
+    members = getattr(exc, "exceptions", None)
+    if members:
+        return _describe(members[0])
+    if isinstance(exc, TimeoutError):
+        return "timed out waiting for the server"
+    return f"{type(exc).__name__}: {exc}" if str(exc) else type(exc).__name__