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

staran/models/__init__.py

@@ -0,0 +1,81 @@
+"""
+Staran Models Module - v0.5.0
+
+专业的机器学习模型配置和管理模块，提供：
+- 模型配置管理 (ModelConfig)
+- 目标变量定义 (TargetDefinition) 
+- 银行特定配置支持
+- SQL驱动的target生成
+- 模型部署和版本管理
+
+支持的模型类型：
+- 分类模型 (Classification)
+- 回归模型 (Regression)
+- 聚类模型 (Clustering)
+- 时间序列模型 (TimeSeries)
+
+支持的银行：
+- 工商银行 (ICBC)
+- 通用配置 (Generic)
+"""
+
+from .config import ModelConfig, ModelType, create_model_config
+from .target import TargetDefinition, TargetType, create_target_definition
+from .registry import ModelRegistry, register_model, get_model_config, save_model_registry
+from .bank_configs import BankConfig, get_bank_config, register_bank_config
+
+# 版本信息
+__version__ = "0.5.0"
+
+# 主要导出
+__all__ = [
+    # 模型配置
+    'ModelConfig',
+    'ModelType', 
+    'create_model_config',
+    
+    # 目标定义
+    'TargetDefinition',
+    'TargetType',
+    'create_target_definition',
+    
+    # 模型注册
+    'ModelRegistry',
+    'register_model',
+    'get_model_config',
+    'save_model_registry',
+    
+    # 银行配置
+    'BankConfig',
+    'get_bank_config', 
+    'register_bank_config',
+]
+
+# 便捷函数
+def create_icbc_model(model_name: str, model_type: str, target_sql: str, algorithm: str = "random_forest", **kwargs):
+    """创建工商银行专用模型配置的便捷函数"""
+    bank_config = get_bank_config('icbc')
+    model_config = create_model_config(
+        name=model_name,
+        model_type=model_type,
+        algorithm=algorithm,
+        bank_code="icbc",
+        **kwargs
+    )
+    
+    target_config = create_target_definition(
+        name=f"{model_name}_target",
+        target_type="sql_based",
+        sql_query=target_sql,
+        bank_code="icbc"
+    )
+    
+    return register_model(model_config, target_config)
+
+def list_available_models():
+    """列出所有可用的模型配置"""
+    return ModelRegistry.list_models()
+
+def get_model_summary(model_name: str):
+    """获取模型配置摘要"""
+    return ModelRegistry.get_model_summary(model_name)

staran/models/bank_configs.py

