deeptrade-quant 0.5.0__tar.gz → 0.6.0__tar.gz

{deeptrade_quant-0.5.0 → deeptrade_quant-0.6.0}/CHANGELOG.md

@@ -2,6 +2,59 @@
 
 All notable changes to DeepTrade. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and SemVer.
 
+## [v0.6.0] — 2026-05-15 — 插件运行时 API + LLM 方言 + 杂项收尾
+
+本版按 2026-05-15 评审研判文档 `DeepTrade-review-assessment-and-fix-plan-2026-05-15.md` §5 中 v0.6 路线落地 6 项主线：
+
+1. **H4 插件运行时 API**：``api_version="2"`` 的插件改用 ``dispatch(ctx, argv)`` 接收 ``PluginContext``，无需再 ``import deeptrade.core.*`` 私有路径取 db / config。``api_version="1"`` 永久向后兼容，运行时按 metadata 决定调用形态。``plugins_api/__init__.py`` 把 ``LLMManager`` / ``TushareClient`` 提升为公共 API。
+2. **H5 LLM 方言收口**：``OpenAICompatTransport`` 加 class 属性 ``supports_reasoning_effort`` 默认 False；新增 ``OpenAIOfficialTransport``（base_url 含 ``api.openai.com``）改 True。其余 OpenAI-compat provider 不再裸送 ``reasoning_effort``，消除国内非推理模型常见的 400 与忽略两种失败模式。
+3. **H1 hard error**：``table_prefix`` 派生不匹配从 v0.5 的 ``DeprecationWarning`` 转 ``ValueError``，与显式声明路径合流，让"插件表必须落在派生命名空间"成为可执行约束。
+4. **M6**：``env_var_for(key)`` 把 provider 名中的 ``-`` 归一化为 ``_``，避免 ``DEEPTRADE_LLM_QWEN-PLUS_API_KEY`` 这种 bash/sh 非法标识符；``set_llm_provider`` 在归一化后冲突时硬拒绝，避免 ``qwen-plus`` / ``qwen_plus`` 共用同一个 env var 时的静默 shadowing。
+5. **M8**：``_try_load_keyring`` 改用 ``keyring.get_keyring()`` 的非写入式 backend 探测，只在 ``backends.fail.*`` / ``backends.null.*`` 类时返回 None；结果缓存到模块级变量，配 ``_invalidate_keyring_cache`` 给测试用。彻底消除 ``SecretStore.__init__`` 每次都向 OS 凭据存储写一个 ``__probe__`` 的副作用。
+6. **M9**：``TushareClient`` 首次遇未知 API 改打 INFO 日志（进程级 + 实例级双 dedup，不再每次默认就刷屏）；``PluginMetadata.permissions.tushare_apis.cache_overrides: dict[str, str]`` 让插件作者声明非默认缓存策略，``TushareClient(cache_overrides=...)`` 在分类决策中优先采纳。
+
+### Added
+
+- ``deeptrade/plugins_api/base.py``：docstring 标注 ``api_version`` 与 ``dispatch`` 签名的对应关系；``Plugin.dispatch`` 改写为变参 Protocol 占位（``runtime_checkable`` 只校验属性存在，签名由框架按 metadata 决定）。
+- ``deeptrade/core/plugin_manager.py::SUPPORTED_API_VERSIONS``（``frozenset({"1", "2"})``）；install / upgrade 路径用集合包含判断替换原先的 ``!= CURRENT_API_VERSION``，对未来扩 ``"3"`` 留接口。
+- ``deeptrade/cli.py::_dispatch``：按 ``rec.api_version`` 选择 ``plugin.dispatch(argv)`` 或 ``plugin.dispatch(ctx, argv)``；v2 路径由框架开 ``Database`` + 构 ``PluginContext`` + 收尾关库，插件不再操心生命周期。
+- ``deeptrade/plugins_api/__init__.py``：重导出 ``LLMManager`` 与 ``TushareClient``，正式纳入公共 surface 的 ``__all__``。
+- ``deeptrade/plugins_api/metadata.py::TushareApiPermissions.cache_overrides: dict[str, str]``，配 ``_cache_overrides_values_valid`` model_validator 强制值落在 ``{static, trade_day_immutable, trade_day_mutable, hot_or_anns}``；非法值在 yaml 解析阶段拒绝，避免运行时缓存行为静默退化。
+- ``deeptrade/core/tushare_client.py``：``TushareClient.__init__`` 新增 ``cache_overrides`` kwarg；新增 ``_resolve_cache_class`` 把"插件 overrides → 框架表 → 默认 + 一次性 INFO 日志"三级优先级集中表达；模块级 ``_UNKNOWN_API_LOGGED`` 做进程级 dedup。
+- ``deeptrade/core/llm_client.py``：``OpenAICompatTransport.supports_reasoning_effort: bool = False`` 类标志位；``OpenAIOfficialTransport`` 子类（``api.openai.com`` base_url 触发）将其覆盖为 True；``chat()`` 仅在 ``supports_reasoning_effort and reasoning_effort`` 时把字段写入 ``kwargs``。``_TRANSPORT_BY_BASE_URL`` 新增 ``("api.openai.com", OpenAIOfficialTransport)`` 路由。
+- ``deeptrade/core/secrets.py``：模块级 ``_keyring_cache`` / ``_keyring_probed`` 缓存；``_invalidate_keyring_cache`` 测试钩子；``_try_load_keyring`` 重写为按 backend FQCN 子串识别 fail/null 类。
+- ``deeptrade/core/config.py::ConfigService.set_llm_provider``：归一化后冲突检测；``env_var_for`` 文档说明 ``-``→``_`` 规则的动机。
+- 测试新增：``tests/plugins_api/test_api_version_2.py``（6 用例，覆盖双 api_version 安装、unknown api_version 拒绝、v1/v2 dispatch arity、公开类导出）、``tests/core/test_secrets.py`` v0.6 M8 节 3 用例（fail backend 拒绝、real backend 不写探针、cache 可重置）、``tests/core/test_config.py`` 3 用例（env 归一化、归一化冲突拒绝、同名更新放行）、``tests/core/test_plugin_security.py`` 3 用例（cache_overrides 默认空 / 合法值 / 非法值）、``tests/core/test_tushare_client.py`` 3 用例（overrides 优先、未知 API override 路径、INFO 日志一次性）、``tests/core/test_llm_client.py`` 4 用例（supports_reasoning_effort 默认 False、OpenAI-official 路由、Generic transport 不发送、empty 字符串不发送）。
+
+### Changed
+
+- ``deeptrade/plugins_api/metadata.py::_tables_match_prefix``：``table_prefix`` 省略且不匹配派生时从 ``warnings.warn(DeprecationWarning)`` 转 ``raise ValueError``；删除现已无用的 ``import warnings``。模块顶部 docstring 把 v0.5 advisory / v0.6 enforcement 的边界明确标注。
+- ``deeptrade/plugins_api/metadata.py``：``TushareApiPermissions`` 加 ``cache_overrides`` 字段；定义 ``_CACHE_CLASS_VALUES`` 内部常量便于校验。
+- ``deeptrade/core/tushare_client.py``：``cache_class = API_CACHE_CLASS.get(api_name, "trade_day_immutable")`` 改为 ``cache_class = self._resolve_cache_class(api_name)``，集中所有分类决策。
+- ``deeptrade/cli.py``：v2 路径在 dispatch 周边内联 ``ConfigService`` / ``PluginContext`` 导入，避免顶层冷启动负担；其余跨 dispatch 路径行为不变。
+- ``tests/core/test_plugin_security.py``：``test_plugin_table_prefix_warns_when_omitted_and_mismatched`` 改名 ``test_plugin_table_prefix_hard_fails_when_omitted_and_mismatched``，正向断言 ``ValidationError``；``test_plugin_table_prefix_no_warning_when_tables_match_derived`` 改名 ``test_plugin_table_prefix_passes_when_tables_match_derived``，保留 ``simplefilter("error", DeprecationWarning)`` 作为反向断言。
+- ``tests/core/test_plugin_install.py::_make_minimal_plugin_dir``：``table_name`` 默认值从硬编码 ``test_table`` 改为按 ``plugin_id`` 派生（``<pkg>_t``），满足 v0.6 派生前缀约束；``table_ddl`` 默认也从默认值同步派生。
+- ``tests/core/test_plugin_dependencies.py::_minimal_meta_dict``：表名 ``x_t`` 改为 ``minimal_x_t`` 以匹配 ``plugin_id="minimal-x"`` 的派生前缀。
+- ``tests/core/test_llm_client.py::test_select_transport_class_defaults_to_generic``：``api.openai.com`` 从"回退到 Generic"断言改为"回退用 Generic / OpenAI-official 走专属路由"的双行声明；docstring 标注 v0.6 行为变化。
+
+### Migration notes
+
+- **插件作者侧（推荐路径）**：迁移到 ``api_version="2"``——
+    1. ``deeptrade_plugin.yaml::api_version`` 改为 ``"2"``。
+    2. ``def dispatch(self, argv):`` 改写为 ``def dispatch(self, ctx, argv):``。
+    3. 把 ``Database(paths.db_path())`` / ``ConfigService(...)`` 等手动构造替换为 ``ctx.db`` / ``ctx.config``；之前从 ``deeptrade.core.*`` import 的 ``LLMManager`` / ``TushareClient`` 改为 ``from deeptrade.plugins_api import LLMManager, TushareClient``。
+- **插件作者侧（最低改动路径）**：不动 ``api_version="1"``，所有既有插件**零代码改动**继续工作；唯一硬约束是 ``metadata.tables`` 必须落在 ``<plugin_id 派生前缀>_*`` 命名空间内（或显式声明 ``table_prefix``）。
+- **多 LLM provider 命名**：使用 ``qwen-plus`` / ``qwen-max-2024`` 这类带连字符的 provider 名时，``DEEPTRADE_LLM_QWEN_PLUS_API_KEY`` 形式的 env var 现在可以正常生效；不要再同时注册归一化后冲突的名字（``qwen-plus`` 与 ``qwen_plus``）。
+- **官方 OpenAI 推理模型**：``reasoning_effort`` 现在只在 ``base_url`` 含 ``api.openai.com`` 时上行。其他 OpenAI-compat 网关如需该字段（少见），临时方案是 fork 当前 transport 类并覆写 ``supports_reasoning_effort = True``；后续版本会按需要在路由表里追加。
+- **Tushare 缓存策略覆盖**：插件作者可在 ``deeptrade_plugin.yaml`` 写
+  ```yaml
+  permissions:
+    tushare_apis:
+      cache_overrides:
+        moneyflow_industry_ths: trade_day_mutable
+  ```
+  把框架表里没列出的 API 显式钉到正确的缓存类，避免依赖默认 ``trade_day_immutable``。运行时由插件自己把这份 dict 作为 ``cache_overrides=...`` 传给 ``TushareClient``。
+
 ## [v0.5.0] — 2026-05-15 — 插件信任边界 + CLI 中文化
 
 本版主线落地 2026-05-15 评审研判文档 `DeepTrade-review-assessment-and-fix-plan-2026-05-15.md` 中的 v0.5 路线：把"插件可以声明并清掉框架核心表"这条被忽视的信任边界明确收口，让框架的 SQL 迁移有边界、插件加载有 sys.modules 守卫、升级路径不会被静默改动的历史 migration 蒙混过关；同时把命令行用户向文案统一为中文，建立首道防回退的回归测试。整体不引入新框架概念（拒绝了报告里的 RuntimeContext 大对象、独立 venv、SQL DSL 等重型方案），保持"框架轻、插件重"的原则。

