deeptrade-quant 0.3.1__tar.gz → 0.4.1__tar.gz

{deeptrade_quant-0.3.1 → deeptrade_quant-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deeptrade-quant
-Version: 0.3.1
+Version: 0.4.1
 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
@@ -15,21 +15,24 @@ Requires-Dist: duckdb>=1.0
 Requires-Dist: keyring>=25.0
 Requires-Dist: openai>=1.0
 Requires-Dist: packaging>=23.0
-Requires-Dist: pandas>=2.2
 Requires-Dist: pydantic>=2.7
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: questionary>=2.0
 Requires-Dist: rich>=13.7
 Requires-Dist: tenacity>=8.0
-Requires-Dist: tushare>=1.4
 Requires-Dist: typer>=0.12
 Provides-Extra: dev
 Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pandas>=2.2; extra == 'dev'
 Requires-Dist: pre-commit>=3.7; extra == 'dev'
 Requires-Dist: pytest-mock>=3.12; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: tushare>=1.4; extra == 'dev'
 Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
+Provides-Extra: plugin-runtime
+Requires-Dist: pandas>=2.2; extra == 'plugin-runtime'
+Requires-Dist: tushare>=1.4; extra == 'plugin-runtime'
 Description-Content-Type: text/markdown
 
 # DeepTrade

{deeptrade_quant-0.3.1 → deeptrade_quant-0.4.1}/deeptrade/__init__.py

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

{deeptrade_quant-0.3.1 → deeptrade_quant-0.4.1}/deeptrade/cli_plugin.py

@@ -71,6 +71,12 @@ def cmd_install(
         None, "--ref", help="Tag / branch / sha (默认 = 该插件最新 release)"
     ),
     yes: bool = typer.Option(False, "-y", "--yes", help="Skip the confirmation prompt"),
+    no_deps: bool = typer.Option(
+        False, "--no-deps", help="Skip plugin Python dependency installation"
+    ),
+    reinstall_deps: bool = typer.Option(
+        False, "--reinstall-deps", help="Re-run installer for all deps (uv/pip --upgrade)"
+    ),
 ) -> None:
     """Install a plugin from the registry, a GitHub URL, or a local directory."""
     resolver = SourceResolver()