@@ -0,0 +1,269 @@
+"""
+银行特定配置模块
+
+为不同银行提供定制化的配置和业务规则
+"""
+
+from enum import Enum
+from typing import Dict, Any, List, Optional
+from dataclasses import dataclass, field
+
+
+class BankCode(Enum):
+    """银行代码枚举"""
+    ICBC = "icbc"           # 工商银行
+    CCB = "ccb"             # 建设银行
+    BOC = "boc"             # 中国银行
+    ABC = "abc"             # 农业银行
+    CMB = "cmb"             # 招商银行
+    GENERIC = "generic"     # 通用配置
+
+
+@dataclass
+class BankConfig:
+    """银行配置类"""
+    # 基本信息
+    bank_code: str                              # 银行代码
+    bank_name: str                              # 银行名称
+    region: str = "cn"                          # 地区代码
+    
+    # 数据库配置
+    database_config: Dict[str, Any] = field(default_factory=dict)
+    
+    # 表名映射 (不同银行的表名可能不同)
+    table_mappings: Dict[str, str] = field(default_factory=dict)
+    
+    # 字段映射 (不同银行的字段名可能不同)
+    field_mappings: Dict[str, Dict[str, str]] = field(default_factory=dict)
+    
+    # 业务规则
+    business_rules: Dict[str, Any] = field(default_factory=dict)
+    
+    # 合规要求
+    compliance_rules: Dict[str, Any] = field(default_factory=dict)
+    
+    # 数据处理规则
+    data_processing_rules: Dict[str, Any] = field(default_factory=dict)
+    
+    # 模型部署配置
+    deployment_config: Dict[str, Any] = field(default_factory=dict)
+    
+    # 特征工程配置
+    feature_engineering_config: Dict[str, Any] = field(default_factory=dict)
+    
+    def get_table_name(self, standard_table: str) -> str:
+        """获取银行特定的表名"""
+        return self.table_mappings.get(standard_table, standard_table)
+    
+    def get_field_name(self, table: str, standard_field: str) -> str:
+        """获取银行特定的字段名"""
+        table_fields = self.field_mappings.get(table, {})
+        return table_fields.get(standard_field, standard_field)
+    
+    def get_business_rule(self, rule_name: str, default=None):
+        """获取业务规则"""
+        return self.business_rules.get(rule_name, default)
+    
+    def validate_compliance(self, operation: str) -> bool:
+        """验证操作是否符合合规要求"""
+        compliance_checks = self.compliance_rules.get(operation, {})
+        # 这里可以实现具体的合规检查逻辑
+        return compliance_checks.get('enabled', True)
+
+
+# 银行配置注册表
+_BANK_CONFIGS: Dict[str, BankConfig] = {}
+
+
+def register_bank_config(config: BankConfig):
+    """注册银行配置"""
+    _BANK_CONFIGS[config.bank_code] = config
+    print(f"✅ 银行配置 {config.bank_code} ({config.bank_name}) 注册成功")
+
+
+def get_bank_config(bank_code: str) -> Optional[BankConfig]:
+    """获取银行配置"""
+    return _BANK_CONFIGS.get(bank_code)
+
+
+def list_bank_configs() -> List[Dict[str, str]]:
+    """列出所有银行配置"""
+    return [
+        {
+            'bank_code': config.bank_code,
+            'bank_name': config.bank_name,
+            'region': config.region
+        }
+        for config in _BANK_CONFIGS.values()
+    ]
+
+
+# 预定义银行配置
+def create_icbc_config() -> BankConfig:
+    """创建工商银行配置"""
+    return BankConfig(
+        bank_code="icbc",
+        bank_name="中国工商银行",
+        region="cn",
+        
+        database_config={
+            "default_database": "dwegdata03000",
+            "connection_pool_size": 10,
+            "query_timeout": 300
+        },
+        
+        table_mappings={
+            "behavior_table": "bi_hlwj_dfcw_f1_f4_wy",
+            "asset_avg_table": "bi_hlwj_zi_chan_avg_wy", 
+            "asset_config_table": "bi_hlwj_zi_chang_month_total_zb",
+            "monthly_stat_table": "bi_hlwj_realy_month_stat_wy"
+        },
+        
+        field_mappings={
+            "behavior_table": {
+                "customer_id": "party_id",
+                "date_field": "data_dt"
+            }
+        },
+        
+        business_rules={
+            "data_retention_days": 90,
+            "min_sample_size": 1000,
+            "max_features": 500,
+            "risk_threshold": 0.8,
+            "aum_threshold": 100000,
+            "longtail_definition": {
+                "asset_threshold": 50000,
+                "activity_threshold": 0.3
+            }
+        },
+        
+        compliance_rules={
+            "data_export": {
+                "enabled": True,
+                "approval_required": True,
+                "encryption_required": True
+            },
+            "model_deployment": {
+                "enabled": True,
+                "testing_required": True,
+                "documentation_required": True
+            },
+            "feature_selection": {
+                "enabled": True,
+                "sensitive_data_allowed": False,
+                "audit_trail_required": True
+            }
+        },
+        
+        data_processing_rules={
+            "missing_value_strategy": "median",
+            "outlier_detection": True,
+            "outlier_threshold": 3.0,
+            "feature_scaling": "standard",
+            "categorical_encoding": "one_hot"
+        },
+        
+        deployment_config={
+            "platform": "turing",
+            "environment": "production",
+            "monitoring_enabled": True,
+            "auto_scaling": True,
+            "backup_required": True
+        },
+        
+        feature_engineering_config={
+            "time_windows": ["1_month", "3_months", "6_months", "1_year"],
+            "aggregation_functions": ["sum", "avg", "max", "min", "std"],
+            "interaction_features": True,
+            "polynomial_features": False,
+            "target_encoding": True
+        }
+    )
+
+
+def create_generic_config() -> BankConfig:
+    """创建通用银行配置"""
+    return BankConfig(
+        bank_code="generic",
+        bank_name="通用银行配置",
+        region="generic",
+        
+        database_config={
+            "default_database": "default_db",
+            "connection_pool_size": 5,
+            "query_timeout": 180
+        },
+        
+        table_mappings={
+            "behavior_table": "customer_behavior",
+            "asset_avg_table": "customer_assets",
+            "asset_config_table": "asset_config", 
+            "monthly_stat_table": "monthly_stats"
+        },
+        
+        business_rules={
+            "data_retention_days": 30,
+            "min_sample_size": 100,
+            "max_features": 100
+        },
+        
+        compliance_rules={
+            "data_export": {"enabled": True},
+            "model_deployment": {"enabled": True}
+        },
+        
+        data_processing_rules={
+            "missing_value_strategy": "mean",
+            "outlier_detection": False,
+            "feature_scaling": "none"
+        }
+    )
+
+
+# 初始化默认银行配置
+def initialize_default_configs():
+    """初始化默认银行配置"""
+    # 注册工商银行配置
+    register_bank_config(create_icbc_config())
+    
+    # 注册通用配置
+    register_bank_config(create_generic_config())
+
+
+# 自动初始化
+initialize_default_configs()
+
+
+# 新疆工行特定配置
+def create_xinjiang_icbc_config() -> BankConfig:
+    """创建新疆工商银行配置"""
+    base_config = create_icbc_config()
+    
+    # 基于基础工行配置进行定制
+    base_config.bank_code = "xinjiang_icbc"
+    base_config.bank_name = "新疆工商银行"
+    base_config.region = "xinjiang"
+    
+    # 新疆特定的业务规则
+    base_config.business_rules.update({
+        "regional_compliance": True,
+        "minority_customer_support": True,
+        "language_support": ["zh", "ug"],  # 中文和维吾尔语
+        "timezone": "Asia/Urumqi",
+        "currency_support": ["CNY"],
+        "cross_border_transaction": True
+    })
+    
+    # 新疆特定的数据处理规则
+    base_config.data_processing_rules.update({
+        "character_encoding": "utf-8",
+        "regional_holidays": True,
+        "time_zone_conversion": True
+    })
+    
+    return base_config
+
+
+# 注册新疆工行配置
+register_bank_config(create_xinjiang_icbc_config())