{deeptrade_quant-0.5.0 → deeptrade_quant-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deeptrade-quant
-Version: 0.5.0
+Version: 0.6.0
 Summary: LLM-driven A-share (Shanghai/Shenzhen main board) stock screening CLI
 Project-URL: Homepage, https://github.com/ty19880929/deeptrade
 Project-URL: Repository, https://github.com/ty19880929/deeptrade

{deeptrade_quant-0.5.0 → deeptrade_quant-0.6.0}/deeptrade/__init__.py

@@ -2,5 +2,5 @@
 
 from __future__ import annotations
 
-__version__ = "0.5.0"
+__version__ = "0.6.0"
 __all__ = ["__version__"]

{deeptrade_quant-0.5.0 → deeptrade_quant-0.6.0}/deeptrade/cli.py

@@ -126,8 +126,29 @@ def _build_plugin_command(plugin_id: str) -> click.Command | None:
         if not hasattr(plugin, "dispatch"):
             typer.echo(f"✘ 插件 {plugin_id!r} 未实现 dispatch()")
             raise typer.Exit(2)
+
+        argv = list(ctx.args)
         try:
-            rc = plugin.dispatch(list(ctx.args))
+            # v0.6 H4 — dispatch arity is selected by ``metadata.api_version``.
+            # ``"1"`` (legacy) keeps the historical ``dispatch(argv)`` signature
+            # so already-shipped plugins remain runnable without a rebuild.
+            # ``"2"`` receives the same ``PluginContext`` shape passed to
+            # ``validate_static`` at install time, removing the need for plugins
+            # to import ``deeptrade.core.*`` private modules.
+            if rec.api_version == "2":
+                from deeptrade.core.config import ConfigService
+                from deeptrade.plugins_api.base import PluginContext
+
+                # Reuse the framework's open Database / dispose lifecycle —
+                # plugins should NOT manage the framework's DB handle.
+                db = Database(paths.db_path())
+                try:
+                    plugin_ctx = PluginContext(db=db, config=ConfigService(db), plugin_id=plugin_id)
+                    rc = plugin.dispatch(plugin_ctx, argv)
+                finally:
+                    db.close()
+            else:
+                rc = plugin.dispatch(argv)
         except (SystemExit, KeyboardInterrupt):
             # Exit codes / Ctrl-C must propagate unaltered.
             raise

{deeptrade_quant-0.5.0 → deeptrade_quant-0.6.0}/deeptrade/core/config.py

@@ -173,8 +173,20 @@ def llm_api_key_name(key: str) -> str | None:
 
 
 def env_var_for(key: str) -> str:
-    """Map dotted key → DEEPTRADE_<UPPER_SNAKE> env var name."""
-    return "DEEPTRADE_" + key.upper().replace(".", "_")
+    """Map dotted key → ``DEEPTRADE_<UPPER_SNAKE>`` env var name.
+
+    Hyphens are normalized to underscores so that hyphen-containing provider
+    names (e.g. ``llm.qwen-plus.api_key``) yield a POSIX-valid identifier
+    (``DEEPTRADE_LLM_QWEN_PLUS_API_KEY``). Without this, the env var
+    ``DEEPTRADE_LLM_QWEN-PLUS_API_KEY`` cannot be set via ``export`` on
+    bash / sh — variable names there must match ``[A-Za-z_][A-Za-z0-9_]*``.
+
+    Collision risk: provider names ``qwen-plus`` and ``qwen_plus`` would map
+    to the same env var. :meth:`ConfigService.set_llm_provider` refuses such
+    a registration so users discover the conflict at write time rather than
+    at first env-var read.
+    """
+    return "DEEPTRADE_" + key.upper().replace(".", "_").replace("-", "_")
 
 
 def known_keys() -> list[str]:
@@ -364,6 +376,24 @@ class ConfigService:
             )
         current_raw = self.get("llm.providers")
         current: dict[str, Any] = dict(current_raw) if isinstance(current_raw, dict) else {}