@@ -90,6 +96,8 @@ def cmd_install(
         typer.echo("─── 即将安装 ─────────────────────────────")
         typer.echo(f"来源: {_format_origin(resolved)}")
         typer.echo(summarize_for_install(meta, resolved.path))
+        if no_deps and meta.dependencies:
+            typer.echo("(deps install will be SKIPPED — --no-deps)")
         typer.echo("──────────────────────────────────────────")
         if not yes:
             ok = questionary.confirm("确认安装?", default=False).ask()
@@ -99,7 +107,11 @@ def cmd_install(
 
         db, mgr = _open()
         try:
-            rec = mgr.install(resolved.path)
+            rec = mgr.install(
+                resolved.path,
+                install_deps=not no_deps,
+                reinstall_deps=reinstall_deps,
+            )
         except PluginInstallError as e:
             typer.echo(f"✘ Install failed: {e}")
             raise typer.Exit(2) from e
@@ -235,6 +247,12 @@ def cmd_upgrade(
     ref: str | None = typer.Option(
         None, "--ref", help="Tag / branch / sha (默认 = 该插件最新 release)"
     ),
+    no_deps: bool = typer.Option(
+        False, "--no-deps", help="Skip plugin Python dependency installation"
+    ),
+    reinstall_deps: bool = typer.Option(
+        False, "--reinstall-deps", help="Re-run installer for all deps (uv/pip --upgrade)"
+    ),
 ) -> None:
     """Upgrade an installed plugin.
 
@@ -254,7 +272,11 @@ def cmd_upgrade(
         db, mgr = _open()
         try:
             try:
-                result = mgr.upgrade(resolved.path)
+                result = mgr.upgrade(
+                    resolved.path,
+                    install_deps=not no_deps,
+                    reinstall_deps=reinstall_deps,
+                )
             except PluginNotFoundError as e:
                 try:
                     meta = _load_metadata_yaml(resolved.path / "deeptrade_plugin.yaml")

deeptrade_quant-0.4.1/deeptrade/core/dep_installer.py

@@ -0,0 +1,225 @@
+"""Plugin dependency resolution & installation.
+
+Called by :class:`PluginManager` during install / upgrade to satisfy a
+plugin's declared third-party Python dependencies (PEP 508 specifiers
+in ``deeptrade_plugin.yaml::dependencies``).
+
+Design: ``docs/plugin_dependency_management_design.md``.
+
+Key invariants:
+  * Plugins share the framework's Python interpreter — deps must be
+    importable from ``sys.executable``'s site-packages.
+  * Installer preference: ``uv`` (with ``--python <sys.executable>``) →
+    ``python -m pip``. Both missing → :class:`DepInstallError`.
+  * Conflicts (installed version not satisfying spec) are detected at
+    install time and raised, not silently overridden.
+  * Failed installs leave any already-installed deps in the environment
+    (do not unwind — common deps would be wrongly removed).
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import shutil
+import subprocess
+import sys
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass, field
+from importlib import metadata as importlib_metadata
+
+from packaging.requirements import InvalidRequirement, Requirement
+from packaging.utils import canonicalize_name
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_TIMEOUT_SECONDS = 300
+
+
+class DepInstallError(Exception):
+    """Dependency resolution, conflict, or install-subprocess failure."""
+
+
+@dataclass
+class DepConflict:
+    requirement: Requirement
+    installed_version: str
+    owner: str  # human-readable attribution string
+
+    def __str__(self) -> str:
+        return (
+            f"{self.requirement} not satisfied by installed "
+            f"{self.requirement.name}=={self.installed_version} (owner: {self.owner})"
+        )
+
+
+@dataclass
+class DepPlan:
+    to_install: list[Requirement] = field(default_factory=list)
+    skipped: list[tuple[Requirement, str]] = field(default_factory=list)
+    conflicts: list[DepConflict] = field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# Parsing
+# ---------------------------------------------------------------------------
+
+
+def parse_specs(specs: Iterable[str]) -> list[Requirement]:
+    """Parse PEP 508 specifier strings into ``Requirement`` objects.
+
+    Rejects VCS/URL forms and duplicate package names. Same validation
+    as :meth:`PluginMetadata._dependencies_valid` — kept here so callers
+    that pre-validated metadata can reuse the parsed objects, and so
+    runtime code (not just Pydantic) reads idiomatically.
+    """
+    out: list[Requirement] = []
+    seen: dict[str, str] = {}
+    for raw in specs:
+        try:
+            req = Requirement(raw)
+        except InvalidRequirement as e:
+            raise DepInstallError(f"invalid dependency spec {raw!r}: {e}") from e
+        if req.url:
+            raise DepInstallError(
+                f"dependency {raw!r}: VCS/URL forms not allowed; use PEP 508 specifiers"
+            )
+        canonical = canonicalize_name(req.name)
+        if canonical in seen:
+            raise DepInstallError(
+                f"duplicate dependency {req.name!r} (also {seen[canonical]!r}); combine into one spec"
+            )
+        seen[canonical] = raw
+        out.append(req)
+    return out
+
+
+# ---------------------------------------------------------------------------
+# Planning (satisfied / conflict / to-install)
+# ---------------------------------------------------------------------------
+
+
+def plan_install(
+    requirements: list[Requirement],
+    *,
+    attribute_conflict: Callable[[str], str | None] | None = None,
+) -> DepPlan:
+    """Sort each requirement into ``skipped`` / ``to_install`` / ``conflicts``.
+
+    ``attribute_conflict(canonical_name)`` returns a human-readable owner
+    (e.g. ``"framework core dependency"``, ``"plugin foo"``) for the package
+    when a conflict is detected. Falls back to ``"external (already in
+    environment)"`` if ``None`` or returns ``None``.
+
+    Marker-gated requirements (``"x>=1; python_version < '3.10'"``) whose
+    marker evaluates to False in the current environment are dropped.
+    """
+    plan = DepPlan()
+    for req in requirements:
+        if req.marker is not None and not req.marker.evaluate():
+            logger.debug("Skipping %s — marker did not match current env", req)
+            continue
+        try:
+            installed = importlib_metadata.version(req.name)
+        except importlib_metadata.PackageNotFoundError:
+            plan.to_install.append(req)
+            continue
+        if not req.specifier or req.specifier.contains(installed, prereleases=True):
+            plan.skipped.append((req, installed))
+            continue
+        owner = (
+            attribute_conflict(canonicalize_name(req.name)) if attribute_conflict else None
+        ) or "external (already in environment)"
+        plan.conflicts.append(DepConflict(req, installed, owner))
+    return plan
+
+
+# ---------------------------------------------------------------------------
+# Installer detection + subprocess invocation
+# ---------------------------------------------------------------------------
+
+
+def detect_installer() -> tuple[str, list[str]]:
+    """Return ``(label, argv_prefix)`` for the chosen installer.
+
+    Prefers ``uv`` (with ``--python <sys.executable>`` so packages land in
+    the framework's interpreter). Falls back to ``python -m pip``. Raises
+    :class:`DepInstallError` if neither is available.
+    """
+    uv_path = shutil.which("uv")
+    if uv_path:
+        return ("uv", [uv_path, "pip", "install", "--python", sys.executable])
+    try:
+        pip_check = subprocess.run(  # noqa: S603 — args fully controlled
+            [sys.executable, "-m", "pip", "--version"],
+            capture_output=True,
+            text=True,
+            timeout=15,
+        )
+    except (subprocess.TimeoutExpired, FileNotFoundError):
+        pip_check = None
+    if pip_check is not None and pip_check.returncode == 0:
+        return ("pip", [sys.executable, "-m", "pip", "install"])
+    raise DepInstallError(
+        "no installer available: neither 'uv' (on PATH) nor 'pip' (python -m pip) usable"
+    )
+
+
+def run_install(
+    requirements: list[Requirement],
+    *,
+    reinstall: bool = False,
+    timeout_seconds: int | None = None,
+) -> None:
+    """Spawn the installer subprocess. Raises :class:`DepInstallError` on
+    timeout, missing binary, or non-zero exit. stdout/stderr are inherited
+    so users see pip/uv progress in real time."""
+    if not requirements:
+        return
+    label, argv = detect_installer()
+    if reinstall:
+        argv.append("--upgrade")
+    argv.extend(str(r) for r in requirements)
+    timeout = timeout_seconds if timeout_seconds is not None else _resolved_timeout()
+    logger.info(
+        "Installing %d plugin dep(s) via %s: %s",
+        len(requirements),
+        label,
+        [str(r) for r in requirements],
+    )
+    try:
+        result = subprocess.run(  # noqa: S603 — args fully controlled
+            argv,
+            timeout=timeout,
+            text=True,
+        )
+    except subprocess.TimeoutExpired as e:
+        raise DepInstallError(
+            f"dependency install timed out after {timeout}s ({label}): "
+            f"{[str(r) for r in requirements]}"
+        ) from e
+    except FileNotFoundError as e:
+        raise DepInstallError(f"installer disappeared mid-run: {e}") from e
+    if result.returncode != 0:
+        raise DepInstallError(
+            f"{label} install failed (exit {result.returncode}) for: "
+            f"{[str(r) for r in requirements]}"
+        )
+
+
+def _resolved_timeout() -> int:
+    raw = os.environ.get("DEEPTRADE_DEP_INSTALL_TIMEOUT")
+    if raw is None:
+        return DEFAULT_TIMEOUT_SECONDS
+    try:
+        v = int(raw)
+        if v <= 0:
+            raise ValueError("must be positive")
+        return v
+    except ValueError:
+        logger.warning(
+            "Invalid DEEPTRADE_DEP_INSTALL_TIMEOUT=%r; using default %ds",
+            raw,
+            DEFAULT_TIMEOUT_SECONDS,
+        )
+        return DEFAULT_TIMEOUT_SECONDS

deeptrade_quant-0.4.1/deeptrade/core/migrations/core/20260512_001_drop_legacy_tushare_cache.sql

@@ -0,0 +1,10 @@
+-- v0.4.1 — drop legacy tushare_cache_blob entries.
+--
+-- Pre-v0.4.1 payloads were stored as a bare JSON array, then read back via
+-- pd.read_json which triggered a pandas FutureWarning on string columns whose
+-- names matched its date heuristic (trade_date, cal_date, ...). The cache
+-- read/write path now wraps payloads as {version:1, schema:{...}, data:[...]}
+-- and restores dtypes explicitly. Old rows are incompatible with that reader,
+-- so wipe the table; TushareClient._ensure_cache_table re-creates it lazily on
+-- the next write.
+DROP TABLE IF EXISTS tushare_cache_blob;

{deeptrade_quant-0.3.1 → deeptrade_quant-0.4.1}/deeptrade/core/plugin_manager.py

@@ -14,14 +14,23 @@ import sys
 import textwrap
 from collections.abc import Sequence
 from dataclasses import dataclass
+from importlib import metadata as importlib_metadata
 from pathlib import Path
 from typing import Any
 
 import yaml
+from packaging.requirements import InvalidRequirement, Requirement
+from packaging.utils import canonicalize_name
 from packaging.version import InvalidVersion, Version
 
 from deeptrade.core import paths
 from deeptrade.core.db import Database
+from deeptrade.core.dep_installer import (
+    DepInstallError,
+    parse_specs,
+    plan_install,
+    run_install,
+)
 from deeptrade.plugins_api.base import Plugin
 from deeptrade.plugins_api.metadata import MigrationSpec, PluginMetadata
 
@@ -190,8 +199,15 @@ class PluginManager:
 
     # --- install -----------------------------------------------------
 
-    def install(self, source_path: Path) -> InstalledPlugin:
-        """Install a plugin from a local directory. Network never touched."""
+    def install(
+        self,
+        source_path: Path,
+        *,
+        install_deps: bool = True,
+        reinstall_deps: bool = False,
+    ) -> InstalledPlugin:
+        """Install a plugin from a local directory. Network never touched
+        by plugin code; framework may run pip/uv if ``install_deps=True``."""
         source_path = source_path.resolve()
         if not source_path.is_dir():
             raise PluginInstallError(f"source path is not a directory: {source_path}")
@@ -233,6 +249,18 @@ class PluginManager:
             shutil.rmtree(target)
         shutil.copytree(source_path, target)
 
+        # Resolve & install Python deps BEFORE migrations + entrypoint load.
+        # validate_static imports the plugin module — deps must be importable
+        # by then. On failure, just remove the copied dir; already-installed
+        # deps stay in the env (see design §4.5).
+        if install_deps:
+            try:
+                self._handle_dependencies(meta, reinstall=reinstall_deps)
+            except DepInstallError as e:
+                if target.exists():
+                    shutil.rmtree(target, ignore_errors=True)
+                raise PluginInstallError(str(e)) from e
+
         # Apply migrations + write registries inside ONE transaction.
         try:
             with self._db.transaction():
@@ -354,7 +382,13 @@ class PluginManager:
 
         return {"purged_tables": dropped, "purge": purge}
 
-    def upgrade(self, source_path: Path) -> InstalledPlugin | UpgradeNoop:
+    def upgrade(
+        self,
+        source_path: Path,
+        *,
+        install_deps: bool = True,
+        reinstall_deps: bool = False,
+    ) -> InstalledPlugin | UpgradeNoop:
         """Upgrade an existing plugin: apply only NEW migrations (S5).
 
         Version semantics (see distribution-and-plugin-install-design.md §7):
@@ -411,6 +445,17 @@ class PluginManager:
             shutil.rmtree(target)
         shutil.copytree(source_path, target)
 
+        # Resolve & install plugin deps BEFORE migrations / load. Failure
+        # path mirrors install(): remove the copied dir, leave installed
+        # deps in place (design §4.5).
+        if install_deps:
+            try:
+                self._handle_dependencies(meta, reinstall=reinstall_deps)
+            except DepInstallError as e:
+                if target.exists():
+                    shutil.rmtree(target, ignore_errors=True)
+                raise PluginInstallError(str(e)) from e
+
         # F-M5 — keep a backup of the previous install_path so we can roll back on failure
         prev_install_path = Path(existing.install_path)
         prev_metadata_yaml = self._db.fetchone(
@@ -489,6 +534,98 @@ class PluginManager:
 
         return self._compose_record(meta, target, enabled=existing.enabled)
 
+    # --- dep handling ------------------------------------------------
+
+    def _handle_dependencies(self, meta: PluginMetadata, *, reinstall: bool) -> None:
+        """Resolve declared deps, fail loudly on conflict, run installer.
+
+        Pre-conditions: ``meta.dependencies`` already passed Pydantic
+        validation (PEP 508, no URL/VCS, unique names).
+        """
+        if not meta.dependencies:
+            return
+
+        specs = parse_specs(meta.dependencies)
+        ownership = self._build_dep_ownership(exclude_plugin_id=meta.plugin_id)
+
+        def attribute(canonical: str) -> str | None:
+            return ownership.get(canonical)
+
+        plan = plan_install(specs, attribute_conflict=attribute)
+
+        if plan.conflicts:
+            lines = [f"  - {c}" for c in plan.conflicts]
+            raise DepInstallError(
+                "plugin dependency conflicts:\n"
+                + "\n".join(lines)
+                + "\nResolve by uninstalling the conflicting plugin or "
+                + "adjusting this plugin's specifier."
+            )
+
+        targets = specs if reinstall else plan.to_install
+        if plan.skipped and not reinstall:
+            logger.info(
+                "plugin %s: %d dep(s) already satisfied: %s",
+                meta.plugin_id,
+                len(plan.skipped),
+                [f"{r.name}=={v}" for r, v in plan.skipped],
+            )
+        run_install(targets, reinstall=reinstall)
+
+    def _build_dep_ownership(self, *, exclude_plugin_id: str) -> dict[str, str]:
+        """Map canonical package name → human-readable owner attribution.
+
+        Sources, in priority order (first wins):
+          1. Framework's own declared deps (``deeptrade-quant`` distribution).
+          2. Already-installed plugins' declared ``dependencies``
+             (looked up from ``plugins.metadata_yaml``).
+
+        Used only for conflict messages; never gates install decisions.
+        """
+        out: dict[str, str] = {}
+
+        # Framework deps
+        try:
+            dist = importlib_metadata.distribution("deeptrade-quant")
+        except importlib_metadata.PackageNotFoundError:
+            dist = None
+        if dist is not None:
+            for raw in dist.requires or []:
+                try:
+                    req = Requirement(raw)
+                except InvalidRequirement:
+                    continue
+                # Skip extras-only requirements (e.g. dev extras)
+                if req.marker is not None:
+                    try:
+                        if not req.marker.evaluate({"extra": ""}):
+                            continue
+                    except Exception:  # noqa: BLE001 — marker eval edge cases
+                        continue
+                out.setdefault(canonicalize_name(req.name), "framework core dependency")
+
+        # Other plugins
+        try:
+            rows = self._db.fetchall(
+                "SELECT plugin_id, metadata_yaml FROM plugins WHERE plugin_id != ?",
+                (exclude_plugin_id,),
+            )
+        except Exception:  # noqa: BLE001 — DB may be in transitional state
+            rows = []
+        for pid, meta_yaml in rows:
+            try:
+                meta_dict = yaml.safe_load(meta_yaml) or {}
+            except yaml.YAMLError:
+                continue
+            for raw in meta_dict.get("dependencies", []) or []:
+                try:
+                    req = Requirement(raw)
+                except InvalidRequirement:
+                    continue
+                out.setdefault(canonicalize_name(req.name), f"plugin {pid}")
+
+        return out
+
     # --- internal helpers --------------------------------------------
 
     def _apply_migrations(
@@ -631,16 +768,17 @@ def summarize_for_install(meta: PluginMetadata, source_path: Path) -> str:
     """Render the install confirmation pre-flight summary (CLI only)."""
     lines = textwrap.dedent(
         f"""
-        plugin_id  : {meta.plugin_id}
-        name       : {meta.name}
-        version    : {meta.version}
-        type       : {meta.type}
-        entrypoint : {meta.entrypoint}
-        source     : {source_path}
-        required   : {", ".join(meta.permissions.tushare_apis.required) or "(none)"}
-        optional   : {", ".join(meta.permissions.tushare_apis.optional) or "(none)"}
-        migrations : {", ".join(m.version for m in meta.migrations)}
-        tables ({len(meta.tables)}): {", ".join(t.name for t in meta.tables)}
+        plugin_id    : {meta.plugin_id}
+        name         : {meta.name}
+        version      : {meta.version}
+        type         : {meta.type}
+        entrypoint   : {meta.entrypoint}
+        source       : {source_path}
+        required     : {", ".join(meta.permissions.tushare_apis.required) or "(none)"}
+        optional     : {", ".join(meta.permissions.tushare_apis.optional) or "(none)"}
+        migrations   : {", ".join(m.version for m in meta.migrations)}
+        tables ({len(meta.tables)})   : {", ".join(t.name for t in meta.tables)}
+        dependencies : {", ".join(meta.dependencies) or "(none)"}
         """
     ).strip()
     return lines

{deeptrade_quant-0.3.1 → deeptrade_quant-0.4.1}/deeptrade/core/tushare_client.py

@@ -19,7 +19,6 @@ Cache class buckets:
 from __future__ import annotations
 
 import hashlib
-import io
 import json
 import logging
 import threading
@@ -896,6 +895,15 @@ class TushareClient:
             ")"
         )
 
+    # Payload wrapper format (v0.4.1+):
+    #   {"version": 1, "schema": {col: dtype_str}, "data": [...records...]}
+    # Bypasses pd.read_json's date-column heuristic (which warns on string
+    # columns named like dates — trade_date / cal_date / ann_date) and
+    # restores dtypes explicitly from the recorded schema. Pre-v0.4.1 rows
+    # were a bare records array; those are wiped by core migration
+    # 20260512_001_drop_legacy_tushare_cache.sql, so no legacy branch here.
+    _CACHE_PAYLOAD_VERSION = 1
+
     def _write_cached(
         self,
         api_name: str,
@@ -906,7 +914,14 @@ class TushareClient:
         self._ensure_cache_table()
         body = json.dumps(params, sort_keys=True, default=str)
         h = hashlib.sha256(body.encode("utf-8")).hexdigest()
-        payload = df.to_json(orient="records", date_format="iso")
+        records_json = df.to_json(orient="records", date_format="iso")
+        payload = json.dumps(
+            {
+                "version": self._CACHE_PAYLOAD_VERSION,
+                "schema": {col: str(dt) for col, dt in df.dtypes.items()},
+                "data": json.loads(records_json) if records_json else [],
+            }
+        )
         with self._db.transaction():
             self._db.execute(
                 "DELETE FROM tushare_cache_blob "
@@ -937,12 +952,34 @@ class TushareClient:
         )
         if row is None:
             return pd.DataFrame()
-        df = pd.read_json(io.StringIO(row[0]), orient="records")
+        wrapper = json.loads(row[0])
+        df = self._restore_cached_frame(wrapper)
         if fields:
             cols = [c.strip() for c in fields.split(",") if c.strip() in df.columns]
             df = df[cols]
         return df
 
+    @classmethod
+    def _restore_cached_frame(cls, wrapper: dict[str, Any]) -> pd.DataFrame:
+        schema: dict[str, str] = wrapper["schema"]
+        data: list[dict[str, Any]] = wrapper["data"]
+        df = pd.DataFrame.from_records(data, columns=list(schema.keys()))
+        for col, dtype_str in schema.items():
+            if col not in df.columns:
+                continue
+            if dtype_str.startswith("datetime"):
+                df[col] = pd.to_datetime(df[col], errors="coerce")
+            elif dtype_str == "object":
+                continue
+            else:
+                try:
+                    df[col] = df[col].astype(dtype_str)
+                except (TypeError, ValueError):
+                    # Best-effort: if a numeric/bool column can't be coerced
+                    # back (e.g. all-null), leave the inferred dtype.
+                    pass
+        return df
+
 
 # ---------------------------------------------------------------------------
 # Fallback predicate (DESIGN §13.2 + S4)

{deeptrade_quant-0.3.1 → deeptrade_quant-0.4.1}/deeptrade/plugins_api/metadata.py

@@ -4,12 +4,18 @@ 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).
+DESIGN v0.4 (plugin dependency management):
+    * `dependencies` declares third-party Python packages the plugin needs.
+      PEP 508 specifier strings; framework installs them at plugin install /
+      upgrade time. See ``docs/plugin_dependency_management_design.md``.
 """
 
 from __future__ import annotations
 
 from typing import Literal
 
+from packaging.requirements import InvalidRequirement, Requirement
+from packaging.utils import canonicalize_name
 from pydantic import BaseModel, ConfigDict, Field, model_validator
 
 
@@ -61,6 +67,31 @@ class PluginMetadata(BaseModel):
     permissions: PluginPermissions = Field(default_factory=PluginPermissions)
     tables: list[TableSpec]
     migrations: list[MigrationSpec]
+    dependencies: list[str] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def _dependencies_valid(self) -> PluginMetadata:
+        """Each entry must parse as PEP 508 ``Requirement``; no VCS/URL forms;
+        no duplicate package names (canonicalized)."""
+        seen: dict[str, str] = {}
+        for raw in self.dependencies:
+            try:
+                req = Requirement(raw)
+            except InvalidRequirement as e:
+                raise ValueError(f"invalid dependency spec {raw!r}: {e}") from e
+            if req.url:
+                raise ValueError(
+                    f"dependency {raw!r}: VCS/URL forms (git+https://, package @ url) "
+                    f"are not allowed; use PEP 508 version specifiers only"
+                )
+            canonical = canonicalize_name(req.name)
+            if canonical in seen:
+                raise ValueError(
+                    f"duplicate dependency package {req.name!r} "
+                    f"(also declared as {seen[canonical]!r}); combine into a single spec"
+                )
+            seen[canonical] = raw
+        return self
 
     @model_validator(mode="after")
     def _migrations_not_empty(self) -> PluginMetadata: