by-framework 0.2.0__tar.gz → 0.2.2.dev0__tar.gz

{by_framework-0.2.0 → by_framework-0.2.2.dev0}/.github/workflows/publish.yml

@@ -9,9 +9,11 @@ on:
       - "by-framework-trace-langfuse-v*"
       - "by-framework-trace-phoenix-v*"
       - "by-framework-langgraph-v*"
+      - "by-framework-adk-v*"
 
 permissions:
-  contents: read
+  contents: write
+  pull-requests: write
 
 jobs:
   resolve-package:
@@ -57,6 +59,11 @@ jobs:
               echo "package_dir=libs/by-framework-langgraph" >> "$GITHUB_OUTPUT"
               echo "version=${REF_NAME#by-framework-langgraph-v}" >> "$GITHUB_OUTPUT"
               ;;
+            by-framework-adk-v*)
+              echo "package_name=by-framework-adk" >> "$GITHUB_OUTPUT"
+              echo "package_dir=libs/by-framework-adk" >> "$GITHUB_OUTPUT"
+              echo "version=${REF_NAME#by-framework-adk-v}" >> "$GITHUB_OUTPUT"
+              ;;
             *)
               echo "Unsupported tag: $REF_NAME" >&2
               exit 1
@@ -133,3 +140,74 @@ jobs:
         uses: pypa/gh-action-pypi-publish@release/v1
         with:
           packages-dir: dist/
