aimoon 0.1.0__py3-none-any.whl

aimoon/__init__.py

@@ -0,0 +1,7 @@
+"""aimoon — A股量化筛选与交易建议系统"""
+from __future__ import annotations
+
+__all__ = [
+    "config", "models", "cache", "data", "indicators",
+    "scoring", "screener", "backtest", "output", "demo", "cli",
+]

aimoon/__main__.py

@@ -0,0 +1,4 @@
+from aimoon.cli import main
+
+if __name__ == "__main__":
+    main()

aimoon/backtest.py

@@ -0,0 +1,81 @@
+"""回测引擎"""
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+
+import pandas as pd
+
+from aimoon.config import Config
+from aimoon.screener import screen_stock
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class TradeRecord:
+    entry_date: str
+    exit_date: str
+    entry_price: float
+    exit_price: float
+    return_pct: float
+
+
+@dataclass(frozen=True)
+class BacktestResult:
+    code: str
+    total_return: float
+    win_rate: float
+    max_drawdown: float
+    trade_count: int
+    trades: tuple[TradeRecord, ...]
+
+
+class BacktestEngine:
+    def __init__(self, cfg: Config, hold_days: int = 5) -> None:
+        self.cfg = cfg
+        self.hold_days = hold_days
+
+    def run(self, code: str, name: str, kline: pd.DataFrame) -> BacktestResult:
+        min_window = self.cfg.ma_long
+        if len(kline) < min_window + self.hold_days:
+            return BacktestResult(code, 0.0, 0.0, 0.0, 0, ())
+        trades: list[TradeRecord] = []
+        dates = kline.index.tolist()
+        in_trade = False
+        exit_idx = 0
+        for i in range(min_window, len(kline) - self.hold_days):
+            if in_trade and i < exit_idx:
+                continue
+            in_trade = False
+            window = kline.iloc[:i + 1]
+            scored = screen_stock(code, name, window)
+            if scored is None or scored.total_score < 2:
+                continue
+            entry_price = float(kline["close"].iloc[i])
+            exit_i = min(i + self.hold_days, len(kline) - 1)
+            exit_price = float(kline["close"].iloc[exit_i])
+            ret = (exit_price - entry_price) / entry_price * 100
+            trades.append(TradeRecord(str(dates[i].date()), str(dates[exit_i].date()), entry_price, exit_price, ret))
+            in_trade = True
+            exit_idx = exit_i + 1
+        return self._metrics(code, trades, kline)
+
+    def _metrics(self, code: str, trades: list[TradeRecord], kline: pd.DataFrame) -> BacktestResult:
+        if not trades:
+            return BacktestResult(code, 0.0, 0.0, 0.0, 0, ())
+        total_ret = sum(t.return_pct for t in trades)
+        win_rate = sum(1 for t in trades if t.return_pct > 0) / len(trades)
+        equity = [100.0]
+        trade_idx = 0
+        for i in range(1, len(kline)):
+            if trade_idx < len(trades) and str(kline.index[i].date()) == trades[trade_idx].exit_date:
+                equity.append(equity[-1] * (1 + trades[trade_idx].return_pct / 100))
+                trade_idx += 1
+            else:
+                equity.append(equity[-1])
+        peak = max_dd = 0.0
+        for v in equity:
+            peak = max(peak, v)
+            max_dd = max(max_dd, (peak - v) / peak if peak > 0 else 0)
+        return BacktestResult(code, total_ret, win_rate, max_dd, len(trades), tuple(trades))

aimoon/cache.py

@@ -0,0 +1,53 @@
+"""文件缓存层 - pickle 序列化 + TTL 过期"""
+from __future__ import annotations
+
+import logging
+import os
+import time
+from pathlib import Path
+
+import pandas as pd
+
+logger = logging.getLogger(__name__)
+
+
+class DataCache:
+    """缓存 DataFrame 到磁盘，支持 TTL 过期。"""
+
+    def __init__(self, cache_dir: str = ".aimoon_cache", ttl_hours: int = 4) -> None:
+        self.cache_dir = Path(cache_dir)
+        self.ttl_seconds = ttl_hours * 3600
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+
+    def _path_for(self, stock_code: str) -> Path:
+        return self.cache_dir / f"{stock_code}.pkl"
+
+    def get(self, stock_code: str) -> pd.DataFrame | None:
+        """返回缓存的 DataFrame，过期或不存在返回 None。"""
+        path = self._path_for(stock_code)
+        if not path.exists():
+            return None
+        age = time.time() - path.stat().st_mtime
+        if age > self.ttl_seconds:
+            logger.debug("Cache expired for %s (%.0fs old)", stock_code, age)
+            return None
+        try:
+            return pd.read_pickle(path)
+        except Exception as e:
+            logger.warning("Cache read failed for %s: %s", stock_code, e)
+            return None
+
+    def put(self, stock_code: str, df: pd.DataFrame) -> None:
+        """写入 DataFrame 到缓存。"""
+        try:
+            df.to_pickle(self._path_for(stock_code))
+        except Exception as e:
+            logger.warning("Cache write failed for %s: %s", stock_code, e)
+
+    def clear(self) -> int:
+        """清除所有缓存文件，返回删除数量。"""
+        count = 0
+        for p in self.cache_dir.glob("*.pkl"):
+            p.unlink()
+            count += 1
+        return count

