fund-cli 2.0.0__py3-none-any.whl

fund_cli/core/optimizer.py

@@ -0,0 +1,50 @@
+"""
+优化引擎基类
+
+定义组合优化引擎的标准接口。
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+import pandas as pd
+
+
+class Optimizer(ABC):
+    """
+    优化引擎基类
+
+    所有优化引擎必须继承此类。
+    """
+
+    @abstractmethod
+    def optimize(
+        self,
+        returns: pd.DataFrame,
+        **kwargs,
+    ) -> dict[str, Any]:
+        """
+        执行组合优化
+
+        Args:
+            returns: 多资产收益率 DataFrame，每列一个资产
+            **kwargs: 额外参数（如目标收益率、最大回撤限制等）
+
+        Returns:
+            优化结果字典，包含：
+            - weights: 各资产权重字典
+            - expected_return: 预期收益率
+            - expected_volatility: 预期波动率
+            - sharpe_ratio: 夏普比率
+        """
+        pass
+
+    @abstractmethod
+    def get_methods(self) -> list[str]:
+        """
+        获取支持的优化方法列表
+
+        Returns:
+            方法名称列表
+        """
+        pass

fund_cli/core/optimizers/__init__.py

@@ -0,0 +1,13 @@
+"""组合优化引擎"""
+
+from fund_cli.core.optimizers.efficient_frontier import EfficientFrontierCalculator
+from fund_cli.core.optimizers.max_sharpe import MaxSharpeOptimizer
+from fund_cli.core.optimizers.mean_variance import MeanVarianceOptimizer
+from fund_cli.core.optimizers.risk_parity import RiskParityOptimizer
+
+__all__ = [
+    "MeanVarianceOptimizer",
+    "MaxSharpeOptimizer",
+    "RiskParityOptimizer",
+    "EfficientFrontierCalculator",
+]

fund_cli/core/optimizers/efficient_frontier.py

@@ -0,0 +1,91 @@
+"""有效前沿计算器"""
+
+from typing import Any
+
+import numpy as np
+import pandas as pd
+
+
+class EfficientFrontierCalculator:
+    """有效前沿计算器 - PORTFOLIO-OPT-006"""
+
+    def calculate(
+        self,
+        returns: pd.DataFrame,
+        n_points: int = 50,
+        risk_free_rate: float = 0.03,
+    ) -> dict[str, Any]:
+        """
+        计算有效前沿上的点集
+
+        Args:
+            returns: 收益率 DataFrame
+            n_points: 前沿点数
+            risk_free_rate: 无风险利率
+
+        Returns:
+            包含 frontier_returns, frontier_volatilities, frontier_sharpes 的字典
+        """
+        try:
+            from pypfopt import EfficientFrontier, expected_returns, risk_models
+
+            mu = expected_returns.mean_historical_return(returns)
+            S = risk_models.sample_cov(returns)
+
+            min_ret = mu.min()
+            max_ret = mu.max()
+            target_returns = np.linspace(min_ret, max_ret, n_points)
+
+            frontier_volatilities = []
+            frontier_returns = []
+            frontier_sharpes = []
+
+            for target in target_returns:
+                try:
+                    ef = EfficientFrontier(mu, S)
+                    ef.efficient_return(target)
+                    ret, vol, _ = ef.portfolio_performance(
+                        verbose=False, risk_free_rate=risk_free_rate
+                    )
+                    frontier_returns.append(ret)
+                    frontier_volatilities.append(vol)
+                    frontier_sharpes.append((ret - risk_free_rate) / vol if vol > 0 else 0)
+                except Exception:
+                    continue
+
+            if len(frontier_returns) == 0:
+                return self._fallback_calculate(returns, n_points, risk_free_rate)
+
+            return {
+                "frontier_returns": [round(r, 6) for r in frontier_returns],
+                "frontier_volatilities": [round(v, 6) for v in frontier_volatilities],
+                "frontier_sharpes": [round(s, 4) for s in frontier_sharpes],
+                "n_points": len(frontier_returns),
+            }
+        except Exception:
+            return self._fallback_calculate(returns, n_points, risk_free_rate)
+
+    @staticmethod
+    def _fallback_calculate(
+        returns: pd.DataFrame, n_points: int, risk_free_rate: float
+    ) -> dict[str, Any]:
+        """回退实现"""
+        n = returns.shape[1]
+        vols = []
+        rets = []
+        for i in range(n_points):
+            np.random.seed(i)
+            w = np.random.dirichlet(np.ones(n))
+            port_ret = (returns.mean() * 252 * w).sum()
+            port_vol = np.sqrt(w @ returns.cov().values @ w * 252)
+            vols.append(port_vol)
+            rets.append(port_ret)
+        return {
+            "frontier_returns": [round(r, 6) for r in rets],
+            "frontier_volatilities": [round(v, 6) for v in vols],
+            "frontier_sharpes": [
+                round((r - risk_free_rate) / v, 4) if v > 0 else 0
+                for r, v in zip(rets, vols, strict=False)
+            ],
+            "n_points": n,
+        }

fund_cli/core/optimizers/max_sharpe.py

@@ -0,0 +1,54 @@
+"""最大夏普比率优化器"""
+
+from typing import Any
+
+import pandas as pd
+
+from fund_cli.core.optimizer import Optimizer
+from fund_cli.core.optimizers.mean_variance import MeanVarianceOptimizer
+from fund_cli.data.models import OptimizationConstraint
+
+
+class MaxSharpeOptimizer(Optimizer):
+    """最大夏普比率优化器 - PORTFOLIO-OPT-002"""
+
+    def __init__(self, risk_free_rate: float = 0.03):
+        self.risk_free_rate = risk_free_rate
+
+    def optimize(
+        self,
+        returns: pd.DataFrame,
+        constraints: OptimizationConstraint | None = None,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        """执行最大夏普比率优化"""
+        try:
+            from pypfopt import EfficientFrontier, expected_returns, risk_models
+        except ImportError:
+            return MeanVarianceOptimizer._fallback_optimize(returns, constraints)
+
+        try:
+            mu = expected_returns.mean_historical_return(returns)
+            S = risk_models.sample_cov(returns)
+
+            min_w = constraints.min_weight if constraints else 0.0
+            max_w = constraints.max_weight if constraints else 1.0
+
+            ef = EfficientFrontier(mu, S, weight_bounds=(min_w, max_w))
+            ef.max_sharpe(risk_free_rate=self.risk_free_rate)
+
+            weights = ef.clean_weights()
+            perf = ef.portfolio_performance(verbose=False, risk_free_rate=self.risk_free_rate)
+
+            return {
+                "weights": {k: round(v, 6) for k, v in weights.items()},
+                "expected_return": round(perf[0], 6),
+                "volatility": round(perf[1], 6),
+                "sharpe_ratio": round(perf[2], 4),
+                "method": "max_sharpe",
+            }
+        except Exception:
+            return MeanVarianceOptimizer._fallback_optimize(returns, constraints)
+
+    def get_methods(self) -> list[str]:
+        return ["max_sharpe"]

fund_cli/core/optimizers/mean_variance.py

@@ -0,0 +1,84 @@
+"""均值-方差优化器（Markowitz模型）"""
+
+from typing import Any
+
+import numpy as np
+import pandas as pd
+
+from fund_cli.core.optimizer import Optimizer
+from fund_cli.data.models import OptimizationConstraint
+
+
+class MeanVarianceOptimizer(Optimizer):
+    """均值-方差优化器 - PORTFOLIO-OPT-001"""
+
+    def __init__(self, risk_free_rate: float = 0.03):
+        self.risk_free_rate = risk_free_rate
+
+    def optimize(
+        self,
+        returns: pd.DataFrame,
+        constraints: OptimizationConstraint | None = None,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        """
+        执行均值-方差优化
+
+        Args:
+            returns: 收益率 DataFrame，每列一只基金
+            constraints: 优化约束条件
+
+        Returns:
+            优化结果字典，包含 weights, expected_return, volatility, sharpe_ratio
+        """
+        try:
+            from pypfopt import EfficientFrontier, expected_returns, risk_models
+        except ImportError:
+            return self._fallback_optimize(returns, constraints)
+
+        try:
+            mu = expected_returns.mean_historical_return(returns)
+            S = risk_models.sample_cov(returns)
+
+            min_w = constraints.min_weight if constraints else 0.0
+            max_w = constraints.max_weight if constraints else 1.0
+
+            ef = EfficientFrontier(mu, S, weight_bounds=(min_w, max_w))
+
+            if constraints and constraints.target_return is not None:
+                ef.efficient_return(constraints.target_return)
+            else:
+                ef.max_sharpe(risk_free_rate=self.risk_free_rate)
+
+            weights = ef.clean_weights()
+            perf = ef.portfolio_performance(verbose=False, risk_free_rate=self.risk_free_rate)
+
+            return {
+                "weights": {k: round(v, 6) for k, v in weights.items()},
+                "expected_return": round(perf[0], 6),
+                "volatility": round(perf[1], 6),
+                "sharpe_ratio": round(perf[2], 4),
+                "method": "mean_variance",
+            }
+        except Exception:
+            return self._fallback_optimize(returns, constraints)
+
+    def get_methods(self) -> list[str]:
+        return ["mean_variance"]
+
+    @staticmethod
+    def _fallback_optimize(
+        returns: pd.DataFrame, constraints: OptimizationConstraint | None = None
+    ) -> dict[str, Any]:
+        """PyPortfolioOpt不可用时的回退实现"""
+        n = returns.shape[1]
+        equal_weights = {col: round(1.0 / n, 6) for col in returns.columns}
+        port_return = (returns.mean() * 252).mean()
+        port_vol = returns.std().mean() * np.sqrt(252)
+        return {
+            "weights": equal_weights,
+            "expected_return": round(port_return, 6),
+            "volatility": round(port_vol, 6),
+            "sharpe_ratio": round((port_return - 0.03) / port_vol, 4) if port_vol > 0 else 0.0,
+            "method": "equal_weight_fallback",
+        }

fund_cli/core/optimizers/risk_parity.py

@@ -0,0 +1,60 @@
+"""风险平价优化器"""
+
+from typing import Any
+
+import numpy as np
+import pandas as pd
+
+from fund_cli.core.optimizer import Optimizer
+
+
+class RiskParityOptimizer(Optimizer):
+    """风险平价优化器 - PORTFOLIO-OPT-003"""
+
+    def optimize(
+        self,
+        returns: pd.DataFrame,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        """执行风险平价优化"""
+        try:
+            from pypfopt import HRPOpt
+        except ImportError:
+            return self._fallback_risk_parity(returns)
+
+        hrp = HRPOpt(returns)
+        weights = hrp.optimize()
+
+        port_returns = (returns * pd.Series(weights)).sum(axis=1)
+        expected_return = port_returns.mean() * 252
+        volatility = port_returns.std() * np.sqrt(252)
+        sharpe = (expected_return - 0.03) / volatility if volatility > 0 else 0.0
+
+        return {
+            "weights": {k: round(v, 6) for k, v in weights.items()},
+            "expected_return": round(expected_return, 6),
+            "volatility": round(volatility, 6),
+            "sharpe_ratio": round(sharpe, 4),
+            "method": "risk_parity",
+        }
+
+    def get_methods(self) -> list[str]:
+        return ["risk_parity"]
+
+    @staticmethod
+    def _fallback_risk_parity(returns: pd.DataFrame) -> dict[str, Any]:
+        """回退实现：基于波动率倒数加权"""
+        vols = returns.std()
+        inv_vols = 1.0 / vols
+        weights = inv_vols / inv_vols.sum()
+        port_returns = (returns * weights).sum(axis=1)
+        expected_return = port_returns.mean() * 252
+        volatility = port_returns.std() * np.sqrt(252)
+        sharpe = (expected_return - 0.03) / volatility if volatility > 0 else 0.0
+        return {
+            "weights": {k: round(v, 6) for k, v in weights.items()},
+            "expected_return": round(expected_return, 6),
+            "volatility": round(volatility, 6),
+            "sharpe_ratio": round(sharpe, 4),
+            "method": "inverse_volatility_fallback",
+        }

fund_cli/core/reporter.py

@@ -0,0 +1,67 @@
+"""
+报告生成器基类
+
+定义报告生成的标准接口。
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+import pandas as pd
+
+
+class Reporter(ABC):
+    """
+    报告生成器基类
+
+    所有报告生成器必须继承此类。
+    """
+
+    @abstractmethod
+    def generate(
+        self,
+        fund_code: str,
+        metrics: dict[str, Any],
+        nav_data: pd.DataFrame | None = None,
+        benchmark_data: pd.DataFrame | None = None,
+        **kwargs,
+    ) -> str:
+        """
+        生成报告
+
+        Args:
+            fund_code: 基金代码
+            metrics: 分析指标字典
+            nav_data: 净值数据
+            benchmark_data: 基准数据
+            **kwargs: 额外参数
+
+        Returns:
+            报告内容字符串
+        """
+        pass
+
+    @abstractmethod
+    def save(
+        self,
+        content: str,
+        output_path: str,
+    ) -> None:
+        """
+        保存报告到文件
+
+        Args:
+            content: 报告内容
+            output_path: 输出文件路径
+        """
+        pass
+
+    @abstractmethod
+    def get_formats(self) -> list:
+        """
+        获取支持的报告格式
+
+        Returns:
+            格式列表（如 ['html', 'markdown', 'pdf']）
+        """
+        pass

