staran 0.2.3__tar.gz → 0.3.0__tar.gz

{staran-0.2.3/staran.egg-info → staran-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: staran
-Version: 0.2.3
+Version: 0.3.0
 Summary: staran - 高性能Python工具库
 Home-page: https://github.com/starlxa/staran
 Author: StarAn
@@ -30,12 +30,15 @@ Dynamic: summary
 
 Staran是一个强大的特征工程和数据处理工具包，提供从数据到模型的完整解决方案。特别针对工银图灵平台优化，让特征工程和模型训练变得前所未有的简单。
 
-## ✨ v1.2.0 新特性
+## ✨ v0.3.0 新特性
 
-- 🏦 **图灵平台完整集成** - 无缝集成turingPythonLib，简化95%代码
-- 📥 **智能数据下载** - 一键从Hive/Hadoop下载特征数据
-- 🔄 **批量特征管理** - 自动化特征表创建、命名和下载
-- 🎯 **端到端ML流程** - 从特征工程到模型训练数据的完整自动化
+- �️ **模块化引擎架构** - 独立的引擎模块，支持Spark、Hive、图灵平台
+- 🔧 **统一接口设计** - 所有引擎提供一致的SQL生成、执行和下载接口
+- 🎯 **继承复用架构** - TuringEngine继承SparkEngine，复用SQL生成逻辑
+- 📦 **清晰代码分离** - SQL生成与平台特定执行逻辑完全分离
+- � **易于扩展** - 新增数据库支持只需实现BaseEngine接口
+- � **独立引擎存储** - engines/文件夹专门存放所有数据库引擎
+- 🔄 **向后兼容** - 保持对原有API的完全兼容
 
 ## 🚀 快速开始
 
@@ -59,10 +62,30 @@ date3 = Date(2025, 4, 15)   # 输出: 2025-04-15
 new_date = date1.add_months(2)  # 输出: 202506 (保持YYYYMM格式)
 ```
 
+### 引擎架构 - 多平台支持
+
+```python
+from staran.engines import create_engine, create_turing_engine
+
+# 1. 使用Spark引擎
+spark_engine = create_engine('spark', 'analytics_db')
+
+# 2. 使用Hive引擎  
+hive_engine = create_engine('hive', 'warehouse_db')
+
+# 3. 使用图灵平台引擎 (继承Spark + turingPythonLib)
+turing_engine = create_turing_engine('analytics_db')
+
+# 统一接口 - 所有引擎都支持相同方法
+sql = spark_engine.generate_aggregation_sql(schema, 2025, 7, ['sum', 'avg'])
+result = turing_engine.create_table('my_table', sql, execute=True)
+download = turing_engine.download_table_data('my_table', 'file:///nfsHome/data.parquet')
+```
+
 ### 特征工程 - SQL自动生成
 
 ```python
-from staran import TableSchema, FeatureGenerator, SQLManager
+from staran import TableSchema, FeatureGenerator, FeatureManager
 
 # 1. 定义表结构
 schema = TableSchema('user_behavior')
@@ -72,11 +95,11 @@ schema.add_field('amount', 'decimal', aggregatable=True)
 schema.add_field('category', 'string')
 schema.set_monthly_unique(True)
 
-# 2. 创建SQL管理器
-manager = SQLManager('analytics_db')
+# 2. 创建特征管理器 (基于引擎架构)
+manager = FeatureManager('analytics_db', engine_type='spark')
 
 # 3. 生成特征SQL
-generator = FeatureGenerator(schema)
+generator = FeatureGenerator(schema, manager)
 result = generator.generate_feature_by_type('aggregation', 2025, 7)
 print(result['sql'])  # 自动生成的聚合特征SQL
 ```
@@ -84,40 +107,54 @@ print(result['sql'])  # 自动生成的聚合特征SQL
 ### 🏦 图灵平台集成 - 一键ML流程
 
 ```python
-from staran.sql.turing_integration import create_turing_integration
+from staran.engines import create_turing_engine
 
-# 1. 创建图灵平台集成实例
-turing = create_turing_integration("ml_analytics")
+# 1. 创建图灵引擎
+turing = create_turing_engine("ml_analytics")
 
-# 2. 一键特征工程 + 数据下载
-result = turing.create_and_download_features(
-    feature_sqls=[
-        "SELECT user_id, sum(amount) as total_amount FROM user_behavior GROUP BY user_id",
-        "SELECT user_id, count(*) as behavior_count FROM user_behavior GROUP BY user_id"
-    ],
-    base_table="user_features",
-    output_dir="file:///nfsHome/ml_features/",
-    mode="cluster"  # 使用集群模式处理大数据
+# 2. 创建特征表
+create_result = turing.create_table(
+    table_name="user_features_2025_07_raw",
+    select_sql="SELECT user_id, sum(amount) as total_amount FROM user_behavior GROUP BY user_id",
+    execute=True,
+    mode="cluster"
 )
 
-print(f"成功创建 {result['summary']['created_successfully']} 个特征表")
-print(f"成功下载 {result['summary']['downloaded_successfully']} 个数据集")
+# 3. 下载特征数据
+download_result = turing.download_table_data(
+    table_name="user_features_2025_07_raw",
+    output_path="file:///nfsHome/ml_features/user_features.parquet",
+    mode="cluster"
+)
 
-# 3. 下载标签数据  
-labels = turing.download_with_turinglib(
+# 4. 批量下载查询结果
+query_result = turing.download_query_result(
     sql="SELECT user_id, label FROM ml.training_labels WHERE dt='2025-07-28'",
-    output_path="file:///nfsHome/ml_labels/",
-    mode="cluster"
+    output_path="file:///nfsHome/ml_labels/labels.parquet"
 )
 
-# 4. 现在可以开始模型训练了！
+print(f"特征表创建: {create_result['status']}")
+print(f"数据下载: {download_result['status']}")
 ```
 
 ## 📖 核心功能
 
-### 🏦 图灵平台集成 - 终极ML解决方案
+### �️ 引擎架构设计
 
-**专为工银图灵平台设计，大幅简化turingPythonLib使用：**
+**模块化引擎架构，清晰分离关注点：**
+
+```
+BaseEngine (抽象基类)
+├── SparkEngine (Spark SQL实现)
+│   └── TuringEngine (继承Spark + turingPythonLib)
+└── HiveEngine (Hive SQL实现)
+```
+
+| 引擎类型 | SQL生成 | 执行方式 | 下载方式 | 适用场景 |
+|---------|---------|---------|---------|---------|
+| SparkEngine | Spark SQL | 本地执行器 | DataFrame保存 | 本地开发、测试 |
+| HiveEngine | Hive SQL | 本地执行器 | 目录导出 | 传统Hive环境 |
+| TuringEngine | Spark SQL | turingPythonLib | tp.download() | 工银图灵平台 |
 
 | 功能对比 | 原生turingPythonLib | Staran集成 |
 |---------|-------------------|------------|
@@ -278,68 +315,69 @@ tomorrow = date.add_days(1)         # 202504 (智能处理)
 
 ```
 staran/
-├── __init__.py                    # 主包入口，v1.2.0功能导出
+├── __init__.py                    # 主包入口，v0.3.0功能导出
+├── engines/                       # 🆕 模块化引擎架构
+│   ├── __init__.py               # 引擎模块入口
+│   ├── base.py                   # BaseEngine抽象基类
+│   ├── spark.py                  # SparkEngine实现
+│   ├── hive.py                   # HiveEngine实现
+│   └── turing.py                 # TuringEngine (继承SparkEngine)
+├── features/                      # 🆕 特征工程模块
+│   ├── __init__.py               # 特征模块入口
+│   ├── manager.py                # FeatureManager (使用引擎架构)
+│   ├── schema.py                 # 表结构定义
+│   └── generator.py              # 特征生成器
+├── examples/                      # 🆕 完整示例模块
+│   ├── __init__.py               # 示例模块入口
+│   └── aum_longtail.py           # AUM代发长尾模型示例
 ├── tools/
 │   ├── __init__.py               # 工具模块
 │   └── date.py                   # Date类实现
-├── sql/
-│   ├── __init__.py              # SQL模块
-│   ├── manager.py               # 🆕 SQL中央管理器 + 下载功能
-│   ├── turing_integration.py    # 🆕 图灵平台完整集成
-│   ├── schema.py                # 表结构定义
-│   ├── generator.py             # 特征生成器 (已增强)
-│   └── engines.py               # SQL引擎（Spark等）
-├── example_download.py           # 🆕 下载功能演示
-├── example_turing_platform.py   # 🆕 图灵平台使用指南
-├── setup.py                     # 安装配置  
-├── README.md                    # 本文档 (已更新)
-└── DOWNLOAD_FEATURES_SUMMARY.py # 🆕 新功能详细说明
+├── setup.py                      # 安装配置  
+├── README.md                     # 本文档 v0.3.0
+└── quick-upload.sh               # 快速部署脚本
 ```
 
 ## 🧪 快速测试
 
-### 图灵平台集成测试
+### 引擎架构测试
 ```python
-from staran.sql.turing_integration import create_turing_integration
+from staran import create_engine, create_turing_engine
 
-# 测试图灵平台环境
-turing = create_turing_integration("test_analytics")
-platform_info = turing.get_platform_info()
+# 测试SparkEngine
+spark = create_engine('spark')
+print(f"Spark引擎: {spark.__class__.__name__}")
 
-print(f"turingPythonLib可用: {platform_info['turinglib_available']}")
-print(f"图灵环境检测: {platform_info['nfs_home_exists']}")
+# 测试TuringEngine继承
+turing = create_turing_engine("test_analytics")
+print(f"Turing引擎父类: {turing.__class__.__bases__[0].__name__}")
+print(f"是否为SparkEngine子类: {isinstance(turing, spark.__class__)}")
 
-# 测试快速下载
-from staran.sql.turing_integration import quick_download
-result = quick_download(
-    sql="SELECT 1 as test_col",
-    output_path="file:///nfsHome/test_data/"
-)
-print(f"快速下载测试: {result['status']}")
+# 测试引擎功能
+sql = turing.generate_sql("SELECT user_id, amount FROM users", {"table": "test"})
+print(f"SQL生成测试: {'success' if sql else 'failed'}")
 ```
 
-### 特征工程测试
+### AUM示例测试  
 ```python
-from staran import TableSchema, FeatureGenerator, SQLManager
+from staran import create_aum_example
 
-# 定义表结构
-schema = TableSchema('user_stats')
-schema.add_primary_key('user_id', 'string')
-schema.add_date_field('date', 'date')
-schema.add_field('amount', 'decimal', aggregatable=True)
-schema.set_monthly_unique(True)
+# 创建示例并查看摘要
+example = create_aum_example("dwegdata03000")
+example.print_summary()
 
-# 创建管理器和生成器
-manager = SQLManager('analytics_db')
-generator = FeatureGenerator(schema)
+# 快速运行（测试模式，不执行实际SQL）
+print("🎯 AUM长尾模型示例已准备就绪")
+print("📊 包含4张业务表的完整特征工程流程")
+```
 
-# 生成特征并查看摘要
-summary = generator.get_feature_summary()
-print(f"生成特征数: {summary['total']}")
+### 一键运行示例
+```python
+from staran import run_aum_example
 
-# 生成聚合特征SQL
-result = generator.generate_feature_by_type('aggregation', 2025, 7)
-print("SQL长度:", len(result['sql']))
+# 最简单的使用方式
+results = run_aum_example("202507")  # 指定特征月份
+print(f"✅ 处理完成: {len(results)} 个表")
 ```
 
 ### Date工具测试
@@ -364,23 +402,46 @@ print(f"完整: {date.format_full()}")      # 2025-04-01
 import sys
 sys.path.append("/nfsHome/staran")  # 假设已上传staran包
 
-# 检查环境
-from staran.sql.turing_integration import create_turing_integration
-turing = create_turing_integration("your_analytics_db")
-print("环境就绪！开始特征工程之旅 🚀")
+# 检查新引擎架构
+from staran import create_turing_engine
+turing = create_turing_engine("your_analytics_db")
+print(f"✅ 引擎类型: {turing.__class__.__name__}")
+print(f"✅ 继承关系: 继承自{turing.__class__.__bases__[0].__name__}")
+print("🚀 环境就绪！开始特征工程之旅")
 ```
 
-### 2. 完整ML流程
+### 2. 运行AUM示例
 ```python
-# 一键完成特征工程到模型训练数据准备
-result = turing.create_and_download_features(
-    feature_sqls=your_feature_sqls,
-    base_table="production_features",
-    output_dir="file:///nfsHome/ml_pipeline/",
-    mode="cluster"
+# 最简单的方式 - 一行代码完成复杂特征工程
+from staran import run_aum_example
+
+results = run_aum_example(
+    feature_date="202507",           # 特征月份
+    database="dwegdata03000",        # 数据库名
+    output_path="file:///nfsHome/aum_features"  # 输出路径
 )
 
-print(f"✅ 成功！{result['summary']['downloaded_successfully']} 个数据集已准备就绪")
+print(f"✅ 成功！处理了4张表，生成了完整的特征数据集")
+print("📂 数据已保存到 /nfsHome/aum_features/ 目录")
+```
+
+### 3. 自定义特征工程
+```python
+# 如需更多控制，使用详细API
+from staran import create_aum_example
+
+example = create_aum_example("dwegdata03000")
+
+# 查看会生成哪些特征
+example.print_summary()
+
+# 运行特征工程
+results = example.run("202507")
+
+# 查看结果
+for table_type, result in results.items():
+    if 'table_name' in result:
+        print(f"{table_type}: {result['table_name']}")
 ```
 
 ## 📊 性能优势
@@ -395,10 +456,58 @@ print(f"✅ 成功！{result['summary']['downloaded_successfully']} 个数据集
 - **批量处理**: 并行下载和增量处理
 - **错误恢复**: 自动重试和断点续传
 
+## 🎯 完整示例
+
+### AUM代发长尾模型 - 简化API
+位置：`staran.examples` 模块
+
+基于真实金融业务场景的完整特征工程示例，展示了新的引擎架构优势：
+
+```python
+# 最简单的使用方式
+from staran import run_aum_example
+
+# 一键运行完整特征工程流程
+results = run_aum_example(
+    feature_date="202507",  # 可选，默认当前月
+    database="dwegdata03000",
+    output_path="file:///nfsHome/aum_longtail"
+)
+
+print(f"✅ 特征工程完成！处理了 {len(results)} 个表")
+```
+
+**更多控制的方式：**
+```python
+from staran import create_aum_example
+
+# 创建示例实例
+example = create_aum_example("dwegdata03000")
+
+# 查看特征摘要
+example.print_summary()
+
+# 运行特征工程
+results = example.run("202507")
+```
+
+**示例特点：**
+- 🏦 **真实业务场景** - 4张银行核心业务表的完整处理
+- 🔧 **智能特征配置** - A表(源表+聚合)，其他表(全特征：环比5个月+同比1年)
+- 📊 **多维度特征** - 客户行为、资产配置、交易统计、境外交易等
+- 🚀 **简化API** - 一行代码完成复杂特征工程
+- 📋 **完整文档** - 每个字段都有详细的业务含义说明
+
+**数据表说明：**
+- **A表** (`bi_hlwj_dfcw_f1_f4_wy`): 客户行为特征 → 仅生成原始拷贝+聚合特征
+- **B表** (`bi_hlwj_zi_chan_avg_wy`): 资产平均余额 → 生成全部特征(聚合+环比5个月+同比1年)
+- **C表** (`bi_hlwj_zi_chang_month_total_zb`): 月度资产配置 → 生成全部特征
+- **D表** (`bi_hlwj_realy_month_stat_wy`): 月度实际统计 → 生成全部特征
+
 ## 📄 许可证
 
 MIT License
 
 ---
 
-**Staran v1.2.0** - 让机器学习特征工程变得前所未有的简单 🌟
+**Staran v0.3.0** - 模块化引擎架构，让机器学习特征工程变得前所未有的简单 🌟