staran 0.4.1__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
+    )