deeptrade-quant 0.0.2__py3-none-any.whl

deeptrade/plugins_api/__init__.py

@@ -0,0 +1,44 @@
+"""Public plugin API.
+
+All plugins import from this package; the rest of ``deeptrade.*`` is internal.
+
+Stable surface (api_version = "1"):
+    - Plugin (Protocol), PluginContext — every plugin's contract: metadata + validate_static + dispatch
+    - ChannelPlugin (Protocol) — channel-specific extension (push hook)
+    - NotificationPayload, NotificationSection, NotificationItem — notify data contract
+    - PluginMetadata, TableSpec, MigrationSpec, PluginPermissions, ...
+    - StageProfile — LLM 调参档；插件持有 preset → stage 映射表，自行解析
+"""
+
+from __future__ import annotations
+
+from deeptrade.plugins_api.base import Plugin, PluginContext
+from deeptrade.plugins_api.channel import ChannelPlugin
+from deeptrade.plugins_api.llm import StageProfile
+from deeptrade.plugins_api.metadata import (
+    MigrationSpec,
+    PluginMetadata,
+    PluginPermissions,
+    TableSpec,
+    TushareApiPermissions,
+)
+from deeptrade.plugins_api.notify import (
+    NotificationItem,
+    NotificationPayload,
+    NotificationSection,
+)
+
+__all__ = [
+    "ChannelPlugin",
+    "MigrationSpec",
+    "NotificationItem",
+    "NotificationPayload",
+    "NotificationSection",
+    "Plugin",
+    "PluginContext",
+    "PluginMetadata",
+    "PluginPermissions",
+    "StageProfile",
+    "TableSpec",
+    "TushareApiPermissions",
+]

deeptrade/plugins_api/base.py

@@ -0,0 +1,66 @@
+"""Plugin contract — api_version "1".
+
+A plugin is a Python class implementing this Protocol. The framework loads it
+via the dotted entrypoint declared in the YAML metadata. The framework knows
+NOTHING about the plugin's domain semantics; the plugin owns its own command
+parsing, execution, persistence, and output.
+
+``PluginContext`` is the minimal services bundle the framework hands to every
+plugin's ``validate_static`` (during install) and to channel plugins' ``push``
+(during notify). It lives here — alongside the base ``Plugin`` Protocol —
+because it is the universal context for the base contract; channel-specific
+extensions live in :mod:`deeptrade.plugins_api.channel`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:  # pragma: no cover
+    from deeptrade.core.config import ConfigService
+    from deeptrade.core.db import Database
+    from deeptrade.plugins_api.metadata import PluginMetadata
+
+
+@dataclass
+class PluginContext:
+    """Minimal services bundle the framework hands to a plugin's
+    ``validate_static`` (during install) and to a channel plugin's ``push``
+    (during notify).
+
+    Plugins that need richer services (TushareClient, LLMManager / LLMClient, etc.)
+    construct them inside their own ``dispatch`` from these primitives.
+    """
+
+    db: Database
+    config: ConfigService
+    plugin_id: str | None = None
+
+
+@runtime_checkable
+class Plugin(Protocol):
+    """The minimal interface a plugin entrypoint class must satisfy."""
+
+    metadata: PluginMetadata
+
+    def validate_static(self, ctx: PluginContext) -> None:
+        """Post-install self-check. MUST NOT touch the network.
+
+        Called once by the framework during ``deeptrade plugin install``. Use
+        it to verify required tables exist, required config keys are present,
+        and the entrypoint class loads cleanly. Raise on failure to abort
+        install (the framework will roll back).
+        """
+
+    def dispatch(self, argv: list[str]) -> int:
+        """CLI dispatch entry point.
+
+        ``argv`` is the remaining command-line tail after the framework strips
+        the leading ``<plugin_id>`` token. For example, when the user runs
+        ``deeptrade limit-up-board run --force-sync``, the plugin receives
+        ``argv == ['run', '--force-sync']``.
+
+        The plugin owns parsing, ``--help`` rendering, execution, persistence,
+        and output. Returns the process exit code (0 = success).
+        """

deeptrade/plugins_api/channel.py

@@ -0,0 +1,42 @@
+"""ChannelPlugin contract — api_version "1".
+
+A notification channel is a Python class implementing this Protocol. Channels
+are loaded by the framework via the dotted entrypoint declared in their YAML
+metadata, just like any other plugin.
+
+Channel plugins are EXPLICITLY EXEMPTED from the "no direct external API" rule
+that applies to other plugins: a channel IS an HTTP client by nature, so it may
+``import httpx``/``requests`` directly. They still go through ``PluginContext``
+(defined in :mod:`deeptrade.plugins_api.base`) for DB and config access.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+from deeptrade.plugins_api.base import Plugin, PluginContext
+
+if TYPE_CHECKING:  # pragma: no cover
+    from deeptrade.plugins_api.metadata import PluginMetadata
+    from deeptrade.plugins_api.notify import NotificationPayload
+
+__all__ = ["ChannelPlugin", "PluginContext"]
+
+
+@runtime_checkable
+class ChannelPlugin(Plugin, Protocol):
+    """A plugin that can also receive ``NotificationPayload`` from the
+    framework's notifier (in addition to providing the standard CLI dispatch).
+
+    Implementations satisfy both the :class:`Plugin` contract (``metadata`` +
+    ``validate_static`` + ``dispatch``) AND the channel-specific ``push`` hook.
+    """
+
+    metadata: PluginMetadata
+
+    def push(self, ctx: PluginContext, payload: NotificationPayload) -> None:
+        """Format payload and dispatch to the IM platform.
+
+        May raise — the framework's MultiplexNotifier catches and isolates
+        per-channel failures so one broken channel never blocks others.
+        """

