deeptrade-quant 0.0.2__py3-none-any.whl

deeptrade/core/llm_manager.py

@@ -0,0 +1,174 @@
+"""LLM Manager — framework-level service for multi-provider LLM access.
+
+DESIGN §0.7 + §10. The manager is the **only** path plugins should use to
+obtain an ``LLMClient``. It provides:
+
+    * ``list_providers()``      — names of currently usable providers
+    * ``get_provider_info()``   — display metadata (no api_key)
+    * ``get_client()``          — a fully-wired ``LLMClient`` for one provider
+
+Multiple providers coexist; there is no "default" provider concept. A single
+plugin may call ``get_client("deepseek", ...)`` and ``get_client("kimi", ...)``
+in the same run and treat them as independent clients.
+
+Thread safety
+-------------
+**Not thread-safe.** Cached ``LLMClient`` instances are shared by callers
+holding the same ``LLMManager`` and asking for the same
+``(name, plugin_id, run_id)`` triple. The underlying ``OpenAI`` SDK + httpx
+pool is itself thread-safe, but ``LLMClient.complete_json()`` writes to the
+shared DB connection (``llm_calls`` audit) and ``llm_calls.jsonl`` file —
+those are **not** serialized inside the client. Callers wanting parallel
+LLM calls must either:
+
+    * use a separate ``LLMManager`` per worker thread, or
+    * serialize their ``complete_json`` calls externally with a lock.
+
+Inside a single-threaded plugin run (the default), caching strictly improves
+performance (one transport per provider) with no correctness risk.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from deeptrade.core.llm_client import LLMClient, _select_transport_class
+
+if TYPE_CHECKING:  # pragma: no cover
+    from deeptrade.core.config import ConfigService
+    from deeptrade.core.db import Database
+
+
+class LLMNotConfiguredError(RuntimeError):
+    """Raised when a provider is not configured, or its ``api_key`` is missing.
+
+    Distinct from a generic ``KeyError`` so callers can branch on this
+    specifically (e.g. CLI returns a friendly hint pointing at
+    ``deeptrade config set-llm``).
+    """
+
+
+@dataclass(frozen=True)
+class LLMProviderInfo:
+    """Display metadata for a provider; intentionally excludes ``api_key``
+    so this can be safely logged or shown in a TUI.
+    """
+
+    name: str
+    model: str
+    base_url: str
+
+
+_CacheKey = tuple[str, str, str | None]
+
+
+class LLMManager:
+    """Framework-level LLM access for plugins.
+
+    Construction is cheap (no network IO, no client building); the actual
+    ``OpenAI`` transport is created lazily on the first ``get_client()`` for
+    a given ``(name, plugin_id, run_id)`` and then cached on this manager.
+    """
+
+    def __init__(self, db: Database, config: ConfigService) -> None:
+        self._db = db
+        self._config = config
+        self._cache: dict[_CacheKey, LLMClient] = {}
+
+    # ------------------------------------------------------------------
+    # Listing / introspection
+    # ------------------------------------------------------------------
+
+    def list_providers(self) -> list[str]:
+        """Names of providers that are configured AND have an api_key set.
+
+        Filtering by api_key prevents callers from receiving a name that
+        will 401 at the first ``complete_json`` call. Returned list is
+        sorted for determinism.
+        """
+        cfg = self._config.get_app_config()
+        out: list[str] = []
+        for name in sorted(cfg.llm_providers.keys()):
+            if self._config.get(f"llm.{name}.api_key"):
+                out.append(name)
+        return out
+
+    def get_provider_info(self, name: str) -> LLMProviderInfo:
+        """Return display metadata for ``name``.
+
+        Raises ``LLMNotConfiguredError`` if the provider is not in
+        ``llm.providers``. Does NOT check that an api_key is set — this
+        method is intentionally usable for inspecting partially-configured
+        entries (e.g. listing for an "edit existing" CLI flow).
+        """
+        cfg = self._config.get_app_config()
+        provider = cfg.llm_providers.get(name)
+        if provider is None:
+            raise LLMNotConfiguredError(
+                f"LLM provider {name!r} is not configured; "
+                "run `deeptrade config set-llm` to add it"
+            )
+        return LLMProviderInfo(name=name, model=provider.model, base_url=provider.base_url)
+
+    # ------------------------------------------------------------------
+    # Client construction
+    # ------------------------------------------------------------------
+
+    def get_client(
+        self,
+        name: str,
+        *,
+        plugin_id: str,
+        run_id: str | None = None,
+        reports_dir: Path | None = None,
+    ) -> LLMClient:
+        """Return an ``LLMClient`` bound to provider ``name``.
+
+        Cached by ``(name, plugin_id, run_id)`` for the lifetime of this
+        manager — repeated calls during a single run reuse the same
+        transport / httpx pool.
+
+        Raises:
+            LLMNotConfiguredError — provider not in ``llm.providers``, or
+                its ``llm.<name>.api_key`` is unset.
+        """
+        cache_key: _CacheKey = (name, plugin_id, run_id)
+        cached = self._cache.get(cache_key)
+        if cached is not None:
+            return cached
+
+        cfg = self._config.get_app_config()
+        provider = cfg.llm_providers.get(name)
+        if provider is None:
+            raise LLMNotConfiguredError(
+                f"LLM provider {name!r} is not configured; "
+                "run `deeptrade config set-llm` to add it"
+            )
+        api_key = self._config.get(f"llm.{name}.api_key")
+        if not api_key:
+            raise LLMNotConfiguredError(
+                f"LLM provider {name!r} has no api_key set; "
+                f"run `deeptrade config set-llm` and choose {name!r}"
+            )
+
+        transport_cls = _select_transport_class(provider.base_url)
+        transport = transport_cls(
+            api_key=str(api_key),
+            base_url=provider.base_url,
+            timeout=provider.timeout,
+        )
+        # v0.7 — LLMClient no longer holds a profile set; the per-call
+        # ``StageProfile`` is supplied by the plugin at ``complete_json`` time.
+        client = LLMClient(
+            self._db,
+            transport,
+            model=provider.model,
+            plugin_id=plugin_id,
+            run_id=run_id,
+            audit_full_payload=cfg.llm_audit_full_payload,
+            reports_dir=reports_dir,
+        )
+        self._cache[cache_key] = client
+        return client

deeptrade/core/logging_config.py

@@ -0,0 +1,61 @@
+"""Logging configuration with file rotation.
+
+ADR-006: log records go to STDERR (avoiding stdout where questionary lives) and
+to a rotating file under ~/.deeptrade/logs/.
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+from logging.handlers import RotatingFileHandler
+
+from deeptrade.core import paths
+
+DEFAULT_LOG_FILENAME = "deeptrade.log"
+DEFAULT_MAX_BYTES = 5 * 1024 * 1024  # 5 MB per file
+DEFAULT_BACKUP_COUNT = 5
+
+
+def setup_logging(
+    *,
+    level: str = "INFO",
+    log_filename: str = DEFAULT_LOG_FILENAME,
+    max_bytes: int = DEFAULT_MAX_BYTES,
+    backup_count: int = DEFAULT_BACKUP_COUNT,
+) -> None:
+    """Configure root logger with stderr + rotating file handler.
+
+    Idempotent — calling twice replaces existing deeptrade handlers.
+    """
+    root = logging.getLogger()
+    # Remove any prior deeptrade-tagged handlers so configure-after-init works
+    for h in list(root.handlers):
+        if getattr(h, "_deeptrade", False):
+            root.removeHandler(h)
+
+    fmt = logging.Formatter(
+        "%(asctime)s [%(levelname).1s] %(name)s: %(message)s",
+        datefmt="%H:%M:%S",
+    )
+
+    # stderr (so stdout stays clean for questionary / dashboards)
+    stderr_h = logging.StreamHandler(stream=sys.stderr)
+    stderr_h.setFormatter(fmt)
+    stderr_h._deeptrade = True  # type: ignore[attr-defined]
+    root.addHandler(stderr_h)
+
+    # rotating file under ~/.deeptrade/logs/
+    log_dir = paths.logs_dir()
+    log_dir.mkdir(parents=True, exist_ok=True)
+    file_h = RotatingFileHandler(
+        log_dir / log_filename,
+        maxBytes=max_bytes,
+        backupCount=backup_count,
+        encoding="utf-8",
+    )
+    file_h.setFormatter(fmt)
+    file_h._deeptrade = True  # type: ignore[attr-defined]
+    root.addHandler(file_h)
+
+    root.setLevel(level)

