staran 0.4.1__py3-none-any.whl → 0.5.0__py3-none-any.whl

staran/models/registry.py

@@ -0,0 +1,281 @@
+"""
+模型注册和管理模块
+
+提供模型配置的注册、查询、版本管理等功能
+"""
+
+from typing import Dict, Any, List, Optional, Tuple
+from dataclasses import dataclass
+from datetime import datetime
+import json
+import os
+
+from .config import ModelConfig
+from .target import TargetDefinition
+
+
+@dataclass
+class ModelEntry:
+    """模型注册条目"""
+    model_config: ModelConfig
+    target_definition: TargetDefinition
+    registered_at: datetime
+    status: str = "active"  # active, inactive, deprecated
+    performance_metrics: Dict[str, float] = None
+    
+    def __post_init__(self):
+        if self.performance_metrics is None:
+            self.performance_metrics = {}
+
+
+class ModelRegistry:
+    """模型注册表"""
+    
+    _models: Dict[str, ModelEntry] = {}
+    _version_history: Dict[str, List[str]] = {}  # 模型名称 -> 版本列表
+    
+    @classmethod
+    def register(cls, model_config: ModelConfig, target_definition: TargetDefinition) -> str:
+        """
+        注册一个新模型
+        
+        Args:
+            model_config: 模型配置
+            target_definition: 目标变量定义
+            
+        Returns:
+            模型的唯一标识符
+        """
+        model_id = f"{model_config.name}_{model_config.version}"
+        
+        # 检查是否已存在
+        if model_id in cls._models:
+            raise ValueError(f"模型 {model_id} 已存在")
+        
+        # 创建模型条目
+        entry = ModelEntry(
+            model_config=model_config,
+            target_definition=target_definition,
+            registered_at=datetime.now()
+        )
+        
+        # 注册模型
+        cls._models[model_id] = entry
+        
+        # 更新版本历史
+        if model_config.name not in cls._version_history:
+            cls._version_history[model_config.name] = []
+        cls._version_history[model_config.name].append(model_config.version)
+        
+        print(f"✅ 模型 {model_id} 注册成功")
+        return model_id
+    
+    @classmethod
+    def get_model(cls, model_name: str, version: str = None) -> Optional[ModelEntry]:
+        """
+        获取模型条目
+        
+        Args:
+            model_name: 模型名称
+            version: 版本号，如果不指定则返回最新版本
+            
+        Returns:
+            模型条目或None
+        """
+        if version:
+            model_id = f"{model_name}_{version}"
+            return cls._models.get(model_id)
+        else:
+            # 获取最新版本
+            versions = cls._version_history.get(model_name, [])
+            if not versions:
+                return None
+            
+            latest_version = max(versions)  # 简单的字符串比较，实际应该用版本比较
+            model_id = f"{model_name}_{latest_version}"
+            return cls._models.get(model_id)
+    
+    @classmethod
+    def get_model_config(cls, model_name: str, version: str = None) -> Optional[ModelConfig]:
+        """获取模型配置"""
+        entry = cls.get_model(model_name, version)
+        return entry.model_config if entry else None
+    
+    @classmethod
+    def get_target_definition(cls, model_name: str, version: str = None) -> Optional[TargetDefinition]:
+        """获取目标变量定义"""
+        entry = cls.get_model(model_name, version)
+        return entry.target_definition if entry else None
+    
+    @classmethod
+    def list_models(cls) -> List[Dict[str, Any]]:
+        """列出所有注册的模型"""
+        result = []
+        for model_id, entry in cls._models.items():
+            result.append({
+                'model_id': model_id,
+                'name': entry.model_config.name,
+                'version': entry.model_config.version,
+                'type': entry.model_config.model_type.value,
+                'algorithm': entry.model_config.algorithm.value,
+                'bank_code': entry.model_config.bank_code,
+                'status': entry.status,
+                'registered_at': entry.registered_at.isoformat(),
+                'description': entry.model_config.description
+            })
+        return result
+    
+    @classmethod
+    def list_versions(cls, model_name: str) -> List[str]:
+        """列出模型的所有版本"""
+        return cls._version_history.get(model_name, [])
+    
+    @classmethod
+    def update_status(cls, model_name: str, status: str, version: str = None):
+        """更新模型状态"""
+        entry = cls.get_model(model_name, version)
+        if entry:
+            entry.status = status
+            print(f"✅ 模型 {model_name} 状态更新为: {status}")
+        else:
+            print(f"❌ 模型 {model_name} 不存在")
+    
+    @classmethod
+    def update_performance(cls, model_name: str, metrics: Dict[str, float], version: str = None):
+        """更新模型性能指标"""
+        entry = cls.get_model(model_name, version)
+        if entry:
+            entry.performance_metrics.update(metrics)
+            print(f"✅ 模型 {model_name} 性能指标已更新")
+        else:
+            print(f"❌ 模型 {model_name} 不存在")
+    
+    @classmethod
+    def get_model_summary(cls, model_name: str, version: str = None) -> Optional[Dict[str, Any]]:
+        """获取模型详细信息摘要"""
+        entry = cls.get_model(model_name, version)
+        if not entry:
+            return None
+        
+        model_config = entry.model_config
+        target_def = entry.target_definition
+        
+        return {
+            'basic_info': {
+                'name': model_config.name,
+                'version': model_config.version,
+                'type': model_config.model_type.value,
+                'algorithm': model_config.algorithm.value,
+                'description': model_config.description,
+                'created_by': model_config.created_by,
+                'bank_code': model_config.bank_code
+            },
+            'feature_config': {
+                'schema_name': model_config.feature_config.schema_name,
+                'table_types': model_config.feature_config.table_types,
+                'feature_selection': model_config.feature_config.feature_selection,
+                'feature_engineering': model_config.feature_config.feature_engineering
+            },
+            'target_config': {
+                'name': target_def.name,
+                'type': target_def.target_type.value,
+                'column': target_def.target_column,
+                'description': target_def.description
+            },
+            'training_config': model_config.training_config,
+            'hyperparameters': model_config.hyperparameters,
+            'evaluation_metrics': model_config.evaluation_metrics,
+            'registry_info': {
+                'status': entry.status,
+                'registered_at': entry.registered_at.isoformat(),
+                'performance_metrics': entry.performance_metrics
+            }
+        }
+    
+    @classmethod
+    def save_to_file(cls, filepath: str):
+        """保存注册表到文件"""
+        data = {
+            'models': {},
+            'version_history': cls._version_history,
+            'saved_at': datetime.now().isoformat()
+        }
+        
+        # 序列化模型数据
+        for model_id, entry in cls._models.items():
+            data['models'][model_id] = {
+                'model_config': entry.model_config.to_dict(),
+                'target_definition': entry.target_definition.to_dict(),
+                'registered_at': entry.registered_at.isoformat(),
+                'status': entry.status,
+                'performance_metrics': entry.performance_metrics
+            }
+        
+        os.makedirs(os.path.dirname(filepath), exist_ok=True)
+        with open(filepath, 'w', encoding='utf-8') as f:
+            json.dump(data, f, indent=2, ensure_ascii=False)
+        
+        print(f"✅ 模型注册表已保存到: {filepath}")
+    
+    @classmethod
+    def load_from_file(cls, filepath: str):
+        """从文件加载注册表"""
+        if not os.path.exists(filepath):
+            print(f"❌ 文件不存在: {filepath}")
+            return
+        
+        with open(filepath, 'r', encoding='utf-8') as f:
+            data = json.load(f)
+        
+        cls._version_history = data.get('version_history', {})
+        cls._models = {}
+        
+        # 反序列化模型数据
+        for model_id, entry_data in data.get('models', {}).items():
+            model_config = ModelConfig.from_dict(entry_data['model_config'])
+            target_definition = TargetDefinition(
+                **entry_data['target_definition']
+            )
+            
+            entry = ModelEntry(
+                model_config=model_config,
+                target_definition=target_definition,
+                registered_at=datetime.fromisoformat(entry_data['registered_at']),
+                status=entry_data.get('status', 'active'),
+                performance_metrics=entry_data.get('performance_metrics', {})
+            )
+            
+            cls._models[model_id] = entry
+        
+        print(f"✅ 从 {filepath} 加载了 {len(cls._models)} 个模型")
+
+
+# 便捷函数
+def register_model(model_config: ModelConfig, target_definition: TargetDefinition) -> str:
+    """注册模型的便捷函数"""
+    return ModelRegistry.register(model_config, target_definition)
+
+
+def get_model_config(model_name: str, version: str = None) -> Optional[ModelConfig]:
+    """获取模型配置的便捷函数"""
+    return ModelRegistry.get_model_config(model_name, version)
+
+
+def get_target_definition(model_name: str, version: str = None) -> Optional[TargetDefinition]:
+    """获取目标变量定义的便捷函数"""
+    return ModelRegistry.get_target_definition(model_name, version)
+
+
+def list_available_models() -> List[Dict[str, Any]]:
+    """列出可用模型的便捷函数"""
+    return ModelRegistry.list_models()
+
+
+def save_model_registry(filepath: str = "./models/model_registry.json"):
+    """保存模型注册表的便捷函数"""
+    ModelRegistry.save_to_file(filepath)
+
+
+def load_model_registry(filepath: str = "./models/model_registry.json"):
+    """加载模型注册表的便捷函数"""
+    ModelRegistry.load_from_file(filepath)