deeptrade/plugins_api/events.py

@@ -0,0 +1,61 @@
+"""Strategy event model.
+
+DESIGN §8.5: full enumeration of EventType values. v0.5+: each plugin owns
+its own ``<prefix>_events`` table (e.g. ``lub_events`` / ``va_events``) and
+decides whether/how to persist these — the framework no longer provides a
+unified ``strategy_events`` table or a runner that writes into one.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class EventType(StrEnum):
+    # step lifecycle
+    STEP_STARTED = "step.started"
+    STEP_PROGRESS = "step.progress"
+    STEP_FINISHED = "step.finished"
+    # data sync
+    DATA_SYNC_STARTED = "data.sync.started"
+    DATA_SYNC_FINISHED = "data.sync.finished"
+    # tushare
+    TUSHARE_CALL = "tushare.call"
+    TUSHARE_FALLBACK = "tushare.fallback"
+    TUSHARE_UNAUTH = "tushare.unauthorized"
+    # llm
+    LLM_BATCH_STARTED = "llm.batch.started"
+    LLM_BATCH_FINISHED = "llm.batch.finished"
+    LLM_FINAL_RANK = "llm.final_ranking"
+    VALIDATION_FAILED = "validation.failed"
+    # result
+    RESULT_PERSISTED = "result.persisted"
+    LOG = "log"
+    # Live row content — plugin-driven dashboard "current phase" message.
+    # The dashboard's Live row reads `event.message` of LIVE_STATUS events
+    # verbatim and shows nothing else there. The framework deliberately does
+    # NOT parse any other event's message string to infer phase, so plugin
+    # wording stays decoupled from framework code. Optional payload key
+    # ``terminal=True`` marks the emit as the run's final-state text so
+    # the framework's mark_finished default doesn't overwrite it.
+    LIVE_STATUS = "live.status"
+
+
+class EventLevel(StrEnum):
+    INFO = "info"
+    WARN = "warn"
+    ERROR = "error"
+
+
+class StrategyEvent(BaseModel):
+    """Single event emitted by a strategy plugin."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    type: EventType
+    level: EventLevel = EventLevel.INFO
+    message: str
+    payload: dict[str, Any] = Field(default_factory=dict)

deeptrade/plugins_api/llm.py