aimoon/cli.py

@@ -0,0 +1,123 @@
+"""CLI 入口 — 薄管道"""
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+import time
+from pathlib import Path
+
+from aimoon.cache import DataCache
+from aimoon.config import Config, load_config
+from aimoon.data import get_spot_for_codes, filter_universe, get_sector_context
+from aimoon.data.filters import get_holdings_pool
+from aimoon.output import OutputFormatter
+from aimoon.scoring.rps import compute_rps
+from aimoon.screener import screen_universe
+
+logging.basicConfig(level=logging.WARNING)
+logger = logging.getLogger(__name__)
+
+
+def parse_args() -> argparse.Namespace:
+    p = argparse.ArgumentParser(description="A-share quant screener")
+    p.add_argument("--config", type=str, default=None)
+    p.add_argument("--top", type=int, default=30)
+    p.add_argument("--workers", type=int, default=5)
+    p.add_argument("--no-csv", action="store_true")
+    p.add_argument("--demo", action="store_true")
+    p.add_argument("--refresh", action="store_true")
+    sub = p.add_subparsers(dest="command")
+    bt = sub.add_parser("backtest")
+    bt.add_argument("--stocks", type=str, default="000001")
+    bt.add_argument("--hold-days", type=int, default=5)
+    cp = sub.add_parser("cache")
+    cs = cp.add_subparsers(dest="cache_action")
+    cs.add_parser("clear")
+    sub.add_parser("update", help="Clear all caches and re-fetch data")
+    return p.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    cfg = load_config(args, path=getattr(args, "config", None))
+    fmt = OutputFormatter(cfg)
+
+    # 缓存管理
+    if cfg.command == "cache":
+        cache = DataCache(cfg.cache_dir, cfg.cache_ttl_hours)
+        print(f"Cleared {cache.clear()} cached files")
+        return
+
+    # update：清除所有缓存后重新运行
+    if cfg.command == "update":
+        import shutil
+        cache_dir = Path(cfg.cache_dir)
+        if cache_dir.exists():
+            shutil.rmtree(cache_dir)
+            print(f"Cleared cache dir: {cache_dir}")
+        # 继续执行正常管道（会重新获取所有数据）
+
+    # 回测
+    if cfg.command == "backtest":
+        from aimoon.backtest import BacktestEngine
+        from aimoon.data.history import get_kline
+        engine = BacktestEngine(cfg, hold_days=cfg.hold_days)
+        cache = DataCache(cfg.cache_dir, cfg.cache_ttl_hours)
+        fmt.console.print(f"[bold blue]=== Backtest (hold {cfg.hold_days}d) ===[/bold blue]")
+        for code in cfg.stocks.split(","):
+            code = code.strip()
+            r = get_kline(code, cfg.history_days, cache)
+            if r.is_ok():
+                result = engine.run(code, code, r.unwrap())
+                color = "green" if result.total_return > 0 else "red"
+                fmt.console.print(
+                    f"  {result.code}: [{color}]{result.total_return:+.2f}%[/{color}] "
+                    f"胜率={result.win_rate:.0%} 交易={result.trade_count}次 "
+                    f"最大回撤={result.max_drawdown:.2%}"
+                )
+        return
+
+    # Demo 模式
+    if cfg.demo:
+        from aimoon.demo import generate_demo
+        spot_df, klines = generate_demo()
+        cache = DataCache(cfg.cache_dir, cfg.cache_ttl_hours)
+        results, tails = screen_universe(spot_df, cfg, cache, klines=klines)
+    else:
+        # 实时筛选管道 — 持仓池先行，减少行情请求量
+        fmt.console.print("[dim]Loading holdings pool (cached)...[/dim]")
+        pool = get_holdings_pool(cfg)
+        fmt.console.print(f"[dim]Holdings pool: {len(pool)} stocks[/dim]")
+
+        sr = get_spot_for_codes(pool, cfg)
+        if sr.is_err():
+            fmt.console.print(f"[red]Failed: {sr.error}[/red]")
+            fmt.console.print("[yellow]Try: python -m aimoon --demo[/yellow]")
+            sys.exit(1)
+        spot = sr.unwrap()
+        fmt.console.print(f"[dim]Spot data for {len(spot)} stocks[/dim]")
+
+        fmt.console.print("[dim]Filtering universe...[/dim]")
+        universe = filter_universe(spot, cfg)
+
+        fmt.console.print("[dim]Building sector context...[/dim]")
+        ctx = get_sector_context(spot)
+
+        cache = DataCache(cfg.cache_dir, cfg.cache_ttl_hours)
+        fmt.console.print(f"[dim]Analyzing {len(universe)} stocks...[/dim]")
+        t0 = time.time()
+        results, tails = screen_universe(universe, cfg, cache, ctx)
+        fmt.console.print(f"[dim]Done in {time.time() - t0:.1f}s[/dim]")
+
+    # RPS + 排序 + 输出
+    results = compute_rps(results, tails)
+    top = sorted(results, key=lambda s: s.total_score, reverse=True)[:cfg.top_n]
+    fmt.display(top)
+    if not cfg.no_csv and top:
+        fmt.console.print(f"[dim]Exported: {fmt.export_csv(top)}[/dim]")
+        fmt.console.print(f"[dim]Exported: {fmt.export_markdown(top)}[/dim]")
+
+
+if __name__ == "__main__":
+    main()

