Metadata-Version: 2.4
Name: hello-datap-component-base
Version: 0.5.1
Summary: A unified server management framework for data processing component
Author: Data Processing Team
License: MIT
Keywords: data,hello,management,microservice
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: click>=8.0.0
Requires-Dist: pydantic<2.10.0,>=2.0.0
Requires-Dist: python-json-logger>=2.0.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: aliyun-mns-sdk>=1.3.0
Requires-Dist: alibabacloud-oss-v2>=1.1.0
Requires-Dist: pycryptodome>=3.18.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: hypothesis>=6.0.0; extra == "test"

# hello-datap-component-base

数据处理平台组件 SDK：统一入参/出参、Ray 分布式日志、数据跟踪（track）、结果投递（OSS + MNS）。

当前版本：**0.5.1**

## 安装

```bash
pip install hello-datap-component-base
```

Ray 集群由平台或作业入口初始化，组件代码内无需 `ray.init()`。

## 集成方式（推荐：提示词）

**不要从零对照 API 手写骨架。** 将下方提示词交给 Cursor / Copilot 等 AI，附上你的业务描述，即可生成符合平台规范的完整组件代码。

| 场景 | 提示词文件 | SDK 要求 |
|------|------------|----------|
| 普通流水线节点（自行 `ray.get` 批量聚合） | [`prompts/普通组件集成提示词.md`](prompts/普通组件集成提示词.md) | ≥ 0.4.10 |
| 流水线已开启 **「DAG 流式执行 / DAG 漏斗视角」** | [`prompts/DAG流式组件集成提示词.md`](prompts/DAG流式组件集成提示词.md) | ≥ 0.5.0 |

### 如何选型

```
流水线「高级」里是否勾选「启用 DAG 流式执行」？
├── 否 → 用「普通组件」提示词，继承 BaseService
└── 是 → 用「DAG 流式」提示词，继承 DagStreamingService（自动 dagStream 计数 + 并发/超时）
```

提示词内已包含：Ray `runtime_env` 透传、`logger` / `track` 用法、失败隔离、代码骨架。**以提示词为准**，本文不再重复展开。

### 参考示例

提交远程 Ray 集群前，可先对照仓库内完整 Demo：

| 目录 | 类型 | 说明 |
|------|------|------|
| [`examples/batch_compute/`](examples/batch_compute/) | 普通组件 | 加减乘除批量计算，`BaseService` + `ray.get` |
| [`examples/dag_streaming/`](examples/dag_streaming/) | DAG 流式 | 同上业务，含 `outputResult.dagStream` |

各子目录含 `service.py` + `config.json`，运行方式见对应 `README.md`。

## 运行组件

```bash
component_manager start <config.json> --class-name <YourServiceClass>
```

等价：`python -m hello_datap_component_base.cli start ...`

常用子命令：`list` · `validate` · `test`

## 配置要点

`config.json` 中 `params` 会作为 `process(data)` / `extract_items(params)` 的入参；平台注入的跟踪、MNS、OSS 等变量写在 `runtime_env.env_vars` 或由平台下发（提示词中说明如何传给 Ray worker）。

最小字段：`name`（必需）、`version`、`work_flow_id`、`work_flow_instance_id`、`task_id`、`runtime_env`、`params`。

## 返回格式

框架将业务 `process` 返回值包在 `data.out_put` 中；整体结构：

```json
{
  "code": 0,
  "message": "success",
  "processing_time": 0.12,
  "data": {
    "work_flow_id": 123,
    "work_flow_instance_id": 456,
    "task_id": "task-001",
    "out_put": { }
  }
}
```

失败时 `code = -1`，`out_put` 为 `null`。DAG 流式组件的业务结果与 `dagStream` 字段同在 `out_put` 内（详见 DAG 提示词）。

## SDK 能力一览

| 模块 | 用途 |
|------|------|
| `BaseService` | 普通组件基类 |
| `DagStreamingService` | DAG 流式组件（v0.5.0+） |
| `logger` | Header / 按数据 key 分文件的 Ray 业务日志，可上传 OSS |
| `track` | 数据跟踪，两段式上报 MNS |
| `tools` | `extract_specific_env_vars()`、bag 路径解析等 |

## 项目结构

```
hello_datap_component_base/   # SDK 源码
prompts/                      # 集成提示词（推荐入口）
examples/                     # 可运行的参考 Demo
tests/
```

## 许可证

MIT License