@@ -0,0 +1,46 @@
+"""LLM调参契约 — 插件作者唯一需要 import 的 LLM 调参类型。
+
+v0.7：Stage 概念彻底退出框架。框架的 ``LLMClient.complete_json`` 不再认识
+stage 名字，由调用方直接传入一个已解析好的 ``StageProfile`` 实例；预设档名
+（``fast / balanced / quality``）保留为框架级用户配置（``app.profile``），
+但**预设档 → 各 stage tuning 的映射表归插件自己维护**。
+
+插件作者用法：
+
+    from deeptrade.plugins_api import StageProfile
+
+    PROFILES: dict[str, dict[str, StageProfile]] = {
+        "fast":     {"my_stage": StageProfile(thinking=False, ...)},
+        "balanced": {"my_stage": StageProfile(thinking=True,  ...)},
+        "quality":  {"my_stage": StageProfile(thinking=True,  ...)},
+    }
+
+    def resolve_profile(preset: str, stage: str) -> StageProfile:
+        return PROFILES[preset][stage]
+
+随后在 pipeline 中：
+
+    prof = resolve_profile(rt.config.get_app_config().app_profile, "my_stage")
+    obj, _ = llm.complete_json(system=..., user=..., schema=..., profile=prof)
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class StageProfile(BaseModel):
+    """单次 LLM 调用的调参档：四字段对应 OpenAI Chat Completions 协议参数。
+
+    ``thinking`` / ``reasoning_effort`` 在不支持思维链的 provider 上由 transport
+    静默丢弃（DeepSeek/Qwen/Kimi/Doubao/GLM/... 各家支持情况不同）。
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    thinking: bool
+    reasoning_effort: Literal["low", "medium", "high"]
+    temperature: float = Field(ge=0.0, le=2.0)
+    max_output_tokens: int = Field(ge=1024, le=384_000)

deeptrade/plugins_api/metadata.py

@@ -0,0 +1,84 @@
+"""Plugin metadata schema.
+
+DESIGN §8.2 (v0.3.1):
+    * `tables` declares table names + purge policy ONLY (no inline DDL).
+    * `migrations` is the SOLE DDL execution path (S1 fix).
+    * `permissions.llm_tools` is fixed False (M3 hard constraint).
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+class TableSpec(BaseModel):
+    """Table the plugin owns. DDL is in migrations/, NOT here."""
+
+    model_config = ConfigDict(extra="forbid")
+    name: str = Field(..., pattern=r"^[a-z][a-z0-9_]{1,63}$")
+    description: str = ""
+    purge_on_uninstall: bool = True
+
+
+class MigrationSpec(BaseModel):
+    """One SQL migration file. Filename version pattern: 'YYYYMMDD_NNN'."""
+
+    model_config = ConfigDict(extra="forbid")
+    version: str = Field(..., pattern=r"^\d{8}_\d{3,}$")
+    file: str
+    checksum: str = Field(..., pattern=r"^sha256:[0-9a-f]{64}$")
+
+
+class TushareApiPermissions(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    required: list[str] = Field(default_factory=list)
+    optional: list[str] = Field(default_factory=list)
+
+
+class PluginPermissions(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    tushare_apis: TushareApiPermissions = Field(default_factory=TushareApiPermissions)
+    llm: bool = False
+    # M3 hard constraint: any non-False value is rejected at install time.
+    llm_tools: Literal[False] = False
+
+
+class PluginMetadata(BaseModel):
+    """Top-level plugin descriptor parsed from deeptrade_plugin.yaml."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    plugin_id: str = Field(..., pattern=r"^[a-z][a-z0-9-]{2,31}$")
+    name: str
+    version: str
+    # v0.4: widened to support channel plugins (DESIGN §18.4). Old yaml with
+    # type='strategy' (or omitted) remains valid via the default.
+    type: Literal["strategy", "channel"] = "strategy"
+    api_version: str
+    entrypoint: str = Field(..., pattern=r"^[A-Za-z_][\w\.]*:[A-Za-z_]\w*$")
+    description: str
+    author: str = ""
+    permissions: PluginPermissions = Field(default_factory=PluginPermissions)
+    tables: list[TableSpec]
+    migrations: list[MigrationSpec]
+
+    @model_validator(mode="after")
+    def _migrations_not_empty(self) -> PluginMetadata:
+        if not self.migrations:
+            raise ValueError(
+                "metadata.migrations cannot be empty; DDL must be managed via migrations/*.sql"
+            )
+        # version uniqueness
+        versions = [m.version for m in self.migrations]
+        if len(versions) != len(set(versions)):
+            raise ValueError("duplicate migration versions in metadata.migrations")
+        return self
+
+    @model_validator(mode="after")
+    def _tables_unique(self) -> PluginMetadata:
+        names = [t.name for t in self.tables]
+        if len(names) != len(set(names)):
+            raise ValueError("duplicate table names in metadata.tables")
+        return self

deeptrade/plugins_api/notify.py