staran/models/target.py

@@ -0,0 +1,321 @@
+"""
+目标变量定义模块
+
+提供基于SQL的目标变量定义和生成功能
+"""
+
+from enum import Enum
+from typing import Dict, Any, List, Optional, Union
+from dataclasses import dataclass, field
+from datetime import datetime
+import re
+
+
+class TargetType(Enum):
+    """目标变量类型"""
+    BINARY_CLASSIFICATION = "binary_classification"    # 二分类
+    MULTI_CLASSIFICATION = "multi_classification"      # 多分类
+    REGRESSION = "regression"                           # 回归
+    RANKING = "ranking"                                 # 排序
+    CLUSTERING = "clustering"                           # 聚类
+    SQL_BASED = "sql_based"                            # 基于SQL的自定义目标
+
+
+class TargetEncoding(Enum):
+    """目标变量编码方式"""
+    NONE = "none"                    # 不编码
+    LABEL_ENCODING = "label"         # 标签编码
+    ONE_HOT = "one_hot"             # 独热编码
+    ORDINAL = "ordinal"             # 序数编码
+    BINARY = "binary"               # 二进制编码
+
+
+@dataclass
+class TargetDefinition:
+    """目标变量定义类"""
+    # 基本信息
+    name: str                                   # 目标变量名称
+    target_type: TargetType                     # 目标类型
+    description: str = ""                       # 描述
+    
+    # SQL定义 (核心功能)
+    sql_query: str = ""                         # 生成目标变量的SQL查询
+    target_column: str = "target"               # 目标列名
+    
+    # 数据信息
+    data_type: str = "float"                    # 数据类型
+    encoding: TargetEncoding = TargetEncoding.NONE  # 编码方式
+    
+    # 分类相关
+    class_labels: List[str] = field(default_factory=list)  # 类别标签
+    class_weights: Dict[str, float] = field(default_factory=dict)  # 类别权重
+    
+    # 回归相关
+    min_value: Optional[float] = None           # 最小值
+    max_value: Optional[float] = None           # 最大值
+    normalization: bool = False                 # 是否标准化
+    
+    # 时间相关
+    time_window: str = ""                       # 时间窗口 (如 "30_days", "3_months")
+    prediction_horizon: str = ""                # 预测时间范围
+    
+    # 银行特定
+    bank_code: str = "generic"                  # 银行代码
+    business_rules: Dict[str, Any] = field(default_factory=dict)  # 业务规则
+    
+    # 元数据
+    created_at: datetime = field(default_factory=datetime.now)
+    created_by: str = "system"
+    version: str = "1.0.0"
+    tags: List[str] = field(default_factory=list)
+    
+    # 验证配置
+    validation_rules: Dict[str, Any] = field(default_factory=dict)
+    
+    def __post_init__(self):
+        """初始化后处理"""
+        if not self.sql_query and self.target_type != TargetType.SQL_BASED:
+            self.sql_query = self._generate_default_sql()
+        
+        # 验证SQL语法
+        if self.sql_query:
+            self._validate_sql()
+    
+    def _generate_default_sql(self) -> str:
+        """根据目标类型生成默认SQL"""
+        if self.target_type == TargetType.BINARY_CLASSIFICATION:
+            return f"""
+            SELECT party_id, 
+                   CASE WHEN condition THEN 1 ELSE 0 END as {self.target_column}
+            FROM source_table 
+            WHERE data_dt = '{{data_dt}}'
+            """
+        elif self.target_type == TargetType.REGRESSION:
+            return f"""
+            SELECT party_id,
+                   target_value as {self.target_column}
+            FROM source_table
+            WHERE data_dt = '{{data_dt}}'
+            """
+        else:
+            return ""
+    
+    def _validate_sql(self):
+        """验证SQL语法基本正确性"""
+        sql = self.sql_query.strip().upper()
+        
+        # 基本SQL结构检查 (支持WITH语句)
+        if not (sql.startswith('SELECT') or sql.startswith('WITH')):
+            raise ValueError("SQL查询必须以SELECT或WITH开始")
+        
+        # 检查是否包含目标列
+        if self.target_column.upper() not in sql:
+            print(f"警告: SQL中未找到目标列 '{self.target_column}'")
+        
+        # 检查参数占位符
+        placeholders = re.findall(r'\{(\w+)\}', self.sql_query)
+        if placeholders:
+            print(f"发现参数占位符: {placeholders}")
+    
+    def generate_sql(self, **params) -> str:
+        """
+        生成最终的SQL查询，替换参数占位符
+        
+        Args:
+            **params: SQL参数字典
+            
+        Returns:
+            最终的SQL查询字符串
+        """
+        sql = self.sql_query
+        
+        # 替换参数占位符
+        for key, value in params.items():
+            placeholder = f"{{{key}}}"
+            sql = sql.replace(placeholder, str(value))
+        
+        return sql
+    
+    def get_sample_sql(self, data_dt: str = "20250728") -> str:
+        """获取示例SQL"""
+        return self.generate_sql(data_dt=data_dt)
+    
+    def validate_target_values(self, values: List[Any]) -> bool:
+        """验证目标值是否符合定义"""
+        if self.target_type == TargetType.BINARY_CLASSIFICATION:
+            unique_values = set(values)
+            return unique_values.issubset({0, 1, 0.0, 1.0})
+        
+        elif self.target_type == TargetType.MULTI_CLASSIFICATION:
+            if self.class_labels:
+                unique_values = set(values)
+                return unique_values.issubset(set(self.class_labels))
+        
+        elif self.target_type == TargetType.REGRESSION:
+            if self.min_value is not None and self.max_value is not None:
+                return all(self.min_value <= v <= self.max_value for v in values)
+        
+        return True
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """转换为字典格式"""
+        return {
+            'name': self.name,
+            'target_type': self.target_type.value,
+            'description': self.description,
+            'sql_query': self.sql_query,
+            'target_column': self.target_column,
+            'data_type': self.data_type,
+            'encoding': self.encoding.value,
+            'class_labels': self.class_labels,
+            'class_weights': self.class_weights,
+            'min_value': self.min_value,
+            'max_value': self.max_value,
+            'normalization': self.normalization,
+            'time_window': self.time_window,
+            'prediction_horizon': self.prediction_horizon,
+            'bank_code': self.bank_code,
+            'business_rules': self.business_rules,
+            'created_at': self.created_at.isoformat(),
+            'created_by': self.created_by,
+            'version': self.version,
+            'tags': self.tags,
+            'validation_rules': self.validation_rules
+        }
+
+
+def create_target_definition(
+    name: str,
+    target_type: str,
+    sql_query: str,
+    target_column: str = "target",
+    bank_code: str = "generic",
+    **kwargs
+) -> TargetDefinition:
+    """
+    创建目标变量定义的便捷函数
+    
+    Args:
+        name: 目标变量名称
+        target_type: 目标类型
+        sql_query: SQL查询
+        target_column: 目标列名
+        bank_code: 银行代码
+        **kwargs: 其他配置参数
+        
+    Returns:
+        TargetDefinition实例
+    """
+    return TargetDefinition(
+        name=name,
+        target_type=TargetType(target_type),
+        sql_query=sql_query,
+        target_column=target_column,
+        bank_code=bank_code,
+        **kwargs
+    )
+
+
+# 预定义的目标变量模板
+TARGET_TEMPLATES = {
+    "aum_longtail_purchase": {
+        "target_type": "binary_classification",
+        "description": "AUM长尾客户未来购买预测",
+        "sql_query": """
+        SELECT 
+            a.party_id,
+            CASE 
+                WHEN b.purchase_amount > 0 THEN 1 
+                ELSE 0 
+            END as target
+        FROM 
+            bi_hlwj_dfcw_f1_f4_wy a
+        LEFT JOIN (
+            SELECT party_id, SUM(productamount_sum) as purchase_amount
+            FROM bi_hlwj_dfcw_f1_f4_wy
+            WHERE data_dt BETWEEN '{start_dt}' AND '{end_dt}'
+            GROUP BY party_id
+        ) b ON a.party_id = b.party_id
+        WHERE a.data_dt = '{feature_dt}'
+        """,
+        "target_column": "target",
+        "time_window": "30_days",
+        "class_labels": ["no_purchase", "purchase"]
+    },
+    
+    "customer_value_prediction": {
+        "target_type": "regression",
+        "description": "客户价值预测",
+        "sql_query": """
+        SELECT 
+            party_id,
+            asset_total_bal as target
+        FROM 
+            bi_hlwj_zi_chan_avg_wy
+        WHERE 
+            data_dt = '{target_dt}'
+        """,
+        "target_column": "target",
+        "data_type": "float",
+        "normalization": True
+    },
+    
+    "risk_level_classification": {
+        "target_type": "multi_classification", 
+        "description": "风险等级分类",
+        "sql_query": """
+        SELECT 
+            party_id,
+            CASE 
+                WHEN asset_total_bal < 10000 THEN 'low_risk'
+                WHEN asset_total_bal < 100000 THEN 'medium_risk'
+                ELSE 'high_risk'
+            END as target
+        FROM 
+            bi_hlwj_zi_chan_avg_wy
+        WHERE 
+            data_dt = '{data_dt}'
+        """,
+        "target_column": "target",
+        "class_labels": ["low_risk", "medium_risk", "high_risk"]
+    }
+}
+
+
+def create_preset_target(preset_name: str, **overrides) -> TargetDefinition:
+    """
+    基于预设模板创建目标变量定义
+    
+    Args:
+        preset_name: 预设模板名称
+        **overrides: 覆盖的配置参数
+        
+    Returns:
+        TargetDefinition实例
+    """
+    if preset_name not in TARGET_TEMPLATES:
+        raise ValueError(f"未知的目标变量模板: {preset_name}")
+    
+    template = TARGET_TEMPLATES[preset_name].copy()
+    template.update(overrides)
+    
+    return create_target_definition(
+        name=preset_name,
+        **template
+    )
+
+
+def create_icbc_target(name: str, sql_query: str, target_type: str = "binary_classification", **kwargs) -> TargetDefinition:
+    """创建工商银行专用目标变量定义"""
+    return create_target_definition(
+        name=name,
+        target_type=target_type,
+        sql_query=sql_query,
+        bank_code="icbc",
+        business_rules={
+            "data_retention_days": 90,
+            "privacy_compliance": True,
+            "audit_required": True
+        },
+        **kwargs
+    )