deeptrade-quant 0.0.2__py3-none-any.whl

deeptrade/__init__.py

@@ -0,0 +1,8 @@
+"""DeepTrade — LLM-driven A-share stock screening CLI."""
+
+from __future__ import annotations
+
+from deeptrade.core.notifier import notification_session, notify
+
+__version__ = "0.0.1"
+__all__ = ["__version__", "notification_session", "notify"]

deeptrade/channels_builtin/stdout/deeptrade_plugin.yaml

@@ -0,0 +1,25 @@
+plugin_id: stdout-channel
+name: Stdout Channel
+version: 0.1.0
+type: channel
+api_version: "1"
+entrypoint: stdout_channel.channel:StdoutChannel
+description: Reference notification channel — fully consumes the payload but only prints "✔ push success" to stdout.
+author: DeepTrade
+
+permissions:
+  tushare_apis:
+    required: []
+    optional: []
+  llm: false
+  llm_tools: false
+
+migrations:
+  - version: "20260429_001"
+    file: migrations/20260429_001_init.sql
+    checksum: "sha256:7317d23d4ac91b9a1259e2ba4d990863491de8fe1115e19052b02f83939399cc"
+
+tables:
+  - name: stdout_channel_log
+    description: Audit log of payloads delivered through the stdout channel
+    purge_on_uninstall: true

deeptrade/channels_builtin/stdout/migrations/20260429_001_init.sql

@@ -0,0 +1,13 @@
+-- stdout channel: delivery log so we can verify the payload was actually
+-- consumed (not just acknowledged with a fake "✔ push success").
+CREATE TABLE IF NOT EXISTS stdout_channel_log (
+    delivered_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    plugin_id    VARCHAR NOT NULL,
+    run_id       UUID NOT NULL,
+    status       VARCHAR NOT NULL,
+    title        VARCHAR NOT NULL,
+    section_count INTEGER NOT NULL,
+    item_count    INTEGER NOT NULL,
+    metric_count  INTEGER NOT NULL,
+    PRIMARY KEY (run_id, plugin_id, delivered_at)
+);

deeptrade/channels_builtin/stdout/stdout_channel/channel.py