+
+        # M6 — refuse a name that collides with an existing provider after
+        # ``env_var_for`` normalization (``-`` → ``_``). Without this, two
+        # providers ``qwen-plus`` and ``qwen_plus`` would share the env var
+        # ``DEEPTRADE_LLM_QWEN_PLUS_API_KEY`` and silently shadow each other
+        # on read. Surface the conflict at registration time.
+        normalized = name.replace("-", "_")
+        for existing_name in current:
+            if existing_name == name:
+                continue
+            if existing_name.replace("-", "_") == normalized:
+                raise ValueError(
+                    f"provider name {name!r} collides with {existing_name!r} after "
+                    f"env-var normalization (both map to "
+                    f"{env_var_for(f'llm.{name}.api_key')!r}); rename one to avoid "
+                    f"silent env-var shadowing"
+                )
+
         is_first = len(current) == 0
         existing = dict(current.get(name) or {})
         prior_default = bool(existing.get("is_default", False))

{deeptrade_quant-0.5.0 → deeptrade_quant-0.6.0}/deeptrade/core/llm_client.py

@@ -139,8 +139,19 @@ class OpenAICompatTransport(LLMTransport):
     implementation returns ``{}``: appropriate for OpenAI-compatible providers
     that don't recognize a thinking concept, where ``StageProfile.thinking``
     is silently dropped per the plugins_api/llm.py contract.