fund_cli/core/reporters/__init__.py

@@ -0,0 +1,6 @@
+"""报告生成器"""
+
+from fund_cli.core.reporters.html_reporter import HtmlReporter
+from fund_cli.core.reporters.markdown_reporter import MarkdownReporter
+
+__all__ = ["HtmlReporter", "MarkdownReporter"]

fund_cli/core/reporters/html_reporter.py

@@ -0,0 +1,62 @@
+"""HTML报告生成器"""
+
+from datetime import date
+from typing import Any
+
+from fund_cli.core.reporter import Reporter
+
+
+class HtmlReporter(Reporter):
+    """HTML报告生成器 (FUND-ANALYZE-011)"""
+
+    def generate(self, fund_code: str, metrics: dict[str, Any], **kwargs) -> str:
+        kwargs.get("nav_data")
+        html = f"""<!DOCTYPE html>
+<html lang="zh-CN">
+<head><meta charset="UTF-8"><title>{fund_code} 分析报告</title>
+<style>
+body {{ font-family: -apple-system, sans-serif; max-width: 800px; margin: 0 auto; padding: 20px; color: #333; }}
+h1 {{ color: #1a5276; border-bottom: 2px solid #2980b9; padding-bottom: 10px; }}
+h2 {{ color: #2c3e50; margin-top: 30px; }}
+table {{ border-collapse: collapse; width: 100%; margin: 10px 0; }}
+th, td {{ border: 1px solid #ddd; padding: 8px 12px; text-align: left; }}
+th {{ background: #2980b9; color: white; }}
+tr:nth-child(even) {{ background: #f2f2f2; }}
+.positive {{ color: #27ae60; }}
+.negative {{ color: #e74c3c; }}
+.footer {{ margin-top: 30px; font-size: 12px; color: #999; border-top: 1px solid #eee; padding-top: 10px; }}
+</style></head><body>
+<h1>{fund_code} 基金分析报告</h1>
+<p>报告日期: {date.today().strftime('%Y-%m-%d')}</p>
+<h2>核心指标</h2>
+<table><tr><th>指标</th><th>值</th></tr>"""
+
+        key_metrics = [
+            ("总收益率", metrics.get("total_return", "N/A")),
+            ("年化收益率", metrics.get("annualized_return", "N/A")),
+            ("波动率", metrics.get("volatility", "N/A")),
+            ("夏普比率", metrics.get("sharpe_ratio", "N/A")),
+            ("最大回撤", metrics.get("max_drawdown", "N/A")),
+            ("索提诺比率", metrics.get("sortino_ratio", "N/A")),
+            ("Alpha", metrics.get("alpha", "N/A")),
+            ("Beta", metrics.get("beta", "N/A")),
+        ]
+        for name, value in key_metrics:
+            if isinstance(value, float):
+                cls = "positive" if value > 0 else "negative" if value < 0 else ""
+                html += f"<tr><td>{name}</td><td class='{cls}'>{value:.4f}</td></tr>"
+            else:
+                html += f"<tr><td>{name}</td><td>{value}</td></tr>"
+
+        html += "</table>"
+        html += "<div class='footer'>本报告由 Fund CLI 自动生成，仅供参考，不构成投资建议。</div>"
+        html += "</body></html>"
+        return html
+
+    def save(self, content: str, output_path: str) -> None:
+        from pathlib import Path
+
+        Path(output_path).write_text(content, encoding="utf-8")
+
+    def get_formats(self) -> list[str]:
+        return ["html"]