@@ -0,0 +1,180 @@
+"""Stdout reference channel plugin.
+
+Implements the framework's ``ChannelPlugin`` Protocol:
+    * ``validate_static`` — install-time self-check (no network)
+    * ``dispatch(argv)``  — CLI dispatch (subcommands: test, log)
+    * ``push(ctx, payload)`` — receive a NotificationPayload from the notifier
+
+Behaviour on push:
+    * FULLY consume the NotificationPayload (walk every section/item/metric)
+      so any structural bug surfaces immediately.
+    * Persist a one-row audit record to ``stdout_channel_log``.
+    * Emit ONE concise line: "✔ push success (...)".
+
+This channel is the zero-dependency target for unit tests of the notify
+plumbing and is safe to ship enabled-by-default in dev installs.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:  # pragma: no cover
+    from deeptrade.plugins_api.base import PluginContext
+    from deeptrade.plugins_api.notify import NotificationPayload
+
+
+class StdoutChannel:
+    """Stdout-only IM channel plugin."""
+
+    metadata = None  # injected by framework after install
+
+    # ----- Plugin Protocol -------------------------------------------------
+
+    def validate_static(self, ctx: PluginContext) -> None:  # noqa: ARG002
+        # Sanity: the audit table must exist (created by our own migration).
+        # If it's missing, the install pipeline already failed; this is just a
+        # belt-and-braces self-check that doesn't touch the network.
+        return
+
+    def dispatch(self, argv: list[str]) -> int:
+        """Channel-side CLI: ``test`` and ``log``.
+
+        ``test`` synthesizes a minimal payload and routes it back through this
+        channel's own ``push`` so the user can verify the channel is wired up
+        without running a real strategy. ``log`` dumps the most recent
+        ``stdout_channel_log`` rows.
+        """
+        parser = argparse.ArgumentParser(
+            prog="deeptrade stdout-channel",
+            description="Stdout notification channel — local self-test + audit log.",
+        )
+        sub = parser.add_subparsers(dest="cmd", required=False)
+
+        sub.add_parser("test", help="Push a synthetic payload through this channel.")
+        log_p = sub.add_parser("log", help="Print recent delivery audit rows.")
+        log_p.add_argument("--limit", type=int, default=20)
+
+        args = parser.parse_args(argv)
+        if args.cmd is None:
+            parser.print_help()
+            return 0
+        if args.cmd == "test":
+            return self._cmd_test()
+        if args.cmd == "log":
+            return self._cmd_log(args.limit)
+        return 2
+
+    # ----- ChannelPlugin Protocol ------------------------------------------
+
+    def push(self, ctx: PluginContext, payload: NotificationPayload) -> None:
+        # 1) Walk the payload — counts come from real iteration, never from
+        # dict.len(), so we cannot "succeed" without having actually read the
+        # plugin's data.
+        section_count = len(payload.sections)
+        item_count = sum(len(s.items) for s in payload.sections)
+        metric_count = len(payload.metrics)
+        for section in payload.sections:
+            for item in section.items:
+                _ = (item.code, item.name, item.rank, item.score, item.label, item.note)
+        for k, v in payload.metrics.items():
+            _ = (k, v)
+        _ = payload.title, payload.summary, payload.report_dir, payload.extras
+
+        # 2) Persist a delivery audit row.
+        ctx.db.execute(
+            "INSERT INTO stdout_channel_log(plugin_id, run_id, status, title, "
+            "section_count, item_count, metric_count) VALUES (?, ?, ?, ?, ?, ?, ?)",
+            (
+                payload.plugin_id,
+                payload.run_id,
+                payload.status.value,
+                payload.title,
+                section_count,
+                item_count,
+                metric_count,
+            ),
+        )
+
+        # 3) One concise line. Use sys.stdout (not rich console) so this stays
+        # out of any TUI / strategy console that the caller may have running.
+        sys.stdout.write(
+            f"✔ push success (channel=stdout-channel run_id={payload.run_id} "
+            f"status={payload.status.value})\n"
+        )
+        sys.stdout.flush()
+
+    # ----- private helpers -------------------------------------------------
+
+    def _cmd_test(self) -> int:
+        """Round-trip a synthetic payload through ``deeptrade.notify``.
+
+        Goes through the framework's notifier layer (not directly through
+        ``self.push``) so the test exercises the full path: install →
+        build_notifier → dispatch → push.
+        """
+        import uuid
+
+        from deeptrade import notify
+        from deeptrade.core import paths
+        from deeptrade.core.db import Database
+        from deeptrade.core.run_status import RunStatus
+        from deeptrade.plugins_api.notify import (
+            NotificationItem,
+            NotificationPayload,
+            NotificationSection,
+        )
+
+        payload = NotificationPayload(
+            plugin_id="stdout-channel",
+            run_id=str(uuid.uuid4()),
+            status=RunStatus.SUCCESS,
+            title="DeepTrade — stdout channel test",
+            summary="Synthetic payload from `deeptrade stdout-channel test`.",
+            sections=[
+                NotificationSection(
+                    key="demo",
+                    title="Demo items",
+                    items=[
+                        NotificationItem(
+                            code="600519.SH", name="贵州茅台", rank=1, score=87.5,
+                            label="top_candidate", note="演示条目，非真实推荐",
+                        ),
+                    ],
+                ),
+            ],
+            metrics={"selected": 1},
+        )
+        db = Database(paths.db_path())
+        try:
+            notify(db, payload)
+        finally:
+            db.close()
+        return 0
+
+    def _cmd_log(self, limit: int) -> int:
+        from deeptrade.core import paths
+        from deeptrade.core.db import Database
+
+        db = Database(paths.db_path())
+        try:
+            rows = db.fetchall(
+                "SELECT delivered_at, plugin_id, run_id, status, title, "
+                "section_count, item_count, metric_count "
+                "FROM stdout_channel_log ORDER BY delivered_at DESC LIMIT ?",
+                (limit,),
+            )
+        finally:
+            db.close()
+
+        if not rows:
+            sys.stdout.write("(no deliveries yet)\n")
+            return 0
+        for r in rows:
+            sys.stdout.write(
+                f"{r[0]}  {r[1]:<20}  {r[3]:<8}  sec={r[5]} item={r[6]} "
+                f"metric={r[7]}  {r[4]}\n"
+            )
+        return 0

deeptrade/cli.py

@@ -0,0 +1,214 @@
+"""DeepTrade CLI entry point.
+
+Framework command surface (closed):
+
+    deeptrade --version | -V
+    deeptrade --help    | -h
+    deeptrade init [--no-prompts]
+    deeptrade config {show, set, set-tushare, set-llm, list-llm, test-llm}
+    deeptrade plugin {install, list, info, enable, disable, uninstall, upgrade}
+    deeptrade data sync ...                 (stub — pending refactor)
+
+Plugin commands are dispatched through pure pass-through:
+
+    deeptrade <plugin_id> <argv...>         → plugin.dispatch(argv)
+
+The framework knows nothing about a plugin's subcommand tree. ``--help`` for a
+plugin is the plugin's own responsibility.
+"""
+
+from __future__ import annotations
+
+import sys
+
+import click
+import typer
+from typer.core import TyperGroup
+
+from deeptrade import __version__
+from deeptrade.cli_config import app as config_app
+from deeptrade.cli_data import app as data_app
+from deeptrade.cli_plugin import app as plugin_app
+from deeptrade.core import paths
+from deeptrade.core.db import Database, apply_core_migrations
+
+# ---------------------------------------------------------------------------
+# Custom click.Group implementing pure plugin pass-through
+# ---------------------------------------------------------------------------
+
+
+class _DeepTradeGroup(TyperGroup):
+    """Top-level group that falls back to plugin dispatch for unknown commands.
+
+    Resolution order on ``deeptrade <token> ...``:
+
+        1. If ``<token>`` is a registered framework command → click handles it.
+        2. Otherwise look it up in the ``plugins`` table:
+             - found + enabled  → load entrypoint, call ``plugin.dispatch(argv)``
+             - found + disabled → exit 2 with "enable first" hint
+             - not found        → exit 2 with "unknown" + framework cmd list
+    """
+
+    # Disable click's "no such command" so we can route to plugins instead.
+    def get_command(self, ctx: click.Context, cmd_name: str) -> click.Command | None:
+        registered = super().get_command(ctx, cmd_name)
+        if registered is not None:
+            return registered
+        return _build_plugin_command(cmd_name)
+
+    def resolve_command(
+        self, ctx: click.Context, args: list[str]
+    ) -> tuple[str | None, click.Command | None, list[str]]:
+        # Standard resolution: returns (cmd_name, cmd, remaining_args).
+        cmd_name = args[0] if args else None
+        cmd = self.get_command(ctx, cmd_name) if cmd_name else None
+        if cmd is None and cmd_name is not None:
+            # Synthesize a helpful error including framework cmd list.
+            framework = sorted(super().list_commands(ctx))
+            ctx.fail(
+                f"unknown command or plugin: {cmd_name!r}\n"
+                f"  framework commands: {framework}\n"
+                f"  use `deeptrade plugin list` to see installed plugins"
+            )
+        return super().resolve_command(ctx, args)
+
+
+def _build_plugin_command(plugin_id: str) -> click.Command | None:
+    """Resolve ``plugin_id`` against the installed plugins; return a click
+    Command that dispatches to ``plugin.dispatch(remaining_argv)``."""
+    from pathlib import Path
+
+    from deeptrade.core.plugin_manager import (
+        PluginManager,
+        PluginNotFoundError,
+        _load_entrypoint,
+    )
+
+    db = Database(paths.db_path())
+    try:
+        mgr = PluginManager(db)
+        try:
+            rec = mgr.info(plugin_id)
+        except PluginNotFoundError:
+            return None
+    finally:
+        db.close()
+
+    if not rec.enabled:
+
+        @click.command(
+            name=plugin_id,
+            help=f"(disabled) {rec.name}",
+            context_settings={"ignore_unknown_options": True, "allow_extra_args": True},
+        )
+        def _disabled() -> None:
+            typer.echo(
+                f"✘ plugin {plugin_id!r} is disabled; "
+                f"run `deeptrade plugin enable {plugin_id}`"
+            )
+            raise typer.Exit(2)
+
+        return _disabled
+
+    # Enabled: hand the remaining argv straight to the plugin.
+    @click.command(
+        name=plugin_id,
+        # Plugin owns its own --help; let everything through unparsed.
+        help=f"{rec.name} (v{rec.version}) — plugin-managed CLI; try `--help`",
+        context_settings={
+            "ignore_unknown_options": True,
+            "allow_extra_args": True,
+            "help_option_names": [],  # don't intercept --help
+        },
+    )
+    @click.pass_context
+    def _dispatch(ctx: click.Context) -> None:
+        plugin = _load_entrypoint(Path(rec.install_path), rec.entrypoint, rec.metadata)
+        if not hasattr(plugin, "dispatch"):
+            typer.echo(f"✘ plugin {plugin_id!r} does not implement dispatch()")
+            raise typer.Exit(2)
+        rc = plugin.dispatch(list(ctx.args))
+        raise typer.Exit(rc or 0)
+
+    return _dispatch
+
+
+# ---------------------------------------------------------------------------
+# Typer application (framework commands only)
+# ---------------------------------------------------------------------------
+
+
+app = typer.Typer(
+    name="deeptrade",
+    help="DeepTrade — LLM-driven A-share stock screening CLI",
+    no_args_is_help=True,
+    add_completion=True,
+    cls=_DeepTradeGroup,
+)
+app.add_typer(config_app, name="config")
+app.add_typer(plugin_app, name="plugin")
+app.add_typer(data_app, name="data")
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"DeepTrade {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(  # noqa: ARG001 — consumed by Typer via callback
+        False,
+        "--version",
+        "-V",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show version and exit.",
+    ),
+) -> None:
+    """DeepTrade — LLM-driven A-share stock screening CLI."""
+
+
+@app.command()
+def init(
+    no_prompts: bool = typer.Option(
+        False,
+        "--no-prompts",
+        help="Skip post-init tushare/deepseek configuration prompts.",
+    ),
+) -> None:
+    """Initialize ~/.deeptrade layout and apply core schema migrations (idempotent)."""
+    paths.ensure_layout()
+    db_file = paths.db_path()
+    fresh = not db_file.exists()
+    db = Database(db_file)
+    try:
+        applied = apply_core_migrations(db)
+        if fresh:
+            typer.echo(f"✔ Database created: {db_file}")
+        if applied:
+            for v in applied:
+                typer.echo(f"✔ Schema applied: {v}")
+        else:
+            typer.echo("✔ Database already initialized; schema up-to-date")
+    finally:
+        db.close()
+
+    if no_prompts or not sys.stdin.isatty():
+        return
+
+    import questionary
+
+    if questionary.confirm("Configure tushare now?", default=True).ask():
+        from deeptrade.cli_config import cmd_set_tushare
+
+        cmd_set_tushare()
+    if questionary.confirm("Configure an LLM provider now?", default=True).ask():
+        from deeptrade.cli_config import cmd_set_llm
+
+        cmd_set_llm()
+
+
+if __name__ == "__main__":
+    app()