+
+    v0.6 — ``supports_reasoning_effort`` (class attribute) gates whether
+    ``reasoning_effort`` from :class:`StageProfile` is forwarded to the
+    provider. Default ``False``: most OpenAI-compatible Chinese providers
+    (DeepSeek / Kimi / Qwen non-reasoning models / Doubao) either ignore
+    the field or reject it as a 400, so we drop it by default. Subclasses
+    override to ``True`` only when the provider has documented support.
     """
 
+    # v0.6 H5 — see class docstring. The default is False; OpenAI-official
+    # is the only known transport that flips it to True.
+    supports_reasoning_effort: bool = False
+
     def __init__(self, api_key: str, base_url: str, timeout: int) -> None:
         from openai import OpenAI  # noqa: PLC0415
 
@@ -171,11 +182,16 @@ class OpenAICompatTransport(LLMTransport):
                 {"role": "user", "content": user},
             ],
             "response_format": {"type": "json_object"},
-            "reasoning_effort": reasoning_effort,
             "temperature": temperature,
             "max_tokens": max_tokens,
             "stream": False,
         }
+        # v0.6 H5 — only send ``reasoning_effort`` when the transport
+        # declares support AND the caller actually supplied a non-empty
+        # value. Sending it unconditionally was the v0.5 default and is
+        # the dominant failure mode on Chinese OpenAI-compat providers.
+        if self.supports_reasoning_effort and reasoning_effort:
+            kwargs["reasoning_effort"] = reasoning_effort
         extra_body = self._provider_extra_body(thinking=thinking)
         if extra_body:
             kwargs["extra_body"] = extra_body
@@ -220,6 +236,19 @@ class DashScopeTransport(OpenAICompatTransport):
         return {"enable_thinking": thinking}
 
 
+class OpenAIOfficialTransport(OpenAICompatTransport):
+    """OpenAI's own ``api.openai.com`` endpoint.
+
+    Only this transport documents support for the ``reasoning_effort``
+    parameter (on the o1 / o3 reasoning family); flipping the base-class
+    flag here makes ``OpenAICompatTransport.chat`` forward the value from
+    :class:`StageProfile`. Other OpenAI-compatible providers either ignore
+    the field or 400 on it, so they keep the base-class default (False).
+    """
+
+    supports_reasoning_effort = True
+
+
 # ---------------------------------------------------------------------------
 # Transport routing (framework-internal)
 # ---------------------------------------------------------------------------
@@ -230,6 +259,7 @@ class DashScopeTransport(OpenAICompatTransport):
 # nowhere else; user-facing config has no "dialect" knob on purpose.
 _TRANSPORT_BY_BASE_URL: tuple[tuple[str, type[OpenAICompatTransport]], ...] = (
     ("dashscope.aliyuncs.com", DashScopeTransport),
+    ("api.openai.com", OpenAIOfficialTransport),
 )
 
 

{deeptrade_quant-0.5.0 → deeptrade_quant-0.6.0}/deeptrade/core/plugin_manager.py

@@ -42,6 +42,9 @@ from deeptrade.plugins_api.metadata import (
 logger = logging.getLogger(__name__)
 
 CURRENT_API_VERSION = "1"
+# v0.6 — both legacy v1 and ctx-aware v2 dispatch are first-class. New
+# plugin authors should use "2"; "1" is supported without deprecation.
+SUPPORTED_API_VERSIONS: frozenset[str] = frozenset({"1", "2"})
 
 # Reserved framework-level command names. A plugin_id colliding with any of
 # these would shadow framework dispatch and is rejected at install time.
@@ -270,9 +273,10 @@ class PluginManager:
                 f"(reserved: {sorted(RESERVED_PLUGIN_IDS)})"
             )
 
-        if meta.api_version != CURRENT_API_VERSION:
+        if meta.api_version not in SUPPORTED_API_VERSIONS:
             raise PluginInstallError(
-                f"plugin api_version {meta.api_version} != framework {CURRENT_API_VERSION}"
+                f"plugin api_version {meta.api_version!r} not supported by framework "
+                f"(supported: {sorted(SUPPORTED_API_VERSIONS)})"
             )
 
         # M3 hard-constraint enforcement (Pydantic Literal[False] also catches it)
@@ -539,9 +543,10 @@ class PluginManager:
                 f"如需降级，请先 `deeptrade plugin uninstall {meta.plugin_id} --purge`"
             )
 
-        if meta.api_version != CURRENT_API_VERSION:
+        if meta.api_version not in SUPPORTED_API_VERSIONS:
             raise PluginInstallError(
-                f"plugin api_version {meta.api_version} != framework {CURRENT_API_VERSION}"
+                f"plugin api_version {meta.api_version!r} not supported by framework "
+                f"(supported: {sorted(SUPPORTED_API_VERSIONS)})"
             )
         if meta.permissions.llm_tools is not False:
             raise PluginInstallError("permissions.llm_tools=true is forbidden")

{deeptrade_quant-0.5.0 → deeptrade_quant-0.6.0}/deeptrade/core/secrets.py

@@ -28,24 +28,80 @@ class _KeyringBackend(Protocol):
     def delete_password(self, service_name: str, username: str) -> None: ...
 
 
+# M8 — module-level cache so the keyring probe runs at most once per process.
+# Pre-v0.6 each ``SecretStore.__init__`` round-tripped a `__probe__` credential
+# through the OS credential store (macOS Keychain / Windows Credential Manager
+# / Linux Secret Service), which (a) cost a syscall per construction and (b)
+# polluted the credential store's audit log every time. v0.6 inspects the
+# selected backend's class instead and only marks the keyring unavailable
+# when it's an explicitly broken backend (``null`` / ``fail`` family).
+_keyring_cache: _KeyringBackend | None = None
+_keyring_probed: bool = False
+
+
+def _invalidate_keyring_cache() -> None:
+    """Test hook — clear the module-level probe cache so the next
+    ``_try_load_keyring`` re-probes. Production code never calls this."""
+    global _keyring_cache, _keyring_probed
+    _keyring_cache = None
+    _keyring_probed = False
+
+
 def _try_load_keyring() -> _KeyringBackend | None:
-    """Attempt to import & probe keyring. Return backend or None on failure."""
+    """Detect whether a usable keyring backend is present.
+
+    Strategy (v0.6 M8 — non-write probe):
+
+    1. Import ``keyring``; missing module → return None.
+    2. Inspect the active backend class via ``keyring.get_keyring()``.
+       The standard library distinguishes "no usable backend" as the
+       ``keyring.backends.fail.Keyring`` / ``keyring.backends.null.Keyring``
+       classes (matched by FQCN substring so we don't have to import
+       optional internals).
+    3. Any other backend (Windows Credential Manager, macOS Keychain,
+       Secret Service, kwallet, chainer, ...) is trusted. We do NOT
+       round-trip a sentinel credential — that was the v0.5 behavior and
+       it polluted the credential store on every ``SecretStore.__init__``.
+
+    The result is cached at module level (:func:`_invalidate_keyring_cache`
+    is the test escape hatch). Process-global cache is safe because
+    keyring backends are themselves process-global state.
+    """
+    global _keyring_cache, _keyring_probed
+    if _keyring_probed:
+        return _keyring_cache
+
+    _keyring_probed = True
     try:
         import keyring  # noqa: PLC0415 — deferred import on purpose
-        from keyring.errors import KeyringError  # noqa: PLC0415
     except ImportError:
+        _keyring_cache = None
         return None
     try:
-        # Probe: round-trip a sentinel
-        keyring.set_password(_KR_SERVICE, "__probe__", "ok")
-        if keyring.get_password(_KR_SERVICE, "__probe__") != "ok":
-            return None
-        keyring.delete_password(_KR_SERVICE, "__probe__")
-        return keyring  # type: ignore[return-value]
-    except (KeyringError, Exception) as e:  # noqa: BLE001 — capture all backend errors
-        logger.warning("keyring unavailable: %s; falling back to plaintext", e)
+        backend = keyring.get_keyring()
+    except Exception as e:  # noqa: BLE001 — keyring init can fail on weird hosts
+        logger.warning("keyring backend introspection failed: %s; using plaintext", e)
+        _keyring_cache = None
         return None
 
+    # Reject only the explicitly-broken backend classes; everything else
+    # is presumed functional. Match by FQCN substring rather than isinstance
+    # so we avoid importing optional internals that may not exist on every
+    # keyring version.
+    backend_fqcn = f"{type(backend).__module__}.{type(backend).__name__}"
+    if any(
+        marker in backend_fqcn for marker in ("keyring.backends.fail.", "keyring.backends.null.")
+    ):
+        logger.info(
+            "keyring backend is %s (no usable credential store); using plaintext",
+            backend_fqcn,
+        )
+        _keyring_cache = None
+        return None
+
+    _keyring_cache = keyring  # type: ignore[assignment]
+    return _keyring_cache
+
 
 @dataclass
 class SecretRecord:

{deeptrade_quant-0.5.0 → deeptrade_quant-0.6.0}/deeptrade/core/tushare_client.py

@@ -110,6 +110,11 @@ DEFAULT_HOT_TTL_SECONDS = 6 * 3600
 # Default TTL for static class
 STATIC_TTL_SECONDS = 7 * 24 * 3600
 
+# v0.6 M9 — process-level dedup of "unknown api defaulted to trade_day_immutable"
+# log lines. Without this each call site for an unclassified API would emit a
+# fresh INFO row.
+_UNKNOWN_API_LOGGED: set[str] = set()
+
 
 # ---------------------------------------------------------------------------
 # Errors
@@ -454,6 +459,7 @@ class TushareClient:
         intraday: bool = False,
         max_retries: int = 7,
         event_cb: Callable[[str, str, dict[str, Any]], None] | None = None,
+        cache_overrides: dict[str, CacheClass] | None = None,
     ) -> None:
         self._db = db
         self._transport = transport
@@ -461,6 +467,15 @@ class TushareClient:
         self._bucket = _TokenBucket(rps)
         self._intraday = intraday
         self._event_cb = event_cb
+        # v0.6 M9 — per-instance cache classification overrides. Plugin authors
+        # supply this from their ``deeptrade_plugin.yaml::permissions.tushare_apis
+        # .cache_overrides`` so an API the framework doesn't know about can be
+        # classified correctly without monkey-patching the framework's table.
+        self._cache_overrides: dict[str, CacheClass] = dict(cache_overrides or {})
+        # One-shot INFO log dedup: each unknown api_name logs at most once
+        # per client instance (and via _UNKNOWN_API_LOGGED below, once per
+        # process across all clients).
+        self._unknown_api_logged: set[str] = set()
         # R1 (HARD CONSTRAINT): the Retrying object wraps `_do_fetch`, whose
         # FIRST line is `self._bucket.acquire()`. Every retry attempt re-enters
         # `_do_fetch`, so the token bucket is honored on every attempt — the
@@ -582,7 +597,7 @@ class TushareClient:
         # so that daily(start=A,end=B) and daily(start=C,end=D) live in
         # different cache rows even when neither passes a single trade_date.
         cache_key_date = self._compute_cache_key_date(trade_date, params)
-        cache_class = API_CACHE_CLASS.get(api_name, "trade_day_immutable")
+        cache_class = self._resolve_cache_class(api_name)
 
         state = self._read_state(api_name, cache_key_date)
         if not force_sync and self._cache_hit(
@@ -599,6 +614,39 @@ class TushareClient:
         # Apply field projection at the read site (cache stays full).
         return self._project_fields(df, fields)
 
+    def _resolve_cache_class(self, api_name: str) -> CacheClass:
+        """Pick the cache classification for ``api_name``, in priority order:
+
+        1. Plugin-supplied ``cache_overrides`` (highest priority — lets a
+           plugin author correct the framework's table without a release).
+        2. Framework-curated ``API_CACHE_CLASS`` table.
+        3. Default ``trade_day_immutable``. The default fits the quant
+           workload (historical data dominates) but is wrong for
+           intraday-mutable APIs; emit a one-shot INFO log when we fall
+           into this branch so plugin authors notice and can declare the
+           correct class in their metadata.
+        """
+        override = self._cache_overrides.get(api_name)
+        if override is not None:
+            return override
+        explicit = API_CACHE_CLASS.get(api_name)
+        if explicit is not None:
+            return explicit
+        # Default + one-shot INFO log dedup'd both per-instance and
+        # per-process so high-frequency call paths don't drown logs.
+        if api_name not in self._unknown_api_logged:
+            self._unknown_api_logged.add(api_name)
+            if api_name not in _UNKNOWN_API_LOGGED:
+                _UNKNOWN_API_LOGGED.add(api_name)
+                logger.info(
+                    "Tushare API %r has no explicit cache class; defaulting to "
+                    "trade_day_immutable. Plugin authors: declare it under "
+                    "metadata.permissions.tushare_apis.cache_overrides if this "
+                    "API returns mutable data.",
+                    api_name,
+                )
+        return "trade_day_immutable"
+
     @staticmethod
     def _compute_cache_key_date(trade_date: str | None, params: dict[str, Any]) -> str:
         """Pick a cache_key_date that uniquely partitions queries by date scope.

deeptrade_quant-0.6.0/deeptrade/plugins_api/__init__.py

@@ -0,0 +1,85 @@
+"""Public plugin API.
+
+All plugins import from this package; the rest of ``deeptrade.*`` is internal.
+
+Stable surface:
+
+* Contract:        Plugin (Protocol), PluginContext (api_version "1" and "2").
+* Metadata schema: PluginMetadata, TableSpec, MigrationSpec, PluginPermissions,
+                   TushareApiPermissions.
+* LLM profile:     StageProfile — plugin-owned preset → stage mapping.
+* Services:        LLMManager, TushareClient — construct directly from
+                   :class:`PluginContext` primitives. v0.6+ promotes these
+                   to the public surface (was: ``deeptrade.core.*`` internals).
+                   Lazy-loaded via PEP 562 ``__getattr__`` so ``TushareClient``
+                   never drags ``pandas`` onto framework startup (the
+                   ``plugin-runtime`` extras separation depends on this).
+* Errors:          render_exception — DEEPTRADE_DEBUG-aware formatter for
+                   dispatch tails; debug_enabled — env-flag probe.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from deeptrade.plugins_api.base import Plugin, PluginContext
+from deeptrade.plugins_api.errors import debug_enabled, render_exception
+from deeptrade.plugins_api.llm import StageProfile
+from deeptrade.plugins_api.metadata import (
+    MigrationSpec,
+    PluginMetadata,
+    PluginPermissions,
+    TableSpec,
+    TushareApiPermissions,
+)
+
+if TYPE_CHECKING:  # pragma: no cover — import-time hint only
+    from deeptrade.core.llm_manager import LLMManager
+    from deeptrade.core.tushare_client import TushareClient
+
+__all__ = [
+    "LLMManager",
+    "MigrationSpec",
+    "Plugin",
+    "PluginContext",
+    "PluginMetadata",
+    "PluginPermissions",
+    "StageProfile",
+    "TableSpec",
+    "TushareApiPermissions",
+    "TushareClient",
+    "debug_enabled",
+    "render_exception",
+]
+
+
+# PEP 562 lazy attribute resolution.
+#
+# Eagerly importing ``deeptrade.core.tushare_client`` here would pull
+# ``pandas`` into every framework startup — but ``pandas`` is intentionally
+# NOT a framework dependency (see ``pyproject.toml::optional-dependencies
+# .plugin-runtime``). Wheels published to PyPI install with only the 11
+# framework deps; plugins that need TushareClient install pandas via their
+# own ``deeptrade_plugin.yaml::dependencies``.
+#
+# Resolving ``LLMManager`` / ``TushareClient`` on first attribute access
+# keeps the public surface promise (you can ``from deeptrade.plugins_api
+# import TushareClient``) while preserving the import-time invariant.
+_LAZY_IMPORTS: dict[str, tuple[str, str]] = {
+    "LLMManager": ("deeptrade.core.llm_manager", "LLMManager"),
+    "TushareClient": ("deeptrade.core.tushare_client", "TushareClient"),
+}
+
+
+def __getattr__(name: str) -> Any:
+    target = _LAZY_IMPORTS.get(name)
+    if target is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    import importlib  # noqa: PLC0415
+
+    module = importlib.import_module(target[0])
+    return getattr(module, target[1])
+
+
+def __dir__() -> list[str]:
+    return sorted(__all__)

{deeptrade_quant-0.5.0 → deeptrade_quant-0.6.0}/deeptrade/plugins_api/base.py

@@ -1,4 +1,4 @@
-"""Plugin contract — api_version "1".
+"""Plugin contract — api_version "1" (legacy) and "2" (v0.6+).
 
 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
@@ -6,7 +6,19 @@ 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).
+plugin's ``validate_static`` (during install). v0.6 ``api_version="2"``
+plugins ALSO receive it at dispatch time, removing the need to reach into
+``deeptrade.core.*`` from plugin code.
+
+Dispatch signatures by ``api_version``:
+
+* ``"1"`` — ``def dispatch(self, argv: list[str]) -> int`` (legacy).
+  Plugin reaches back into ``deeptrade.core.*`` for DB / config / etc.
+* ``"2"`` — ``def dispatch(self, ctx: PluginContext, argv: list[str]) -> int``.
+  Framework hands the same ``PluginContext`` shape ``validate_static``
+  gets, so plugins can stay on the public surface.
+
+Both versions remain supported; v0.6 does NOT deprecate v1.
 """
 
 from __future__ import annotations
@@ -49,9 +61,14 @@ class Plugin(Protocol):
         install (the framework will roll back).
         """
 
-    def dispatch(self, argv: list[str]) -> int:
+    def dispatch(self, *args: object) -> int:
         """CLI dispatch entry point.
 
+        Signature depends on ``metadata.api_version``:
+
+        * ``"1"`` — ``dispatch(self, argv: list[str]) -> int``.
+        * ``"2"`` — ``dispatch(self, ctx: PluginContext, argv: list[str]) -> int``.
+
         ``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
@@ -59,4 +76,10 @@ class Plugin(Protocol):
 
         The plugin owns parsing, ``--help`` rendering, execution, persistence,
         and output. Returns the process exit code (0 = success).
+
+        The Protocol is declared variadic so ``isinstance(obj, Plugin)`` works
+        for both v1 and v2 implementations — ``runtime_checkable`` only
+        verifies attribute presence, never argument arity. The framework's
+        ``cli._dispatch`` decides which form to call based on
+        ``metadata.api_version``.
         """