by-framework 0.2.1__tar.gz → 0.2.2.dev1__tar.gz

{by_framework-0.2.1 → by_framework-0.2.2.dev1}/.github/workflows/publish.yml

@@ -63,7 +63,7 @@ jobs:
               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
@@ -152,6 +152,10 @@ jobs:
           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:
@@ -169,20 +173,36 @@ jobs:
           PACKAGE_DIR: ${{ needs.resolve-package.outputs.package_dir }}
           VERSION: ${{ needs.resolve-package.outputs.version }}
         run: |
-          # Calculate next dev version (e.g., 0.2.1 -> 0.2.2.dev0)
-          IFS='.' read -ra PARTS <<< "$VERSION"
-          LAST_INDEX=$((${#PARTS[@]} - 1))
-          PARTS[$LAST_INDEX]=$((PARTS[$LAST_INDEX] + 1))
-          NEXT_VERSION=$(IFS='.'; echo "${PARTS[*]}").dev0
+          # 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"
+          git add "$PYPROJECT" uv.lock
           git commit -m "chore: bump ${PACKAGE_NAME} version to ${NEXT_VERSION}"
           git push origin "$BUMP_BRANCH"
 

{by_framework-0.2.1 → by_framework-0.2.2.dev1}/.gitignore

@@ -3,6 +3,7 @@ __pycache__/
 *.py[cod]
 *$py.class
 *.so
+.ruff_cache/
 .Python
 build/
 develop-eggs/
@@ -66,3 +67,7 @@ Thumbs.db
 *gateway-sdk.log*
 .claude/settings.local.json
 .claude/settings.json
+
+core
+
+.coderfleet-uploads/

by_framework-0.2.1/README.md → by_framework-0.2.2.dev1/PKG-INFO

@@ -1,3 +1,27 @@
+Metadata-Version: 2.4
+Name: by-framework
+Version: 0.2.2.dev1
+Summary: 分布式 Agent 调度框架
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: dill>=0.4.1
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: redis>=7.0.0
+Requires-Dist: typing-extensions>=4.0.0
+Provides-Extra: dev
+Requires-Dist: isort>=5.13.0; extra == 'dev'
+Requires-Dist: pre-commit>=4.0.0; extra == 'dev'
+Requires-Dist: pyink>=24.0.0; extra == 'dev'
+Requires-Dist: pylint>=3.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.3.0; extra == 'dev'
+Provides-Extra: observability
+Requires-Dist: opentelemetry-api>=1.25.0; extra == 'observability'
+Requires-Dist: opentelemetry-sdk>=1.25.0; extra == 'observability'
+Requires-Dist: prometheus-client>=0.20.0; extra == 'observability'
+Description-Content-Type: text/markdown
+
 # by-framework
 
 <div align="center">
@@ -608,11 +632,38 @@ import logging
 setup_logging(level=logging.INFO, use_json=True)  # JSON for log aggregation
 ```
 
+### Observability Dashboard
+
+Serve the built-in dashboard to inspect worker health, agent health, execution
+state counts, recent executions, Redis stream queue depth, consumer-group
+pending/lag, failure details, routing decisions, derived alerts, and segmented
+queue/run/end-to-end task latency:
+
+```bash
+uv run python -m by_framework.observability.dashboard --host 127.0.0.1 --port 8765
+```
+
+Open `http://127.0.0.1:8765/`. For a local UI preview without Redis, open
+`http://127.0.0.1:8765/?demo=1`. Prometheus-style metrics are available at
+`http://127.0.0.1:8765/metrics`, and the dashboard keeps short in-memory trend
+history at `http://127.0.0.1:8765/api/history`. The UI uses split polling
+endpoints (`/api/workers`, `/api/executions`, `/api/queues`, `/api/history`)
+instead of polling the full `/api/snapshot` endpoint on every refresh. Runtime
+self-check data is exposed at `/api/health`, shown in the toolbar, and exported
+through `/metrics`.
+Alert thresholds can be tuned with `--queue-backlog-threshold`,
+`--delivery-pending-threshold`, `--consumer-pending-threshold`, and
+`--failed-execution-threshold`.
+
+The dashboard frontend is built with React/Vite under
+`src/by_framework/observability/frontend`; its production build is packaged in
+`src/by_framework/observability/static`.
+
 ---
 
 ## Roadmap
 
-- [ ] Observability dashboard for Worker health and task streams
+- [x] Observability dashboard for Worker health and task streams
 - [ ] WASM-based sandbox for stronger execution isolation
 - [ ] Enhanced LangGraph multi-agent orchestration adapter
 

by_framework-0.2.1/PKG-INFO → by_framework-0.2.2.dev1/README.md

@@ -1,23 +1,3 @@
-Metadata-Version: 2.4
-Name: by-framework
-Version: 0.2.1
-Summary: 分布式 Agent 调度框架
-License-File: LICENSE
-Requires-Python: >=3.12
-Requires-Dist: dill>=0.4.1
-Requires-Dist: httpx>=0.28.1
-Requires-Dist: redis>=7.0.0
-Requires-Dist: typing-extensions>=4.0.0
-Provides-Extra: dev
-Requires-Dist: isort>=5.13.0; extra == 'dev'
-Requires-Dist: pre-commit>=4.0.0; extra == 'dev'
-Requires-Dist: pyink>=24.0.0; extra == 'dev'
-Requires-Dist: pylint>=3.0.0; extra == 'dev'
-Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
-Requires-Dist: pytest>=8.0.0; extra == 'dev'
-Requires-Dist: ruff>=0.3.0; extra == 'dev'
-Description-Content-Type: text/markdown
-
 # by-framework
 
 <div align="center">
@@ -628,11 +608,38 @@ import logging
 setup_logging(level=logging.INFO, use_json=True)  # JSON for log aggregation
 ```
 
+### Observability Dashboard
+
+Serve the built-in dashboard to inspect worker health, agent health, execution
+state counts, recent executions, Redis stream queue depth, consumer-group
+pending/lag, failure details, routing decisions, derived alerts, and segmented
+queue/run/end-to-end task latency:
+
+```bash
+uv run python -m by_framework.observability.dashboard --host 127.0.0.1 --port 8765
+```
+
+Open `http://127.0.0.1:8765/`. For a local UI preview without Redis, open
+`http://127.0.0.1:8765/?demo=1`. Prometheus-style metrics are available at
+`http://127.0.0.1:8765/metrics`, and the dashboard keeps short in-memory trend
+history at `http://127.0.0.1:8765/api/history`. The UI uses split polling
+endpoints (`/api/workers`, `/api/executions`, `/api/queues`, `/api/history`)
+instead of polling the full `/api/snapshot` endpoint on every refresh. Runtime
+self-check data is exposed at `/api/health`, shown in the toolbar, and exported
+through `/metrics`.
+Alert thresholds can be tuned with `--queue-backlog-threshold`,
+`--delivery-pending-threshold`, `--consumer-pending-threshold`, and
+`--failed-execution-threshold`.
+
+The dashboard frontend is built with React/Vite under
+`src/by_framework/observability/frontend`; its production build is packaged in
+`src/by_framework/observability/static`.
+
 ---
 
 ## Roadmap
 
-- [ ] Observability dashboard for Worker health and task streams
+- [x] Observability dashboard for Worker health and task streams
 - [ ] WASM-based sandbox for stronger execution isolation
 - [ ] Enhanced LangGraph multi-agent orchestration adapter
 

{by_framework-0.2.1 → by_framework-0.2.2.dev1}/README_zh.md

@@ -608,11 +608,34 @@ import logging
 setup_logging(level=logging.INFO, use_json=True)  # JSON 格式便于日志聚合
 ```
 
+### 可观测仪表盘
+
+启动内置仪表盘，用于查看 Worker 健康、Agent 健康、执行状态计数、最近执行、Redis Stream 队列深度、consumer group pending/lag、失败详情、路由决策、派生告警，以及排队/执行/端到端分段延迟：
+
+```bash
+uv run python -m by_framework.observability.dashboard --host 127.0.0.1 --port 8765
+```
+
+打开 `http://127.0.0.1:8765/`。如果本地没有 Redis，可打开
+`http://127.0.0.1:8765/?demo=1` 预览 UI。Prometheus 风格指标位于
+`http://127.0.0.1:8765/metrics`，仪表盘也会在
+`http://127.0.0.1:8765/api/history` 保留短期内存趋势历史。UI 使用拆分后的
+轮询接口（`/api/workers`、`/api/executions`、`/api/queues`、`/api/history`），
+不会每次刷新都请求完整的 `/api/snapshot`。运行时自检数据位于
+`/api/health`，会显示在工具栏中，也会通过 `/metrics` 导出。
+告警阈值可通过 `--queue-backlog-threshold`、
+`--delivery-pending-threshold`、`--consumer-pending-threshold` 和
+`--failed-execution-threshold` 调整。
+
+仪表盘前端使用 React/Vite 构建，源码位于
+`src/by_framework/observability/frontend`，生产构建产物打包在
+`src/by_framework/observability/static`。
+
 ---
 
 ## 路线图
 
-- [ ] Worker 健康与任务流的可观测仪表盘
+- [x] Worker 健康与任务流的可观测仪表盘
 - [ ] 基于 WASM 的沙箱，实现更强隔离
 - [ ] 增强的 LangGraph 多 Agent 编排适配器
 

{by_framework-0.2.1 → by_framework-0.2.2.dev1}/libs/by-framework-adk/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "by-framework-adk"
-version = "0.0.2"
+version = "0.0.3.dev0"
 description = "ADK integration for by-framework"
 readme = "README.md"
 requires-python = ">=3.12"

{by_framework-0.2.1 → by_framework-0.2.2.dev1}/libs/by-framework-history-byclaw/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "by-framework-history-byclaw"
-version = "0.0.2"
+version = "0.0.4.dev0"
 description = "ByClaw remote history backend for by-framework"
 readme = "README.md"
 requires-python = ">=3.12"

{by_framework-0.2.1 → by_framework-0.2.2.dev1}/libs/by-framework-history-byclaw/src/by_framework_history_byclaw/byclaw_history.py

@@ -1,6 +1,7 @@
 # pylint: disable=C0114,C0301,R0914,W0718
 from __future__ import annotations
 
+import json
 import os
 from typing import Any, Dict, List, Optional
 
@@ -152,16 +153,32 @@ class ByClawHistoryBackend(BaseHistoryBackend):
                 else item.get("role", "unknown")
             )
             # 兼容多种字段名：messageContent 是 ByClaw 风格，content 是标准风格
-            content = item.get("messageContent") or item.get("content") or ""
-
-            if role and content:
-                transformed.append(
-                    {
-                        "role": role,
-                        "content": content,
-                        "metadata": item.get("metadata", {}),
-                    }
-                )
+            raw_content = item.get("messageContent") or item.get("content") or ""
+            related_resources = item.get("relatedResources")
+            files = []
+            if related_resources:
+                try:
+                    res_dict = json.loads(related_resources)
+                    files = res_dict.get("files") or []
+                except Exception:
+                    pass
+
+            if role and (raw_content or files):
+                content_list = []
+                if raw_content:
+                    content_list.append({"type": "text", "text": raw_content})
+
+                if files:
+                    for f in files:
+                        content_list.append({"type": "file", "file": f})
+
+                message = {
+                    "role": role,
+                    "content": content_list,
+                    "metadata": item.get("metadata", {}),
+                }
+                transformed.append(message)
+
         return transformed
 
     async def save_message(

{by_framework-0.2.1 → by_framework-0.2.2.dev1}/libs/by-framework-history-byclaw/tests/test_byclaw_history.py

@@ -57,8 +57,16 @@ async def test_byclaw_history_backend_formats_messages(monkeypatch) -> None:
     history = await backend.get_history("sess-1", limit=2)
 
     assert history == [
-        {"role": "user", "content": "hello", "metadata": {"n": 1}},
-        {"role": "assistant", "content": "world", "metadata": {"n": 2}},
+        {
+            "role": "user",
+            "content": [{"type": "text", "text": "hello"}],
+            "metadata": {"n": 1},
+        },
+        {
+            "role": "assistant",
+            "content": [{"type": "text", "text": "world"}],
+            "metadata": {"n": 2},
+        },
     ]
 
 
@@ -101,8 +109,16 @@ async def test_byclaw_history_backend_with_discovery() -> None:
 
     # Verify transformed results
     assert history == [
-        {"role": "user", "content": "hello from discovery", "metadata": {}},
-        {"role": "assistant", "content": "response from discovery", "metadata": {}},
+        {
+            "role": "user",
+            "content": [{"type": "text", "text": "hello from discovery"}],
+            "metadata": {},
+        },
+        {
+            "role": "assistant",
+            "content": [{"type": "text", "text": "response from discovery"}],
+            "metadata": {},
+        },
     ]
 
 

{by_framework-0.2.1 → by_framework-0.2.2.dev1}/libs/by-framework-history-postgres/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "by-framework-history-postgres"
-version = "0.0.2"
+version = "0.0.3.dev0"
 description = "PostgreSQL history backend for by-framework"
 readme = "README.md"
 requires-python = ">=3.12"

{by_framework-0.2.1 → by_framework-0.2.2.dev1}/libs/by-framework-langgraph/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "by-framework-langgraph"
-version = "0.0.2"
+version = "0.0.3.dev0"
 description = "LangGraph integration for by-framework"
 readme = "README.md"
 requires-python = ">=3.12"

{by_framework-0.2.1 → by_framework-0.2.2.dev1}/libs/by-framework-langgraph/src/by_framework_langgraph/_utils.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import hashlib
 from typing import Any
 
 from by_framework.core.protocol.commands import ResumeCommand
@@ -52,13 +51,3 @@ def extract_resume_data(command: ResumeCommand) -> str:
         return extract_content_text(command.content)
 
     return ""
-
-
-def str_to_uint128(s: str) -> int:
-    """Convert a string to a 128-bit integer (for OTEL TraceId)."""
-    return int(hashlib.md5(s.encode()).hexdigest(), 16)
-
-
-def str_to_uint64(s: str) -> int:
-    """Convert a string to a 64-bit integer (for OTEL SpanId)."""
-    return int(hashlib.md5(s.encode()).hexdigest()[:16], 16)

{by_framework-0.2.1 → by_framework-0.2.2.dev1}/libs/by-framework-langgraph/src/by_framework_langgraph/adapter.py

@@ -16,15 +16,11 @@ from by_framework.common.logger import logger
 from by_framework.core.protocol.agent_state import AgentState
 from by_framework.core.protocol.commands import ResumeCommand
 from by_framework.core.protocol.events import StreamChunkEvent
+from by_framework.observability.span_recorder import (str_to_uint64, str_to_uint128)
 from langchain_core.messages import HumanMessage
 from langgraph.types import Command
 
-from ._utils import (
-    extract_content_text,
-    extract_resume_data,
-    str_to_uint64,
-    str_to_uint128,
-)
+from ._utils import extract_content_text, extract_resume_data
 
 if TYPE_CHECKING:
     from by_framework.core.protocol.commands import GatewayCommand
@@ -383,6 +379,26 @@ class LangGraphAdapter:
     @contextmanager
     def _langfuse_callback_manager(self, callbacks: list[Any]) -> Iterator[None]:
         """Prepare Langfuse callback and observation for LangChain."""
+        # Prefer AgentContext's callback factory so trace and parent ids align.
+        # Filter out auto-generated MagicMock attributes when tests use a mock
+        # context — real callback objects always come from a non-test module.
+        langfuse_callback_value = getattr(self._context, "langfuse_callback", None)
+        is_real_callback = langfuse_callback_value is not None and type(
+            langfuse_callback_value
+        ).__module__ not in ("unittest.mock",)
+
+        if is_real_callback:
+            handler = (
+                langfuse_callback_value()
+                if callable(langfuse_callback_value)
+                else langfuse_callback_value
+            )
+            if handler is not None:
+                callbacks.append(handler)
+                yield
+                return
+
+        # Fallback to local import if context method is missing
         # pylint: disable=import-outside-toplevel
         try:
             langfuse_config = import_module(
@@ -414,6 +430,17 @@ class LangGraphAdapter:
             },
             metadata=self._default_metadata(),
         ):
+            # Prevent the generated OTel span from being promoted to a trace root.
+            # The native LangfusePlugin sets the same attribute on its own path
+            # (via _SdkLangfuseTracer); this covers the LangGraph fallback path.
+            try:
+                from opentelemetry import trace
+
+                current_span = trace.get_current_span()
+                if current_span and hasattr(current_span, "set_attribute"):
+                    current_span.set_attribute("langfuse.internal.as_root", False)
+            except Exception:  # pylint: disable=broad-exception-caught
+                pass
             yield
 
     @staticmethod

{by_framework-0.2.1 → by_framework-0.2.2.dev1}/libs/by-framework-langgraph/tests/test_adapter.py

@@ -259,6 +259,50 @@ class TestAdapterRun:
         }
         assert observation_calls[0]["name"] == "planner:langgraph"
 
+    @pytest.mark.asyncio
+    async def test_uses_context_langfuse_callback_property(self):
+        """Verify AgentContext.langfuse_callback property value is used directly as a handler."""
+        handler = object()
+
+        # pylint: disable=too-few-public-methods,missing-class-docstring,missing-function-docstring
+        class ContextWithCallbackProperty:
+            session_id = "test-session"
+            trace_id = "trace-ctx"
+            message_id = "msg-ctx"
+            parent_message_id = ""
+            current_agent_id = "planner"
+            current_command = SimpleNamespace(
+                header=MessageHeader(
+                    message_id="msg-ctx",
+                    session_id="test-session",
+                    trace_id="trace-ctx",
+                    target_agent_type="planner",
+                )
+            )
+
+            def __init__(self):
+                self.emit_chunk = AsyncMock()
+
+            @property
+            def langfuse_callback(self):
+                return handler
+
+        ctx = ContextWithCallbackProperty()
+        graph = MagicMock()
+        graph.ainvoke = AsyncMock(
+            return_value={"messages": [MagicMock(content="hello")]}
+        )
+        snapshot = MagicMock()
+        snapshot.next = ()
+        graph.get_state.return_value = snapshot
+
+        adapter = LangGraphAdapter(graph, ctx, stream=False)
+        result = await adapter.run(AskAgentCommand(header=_make_header(), content="hi"))
+
+        assert result == "hello"
+        _, kwargs = graph.ainvoke.call_args
+        assert kwargs["config"]["callbacks"] == [handler]
+
     @pytest.mark.asyncio
     async def test_skips_langfuse_tracing_silently_when_not_configured(
         self, monkeypatch, caplog

{by_framework-0.2.1 → by_framework-0.2.2.dev1}/libs/by-framework-trace-langfuse/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "by-framework-trace-langfuse"
-version = "0.0.2"
+version = "0.0.3.dev0"
 description = "Langfuse trace provider for by-framework"
 readme = "README.md"
 requires-python = ">=3.12"

by_framework-0.2.2.dev1/libs/by-framework-trace-langfuse/src/by_framework_trace_langfuse/__init__.py

@@ -0,0 +1,17 @@
+"""Langfuse trace provider package for by-framework."""
+
+from .langfuse import (
+    LANGFUSE_PARENT_OBSERVATION_METADATA_KEY,
+    LangfuseConfig,
+    LangfusePlugin,
+    LangfuseTraceProviderFactory,
+    start_client_dispatch_observation,
+)
+
+__all__ = [
+    "LANGFUSE_PARENT_OBSERVATION_METADATA_KEY",
+    "LangfuseConfig",
+    "LangfusePlugin",
+    "LangfuseTraceProviderFactory",
+    "start_client_dispatch_observation",
+]