fund_cli/core/reporters/markdown_reporter.py

@@ -0,0 +1,40 @@
+"""Markdown报告生成器"""
+
+from datetime import date
+from typing import Any
+
+from fund_cli.core.reporter import Reporter
+
+
+class MarkdownReporter(Reporter):
+    """Markdown报告生成器"""
+
+    def generate(self, fund_code: str, metrics: dict[str, Any], **kwargs) -> str:
+        md = f"# {fund_code} 基金分析报告\n\n"
+        md += f"报告日期: {date.today().strftime('%Y-%m-%d')}\n\n"
+        md += "## 核心指标\n\n"
+        md += "| 指标 | 值 |\n|------|-----|\n"
+
+        key_metrics = [
+            ("总收益率", metrics.get("total_return")),
+            ("年化收益率", metrics.get("annualized_return")),
+            ("波动率", metrics.get("volatility")),
+            ("夏普比率", metrics.get("sharpe_ratio")),
+            ("最大回撤", metrics.get("max_drawdown")),
+        ]
+        for name, value in key_metrics:
+            if isinstance(value, float):
+                md += f"| {name} | {value:.4f} |\n"
+            else:
+                md += f"| {name} | {value or 'N/A'} |\n"
+
+        md += "\n---\n*本报告由 Fund CLI 自动生成，仅供参考。*\n"
+        return md
+
+    def save(self, content: str, output_path: str) -> None:
+        from pathlib import Path
+
+        Path(output_path).write_text(content, encoding="utf-8")
+
+    def get_formats(self) -> list[str]:
+        return ["markdown"]