@@ -0,0 +1,67 @@
+"""IM notification payload — strategy plugin → notifier contract.
+
+DESIGN §18.3: payload carries STRUCTURED SEMANTIC DATA only (no pre-rendered
+markdown). Channel plugins are responsible for format conversion (markdown for
+feishu/dingtalk, plain text for SMS, interactive blocks for slack, ...).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from deeptrade.core.run_status import RunStatus
+
+
+class NotificationItem(BaseModel):
+    """One semantic row (a stock pick, a watchlist entry, ...).
+
+    Channels render this as a list row, card field, or a bullet — whichever
+    fits their format. ``fields`` carries channel-agnostic extras the channel
+    may surface if it has the space.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    code: str
+    name: str | None = None
+    rank: int | None = None
+    score: float | None = None
+    label: str | None = None
+    note: str | None = None
+    fields: dict[str, str | int | float] = Field(default_factory=dict)
+
+
+class NotificationSection(BaseModel):
+    """A semantically related group of items (e.g. 'top_candidates' / 'watchlist').
+
+    ``key`` is the stable machine-readable identifier; ``title`` is what
+    channels display.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    key: str
+    title: str
+    items: list[NotificationItem]
+
+
+class NotificationPayload(BaseModel):
+    """Everything a strategy plugin hands to the notifier in one shot.
+
+    Channels MUST tolerate empty ``sections`` / ``metrics`` (degraded modes
+    like SMS only get ``title`` + ``summary``).
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    plugin_id: str
+    run_id: str
+    status: RunStatus
+    title: str
+    summary: str
+    sections: list[NotificationSection] = Field(default_factory=list)
+    metrics: dict[str, str | int | float] = Field(default_factory=dict)
+    report_dir: str | None = None
+    extras: dict[str, Any] = Field(default_factory=dict)

deeptrade/strategies_builtin/limit_up_board/deeptrade_plugin.yaml

@@ -0,0 +1,101 @@
+plugin_id: limit-up-board
+name: 打板策略
+version: 0.4.0
+type: strategy
+api_version: "1"
+entrypoint: limit_up_board.plugin:LimitUpBoardPlugin
+description: A 股打板策略：双轮 LLM 漏斗（强势标的分析 → 连板预测）
+author: DeepTrade
+
+permissions:
+  tushare_apis:
+    required:
+      - stock_basic
+      - trade_cal
+      - daily
+      - daily_basic
+      - stock_st
+      - limit_list_d
+      - limit_step
+      - moneyflow
+      - top_list
+      - top_inst
+      - cyq_perf
+    optional:
+      - limit_list_ths
+      - limit_cpt_list
+      - ths_hot
+      - dc_hot
+      - stk_auction_o
+      - anns_d
+      - suspend_d
+      - stk_limit
+  llm: true
+  llm_tools: false
+
+migrations:
+  - version: "20260430_001"
+    file: migrations/20260430_001_init.sql
+    checksum: "sha256:6009465242554848315fcd058b816829161f1f51803db004361995ddf28814c3"
+  - version: "20260501_002"
+    file: migrations/20260501_002_lub_stage_results_llm_provider.sql
+    checksum: "sha256:9db92478a786984b69fa37a143b806357f940bd2471253d7bd4918735c41690f"
+  - version: "20260508_001"
+    file: migrations/20260508_001_lub_lhb_tables.sql
+    checksum: "sha256:12e32fa078874c1b7d30645646a23e345db2937f00534269d282251c9b497f0d"
+  - version: "20260508_002"
+    file: migrations/20260508_002_lub_cyq_perf.sql
+    checksum: "sha256:5558169e6c5f6ae72be026dfac598f9a5d886d01b76a53565796a6f1b5665772"
+  - version: "20260508_003"
+    file: migrations/20260508_003_lub_lhb_pk_fix.sql
+    checksum: "sha256:a5efaf93f1399131610e2d0ee7b23bb00846a0aec72801589b91d6669443f187"
+  - version: "20260508_004"
+    file: migrations/20260508_004_lub_lhb_drop_pk.sql
+    checksum: "sha256:192837aa88f31b985575d73840a516719cf692ae1be0dce447fcd98d0de0667f"
+  - version: "20260508_005"
+    file: migrations/20260508_005_lub_config.sql
+    checksum: "sha256:5971f06666ee96a23a5297290e8bc725dab61debbb64a58925abcc26d8844a3c"
+
+tables:
+  - name: lub_stock_basic
+    description: stock_basic 落库（限本插件使用）
+    purge_on_uninstall: true
+  - name: lub_trade_cal
+    description: trade_cal 落库
+    purge_on_uninstall: true
+  - name: lub_daily
+    description: daily 行情落库
+    purge_on_uninstall: true
+  - name: lub_daily_basic
+    description: daily_basic 行情指标落库
+    purge_on_uninstall: true
+  - name: lub_moneyflow
+    description: moneyflow 资金流落库
+    purge_on_uninstall: true
+  - name: lub_limit_list_d
+    description: 涨停明细缓存（limit_list_d）
+    purge_on_uninstall: true
+  - name: lub_limit_ths
+    description: 同花顺涨停榜单缓存（limit_list_ths）
+    purge_on_uninstall: true
+  - name: lub_stage_results
+    description: 策略各阶段（R1/R2/final_ranking）结构化结果
+    purge_on_uninstall: true
+  - name: lub_runs
+    description: 本插件 run 历史（替代框架 strategy_runs）
+    purge_on_uninstall: true
+  - name: lub_events
+    description: 本插件 run 事件流（替代框架 strategy_events）
+    purge_on_uninstall: true
+  - name: lub_top_list
+    description: 龙虎榜个股明细（top_list）
+    purge_on_uninstall: true
+  - name: lub_top_inst
+    description: 龙虎榜机构席位明细（top_inst）
+    purge_on_uninstall: true
+  - name: lub_cyq_perf
+    description: 筹码每日指标（cyq_perf）
+    purge_on_uninstall: true
+  - name: lub_config
+    description: 本插件用户可调设置（流通市值 / 股价上限）
+    purge_on_uninstall: true

