celestialflow 3.2.2__tar.gz → 3.2.4__tar.gz

{celestialflow-3.2.2 → celestialflow-3.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: celestialflow
-Version: 3.2.2
+Version: 3.2.4
 Summary: A flexible GRAPH-based task orchestration framework.
 Author-email: Mr-xiaotian <mingxiaomingtian@gmail.com>
 License: MIT
@@ -12,16 +12,14 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Framework :: FastAPI
 Classifier: Topic :: Software Development :: Libraries
-Requires-Python: >=3.11
+Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 Requires-Dist: tqdm
 Requires-Dist: fastapi
 Requires-Dist: uvicorn
 Requires-Dist: requests
 Requires-Dist: networkx
-Requires-Dist: redis
 Requires-Dist: jinja2
-Requires-Dist: celestialtree>=0.1.2
 
 # CelestialFlow ——一个轻量级、可并行、基于图结构的 Python 任务调度框架
 
@@ -39,8 +37,8 @@ Requires-Dist: celestialtree>=0.1.2
 <p align="center">
   <img src="https://img.shields.io/badge/Task%20Graph-DAG-blueviolet">
   <img src="https://img.shields.io/badge/Workflow-Orchestrator-7c3aed">
-  <img src="https://img.shields.io/badge/IPC-Redis%20Ready-red">
-  <img src="https://img.shields.io/badge/Distributed-Worker%20Friendly-orange">
+  <img src="https://img.shields.io/badge/Event%20Tracing-CelestialTree-0ea5e9">
+  <img src="https://img.shields.io/badge/Web-Dashboard-FastAPI-ec4899">
 </p>
 
 <p align="center">
@@ -73,7 +71,7 @@ TaskGraph 能构建完整的 **有向图结构（Directed Graph）**，不仅支
 
 在执行与调度之外，CelestialFlow 进一步引入 **CelestialTree（简称: ctree） 事件追踪系统**，为每一个任务及其衍生行为（成功、失败、重试、拆分、路由等）记录明确的因果关系。借助 ctree，可以从任意一个初始任务出发，完整还原其在 TaskGraph 中的传播路径与执行轨迹，使任务系统可以进行完整的**追溯、分析、解释**。
 
-在此基础上，CelestialFlow 支持 Web 可视化监控，并可通过 Redis 实现跨进程、跨设备协作；同时引入基于 Go 的外部 worker（通过 Redis 通信），用于承载 CPU 密集型任务，弥补 Python 在该场景下的性能瓶颈。
+在此基础上，CelestialFlow 支持 Web 可视化监控，并提供基于 Redis 的 demo 与 Go Worker 外部协作示例，用于展示按需构建跨进程、跨设备任务协作的方式。
 
 ## 项目结构（Project Structure）
 
@@ -136,6 +134,18 @@ uv pip install celestialflow
 pip install celestialflow
 ```
 
+如果你只使用 CelestialFlow 的核心调度、Web、持久化与 demo/test 之外的常规功能，上面的安装已经足够。
+
+如果你还需要启用 CelestialTree 事件追踪能力，则需要**额外安装** `celestialtree`：
+
+```bash
+# 对已发布包使用者
+uv pip install celestialtree
+
+# 如果你是 clone 仓库后的开发者/贡献者
+uv sync --group dev
+```
+
 一个简单的可运行代码:
 
 ```python
@@ -215,7 +225,7 @@ flowchart TD
 - [runtime/util_hash.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/runtime/util_hash.md)
 - [runtime/util_types.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/runtime/util_types.md)
 - [runtime/util_errors.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/runtime/util_errors.md)
-- [persistence/core_fail.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/persistence/core_fail.md)
+- [persistence/core_fallback.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/persistence/core_fallback.md)
 - [persistence/core_log.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/persistence/core_log.md)
 
 如果你更喜欢通过完整案例理解框架的运行方式，可以参考这篇利用 TaskGraph 从零开始构建项目的教程：
@@ -228,67 +238,98 @@ flowchart TD
 
 你可以继续运行更多的演示代码，这里记录了各个演示文件与其中的演示函数说明：
 
-[🎮demo/](https://github.com/Mr-xiaotian/CelestialFlow/tree/main/docs/zh-CN/demo)
+[🎮demo/ 总览](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/demo/README.md)
 
-​如果你想运行测试代码, 可以先查看如下文档内容:
+如果你想运行测试代码，可以先查看如下文档内容：
 
-[🧪tests/](https://github.com/Mr-xiaotian/CelestialFlow/tree/main/docs/zh-CN/tests)
+[🧪tests/ 总览](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/tests/README.md)
 
-如果你想查看bench内容, 这里的数据成为框架中部分设计的决策依据:
+如果你想查看 bench 内容，这些数据也是框架中部分设计取舍的依据：
 
-[⚡bench/](https://github.com/Mr-xiaotian/CelestialFlow/tree/main/docs/zh-CN/bench)
+[⚡bench/ 总览](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/bench/README.md)
 
 ## 环境要求（Requirements）
 
-**CelestialFlow** 基于 Python 3.11+，并依赖以下核心组件。
-请确保你的环境能够正常安装这些依赖（`pip install celestialflow` 会自动安装）。
+**CelestialFlow** 基于 Python 3.12+，默认运行时依赖以下核心组件。
+其中 `celestialtree` 不再属于默认运行时依赖，而是额外安装的可选组件。
 
 | 依赖包           | 说明 |
 | ----------------- | ---- |
-| **Python ≥ 3.11**  | 运行环境，建议使用 3.11 及以上版本 |
+| **Python ≥ 3.12**  | 运行环境，建议使用 3.12 及以上版本 |
 | **fastapi**       | Web 服务接口框架（用于任务可视化与远程控制） |
 | **uvicorn**       | FastAPI 的高性能 ASGI 服务器 |
 | **requests**      | HTTP 客户端库，用于任务状态上报与远程调用 |
 | **networkx**      | 任务图（TaskGraph）结构与依赖分析 |
 | **jinja2**        | FastAPI 模板引擎，用于 Web 可视化界面渲染 |
 | **tqdm**          | 可选组件，进度条显示，用于任务执行可视化 |
-| **redis**         | 可选组件，用于分布式任务通信（`TaskRedis*` 系列模块） |
-| **celestialtree** | 可选组件，用于任务状态上报与远程调用（`ctree_client`） |
+
+如需运行 `demo/demo_redis.py` 或 Go Worker 示例，请额外安装 `redis` 并准备 Redis 服务；这部分不属于默认运行时依赖。
+
+如需运行依赖 CelestialTree 的 demo / bench / 追踪查询，请额外安装 `celestialtree`，或直接在源码仓库中执行 `uv sync --group dev`。
 
 ## 文件结构（File Structure）
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/Mr-xiaotian/CelestialFlow/main/img/file_structure.svg" alt="FileStructure" />
   <br/>
-  <em>celestial-flow 3.2.2</em>
+  <em>celestial-flow 3.2.4</em>
 </p>
 
 (该视图由我的另一个项目[CelestialVault](https://github.com/Mr-xiaotian/CelestialVault)中inst_file.FileTree.print_tree()生成。转换为图片则借助[Carbon](https://carbon.now.sh)。)
 
 ## 版本日志（Version Log）
-- 3.2.2
+- 3.2.4
   - feat:
-    - `core_server` 中添加数据锁, 避免并发访问导致的错误状态
-    - 优化前端设置面板的显示, 现在只显示全局设置与当前页相关设置
-    - 在设置面板中添加全局设置中的 "是否自动更新" 选项与错误日志页面中的 "排序方式" 两项
+    - **[IMPORTANT]** 合并原有的 `fail_funnel` 与 `success_funnel` 机制为 `fallback` , 并采用 `sqlite` 进行存储
+      - 原有基于 `jsonl` 存储的fail持久化机制在存储时非常好用, 但读取时每次都需要全量读取到内存中再进行检索, 非常麻烦; 我虽然也想过用类似 `redis` 的数据库服务, 但实在不想另外启动第三方服务. 然后我意外发现 `sqlite` 完美符合我的一切要求
+      - Richard 万岁!
+      - 至于原有的 `success_funnel` 机制完全是个半成品: 只能用于 `executor`, 而不能用于 `stage`; 完全在内存存储. 所以借着这次机会也一并重构, 合并入 `fallback_funnel`
+      - 现在 `fallback_funnel` 会在任务 `注入/重复/重试/失败/成功` 时对sqlite中相应记录进行插入/更新/删除操作
+      - 其中在任务成功时默认会删除该条记录, 但如果开启 `executor` 中的 `perist_result` 选项, 则会保留该条记录, 并将 `status` 字段更新为 `success`
+    - **[IMPORTANT]** 移除 `stages` 中的三个redis节点, 并添加demo文件, 说明如果自行构建相关节点
+      - 相比 `TaskSplitter` 与 `TaskRouter`, 这三个节点实在可有可无, 还会导致多一个 `redis` 依赖包
+    - **[IMPORTANT]** `celestialtree` 不再继续作为依赖库, 现有的事件声明机制基于一套protol接口, 并默认使用本地的超简化实现
+      - 这样做同样是为了避免太多库依赖, `celestialtree` 库包含对 `grpcio` 与 `protobuf` 的依赖, 而这两者对于python free-threading版本的支持性不太好, 因此在有他们的情况下 `celestialflow` 无法在free-threading版本下运行----而这是我非常期待的
+      - 根据 `bench_gil_vs_nogil`, 在free-threading版本下, `executor` 在cpu密集任务中会得到5.25倍提升, 而 `graph` 在cpu密集任务中则会得到7.55倍提升. 非常喜人
+    - 在前端 `节点指标走向` 卡片中添加 `全局等待队列`
+    - 在 `graph` 中添加 `start_graph_db` 方法, 接受一个fallback数据库地址, 然后根据其中失败数据进行 `start_graph`; 在 `executor` 中添加 `start_db` 方法, 接受一个fallback数据库地址, 然后根据其中失败数据进行 `start`
+      - 很方便
   - refactor:
-    - 删除前后端通讯中的 `summary` , 节点的总体预期结束时间由各个节点的 `status` 分别传递, 并由前端计算整体的预期结束时间
-    - 修改 `structure_graph`(原 `structure_json`) 字段的内容, 现在更为简洁, 避免信息冗余, 同时方便后续拓展
+    - **[IMPORTANT]** 将server端存储error数据的方式从py原生列表改为一个临时sqlite数据库
+      - 在锤子效应下我想更多的尝试sqlite的使用
+    - 为每个 `graph` 添加基于 `name` 与 `time.time()` 的 `graph_id` 作为唯一性标识符
+    - 重写reporter与server端的交互逻辑
+      - 现在每一轮refresh开始时都会进行状态对齐, 通过 `graph_id` 确定两者所持有的数据是否来自一个 `graph` 对象, 是的话则不用重复push structure/analysis数据
+      - 在状态对齐时如果双方的graph一致, server会返回自己所持有的错误数据中最大的 `event_id` 值, 经过严格校验, `event_id` 在数据库中严格递增
+      - 将reporter中原有的 `push_error_meta` 与 `push_error_content` 合并, 每次刷新时只发送新增的错误数据, 而新增数据则根据server返回的最大 `event_id` 值与本地数据库中的最大 `event_id` 值进行筛选
+    - 为 `graph.connect` 与 `graph_set_stage` 绑定更多职责
+      - 现在节点与 `graph` 在 `ctree` `reporter` 上的同步在 `graph_set_stage` 中完成
+      - 而 `task_queue` 与 `result_queue` 的上下流绑定, 以及 `counter` 的绑定都在 `graph.connect` 中完成
+    - 删除 `TaskEnvelope` 中无关数据, 只保留 `task` `hash` `id` 三项
+      - `source` 字段本就不该添加, 它一致没有发挥作用
+      - `prev` 字段是为了原版 `success_funnel` 而服务的, 现在已经没有必要
+    - `TaskMetrics` 中固定使用 `Lock` 对所有 `counter` 进行限定, 而无关乎 `executor` 的 `execution_mode`
+      - 这种固定的模式在牺牲部分性能的情况下使得代码更加稳定
+      - 根据 `bench_lock_overhead`, 这会导致 `counter` 慢3.2倍左右, 考虑到 `counter` 的更新全部基于 `int` 类型, 本就很快, 可以接受
+    - 在 `process_task_success` 中除去已有的一次 `task.success` 声明, 会在 `result_envelope` 进入 `result_queue` 前再进行 `task.input` 声明
+      - 为了保证fallback的sqlite中 `event_id` 全局统一
+    - `executor.get_fail_pairs`(原 `executor.get_error_pairs`) 会返回 `tuple[T, PeristedError]`
+      - `PeristedError` 由记录的 `error_type` 与 `error_message` 组成
+    - 重写 `TaskRouter` 节点, 现在必须传入一个 `router` 函数, 去指定任务的路由方向
+    - 移除一些没用的方法
+      - 比如 `TaskGraph.get_stage_input_trace`
   - fix:
-    - 修复指标折线图中指标选择失效的问题
-    - 修改 `report.stop` 中_refresh_all的执行顺序, 避免与thread中的刷新冲突
-    - 在 `graph._finalize_nodes` 中添加对thread未终止的防御性检查
-    - 修复 `stage` 中 `start_time` 在未定义前被 `report` 调用的问题
-    - 修复 `TaskRedisTransport._transport` 中使用 `id()` 来计算task_id导致的问题
-    - 修复部分任务无法被hash导致的panic问题
+    - 前端仪表盘页面中的结构图不会再因切换tab而显示空白
+      - 这是很古老的bug, 我不知道我为什么译制片没有修复
   - chore:
-    - 删除所有的 `type: ignore`
-      - 好看不少
-    - 在 `start_*` 函数的doc-string中标注该函数为一次性调用函数
+    - 添加更多demo
+    - 添加更多benchmark
+    - 添加 `Agents.md` 文件
+      - 我受够了无休止的对ai进行强调
 
 更多过往日志可看:
 
-[change_log.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/change_log.md )
+[change_log.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/change_log.md)
 
 ## Star 历史趋势（Star History）
 
@@ -297,7 +338,7 @@ flowchart TD
 ![Star History Chart](https://api.star-history.com/svg?repos=Mr-xiaotian/CelestialFlow&type=Date)
 
 ## 许可（License）
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+This project is licensed under the MIT License - see the [LICENSE](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/LICENSE) file for details.
 
 ## 作者（Author）
 Author: Mr-xiaotian

{celestialflow-3.2.2 → celestialflow-3.2.4}/README.md

@@ -14,8 +14,8 @@
 <p align="center">
   <img src="https://img.shields.io/badge/Task%20Graph-DAG-blueviolet">
   <img src="https://img.shields.io/badge/Workflow-Orchestrator-7c3aed">
-  <img src="https://img.shields.io/badge/IPC-Redis%20Ready-red">
-  <img src="https://img.shields.io/badge/Distributed-Worker%20Friendly-orange">
+  <img src="https://img.shields.io/badge/Event%20Tracing-CelestialTree-0ea5e9">
+  <img src="https://img.shields.io/badge/Web-Dashboard-FastAPI-ec4899">
 </p>
 
 <p align="center">
@@ -48,7 +48,7 @@ TaskGraph 能构建完整的 **有向图结构（Directed Graph）**，不仅支
 
 在执行与调度之外，CelestialFlow 进一步引入 **CelestialTree（简称: ctree） 事件追踪系统**，为每一个任务及其衍生行为（成功、失败、重试、拆分、路由等）记录明确的因果关系。借助 ctree，可以从任意一个初始任务出发，完整还原其在 TaskGraph 中的传播路径与执行轨迹，使任务系统可以进行完整的**追溯、分析、解释**。
 
-在此基础上，CelestialFlow 支持 Web 可视化监控，并可通过 Redis 实现跨进程、跨设备协作；同时引入基于 Go 的外部 worker（通过 Redis 通信），用于承载 CPU 密集型任务，弥补 Python 在该场景下的性能瓶颈。
+在此基础上，CelestialFlow 支持 Web 可视化监控，并提供基于 Redis 的 demo 与 Go Worker 外部协作示例，用于展示按需构建跨进程、跨设备任务协作的方式。
 
 ## 项目结构（Project Structure）
 
@@ -111,6 +111,18 @@ uv pip install celestialflow
 pip install celestialflow
 ```
 
+如果你只使用 CelestialFlow 的核心调度、Web、持久化与 demo/test 之外的常规功能，上面的安装已经足够。
+
+如果你还需要启用 CelestialTree 事件追踪能力，则需要**额外安装** `celestialtree`：
+
+```bash
+# 对已发布包使用者
+uv pip install celestialtree
+
+# 如果你是 clone 仓库后的开发者/贡献者
+uv sync --group dev
+```
+
 一个简单的可运行代码:
 
 ```python
@@ -190,7 +202,7 @@ flowchart TD
 - [runtime/util_hash.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/runtime/util_hash.md)
 - [runtime/util_types.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/runtime/util_types.md)
 - [runtime/util_errors.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/runtime/util_errors.md)
-- [persistence/core_fail.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/persistence/core_fail.md)
+- [persistence/core_fallback.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/persistence/core_fallback.md)
 - [persistence/core_log.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/persistence/core_log.md)
 
 如果你更喜欢通过完整案例理解框架的运行方式，可以参考这篇利用 TaskGraph 从零开始构建项目的教程：
@@ -203,67 +215,98 @@ flowchart TD
 
 你可以继续运行更多的演示代码，这里记录了各个演示文件与其中的演示函数说明：
 
-[🎮demo/](https://github.com/Mr-xiaotian/CelestialFlow/tree/main/docs/zh-CN/demo)
+[🎮demo/ 总览](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/demo/README.md)
 
-​如果你想运行测试代码, 可以先查看如下文档内容:
+如果你想运行测试代码，可以先查看如下文档内容：
 
-[🧪tests/](https://github.com/Mr-xiaotian/CelestialFlow/tree/main/docs/zh-CN/tests)
+[🧪tests/ 总览](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/tests/README.md)
 
-如果你想查看bench内容, 这里的数据成为框架中部分设计的决策依据:
+如果你想查看 bench 内容，这些数据也是框架中部分设计取舍的依据：
 
-[⚡bench/](https://github.com/Mr-xiaotian/CelestialFlow/tree/main/docs/zh-CN/bench)
+[⚡bench/ 总览](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/bench/README.md)
 
 ## 环境要求（Requirements）
 
-**CelestialFlow** 基于 Python 3.11+，并依赖以下核心组件。
-请确保你的环境能够正常安装这些依赖（`pip install celestialflow` 会自动安装）。
+**CelestialFlow** 基于 Python 3.12+，默认运行时依赖以下核心组件。
+其中 `celestialtree` 不再属于默认运行时依赖，而是额外安装的可选组件。
 
 | 依赖包           | 说明 |
 | ----------------- | ---- |
-| **Python ≥ 3.11**  | 运行环境，建议使用 3.11 及以上版本 |
+| **Python ≥ 3.12**  | 运行环境，建议使用 3.12 及以上版本 |
 | **fastapi**       | Web 服务接口框架（用于任务可视化与远程控制） |
 | **uvicorn**       | FastAPI 的高性能 ASGI 服务器 |
 | **requests**      | HTTP 客户端库，用于任务状态上报与远程调用 |
 | **networkx**      | 任务图（TaskGraph）结构与依赖分析 |
 | **jinja2**        | FastAPI 模板引擎，用于 Web 可视化界面渲染 |
 | **tqdm**          | 可选组件，进度条显示，用于任务执行可视化 |
-| **redis**         | 可选组件，用于分布式任务通信（`TaskRedis*` 系列模块） |
-| **celestialtree** | 可选组件，用于任务状态上报与远程调用（`ctree_client`） |
+
+如需运行 `demo/demo_redis.py` 或 Go Worker 示例，请额外安装 `redis` 并准备 Redis 服务；这部分不属于默认运行时依赖。
+
+如需运行依赖 CelestialTree 的 demo / bench / 追踪查询，请额外安装 `celestialtree`，或直接在源码仓库中执行 `uv sync --group dev`。
 
 ## 文件结构（File Structure）
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/Mr-xiaotian/CelestialFlow/main/img/file_structure.svg" alt="FileStructure" />
   <br/>
-  <em>celestial-flow 3.2.2</em>
+  <em>celestial-flow 3.2.4</em>
 </p>
 
 (该视图由我的另一个项目[CelestialVault](https://github.com/Mr-xiaotian/CelestialVault)中inst_file.FileTree.print_tree()生成。转换为图片则借助[Carbon](https://carbon.now.sh)。)
 
 ## 版本日志（Version Log）
-- 3.2.2
+- 3.2.4
   - feat:
-    - `core_server` 中添加数据锁, 避免并发访问导致的错误状态
-    - 优化前端设置面板的显示, 现在只显示全局设置与当前页相关设置
-    - 在设置面板中添加全局设置中的 "是否自动更新" 选项与错误日志页面中的 "排序方式" 两项
+    - **[IMPORTANT]** 合并原有的 `fail_funnel` 与 `success_funnel` 机制为 `fallback` , 并采用 `sqlite` 进行存储
+      - 原有基于 `jsonl` 存储的fail持久化机制在存储时非常好用, 但读取时每次都需要全量读取到内存中再进行检索, 非常麻烦; 我虽然也想过用类似 `redis` 的数据库服务, 但实在不想另外启动第三方服务. 然后我意外发现 `sqlite` 完美符合我的一切要求
+      - Richard 万岁!
+      - 至于原有的 `success_funnel` 机制完全是个半成品: 只能用于 `executor`, 而不能用于 `stage`; 完全在内存存储. 所以借着这次机会也一并重构, 合并入 `fallback_funnel`
+      - 现在 `fallback_funnel` 会在任务 `注入/重复/重试/失败/成功` 时对sqlite中相应记录进行插入/更新/删除操作
+      - 其中在任务成功时默认会删除该条记录, 但如果开启 `executor` 中的 `perist_result` 选项, 则会保留该条记录, 并将 `status` 字段更新为 `success`
+    - **[IMPORTANT]** 移除 `stages` 中的三个redis节点, 并添加demo文件, 说明如果自行构建相关节点
+      - 相比 `TaskSplitter` 与 `TaskRouter`, 这三个节点实在可有可无, 还会导致多一个 `redis` 依赖包
+    - **[IMPORTANT]** `celestialtree` 不再继续作为依赖库, 现有的事件声明机制基于一套protol接口, 并默认使用本地的超简化实现
+      - 这样做同样是为了避免太多库依赖, `celestialtree` 库包含对 `grpcio` 与 `protobuf` 的依赖, 而这两者对于python free-threading版本的支持性不太好, 因此在有他们的情况下 `celestialflow` 无法在free-threading版本下运行----而这是我非常期待的
+      - 根据 `bench_gil_vs_nogil`, 在free-threading版本下, `executor` 在cpu密集任务中会得到5.25倍提升, 而 `graph` 在cpu密集任务中则会得到7.55倍提升. 非常喜人
+    - 在前端 `节点指标走向` 卡片中添加 `全局等待队列`
+    - 在 `graph` 中添加 `start_graph_db` 方法, 接受一个fallback数据库地址, 然后根据其中失败数据进行 `start_graph`; 在 `executor` 中添加 `start_db` 方法, 接受一个fallback数据库地址, 然后根据其中失败数据进行 `start`
+      - 很方便
   - refactor:
-    - 删除前后端通讯中的 `summary` , 节点的总体预期结束时间由各个节点的 `status` 分别传递, 并由前端计算整体的预期结束时间
-    - 修改 `structure_graph`(原 `structure_json`) 字段的内容, 现在更为简洁, 避免信息冗余, 同时方便后续拓展
+    - **[IMPORTANT]** 将server端存储error数据的方式从py原生列表改为一个临时sqlite数据库
+      - 在锤子效应下我想更多的尝试sqlite的使用
+    - 为每个 `graph` 添加基于 `name` 与 `time.time()` 的 `graph_id` 作为唯一性标识符
+    - 重写reporter与server端的交互逻辑
+      - 现在每一轮refresh开始时都会进行状态对齐, 通过 `graph_id` 确定两者所持有的数据是否来自一个 `graph` 对象, 是的话则不用重复push structure/analysis数据
+      - 在状态对齐时如果双方的graph一致, server会返回自己所持有的错误数据中最大的 `event_id` 值, 经过严格校验, `event_id` 在数据库中严格递增
+      - 将reporter中原有的 `push_error_meta` 与 `push_error_content` 合并, 每次刷新时只发送新增的错误数据, 而新增数据则根据server返回的最大 `event_id` 值与本地数据库中的最大 `event_id` 值进行筛选
+    - 为 `graph.connect` 与 `graph_set_stage` 绑定更多职责
+      - 现在节点与 `graph` 在 `ctree` `reporter` 上的同步在 `graph_set_stage` 中完成
+      - 而 `task_queue` 与 `result_queue` 的上下流绑定, 以及 `counter` 的绑定都在 `graph.connect` 中完成
+    - 删除 `TaskEnvelope` 中无关数据, 只保留 `task` `hash` `id` 三项
+      - `source` 字段本就不该添加, 它一致没有发挥作用
+      - `prev` 字段是为了原版 `success_funnel` 而服务的, 现在已经没有必要
+    - `TaskMetrics` 中固定使用 `Lock` 对所有 `counter` 进行限定, 而无关乎 `executor` 的 `execution_mode`
+      - 这种固定的模式在牺牲部分性能的情况下使得代码更加稳定
+      - 根据 `bench_lock_overhead`, 这会导致 `counter` 慢3.2倍左右, 考虑到 `counter` 的更新全部基于 `int` 类型, 本就很快, 可以接受
+    - 在 `process_task_success` 中除去已有的一次 `task.success` 声明, 会在 `result_envelope` 进入 `result_queue` 前再进行 `task.input` 声明
+      - 为了保证fallback的sqlite中 `event_id` 全局统一
+    - `executor.get_fail_pairs`(原 `executor.get_error_pairs`) 会返回 `tuple[T, PeristedError]`
+      - `PeristedError` 由记录的 `error_type` 与 `error_message` 组成
+    - 重写 `TaskRouter` 节点, 现在必须传入一个 `router` 函数, 去指定任务的路由方向
+    - 移除一些没用的方法
+      - 比如 `TaskGraph.get_stage_input_trace`
   - fix:
-    - 修复指标折线图中指标选择失效的问题
-    - 修改 `report.stop` 中_refresh_all的执行顺序, 避免与thread中的刷新冲突
-    - 在 `graph._finalize_nodes` 中添加对thread未终止的防御性检查
-    - 修复 `stage` 中 `start_time` 在未定义前被 `report` 调用的问题
-    - 修复 `TaskRedisTransport._transport` 中使用 `id()` 来计算task_id导致的问题
-    - 修复部分任务无法被hash导致的panic问题
+    - 前端仪表盘页面中的结构图不会再因切换tab而显示空白
+      - 这是很古老的bug, 我不知道我为什么译制片没有修复
   - chore:
-    - 删除所有的 `type: ignore`
-      - 好看不少
-    - 在 `start_*` 函数的doc-string中标注该函数为一次性调用函数
+    - 添加更多demo
+    - 添加更多benchmark
+    - 添加 `Agents.md` 文件
+      - 我受够了无休止的对ai进行强调
 
 更多过往日志可看:
 
-[change_log.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/change_log.md )
+[change_log.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/change_log.md)
 
 ## Star 历史趋势（Star History）
 
@@ -272,7 +315,7 @@ flowchart TD
 ![Star History Chart](https://api.star-history.com/svg?repos=Mr-xiaotian/CelestialFlow&type=Date)
 
 ## 许可（License）
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+This project is licensed under the MIT License - see the [LICENSE](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/LICENSE) file for details.
 
 ## 作者（Author）
 Author: Mr-xiaotian

{celestialflow-3.2.2 → celestialflow-3.2.4}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "celestialflow"
-version = "3.2.2"
+version = "3.2.4"
 description = "A flexible GRAPH-based task orchestration framework."
 readme = "README.md"
 license = { text = "MIT" }
 authors = [{ name = "Mr-xiaotian", email = "mingxiaomingtian@gmail.com" }]
 keywords = ["workflow", "task", "graph", "async", "CelestialFlow"]
-requires-python = ">=3.11"
+requires-python = ">=3.12"
 
 dependencies = [
     "tqdm",
@@ -18,9 +18,7 @@ dependencies = [
     "uvicorn",
     "requests",
     "networkx",
-    "redis",
     "jinja2",
-    "celestialtree>=0.1.2",
 ]
 
 classifiers = [
@@ -72,6 +70,8 @@ dev = [
     "python-dotenv>=1.2.2",
     "ruff>=0.15.0",
     "pyright>=1.1.409",
+    "redis",
+    "celestialtree>=0.1.3",
 ]
 
 [tool.pyright]
@@ -79,14 +79,11 @@ include = ["src"]
 ignore = ["tests", "**/tests/**", "typings", "demo", "bench", "experiments", "examples", "temp"]
 
 typeCheckingMode = "strict"
-reportExplicitAny = "none"
-reportAny = "none"
-reportUnannotatedClassAttribute = "none"
 reportUnusedFunction = "none"
 reportImplicitOverride = "none"
 
 [tool.ruff]
-target-version = "py311"
+target-version = "py312"
 exclude = ["tests", "typings", "demo", "bench", "experiments", "examples", "temp"]
 
 [tool.ruff.lint]

{celestialflow-3.2.2 → celestialflow-3.2.4}/src/celestialflow/__init__.py

@@ -13,19 +13,15 @@ from .graph import (
     TaskLoop,
     TaskWheel,
 )
-from .observability import BaseObserver, CallbackObserver, TaskProgress
-from .persistence.util_jsonl import (
-    load_jsonl_logs,
-    load_task_by_error,
-    load_task_by_stage,
+from .observability import BaseObserver, TaskProgress
+from .persistence.util_sqlite import (
+    load_records,
+    load_records_grouped_by_stage,
 )
 from .runtime.util_hash import make_hashable
 from .runtime.util_types import TerminationSignal
 from .stage import (
     TaskExecutor,
-    TaskRedisAck,
-    TaskRedisSource,
-    TaskRedisTransport,
     TaskRouter,
     TaskSplitter,
     TaskStage,
@@ -36,7 +32,6 @@ from .web import TaskWebServer
 
 __all__ = [
     "BaseObserver",
-    "CallbackObserver",
     "TaskChain",
     "TaskComplete",
     "TaskCross",
@@ -45,9 +40,6 @@ __all__ = [
     "TaskGrid",
     "TaskLoop",
     "TaskProgress",
-    "TaskRedisAck",
-    "TaskRedisSource",
-    "TaskRedisTransport",
     "TaskRouter",
     "TaskSplitter",
     "TaskStage",
@@ -57,8 +49,7 @@ __all__ = [
     "benchmark_executor",
     "benchmark_graph",
     "format_table",
-    "load_jsonl_logs",
-    "load_task_by_error",
-    "load_task_by_stage",
+    "load_records",
+    "load_records_grouped_by_stage",
     "make_hashable",
 ]