staran/models/config.py

@@ -0,0 +1,271 @@
+"""
+模型配置管理模块
+
+定义模型的核心配置信息，包括模型类型、参数、特征配置等
+"""
+
+from enum import Enum
+from typing import Dict, Any, List, Optional
+from dataclasses import dataclass, field
+from datetime import datetime
+
+
+class ModelType(Enum):
+    """模型类型枚举"""
+    CLASSIFICATION = "classification"
+    REGRESSION = "regression" 
+    CLUSTERING = "clustering"
+    TIME_SERIES = "time_series"
+    ANOMALY_DETECTION = "anomaly_detection"
+    RECOMMENDATION = "recommendation"
+
+
+class ModelAlgorithm(Enum):
+    """模型算法枚举"""
+    # 分类算法
+    LOGISTIC_REGRESSION = "logistic_regression"
+    RANDOM_FOREST = "random_forest"
+    GRADIENT_BOOSTING = "gradient_boosting"
+    SVM = "svm"
+    NEURAL_NETWORK = "neural_network"
+    
+    # 回归算法
+    LINEAR_REGRESSION = "linear_regression"
+    RIDGE_REGRESSION = "ridge_regression"
+    LASSO_REGRESSION = "lasso_regression"
+    
+    # 聚类算法
+    KMEANS = "kmeans"
+    DBSCAN = "dbscan"
+    HIERARCHICAL = "hierarchical"
+    
+    # 时间序列
+    ARIMA = "arima"
+    LSTM = "lstm"
+    PROPHET = "prophet"
+
+
+@dataclass
+class FeatureConfig:
+    """特征配置"""
+    schema_name: str                    # 使用的schema名称 (如 'aum')
+    table_types: List[str]              # 使用的表类型列表 (如 ['behavior', 'asset_avg'])
+    feature_selection: bool = True      # 是否启用特征选择
+    feature_engineering: bool = True    # 是否启用特征工程
+    scaling: bool = True                # 是否启用特征缩放
+    encoding: Dict[str, str] = field(default_factory=dict)  # 编码配置
+
+
+@dataclass 
+class ModelConfig:
+    """模型配置类"""
+    # 基本信息
+    name: str                           # 模型名称
+    model_type: ModelType               # 模型类型
+    algorithm: ModelAlgorithm           # 使用的算法
+    version: str = "1.0.0"              # 模型版本
+    
+    # 特征配置
+    feature_config: FeatureConfig = None
+    
+    # 模型参数
+    hyperparameters: Dict[str, Any] = field(default_factory=dict)
+    
+    # 训练配置
+    training_config: Dict[str, Any] = field(default_factory=lambda: {
+        'test_size': 0.2,
+        'random_state': 42,
+        'cross_validation': True,
+        'cv_folds': 5
+    })
+    
+    # 评估配置
+    evaluation_metrics: List[str] = field(default_factory=list)
+    
+    # 银行特定配置
+    bank_code: str = "generic"          # 银行代码
+    business_domain: str = "generic"    # 业务领域
+    
+    # 元数据
+    description: str = ""               # 模型描述
+    created_at: datetime = field(default_factory=datetime.now)
+    created_by: str = "system"          # 创建者
+    tags: List[str] = field(default_factory=list)
+    
+    # 部署配置
+    deployment_config: Dict[str, Any] = field(default_factory=dict)
+    
+    def __post_init__(self):
+        """初始化后处理"""
+        if self.feature_config is None:
+            self.feature_config = FeatureConfig(
+                schema_name="generic",
+                table_types=["base"]
+            )
+        
+        # 根据模型类型设置默认评估指标
+        if not self.evaluation_metrics:
+            self.evaluation_metrics = self._get_default_metrics()
+    
+    def _get_default_metrics(self) -> List[str]:
+        """根据模型类型获取默认评估指标"""
+        if self.model_type == ModelType.CLASSIFICATION:
+            return ['accuracy', 'precision', 'recall', 'f1_score', 'auc']
+        elif self.model_type == ModelType.REGRESSION:
+            return ['mae', 'mse', 'rmse', 'r2_score']
+        elif self.model_type == ModelType.CLUSTERING:
+            return ['silhouette_score', 'calinski_harabasz_score']
+        else:
+            return ['custom_metric']
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """转换为字典格式"""
+        return {
+            'name': self.name,
+            'model_type': self.model_type.value,
+            'algorithm': self.algorithm.value,
+            'version': self.version,
+            'feature_config': {
+                'schema_name': self.feature_config.schema_name,
+                'table_types': self.feature_config.table_types,
+                'feature_selection': self.feature_config.feature_selection,
+                'feature_engineering': self.feature_config.feature_engineering,
+                'scaling': self.feature_config.scaling,
+                'encoding': self.feature_config.encoding
+            },
+            'hyperparameters': self.hyperparameters,
+            'training_config': self.training_config,
+            'evaluation_metrics': self.evaluation_metrics,
+            'bank_code': self.bank_code,
+            'business_domain': self.business_domain,
+            'description': self.description,
+            'created_at': self.created_at.isoformat(),
+            'created_by': self.created_by,
+            'tags': self.tags,
+            'deployment_config': self.deployment_config
+        }
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> 'ModelConfig':
+        """从字典创建ModelConfig实例"""
+        feature_config_data = data.get('feature_config', {})
+        feature_config = FeatureConfig(
+            schema_name=feature_config_data.get('schema_name', 'generic'),
+            table_types=feature_config_data.get('table_types', ['base']),
+            feature_selection=feature_config_data.get('feature_selection', True),
+            feature_engineering=feature_config_data.get('feature_engineering', True),
+            scaling=feature_config_data.get('scaling', True),
+            encoding=feature_config_data.get('encoding', {})
+        )
+        
+        return cls(
+            name=data['name'],
+            model_type=ModelType(data['model_type']),
+            algorithm=ModelAlgorithm(data['algorithm']),
+            version=data.get('version', '1.0.0'),
+            feature_config=feature_config,
+            hyperparameters=data.get('hyperparameters', {}),
+            training_config=data.get('training_config', {}),
+            evaluation_metrics=data.get('evaluation_metrics', []),
+            bank_code=data.get('bank_code', 'generic'),
+            business_domain=data.get('business_domain', 'generic'),
+            description=data.get('description', ''),
+            created_by=data.get('created_by', 'system'),
+            tags=data.get('tags', []),
+            deployment_config=data.get('deployment_config', {})
+        )
+
+
+def create_model_config(
+    name: str,
+    model_type: str,
+    algorithm: str,
+    schema_name: str = "generic",
+    table_types: List[str] = None,
+    bank_code: str = "generic",
+    **kwargs
+) -> ModelConfig:
+    """
+    创建模型配置的便捷函数
+    
+    Args:
+        name: 模型名称
+        model_type: 模型类型 
+        algorithm: 算法名称
+        schema_name: 使用的schema名称
+        table_types: 使用的表类型列表
+        bank_code: 银行代码
+        **kwargs: 其他配置参数
+        
+    Returns:
+        ModelConfig实例
+    """
+    if table_types is None:
+        table_types = ["base"]
+    
+    feature_config = FeatureConfig(
+        schema_name=schema_name,
+        table_types=table_types
+    )
+    
+    return ModelConfig(
+        name=name,
+        model_type=ModelType(model_type),
+        algorithm=ModelAlgorithm(algorithm),
+        feature_config=feature_config,
+        bank_code=bank_code,
+        **kwargs
+    )
+
+
+# 预定义的模型配置模板
+PRESET_CONFIGS = {
+    "aum_longtail_classification": {
+        "model_type": "classification",
+        "algorithm": "random_forest",
+        "schema_name": "aum",
+        "table_types": ["behavior", "asset_avg", "asset_config", "monthly_stat"],
+        "hyperparameters": {
+            "n_estimators": 100,
+            "max_depth": 10,
+            "random_state": 42
+        },
+        "description": "AUM长尾客户分类模型"
+    },
+    
+    "customer_value_regression": {
+        "model_type": "regression", 
+        "algorithm": "gradient_boosting",
+        "schema_name": "aum",
+        "table_types": ["behavior", "asset_avg"],
+        "hyperparameters": {
+            "n_estimators": 150,
+            "learning_rate": 0.1,
+            "max_depth": 8
+        },
+        "description": "客户价值预测回归模型"
+    }
+}
+
+
+def create_preset_config(preset_name: str, **overrides) -> ModelConfig:
+    """
+    基于预设模板创建模型配置
+    
+    Args:
+        preset_name: 预设模板名称
+        **overrides: 覆盖的配置参数
+        
+    Returns:
+        ModelConfig实例
+    """
+    if preset_name not in PRESET_CONFIGS:
+        raise ValueError(f"未知的预设配置: {preset_name}")
+    
+    config = PRESET_CONFIGS[preset_name].copy()
+    config.update(overrides)
+    
+    return create_model_config(
+        name=preset_name,
+        **config
+    )

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
+    )

