staran 0.2.4__py3-none-any.whl → 0.4.0__py3-none-any.whl

{staran-0.2.4.dist-info → staran-0.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: staran
-Version: 0.2.4
+Version: 0.4.0
 Summary: staran - 高性能Python工具库
 Home-page: https://github.com/starlxa/staran
 Author: StarAn
@@ -24,13 +24,25 @@ Dynamic: requires-dist
 Dynamic: requires-python
 Dynamic: summary
 
-# Staran - 智能特征工程工具包
+# Star## ✨ v0.4.0 新特性
+
+- 📋 **独立Schema模块** - 专门的表结构定义和管理模块
+- 📄 **文档自动生成** - 支持Markdown/PDF/HTML格式的技术文档生成
+- 🏢 **业务域支持** - AUM等业务领域的标准表结构定义
+- 🔗 **无缝集成** - Schema与特征工程examples模块完美集成
+- 🛠️ **模块化引擎架构** - 独立的引擎模块，支持Spark、Hive、图灵平台
+- 🔧 **统一接口设计** - 所有引擎提供一致的SQL生成、执行和下载接口
+- 🎯 **继承复用架构** - TuringEngine继承SparkEngine，复用SQL生成逻辑
+- 📦 **清晰代码分离** - SQL生成与平台特定执行逻辑完全分离
+- 🚀 **易于扩展** - 新增数据库支持只需实现BaseEngine接口
+- 📁 **独立引擎存储** - engines/文件夹专门存放所有数据库引擎
+- 🔄 **向后兼容** - 保持对原有API的完全兼容工程工具包
 
 ## � 专为机器学习设计的Python工具包
 
 Staran是一个强大的特征工程和数据处理工具包，提供从数据到模型的完整解决方案。特别针对工银图灵平台优化，让特征工程和模型训练变得前所未有的简单。
 
-## ✨ v0.2.4 新特性
+## ✨ v0.4.0 新特性
 
 - �️ **模块化引擎架构** - 独立的引擎模块，支持Spark、Hive、图灵平台
 - 🔧 **统一接口设计** - 所有引擎提供一致的SQL生成、执行和下载接口
@@ -82,6 +94,40 @@ result = turing_engine.create_table('my_table', sql, execute=True)
 download = turing_engine.download_table_data('my_table', 'file:///nfsHome/data.parquet')
 ```
 
+### Schema模块 - 表结构管理与文档生成
+
+```python
+from staran import get_aum_schemas, export_aum_docs, SchemaDocumentGenerator
+
+# 1. 获取预定义业务表结构
+schemas = get_aum_schemas()  # 获取AUM业务域的所有表结构
+
+for table_type, schema in schemas.items():
+    print(f"{table_type}: {schema.table_name} ({len(schema.fields)}个字段)")
+
+# 2. 生成业务文档
+docs = export_aum_docs('./docs', 'markdown')  # 生成Markdown格式文档
+
+# 3. 自定义文档生成
+generator = SchemaDocumentGenerator()
+doc_path = generator.export_schema_doc(
+    schema=schemas['behavior'],
+    business_domain="AUM",
+    table_type="behavior",
+    format_type="markdown"
+)
+
+# 4. 与特征工程集成
+from staran import create_aum_example, run_aum_example
+
+# 基于预定义schema创建特征工程示例
+example = create_aum_example()
+summary = example.get_summary()  # 获取特征统计信息
+
+# 一键运行完整流程
+results = run_aum_example('202507')  # 生成916个特征
+```
+
 ### 特征工程 - SQL自动生成
 
 ```python
@@ -315,7 +361,12 @@ tomorrow = date.add_days(1)         # 202504 (智能处理)
 
 ```
 staran/
-├── __init__.py                    # 主包入口，v0.2.4功能导出
+├── __init__.py                    # 主包入口，v0.4.0功能导出
+├── schemas/                       # 🆕 表结构定义与文档生成模块
+│   ├── __init__.py               # Schema模块入口
+│   ├── document_generator.py     # 文档生成器 (MD/PDF/HTML)
+│   └── aum/                      # AUM业务域表结构
+│       └── __init__.py           # AUM表结构定义
 ├── engines/                       # 🆕 模块化引擎架构
 │   ├── __init__.py               # 引擎模块入口
 │   ├── base.py                   # BaseEngine抽象基类
@@ -327,11 +378,14 @@ staran/
 │   ├── manager.py                # FeatureManager (使用引擎架构)
 │   ├── schema.py                 # 表结构定义
 │   └── generator.py              # 特征生成器
+├── examples/                      # 🆕 完整示例模块
+│   ├── __init__.py               # 示例模块入口
+│   └── aum_longtail.py           # AUM代发长尾模型示例
 ├── tools/
 │   ├── __init__.py               # 工具模块
 │   └── date.py                   # Date类实现
 ├── setup.py                      # 安装配置  
-├── README.md                     # 本文档 v0.2.4
+├── README.md                     # 本文档 v0.4.0
 └── quick-upload.sh               # 快速部署脚本
 ```
 
@@ -355,27 +409,26 @@ 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, FeatureManager
+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 = FeatureManager(engine_type='spark', database='analytics_db')
+# 快速运行（测试模式，不执行实际SQL）
+print("🎯 AUM长尾模型示例已准备就绪")
+print("📊 包含4张业务表的完整特征工程流程")
+```
 
-# 生成特征并查看摘要
-summary = manager.get_feature_summary(schema)
-print(f"生成特征数: {summary['total']}")
+### 一键运行示例
+```python
+from staran import run_aum_example
 
-# 生成聚合特征SQL
-result = manager.generate_feature_by_type(schema, 'aggregation', 2025, 7)
-print("SQL长度:", len(result['sql']))
+# 最简单的使用方式
+results = run_aum_example("202507")  # 指定特征月份
+print(f"✅ 处理完成: {len(results)} 个表")
 ```
 
 ### Date工具测试
@@ -408,21 +461,38 @@ print(f"✅ 继承关系: 继承自{turing.__class__.__bases__[0].__name__}")
 print("🚀 环境就绪！开始特征工程之旅")
 ```
 
-### 2. 完整ML流程
+### 2. 运行AUM示例
 ```python
-# 使用新引擎架构进行特征工程
-from staran import FeatureManager
-
-# 创建基于Turing引擎的特征管理器
-manager = FeatureManager(engine_type='turing', database='production_analytics')
+# 最简单的方式 - 一行代码完成复杂特征工程
+from staran import run_aum_example
 
-# 执行SQL并下载结果
-result = manager.execute_and_download(
-    sql="SELECT user_id, features FROM ml_features WHERE dt='2025-07-28'",
-    output_path="file:///nfsHome/ml_pipeline/"
+results = run_aum_example(
+    feature_date="202507",           # 特征月份
+    database="dwegdata03000",        # 数据库名
+    output_path="file:///nfsHome/aum_features"  # 输出路径
 )
 
-print(f"✅ 成功！使用{manager.engine.__class__.__name__}完成数据处理")
+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']}")
 ```
 
 ## 📊 性能优势
@@ -437,10 +507,58 @@ print(f"✅ 成功！使用{manager.engine.__class__.__name__}完成数据处理
 - **批量处理**: 并行下载和增量处理
 - **错误恢复**: 自动重试和断点续传
 
+## 🎯 完整示例
+
+### 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 v0.2.4** - 模块化引擎架构，让机器学习特征工程变得前所未有的简单 🌟
+**Staran v0.4.0** - 模块化引擎架构，让机器学习特征工程变得前所未有的简单 🌟

staran-0.4.0.dist-info/RECORD

@@ -0,0 +1,24 @@
+staran/__init__.py,sha256=cBUxN-qmS_Bf8r-8k94VdA-OLvjdRZyxTNfgd-X_AE8,7234
+staran/engines/__init__.py,sha256=aQCpDxY_JcKlApEsEp2wg_P3IwNDTCFb7OYcLHiPPmk,1627
+staran/engines/base.py,sha256=IIN-QxPsO-q3KmQ3Lz0cB9bs6Oac0Wy5MIF605HrHVw,7969
+staran/engines/hive.py,sha256=-KwZiAvK5cxwnoyYQlqGWrcZkeKhbd8QCX3chpbezd0,5894
+staran/engines/spark.py,sha256=XPxzefD9UF8oigeQISBW892RINJ9dGLbl994FWpIKBc,9361
+staran/engines/turing.py,sha256=XEKkEMMWedvaGxKQ2vEHmB3TWLNLxOu1upgiBylwqjA,15516
+staran/examples/__init__.py,sha256=rXjHvD_EA1sl04WAcOMGnktOwZstjUxaei6bo7pPMII,229
+staran/examples/aum_longtail.py,sha256=UFeLzhslS0Qw1defD9M8mI6Jq4G2BHoyqdjNfX0cgH0,9915
+staran/examples/aum_longtail_old.py,sha256=wZW_3NsU8lOjohtzI1ewzFIqTDAt8lnUberQJVYePfs,21723
+staran/features/__init__.py,sha256=uMloEuevUjUPfro8Yv4STwvxpSVL0J1xsQTzN_EkLpo,1828
+staran/features/engines.py,sha256=kqdS2xjmCVi0Xz1Oc3WaTMIavgAriX8F7VvUgVcpfqo,10039
+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/schemas/__init__.py,sha256=2RkcWCaIkrOHd37zzRCla0-jNg4cPnc6BGmmW5Vha0Y,652
+staran/schemas/document_generator.py,sha256=Lm9rim6yPnT1U_aStaM4KtU9eKxHnDNVfJIusQf5zQY,13120
+staran/schemas/aum/__init__.py,sha256=n_DuAH3ncaScS3hPR72Eq6RtcFj0WTp3fbXHVes3WsE,16743
+staran/tools/__init__.py,sha256=KtudrYnxKD9HZEL4H-mrWlKrmsI3rYjJrLeC9YDTpG4,1054
+staran/tools/date.py,sha256=-QyEMWVx6czMuOIwcV7kR3gBMRVOwb5qevo7GEFSJKE,10488
+staran-0.4.0.dist-info/licenses/LICENSE,sha256=2EmsBIyDCono4iVXNpv5_px9qt2b7hfPq1WuyGVMNP4,1361
+staran-0.4.0.dist-info/METADATA,sha256=doZ3FJjMqxkOgqYKz74dwlJk4ICd4I0P38Qv48YSJG4,18809
+staran-0.4.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+staran-0.4.0.dist-info/top_level.txt,sha256=NOUZtXSh5oSIEjHrC0lQ9WmoKtD010Q00dghWyag-Zs,7
+staran-0.4.0.dist-info/RECORD,,

staran-0.2.4.dist-info/RECORD

@@ -1,8 +0,0 @@
-staran/__init__.py,sha256=wUE__5gRPVTm7Epdrc9cskI2VtgbmhCnGr63TE482dg,6768
-staran/tools/__init__.py,sha256=KtudrYnxKD9HZEL4H-mrWlKrmsI3rYjJrLeC9YDTpG4,1054
-staran/tools/date.py,sha256=-QyEMWVx6czMuOIwcV7kR3gBMRVOwb5qevo7GEFSJKE,10488
-staran-0.2.4.dist-info/licenses/LICENSE,sha256=2EmsBIyDCono4iVXNpv5_px9qt2b7hfPq1WuyGVMNP4,1361
-staran-0.2.4.dist-info/METADATA,sha256=4LPrB-WKoZ7AGGHon0uA1kZDDaHeX8zv1prSXuJYWwc,14510
-staran-0.2.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-staran-0.2.4.dist-info/top_level.txt,sha256=NOUZtXSh5oSIEjHrC0lQ9WmoKtD010Q00dghWyag-Zs,7
-staran-0.2.4.dist-info/RECORD,,