deeptrade/strategies_builtin/limit_up_board/limit_up_board/calendar.py

@@ -0,0 +1,65 @@
+"""TradeCalendar — pure helper around tushare trade_cal frames."""
+
+from __future__ import annotations
+
+import pandas as pd
+
+
+class TradeCalendar:
+    """Read-only view over the trade_cal DataFrame.
+
+    Required columns: cal_date (str YYYYMMDD), is_open (0/1), pretrade_date (str).
+    """
+
+    def __init__(self, df: pd.DataFrame) -> None:
+        if not {"cal_date", "is_open"}.issubset(df.columns):
+            raise ValueError("trade_cal frame missing required columns")
+
+        # ⚠ Bug fix: tushare trade_cal returns cal_date as int64 in some
+        # environments; JSON cache round-trip can also widen "20260428" → 20260428.
+        # Normalize to string up-front so all downstream comparisons are str↔str.
+        df = df.copy()
+        df["cal_date"] = df["cal_date"].astype(str)
+        if "pretrade_date" in df.columns:
+            # Some non-trading days have NaN pretrade_date; preserve NaN, stringify the rest
+            df["pretrade_date"] = df["pretrade_date"].apply(
+                lambda v: str(v) if pd.notna(v) else None
+            )
+        # is_open is sometimes "1"/"0" strings — coerce to int for ==1 comparison
+        df["is_open"] = pd.to_numeric(df["is_open"], errors="coerce").fillna(0).astype(int)
+
+        # Normalize: deduplicate on cal_date, keeping the SSE/last row
+        sorted_df = df.sort_values("cal_date").drop_duplicates("cal_date", keep="last")
+        self._df = sorted_df.reset_index(drop=True)
+        self._idx: dict[str, int] = {
+            str(row.cal_date): i for i, row in enumerate(self._df.itertuples(index=False))
+        }
+
+    def is_open(self, date: str) -> bool:
+        idx = self._idx.get(date)
+        if idx is None:
+            return False
+        return int(self._df.at[idx, "is_open"]) == 1
+
+    def pretrade_date(self, date: str) -> str:
+        """Return the most recent open day strictly BEFORE `date`."""
+        # Walk backwards through cal_date sorted index
+        candidates = self._df[self._df["cal_date"] < date]
+        opens = candidates[candidates["is_open"] == 1]
+        if opens.empty:
+            raise ValueError(f"no prior open trading day before {date}")
+        return str(opens.iloc[-1]["cal_date"])
+
+    def next_open(self, date: str) -> str:
+        """Return the first open day strictly AFTER `date`."""
+        candidates = self._df[self._df["cal_date"] > date]
+        opens = candidates[candidates["is_open"] == 1]
+        if opens.empty:
+            raise ValueError(f"no future open trading day after {date}")
+        return str(opens.iloc[0]["cal_date"])
+
+    def latest_closed_on_or_before(self, date: str) -> str:
+        """Return the latest open day ≤ `date` (i.e. `date` itself if open, else preceding)."""
+        if self.is_open(date):
+            return date
+        return self.pretrade_date(date)