fund_cli/core/screener.py

@@ -0,0 +1,142 @@
+"""基金筛选引擎"""
+
+import json
+import re
+from pathlib import Path
+
+import pandas as pd
+
+from fund_cli.data.models import FundFilter
+
+
+class FundScreener:
+    """
+    基金筛选引擎
+
+    功能：
+    - 费率筛选 (FUND-FILTER-005)
+    - 经理筛选 (FUND-FILTER-006)
+    - 评级筛选 (FUND-FILTER-007)
+    - 高级表达式筛选 (FUND-FILTER-012)
+    - 模板保存/加载 (FUND-FILTER-011)
+    """
+
+    # 允许的表达式函数白名单
+    _SAFE_FUNCTIONS = {"sum", "mean", "min", "max", "abs", "len"}
+
+    def __init__(self, data_manager=None):
+        from fund_cli.core.data_manager import DataManager
+
+        self._dm = data_manager or DataManager()
+        self._template_dir = Path("~/.fund_cli/templates").expanduser()
+        self._template_dir.mkdir(parents=True, exist_ok=True)
+
+    def screen(self, filter_obj: FundFilter) -> pd.DataFrame:
+        """执行通用筛选"""
+        df = self._dm.search_funds(
+            fund_type=filter_obj.fund_type.value if filter_obj.fund_type else None,
+            company=filter_obj.company,
+            min_scale=filter_obj.min_scale,
+            max_scale=filter_obj.max_scale,
+            keyword=filter_obj.keyword,
+            limit=filter_obj.limit,
+        )
+
+        if df.empty:
+            return df
+
+        # 业绩筛选
+        if filter_obj.min_return_1y is not None and "return_1y" in df.columns:
+            df = df[df["return_1y"] >= filter_obj.min_return_1y]
+        if filter_obj.max_return_1y is not None and "return_1y" in df.columns:
+            df = df[df["return_1y"] <= filter_obj.max_return_1y]
+
+        # 风险筛选
+        if filter_obj.max_drawdown is not None and "max_drawdown" in df.columns:
+            df = df[df["max_drawdown"] >= filter_obj.max_drawdown]
+        if filter_obj.min_sharpe is not None and "sharpe_ratio" in df.columns:
+            df = df[df["sharpe_ratio"] >= filter_obj.min_sharpe]
+
+        # V1.0 新增筛选
+        if filter_obj.fee_rate_max is not None and "fee_rate" in df.columns:
+            df = df[df["fee_rate"] <= filter_obj.fee_rate_max]
+        if filter_obj.manager_name and "manager" in df.columns:
+            df = df[df["manager"].str.contains(filter_obj.manager_name, na=False)]
+        if filter_obj.min_rating is not None and "rating" in df.columns:
+            df = df[df["rating"] >= filter_obj.min_rating]
+
+        # 排序
+        if filter_obj.sort_by and filter_obj.sort_by in df.columns:
+            ascending = filter_obj.sort_order == "asc"
+            df = df.sort_values(filter_obj.sort_by, ascending=ascending)
+
+        return df.reset_index(drop=True)
+
+    def screen_by_fee(self, max_fee_rate: float, fund_type: str | None = None) -> pd.DataFrame:
+        """费率筛选 (FUND-FILTER-005)"""
+        f = FundFilter(fee_rate_max=max_fee_rate)
+        if fund_type:
+            from fund_cli.data.models import FundType
+
+            f.fund_type = FundType(fund_type)
+        return self.screen(f)
+
+    def screen_by_manager(self, manager_name: str) -> pd.DataFrame:
+        """经理筛选 (FUND-FILTER-006)"""
+        f = FundFilter(manager_name=manager_name)
+        return self.screen(f)
+
+    def screen_by_rating(self, min_rating: int) -> pd.DataFrame:
+        """评级筛选 (FUND-FILTER-007)"""
+        f = FundFilter(min_rating=min_rating)
+        return self.screen(f)
+
+    def evaluate_expression(self, df: pd.DataFrame, expression: str) -> pd.DataFrame:
+        """
+        高级表达式筛选 (FUND-FILTER-012)
+
+        使用 pandas query 安全执行表达式。
+        支持的运算符: >, <, =, >=, <=, ==, !=
+        支持的逻辑: AND, OR, and, or, &, |
+        """
+        try:
+            # 安全检查：禁止危险操作
+            dangerous = re.findall(
+                r"(?:__|import|exec|eval|open|os\.|sys\.)", expression, re.IGNORECASE
+            )
+            if dangerous:
+                raise ValueError(f"表达式包含不允许的操作: {dangerous}")
+
+            result = df.query(expression)
+            return result.reset_index(drop=True)
+        except Exception as e:
+            raise ValueError(f"表达式解析失败: {e}") from e
+
+    def save_template(self, name: str, filter_obj: FundFilter) -> None:
+        """保存筛选模板 (FUND-FILTER-011)"""
+        path = self._template_dir / f"{name}.json"
+        data = filter_obj.model_dump(mode="json")
+        path.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")
+
+    def load_template(self, name: str) -> FundFilter:
+        """加载筛选模板"""
+        path = self._template_dir / f"{name}.json"
+        if not path.exists():
+            raise FileNotFoundError(f"模板 {name} 不存在")
+        data = json.loads(path.read_text(encoding="utf-8"))
+        return FundFilter(**data)
+
+    def list_templates(self) -> list[str]:
+        """列出所有筛选模板"""
+        templates = []
+        for f in self._template_dir.glob("*.json"):
+            templates.append(f.stem)
+        return sorted(templates)
+
+    def delete_template(self, name: str) -> bool:
+        """删除筛选模板"""
+        path = self._template_dir / f"{name}.json"
+        if path.exists():
+            path.unlink()
+            return True
+        return False

fund_cli/data/__init__.py

@@ -0,0 +1,6 @@
+"""数据层 - 数据源适配器、缓存管理、数据模型"""
+
+from fund_cli.data.base import DataSourceAdapter
+from fund_cli.data.models import FundInfo, FundType, NavData
+
+__all__ = ["FundInfo", "NavData", "FundType", "DataSourceAdapter"]