{staran-0.4.2.dist-info → staran-0.5.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: staran
-Version: 0.4.2
+Version: 0.5.0
 Summary: staran - 高性能Python工具库
 Home-page: https://github.com/starlxa/staran
 Author: StarAn

{staran-0.4.2.dist-info → staran-0.5.0.dist-info}/RECORD

@@ -12,13 +12,18 @@ staran/features/engines.py,sha256=kqdS2xjmCVi0Xz1Oc3WaTMIavgAriX8F7VvUgVcpfqo,10
 staran/features/generator.py,sha256=CI1F_PshOvokQJelsqSaVp-SNQpMc-WVmjMQKzgdeLw,23114
 staran/features/manager.py,sha256=2-3Hc3qthtyzwiuQy5QTz6RfhKK3szoylconzI3moc4,5201
 staran/features/schema.py,sha256=FwOfpTcxq4K8zkO3MFNqKPQBp_e8qY-N6gazqm9_lAQ,6067
+staran/models/__init__.py,sha256=NH4r6GTAz9MeUfq1jAyVkx-nC4bM78XvbWA9TuwMLik,2141
+staran/models/bank_configs.py,sha256=wN3GA_8cb5wevDC-sWRcJ3lMuaHahZVjC85K_t2aQt0,8177
+staran/models/config.py,sha256=fTbZtJq4-ZuCSSd1eW7TkIbEdDyZv2agHJCYnwOCJ_s,8886
+staran/models/registry.py,sha256=Zeey4TtbHtJ40odyZQzOLijyZCmlMBRuniPk_znS2Q8,10223
+staran/models/target.py,sha256=gKTTatxvOJjmE50qD6G6mhlYLuZL3Cvn3FLNbXl1eeU,10531
 staran/schemas/__init__.py,sha256=2RkcWCaIkrOHd37zzRCla0-jNg4cPnc6BGmmW5Vha0Y,652
 staran/schemas/document_generator.py,sha256=Mr7TjmKwspqxXnp9DhzZxsRx0l2Bo7MOI8mOxRtgwxU,13600
 staran/schemas/aum/__init__.py,sha256=jVkmJdhHGHdGE4rJ605zsRU2zIQMEHWnlgW2ZQk8AdU,13082
 staran/tools/__init__.py,sha256=KtudrYnxKD9HZEL4H-mrWlKrmsI3rYjJrLeC9YDTpG4,1054
 staran/tools/date.py,sha256=-QyEMWVx6czMuOIwcV7kR3gBMRVOwb5qevo7GEFSJKE,10488
-staran-0.4.2.dist-info/licenses/LICENSE,sha256=2EmsBIyDCono4iVXNpv5_px9qt2b7hfPq1WuyGVMNP4,1361
-staran-0.4.2.dist-info/METADATA,sha256=u8_IU7kGJqbFbKZLXUIgACqklcrSp56UWcawoWAtGtY,18809
-staran-0.4.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-staran-0.4.2.dist-info/top_level.txt,sha256=NOUZtXSh5oSIEjHrC0lQ9WmoKtD010Q00dghWyag-Zs,7
-staran-0.4.2.dist-info/RECORD,,
+staran-0.5.0.dist-info/licenses/LICENSE,sha256=2EmsBIyDCono4iVXNpv5_px9qt2b7hfPq1WuyGVMNP4,1361
+staran-0.5.0.dist-info/METADATA,sha256=1c6403YfhOFEsZV7Ng1pe4B_wlRdp8SZypmhIH_AaVo,18809
+staran-0.5.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+staran-0.5.0.dist-info/top_level.txt,sha256=NOUZtXSh5oSIEjHrC0lQ9WmoKtD010Q00dghWyag-Zs,7
+staran-0.5.0.dist-info/RECORD,,