aimoon/config.py

@@ -0,0 +1,95 @@
+"""配置模块 — frozen dataclass，显式传递，无全局单例"""
+from __future__ import annotations
+
+import argparse
+import logging
+from dataclasses import dataclass, fields
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class Config:
+    # 筛选参数
+    history_days: int = 250
+    min_market_cap_yi: float = 50.0
+    max_market_cap_yi: float = 2000.0
+    min_turnover_pct: float = 3.0
+    max_turnover_pct: float = 30.0
+    min_price: float = 5.0
+    max_price: float = 100.0
+    min_list_days: int = 250
+    top_n: int = 30
+    # 机构持仓
+    min_northbound_cap: float = 1.0
+    min_fund_pct: float = 5.0
+    # 技术指标参数
+    ma_short: int = 5
+    ma_mid: int = 20
+    ma_long: int = 60
+    rsi_period: int = 14
+    macd_fast: int = 12
+    macd_slow: int = 26
+    macd_signal: int = 9
+    kdj_period: int = 9
+    boll_period: int = 20
+    boll_std: float = 2.0
+    volume_ma_period: int = 20
+    # 缓存
+    cache_dir: str = ".aimoon_cache"
+    cache_ttl_hours: int = 24
+    # 输出
+    output_dir: str = "output"
+    # CLI 参数
+    no_csv: bool = False
+    workers: int = 5
+    demo: bool = False
+    refresh: bool = False
+    command: str | None = None
+    stocks: str = "000001"
+    hold_days: int = 5
+    # 排除规则
+    exclude_boards: tuple[str, ...] = ("ST", "退", "北交所")
+    exclude_prefixes: tuple[str, ...] = ("8", "4")
+
+
+def load_config(args: argparse.Namespace | None = None, path: str | None = None) -> Config:
+    """合并配置：CLI 参数 > YAML 文件 > 默认值。"""
+    overrides: dict = {}
+
+    # YAML 文件
+    if path:
+        p = Path(path)
+        if p.exists():
+            try:
+                import yaml
+                with open(p, encoding="utf-8") as f:
+                    data = yaml.safe_load(f) or {}
+                valid = {f.name for f in fields(Config)}
+                tuple_fields = {f.name for f in fields(Config) if isinstance(f.default, tuple)}
+                for k, v in data.items():
+                    if k in valid:
+                        overrides[k] = tuple(v) if k in tuple_fields and isinstance(v, list) else v
+            except Exception as e:
+                logger.warning("Failed to load config %s: %s", path, e)
+
+    # CLI 参数覆盖
+    if args:
+        cli_map = {
+            "top": "top_n", "workers": "workers", "no_csv": "no_csv",
+            "demo": "demo", "refresh": "refresh",
+            "hold_days": "hold_days", "stocks": "stocks",
+        }
+        for cli_key, cfg_key in cli_map.items():
+            val = getattr(args, cli_key, None)
+            if val is not None:
+                overrides[cfg_key] = val
+        if hasattr(args, "command") and args.command:
+            overrides["command"] = args.command
+
+    return Config(**overrides)
+
+
+# 向后兼容别名 — 旧代码使用 CONFIG 全局变量，Task 11 清理时移除
+CONFIG = Config()

aimoon/data/__init__.py

@@ -0,0 +1,15 @@
+"""数据获取层"""
+from aimoon.data.spot import get_spot, get_spot_for_codes
+from aimoon.data.history import get_kline
+from aimoon.data.filters import (
+    filter_universe,
+    filter_by_sectors,
+    get_sector_context,
+    get_holdings_pool,
+)
+
+__all__ = [
+    "get_spot", "get_spot_for_codes", "get_kline",
+    "filter_universe", "filter_by_sectors",
+    "get_sector_context", "get_holdings_pool",
+]