+
+  post-release:
+    runs-on: ubuntu-latest
+    needs:
+      - resolve-package
+      - publish
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.ref }}
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Create release branch
+        env:
+          PACKAGE_NAME: ${{ needs.resolve-package.outputs.package_name }}
+          VERSION: ${{ needs.resolve-package.outputs.version }}
+        run: |
+          RELEASE_BRANCH="release/${PACKAGE_NAME}/v${VERSION}"
+          git checkout -b "$RELEASE_BRANCH"
+          git push origin "$RELEASE_BRANCH"
+
+      - name: Bump version and create PR
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PACKAGE_NAME: ${{ needs.resolve-package.outputs.package_name }}
+          PACKAGE_DIR: ${{ needs.resolve-package.outputs.package_dir }}
+          VERSION: ${{ needs.resolve-package.outputs.version }}
+        run: |
+          # Calculate next version using Python to support pre-releases (e.g., 0.2.3b0 -> 0.2.3b1, 0.2.3 -> 0.2.4.dev0)
+          NEXT_VERSION=$(python -c 'if True:
+              import re, sys
+              version = sys.argv[1]
+              match = re.search(r"(a|b|rc|dev)(\d+)$", version)
+              if match:
+                  prefix = version[:match.start()]
+                  suffix_type = match.group(1)
+                  suffix_num = int(match.group(2))
+                  print(f"{prefix}{suffix_type}{suffix_num + 1}")
+              else:
+                  parts = version.split(".")
+                  try:
+                      parts[-1] = str(int(parts[-1]) + 1)
+                      print(".".join(parts) + ".dev0")
+                  except ValueError:
+                      print(version + ".dev0")
+          ' "$VERSION")
+
+          PYPROJECT="${PACKAGE_DIR}/pyproject.toml"
+          sed -i "s/version = \"${VERSION}\"/version = \"${NEXT_VERSION}\"/" "$PYPROJECT"
+
+          # Regenerate uv.lock to align with the new version bump in workspace
+          uv lock
+
+          BUMP_BRANCH="bump/${PACKAGE_NAME}/v${NEXT_VERSION}"
+          git checkout -b "$BUMP_BRANCH"
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add "$PYPROJECT" uv.lock
+          git commit -m "chore: bump ${PACKAGE_NAME} version to ${NEXT_VERSION}"
+          git push origin "$BUMP_BRANCH"
+
+          gh pr create \
+            --title "chore: bump ${PACKAGE_NAME} to ${NEXT_VERSION}" \
+            --body "Auto-bump version after ${PACKAGE_NAME} v${VERSION} release." \
+            --base main \
+            --head "$BUMP_BRANCH"

{by_framework-0.2.0 → by_framework-0.2.2.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: by-framework
-Version: 0.2.0
+Version: 0.2.2.dev0
 Summary: 分布式 Agent 调度框架
 License-File: LICENSE
 Requires-Python: >=3.12
@@ -37,9 +37,34 @@ Description-Content-Type: text/markdown
 
 ---
 
-**by-framework** is a distributed, high-performance Agent scheduling engine built on Redis Streams. It provides Worker orchestration, session-scoped runtime state, and a plugin-based agent capability system — purpose-built for AI agent systems.
+**by-framework** is a distributed, high-performance Agent scheduling engine built on Redis Streams, purpose-built for multi-agent systems.
+
+## Challenges in Traditional Architecture
+
+Traditional AI application architectures often face three critical challenges when dealing with Agent scenarios:
+
+- **Full-link Synchronous Blocking $\rightarrow$ Forced "Manual Monitoring"** — Strong coupling between frontend and backend means tasks are interrupted if the page is closed. Users cannot switch devices or tasks, making workflows fragile to network fluctuations or interruptions.
+- **Inability to Support Long-running Tasks $\rightarrow$ System "Constant Accompaniment"** — For reasoning tasks taking minutes or hours, callers must block threads and wait. This leads to gateway timeouts and massive waste of idle compute resources.
+- **Inter-Agent Orchestration Recovery Dilemma** — In complex cascaded calls, if a timeout or interruption occurs, it's nearly impossible to accurately resume state. Developers are forced to build extremely complex persistent state machines.
+
+## The By-Framework Solution
+
+![Architecture Overview](./assets/img/architecture_en.png)
+
+By-Framework addresses these issues through an asynchronous architecture with **separated Control and Data Planes**:
+
+- **Instruction Asynchrony**: The APP sends control instructions to the **Control Queue** via the **Gateway Client**. Being asynchronous, the APP never blocks, and backend threads are released immediately.
+- **Agent Cluster Consumption**: A distributed cluster of **Agents** competitively consumes messages from the control queue. Logical routing (Agent Type) provides native load balancing and elastic scaling.
+- **Data Stream Feedback**: During execution, Agents asynchronously push chunks, state changes, and artifacts to the **Data Queue**. The APP listens via the **Gateway Client** for progress, natively supporting ultra-long tasks.
+- **Native Orchestration & Resumption**: When an Agent needs to call another Agent, it sends a new instruction to the **Control Queue**. This message-based mechanism allows tasks to release resources while waiting and resume context precisely upon receiving a reply.
+
+## Highlights
+
+- 🔌 **Plugin System** — Hot-reloadable plugins with lifecycle hooks, tools, prompts, and sub-agent configs
+- 🤝 **Inter-Agent Orchestration** — Built-in `call_agent`, scatter-gather fan-out, and human-in-the-loop patterns
+- 🧩 **Extension Ecosystem** — Drop-in packages for Langfuse, Phoenix, PostgreSQL, LangGraph, and Google ADK
+- 🛡️ **Production-Ready** — Competitive consumption, graceful shutdown, message persistence, and execution state tracking
 
----
 
 ## Table of Contents
 

{by_framework-0.2.0 → by_framework-0.2.2.dev0}/README.md

@@ -17,9 +17,34 @@
 
 ---
 
-**by-framework** is a distributed, high-performance Agent scheduling engine built on Redis Streams. It provides Worker orchestration, session-scoped runtime state, and a plugin-based agent capability system — purpose-built for AI agent systems.
+**by-framework** is a distributed, high-performance Agent scheduling engine built on Redis Streams, purpose-built for multi-agent systems.
+
+## Challenges in Traditional Architecture
+
+Traditional AI application architectures often face three critical challenges when dealing with Agent scenarios:
+
+- **Full-link Synchronous Blocking $\rightarrow$ Forced "Manual Monitoring"** — Strong coupling between frontend and backend means tasks are interrupted if the page is closed. Users cannot switch devices or tasks, making workflows fragile to network fluctuations or interruptions.
+- **Inability to Support Long-running Tasks $\rightarrow$ System "Constant Accompaniment"** — For reasoning tasks taking minutes or hours, callers must block threads and wait. This leads to gateway timeouts and massive waste of idle compute resources.
+- **Inter-Agent Orchestration Recovery Dilemma** — In complex cascaded calls, if a timeout or interruption occurs, it's nearly impossible to accurately resume state. Developers are forced to build extremely complex persistent state machines.
+
+## The By-Framework Solution
+
+![Architecture Overview](./assets/img/architecture_en.png)
+
+By-Framework addresses these issues through an asynchronous architecture with **separated Control and Data Planes**:
+
+- **Instruction Asynchrony**: The APP sends control instructions to the **Control Queue** via the **Gateway Client**. Being asynchronous, the APP never blocks, and backend threads are released immediately.
+- **Agent Cluster Consumption**: A distributed cluster of **Agents** competitively consumes messages from the control queue. Logical routing (Agent Type) provides native load balancing and elastic scaling.
+- **Data Stream Feedback**: During execution, Agents asynchronously push chunks, state changes, and artifacts to the **Data Queue**. The APP listens via the **Gateway Client** for progress, natively supporting ultra-long tasks.
+- **Native Orchestration & Resumption**: When an Agent needs to call another Agent, it sends a new instruction to the **Control Queue**. This message-based mechanism allows tasks to release resources while waiting and resume context precisely upon receiving a reply.
+
+## Highlights
+
+- 🔌 **Plugin System** — Hot-reloadable plugins with lifecycle hooks, tools, prompts, and sub-agent configs
+- 🤝 **Inter-Agent Orchestration** — Built-in `call_agent`, scatter-gather fan-out, and human-in-the-loop patterns
+- 🧩 **Extension Ecosystem** — Drop-in packages for Langfuse, Phoenix, PostgreSQL, LangGraph, and Google ADK
+- 🛡️ **Production-Ready** — Competitive consumption, graceful shutdown, message persistence, and execution state tracking
 
----
 
 ## Table of Contents
 

{by_framework-0.2.0 → by_framework-0.2.2.dev0}/README_zh.md

@@ -13,13 +13,38 @@
 
 [**English**](README.md) | [**中文**](README_zh.md)
 
+**重要链接：** [文档](https://beyonai.github.io/by-framework-docs) · [Java 版本](https://beyonai.github.io/by-framework-java) · [TypeScript 版本](https://beyonai.github.io/by-framework-ts)
+
 </div>
 
----
+**by-framework** 是一个基于 Redis Streams 构建的分布式高性能 Agent 调度引擎，专为多 Agent 系统设计。
 
-**by-framework** 是一个基于 Redis Streams 构建的分布式高性能 Agent 调度引擎。它提供了 Worker 编排、会话级运行时状态管理以及基于插件的 Agent 能力系统——专为 AI Agent 系统设计。
+## 传统架构的困境
+
+传统 AI 应用架构在面对 Agent 场景时常面临三大挑战：
+
+- **全链路同步阻塞 $\rightarrow$ 迫使用户“人肉盯看”** — 前端与后端强绑定，页面关闭即任务中断。用户无法跨端切换，工作流极易因网络波动或意外打断而前功尽弃。
+- **无法支撑超长任务 $\rightarrow$ 导致系统“全程陪同”** — 面对数分钟甚至小时级的推理，调用方必须持续阻塞线程等待，不仅面临网关超时截断，更造成了严重的计算资源空转与浪费。
+- **多 Agent 编排的中断恢复困局** — 在复杂级联调用中，一旦出现超时或中断，系统难以精准定位状态并恢复，容易超时或结果错乱。
+
+## By-Framework 的方案
+
+![Architecture Overview](./assets/img/architecture_zh.png)
+
+By-Framework 通过**控制与数据平面分离**的异步架构解决上述问题：
+
+- **指令异步化**：APP 通过 **Gateway Client** 将用户请求转化为控制指令并投入 **Control Queue**（控制队列）。由于是异步解耦，APP 无需阻塞等待，后端线程立即释放。
+- **Agent 集群消费**：分布式的 **Agents** 集群竞争消费控制队列中的消息。通过逻辑寻址（Agent Type）自动实现负载均衡，天然支持动态扩缩容。
+- **过程数据回传**：Agent 在执行过程中，将流式文本（Chunk）、状态变更（State）及产物（Artifact）异步推送到 **Data Queue**（数据队列），APP 通过 **Gateway Client** 实时监听该队列以获取任务进度，从而原生支持超长任务。
+- **原生编排与中断恢复**：当 Agent 需要调用其他 Agent（编排）时，它会将新指令发往 **Control Queue**。这种基于消息的机制允许 Agent 任务在等待期间完全释放资源，并在收到回复指令后精准恢复上下文。
+
+## 亮点
+
+- 🔌 **插件系统** — 支持热加载的插件机制，提供生命周期钩子、工具、提示词和子 Agent 配置
+- 🤝 **多 Agent 编排** — 内置 call_agent、scatter-gather 扇出和人机交互模式
+- 🧩 **扩展生态** — 开箱即用的 Langfuse、Phoenix、PostgreSQL、LangGraph 及 Google ADK 集成包
+- 🛡️ **生产就绪** — 竞争消费、优雅退出、消息持久化与配置快照
 
----
 
 ## 目录