deeptrade/core/migrations/core/20260427_001_init.sql

@@ -0,0 +1,121 @@
+-- DeepTrade core schema initial migration.
+--
+-- Scope: ONLY framework-owned tables. Plugin-owned tables (including any
+-- tushare-derived business tables like stock_basic / daily / moneyflow) are
+-- declared by each plugin in its own deeptrade_plugin.yaml + migrations/*.sql
+-- and applied via plugin_schema_migrations (per-plugin tracking). The
+-- framework never owns business data tables.
+
+-- ============================================================
+-- Framework configuration & secrets
+-- ============================================================
+
+-- Non-secret app config
+CREATE TABLE IF NOT EXISTS app_config (
+    key         VARCHAR PRIMARY KEY,
+    value_json  VARCHAR NOT NULL,
+    is_secret   BOOLEAN DEFAULT FALSE,
+    updated_at  TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+-- Encrypted secrets (keyring-backed; plaintext fallback when keyring unavailable)
+CREATE TABLE IF NOT EXISTS secret_store (
+    key                VARCHAR PRIMARY KEY,
+    encrypted_value    BLOB    NOT NULL,
+    encryption_method  VARCHAR NOT NULL,        -- 'keyring' | 'plaintext'
+    updated_at         TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+-- ============================================================
+-- Framework schema-migration tracking
+-- ============================================================
+
+CREATE TABLE IF NOT EXISTS schema_migrations (
+    version    VARCHAR PRIMARY KEY,
+    applied_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+-- ============================================================
+-- Plugin registry
+-- ============================================================
+
+CREATE TABLE IF NOT EXISTS plugins (
+    plugin_id     VARCHAR PRIMARY KEY,
+    name          VARCHAR NOT NULL,
+    version       VARCHAR NOT NULL,
+    type          VARCHAR NOT NULL,             -- 'strategy' | 'channel' | future
+    api_version   VARCHAR NOT NULL,
+    entrypoint    VARCHAR NOT NULL,
+    install_path  VARCHAR NOT NULL,
+    enabled       BOOLEAN NOT NULL DEFAULT TRUE,
+    metadata_yaml VARCHAR NOT NULL,
+    installed_at  TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at    TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS plugin_tables (
+    plugin_id  VARCHAR NOT NULL,
+    table_name VARCHAR NOT NULL,
+    description VARCHAR,
+    purge_on_uninstall BOOLEAN NOT NULL DEFAULT TRUE,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    PRIMARY KEY (plugin_id, table_name)
+);
+
+CREATE TABLE IF NOT EXISTS plugin_schema_migrations (
+    plugin_id   VARCHAR NOT NULL,
+    version     VARCHAR NOT NULL,
+    checksum    VARCHAR NOT NULL,
+    applied_at  TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    PRIMARY KEY (plugin_id, version)
+);
+
+-- ============================================================
+-- Framework service audit / cache state
+-- ============================================================
+
+-- LLM call audit (LLMClient writes; per-plugin scoped via plugin_id column).
+-- v0.7 dropped the `stage` column — see migration 20260501_002.
+CREATE TABLE IF NOT EXISTS llm_calls (
+    call_id           UUID PRIMARY KEY,
+    run_id            UUID,
+    plugin_id         VARCHAR,
+    model             VARCHAR,
+    prompt_hash       VARCHAR,
+    input_tokens      BIGINT,
+    output_tokens     BIGINT,
+    latency_ms        INTEGER,
+    request_json      VARCHAR,
+    response_json     VARCHAR,
+    validation_status VARCHAR,
+    error             VARCHAR,
+    created_at        TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+-- Tushare sync idempotency state, per (plugin_id, api_name, trade_date).
+-- Each plugin tracks its own sync state — plugins do not share cached
+-- payloads with each other (per pure-isolation data model).
+CREATE TABLE IF NOT EXISTS tushare_sync_state (
+    plugin_id          VARCHAR NOT NULL,
+    api_name           VARCHAR NOT NULL,
+    trade_date         VARCHAR NOT NULL,        -- '*' for non-dated APIs (e.g. stock_basic)
+    status             VARCHAR NOT NULL,        -- ok | partial | failed | unauthorized
+    row_count          BIGINT,
+    cache_class        VARCHAR NOT NULL DEFAULT 'trade_day_immutable',
+                                                -- static | trade_day_immutable | trade_day_mutable | hot_or_anns
+    ttl_seconds        INTEGER,
+    data_completeness  VARCHAR NOT NULL DEFAULT 'final',
+                                                -- final | intraday
+    synced_at          TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    PRIMARY KEY (plugin_id, api_name, trade_date)
+);
+
+-- Tushare per-call audit (per plugin)
+CREATE TABLE IF NOT EXISTS tushare_calls (
+    plugin_id   VARCHAR,
+    api_name    VARCHAR,
+    params_hash VARCHAR,
+    rows        INTEGER,
+    latency_ms  INTEGER,
+    called_at   TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);

deeptrade/core/migrations/core/20260501_002_drop_llm_calls_stage.sql

@@ -0,0 +1,10 @@
+-- v0.7 — drop llm_calls.stage column.
+--
+-- Stage 概念已彻底归插件维护：``LLMClient.complete_json`` 不再接收 stage 入
+-- 参，框架因此也不再写入这一列。历史 run 的 stage 信息仍可在
+-- ``~/.deeptrade/reports/<run_id>/llm_calls.jsonl`` 中按需查阅（旧文件不动；
+-- v0.7 起新写入的 jsonl 行也不再含 ``stage`` 键）。
+--
+-- DuckDB 1.0+ 支持 ALTER TABLE ... DROP COLUMN，且为 IF EXISTS 安全。
+
+ALTER TABLE llm_calls DROP COLUMN IF EXISTS stage;

deeptrade/core/notifier.py

@@ -0,0 +1,302 @@
+"""Notification orchestration — pure framework code, NO IM-protocol logic.
+
+Three layers compose top-down:
+
+    AsyncDispatchNotifier      ← async wrapper: queue + daemon worker + join
+        └─ MultiplexNotifier   ← fan-out + per-channel exception isolation
+              └─ ChannelPlugin instances (loaded from type=channel plugins)
+
+The framework knows nothing about feishu / dingtalk / wechat-work. Channels
+are delivered as plugins (``channels_builtin/`` mirrors ``strategies_builtin/``);
+new channels = new plugin packages, zero framework change.
+
+Top-level API (used by any plugin that needs to notify):
+
+    from deeptrade import notify, notification_session
+
+    notify(db, payload)                       # one-shot
+    with notification_session(db) as ns:      # batch
+        ns.push(p1)
+        ns.push(p2)
+
+If no channel plugins are enabled, both forms degrade to no-op silently.
+"""
+
+from __future__ import annotations
+
+import logging
+import queue
+import threading
+from collections.abc import Iterator, Sequence
+from contextlib import contextmanager
+from pathlib import Path
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:  # pragma: no cover
+    from deeptrade.core.db import Database
+    from deeptrade.core.plugin_manager import InstalledPlugin, PluginManager
+    from deeptrade.plugins_api.base import PluginContext
+    from deeptrade.plugins_api.channel import ChannelPlugin
+    from deeptrade.plugins_api.notify import NotificationPayload
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Protocol
+# ---------------------------------------------------------------------------
+
+
+@runtime_checkable
+class Notifier(Protocol):
+    """Handle exposed to callers (plugins or framework code).
+
+    Implementations MUST guarantee ``push`` returns quickly (no synchronous
+    HTTP) — the asynchrony is provided by ``AsyncDispatchNotifier``.
+    """
+
+    def is_enabled(self) -> bool: ...
+    def push(self, payload: NotificationPayload) -> None: ...
+    def join(self, timeout: float = 0.0) -> None: ...
+
+
+# ---------------------------------------------------------------------------
+# NoopNotifier — used when no channel plugin is installed/enabled
+# ---------------------------------------------------------------------------
+
+
+class NoopNotifier:
+    """Returned by ``build_notifier`` when there are no enabled channels."""
+
+    def is_enabled(self) -> bool:
+        return False
+
+    def push(self, payload: NotificationPayload) -> None:  # noqa: ARG002
+        return
+
+    def join(self, timeout: float = 0.0) -> None:  # noqa: ARG002
+        return
+
+
+# ---------------------------------------------------------------------------
+# MultiplexNotifier — fan-out to all enabled channel plugins
+# ---------------------------------------------------------------------------
+
+
+class MultiplexNotifier:
+    """Synchronous fan-out across one ChannelPlugin per channel.
+
+    Per-channel ``push`` is wrapped in ``try``/``except``: a broken/slow
+    channel never blocks or breaks the others. Consumed by
+    ``AsyncDispatchNotifier`` on a background thread, so blocking on HTTP
+    here is fine.
+    """
+
+    def __init__(self, channels: Sequence[tuple[ChannelPlugin, PluginContext]]) -> None:
+        self._channels: list[tuple[ChannelPlugin, PluginContext]] = list(channels)
+
+    def is_enabled(self) -> bool:
+        return bool(self._channels)
+
+    def push(self, payload: NotificationPayload) -> None:
+        for ch, ctx in self._channels:
+            try:
+                ch.push(ctx, payload)
+            except Exception as e:  # noqa: BLE001 — single-channel isolation
+                pid = getattr(getattr(ch, "metadata", None), "plugin_id", "?")
+                logger.warning("channel %s push failed: %s", pid, e)
+
+    def join(self, timeout: float = 0.0) -> None:  # noqa: ARG002
+        return
+
+
+# ---------------------------------------------------------------------------
+# AsyncDispatchNotifier — wraps a synchronous Notifier in a worker thread
+# ---------------------------------------------------------------------------
+
+
+class _Shutdown:
+    """Sentinel value placed on the queue to signal worker shutdown."""
+
+
+_SHUTDOWN = _Shutdown()
+
+
+class AsyncDispatchNotifier:
+    """Non-blocking adapter: ``push()`` enqueues and returns immediately;
+    a daemon worker thread drains the queue and calls the inner notifier.
+
+    Invariants:
+        * ``push`` MUST NOT block on HTTP. ``put_nowait`` raises Queue.Full
+          if the queue is saturated → drop + warn; never block the caller.
+        * ``join(timeout)`` MUST be called before process exit to flush
+          in-flight payloads (worker is daemon, would be killed otherwise).
+        * Worker exceptions are caught — a broken inner notifier never kills
+          the worker thread.
+    """
+
+    DEFAULT_QUEUE_SIZE = 16
+    DEFAULT_JOIN_TIMEOUT = 10.0  # seconds
+
+    def __init__(
+        self,
+        inner: Notifier,
+        *,
+        queue_size: int = DEFAULT_QUEUE_SIZE,
+    ) -> None:
+        self._inner = inner
+        self._queue: queue.Queue[NotificationPayload | _Shutdown] = queue.Queue(queue_size)
+        self._dispatched_count = 0
+        self._dropped_count = 0
+        self._lock = threading.Lock()
+        self._thread = threading.Thread(
+            target=self._worker, name="deeptrade-notify", daemon=True
+        )
+        self._started = False
+
+    def is_enabled(self) -> bool:
+        return self._inner.is_enabled()
+
+    def push(self, payload: NotificationPayload) -> None:
+        if not self.is_enabled():
+            return
+        if not self._started:
+            self._started = True
+            self._thread.start()
+        try:
+            self._queue.put_nowait(payload)
+        except queue.Full:
+            with self._lock:
+                self._dropped_count += 1
+            logger.warning(
+                "notify queue full (size=%d); dropping payload run_id=%s",
+                self._queue.maxsize,
+                payload.run_id,
+            )
+
+    def join(self, timeout: float = DEFAULT_JOIN_TIMEOUT) -> None:
+        """Block until the queue drains or ``timeout`` seconds elapse.
+        Always call this once before process exit. Idempotent."""
+        if not self._started:
+            return
+        try:
+            self._queue.put(_SHUTDOWN, timeout=max(0.1, timeout))
+        except queue.Full:  # pragma: no cover
+            logger.warning("notify queue full while signaling shutdown")
+            return
+        self._thread.join(timeout=timeout)
+        if self._thread.is_alive():
+            logger.warning(
+                "notify worker did not finish within %.1fs; in-flight payload may be lost",
+                timeout,
+            )
+
+    @property
+    def dispatched_count(self) -> int:
+        with self._lock:
+            return self._dispatched_count
+
+    @property
+    def dropped_count(self) -> int:
+        with self._lock:
+            return self._dropped_count
+
+    def _worker(self) -> None:
+        while True:
+            item = self._queue.get()
+            if isinstance(item, _Shutdown):
+                return
+            try:
+                self._inner.push(item)
+            except Exception as e:  # noqa: BLE001 — keep worker alive
+                logger.warning("notify worker caught inner.push exception: %s", e)
+            else:
+                with self._lock:
+                    self._dispatched_count += 1
+
+
+# ---------------------------------------------------------------------------
+# Discovery + assembly
+# ---------------------------------------------------------------------------
+
+
+def build_notifier(db: Database, plugin_manager: PluginManager) -> Notifier:
+    """Discover all enabled ``type=channel`` plugins and assemble a Notifier.
+
+    Returns a ``NoopNotifier`` if no channels are enabled (zero-cost path).
+    Returns an ``AsyncDispatchNotifier`` wrapping a ``MultiplexNotifier``
+    otherwise. Channel plugin entrypoint load failures are logged and the
+    affected channel is skipped — one bad channel never breaks the others.
+    """
+    from deeptrade.core.config import ConfigService  # avoid circular import
+    from deeptrade.core.plugin_manager import _load_entrypoint
+    from deeptrade.plugins_api.base import PluginContext
+
+    channel_records: list[InstalledPlugin] = [
+        r for r in plugin_manager.list_all() if r.type == "channel" and r.enabled
+    ]
+    if not channel_records:
+        return NoopNotifier()
+
+    pairs: list[tuple[ChannelPlugin, PluginContext]] = []
+    for rec in channel_records:
+        try:
+            instance = _load_entrypoint(Path(rec.install_path), rec.entrypoint, rec.metadata)
+        except Exception as e:  # noqa: BLE001
+            logger.warning("failed to load channel plugin %s: %s", rec.plugin_id, e)
+            continue
+        ctx = PluginContext(db=db, config=ConfigService(db), plugin_id=rec.plugin_id)
+        pairs.append((instance, ctx))
+
+    if not pairs:
+        return NoopNotifier()
+    return AsyncDispatchNotifier(MultiplexNotifier(pairs))
+
+
+# ---------------------------------------------------------------------------
+# Top-level user-facing API: notify(...) / notification_session(...)
+# ---------------------------------------------------------------------------
+
+
+def notify(db: Database, payload: NotificationPayload, *, timeout: float = 10.0) -> None:
+    """Push a single ``NotificationPayload`` through all enabled channel plugins.
+
+    Convenience one-shot: builds a notifier from the current plugin registry,
+    pushes, then joins (waits for in-flight delivery up to ``timeout``).
+
+    Silently no-op if no channel plugins are enabled. Per-channel failures
+    are isolated and logged (never raised).
+
+    For repeated calls in the same process (e.g. multiple payloads in one
+    plugin run), prefer :func:`notification_session` to avoid rebuilding the
+    notifier on every call.
+    """
+    from deeptrade.core.plugin_manager import PluginManager
+
+    notifier = build_notifier(db, PluginManager(db))
+    try:
+        notifier.push(payload)
+    finally:
+        notifier.join(timeout=timeout)
+
+
+@contextmanager
+def notification_session(db: Database, *, timeout: float = 10.0) -> Iterator[Notifier]:
+    """Context manager that yields a ``Notifier`` for batch push and joins on exit.
+
+    Use this when a plugin will push multiple payloads in one run — the
+    notifier (and its worker thread) is built once and reused.
+
+    Example:
+        with notification_session(db) as ns:
+            ns.push(payload_a)
+            ns.push(payload_b)
+        # join + cleanup happen automatically here
+    """
+    from deeptrade.core.plugin_manager import PluginManager
+
+    notifier = build_notifier(db, PluginManager(db))
+    try:
+        yield notifier
+    finally:
+        notifier.join(timeout=timeout)