by-framework 0.2.2.dev4__tar.gz → 0.2.2.dev5__tar.gz

{by_framework-0.2.2.dev4 → by_framework-0.2.2.dev5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: by-framework
-Version: 0.2.2.dev4
+Version: 0.2.2.dev5
 Summary: 分布式 Agent 调度框架
 License-File: LICENSE
 Requires-Python: >=3.12

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

@@ -590,69 +590,47 @@ class LangGraphAdapter:
         # Always inject token accumulator — works regardless of Langfuse config.
         callbacks.append(_TokenAccumulatingCallbackHandler(self._context))
 
-        # 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(
-                "by_framework_trace_langfuse"
-            ).LangfuseConfig
-            if langfuse_config.from_env() is None:
-                raise ImportError("Langfuse not configured")
-
-            callback_handler = import_module("langfuse.langchain").CallbackHandler
-            get_client = import_module("langfuse").get_client
+            build_langchain_callback = getattr(
+                import_module("by_framework_trace_langfuse"),
+                "build_langchain_callback",
+            )
         except (ImportError, AttributeError):
             yield
             return
 
-        callbacks.append(callback_handler())
-
-        framework_observation = getattr(self._context, LANGFUSE_OBSERVATION_ATTR, None)
-        if framework_observation is None:
-            yield
-            return
+        get_parent_observation_id = getattr(
+            self._context,
+            "get_trace_parent_observation_id",
+            None,
+        )
+        parent_observation_id = (
+            str(get_parent_observation_id() or "")
+            if callable(get_parent_observation_id)
+            else ""
+        )
+        if not parent_observation_id:
+            framework_observation = getattr(
+                self._context, LANGFUSE_OBSERVATION_ATTR, None
+            )
+            parent_observation_id = getattr(framework_observation, "id", "") or ""
+        if not parent_observation_id:
+            execution_id = getattr(self._context, "execution_id", "")
+            message_id = getattr(self._context, "message_id", "")
+            raw_parent_id = (
+                f"{execution_id}:worker.execute"
+                if execution_id
+                else f"{message_id}:worker.execute"
+            )
+            parent_observation_id = f"{str_to_uint64(raw_parent_id):016x}"
 
-        langfuse = get_client()
-        with langfuse.start_as_current_observation(
-            as_type="span",
-            name=self._tracing.run_name,
-            trace_context={
-                "trace_id": getattr(self._context, "trace_id", ""),
-                "parent_span_id": framework_observation.id,
-            },
-            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
+        handler = build_langchain_callback(
+            trace_id=getattr(self._context, "trace_id", ""),
+            parent_observation_id=parent_observation_id,
+        )
+        if handler is not None:
+            callbacks.append(handler)
+        yield
 
     @staticmethod
     def _default_input_mapper(content: str) -> dict:

{by_framework-0.2.2.dev4 → by_framework-0.2.2.dev5}/libs/by-framework-langgraph/tests/test_adapter.py

@@ -1,7 +1,6 @@
 """Tests for adapter and worker modules."""
 
 import sys
-from contextlib import contextmanager
 from types import SimpleNamespace
 from unittest.mock import AsyncMock, MagicMock, patch
 
@@ -40,7 +39,7 @@ def _make_mock_context(session_id: str = "test-session"):
             metadata={"source": "test"},
         )
     )
-    ctx._langfuse_observation = SimpleNamespace(id="obs-framework")  # pylint: disable=protected-access
+    ctx.get_trace_parent_observation_id.return_value = "obs-framework"
     return ctx
 
 
@@ -187,7 +186,7 @@ class TestAdapterRun:
     async def test_includes_langfuse_callbacks_and_parent_trace_context(
         self, monkeypatch
     ):
-        """Verify adapter wires Langfuse callback handler into LangGraph config."""
+        """Verify adapter gets Langfuse callback from the trace provider package."""
         ctx = _make_mock_context()
         graph = MagicMock()
         graph.ainvoke = AsyncMock(
@@ -197,45 +196,18 @@ class TestAdapterRun:
         snapshot.next = ()
         graph.get_state.return_value = snapshot
 
-        observation_calls: list[dict] = []
-        callback_instances: list[object] = []
+        callback_handler = object()
+        callback_calls: list[dict[str, str]] = []
 
-        @contextmanager
-        def fake_observation_scope(**kwargs):
-            observation_calls.append(kwargs)
-            yield SimpleNamespace(id="obs-langgraph")
+        def fake_build_langchain_callback(**kwargs):
+            callback_calls.append(kwargs)
+            return callback_handler
 
-        class FakeCallbackHandler:  # pylint: disable=too-few-public-methods
-            """Minimal callback handler stub for adapter config assertions."""
-
-            def __init__(self):
-                callback_instances.append(self)
-
-        fake_langfuse_client = SimpleNamespace(
-            start_as_current_observation=fake_observation_scope
-        )
-
-        monkeypatch.setitem(
-            sys.modules,
-            "langfuse",
-            SimpleNamespace(get_client=MagicMock(return_value=fake_langfuse_client)),
-        )
-        monkeypatch.setitem(
-            sys.modules,
-            "langfuse.langchain",
-            SimpleNamespace(CallbackHandler=FakeCallbackHandler),
-        )
         monkeypatch.setitem(
             sys.modules,
             "by_framework_trace_langfuse",
-            SimpleNamespace(LangfuseConfig=MagicMock()),
+            SimpleNamespace(build_langchain_callback=fake_build_langchain_callback),
         )
-        sys.modules[
-            "by_framework_trace_langfuse"
-        ].LangfuseConfig.from_env.return_value = object()
-        monkeypatch.setenv("LANGFUSE_SECRET_KEY", "sk-test")
-        monkeypatch.setenv("LANGFUSE_PUBLIC_KEY", "pk-test")
-        monkeypatch.setenv("LANGFUSE_BASE_URL", "http://localhost:3000")
 
         adapter = LangGraphAdapter(graph, ctx, stream=False)
 
@@ -255,25 +227,26 @@ class TestAdapterRun:
         assert config["metadata"]["by_framework_message_id"] == "msg-ctx"
         assert config["metadata"]["langgraph_thread_id"] == "test-session"
         # Callbacks list includes the Langfuse handler(s) plus the token accumulator.
-        assert all(cb in config["callbacks"] for cb in callback_instances)
+        assert callback_handler in config["callbacks"]
         assert any(
             type(cb).__name__ == "_TokenAccumulatingCallbackHandler"
             for cb in config["callbacks"]
         )
-        assert len(observation_calls) == 1
-        assert observation_calls[0]["trace_context"] == {
-            "trace_id": "trace-ctx",
-            "parent_span_id": "obs-framework",
-        }
-        assert observation_calls[0]["name"] == "planner:langgraph"
+        assert callback_calls == [
+            {
+                "trace_id": "trace-ctx",
+                "parent_observation_id": "obs-framework",
+            }
+        ]
 
     @pytest.mark.asyncio
-    async def test_uses_context_langfuse_callback_property(self):
-        """Verify AgentContext.langfuse_callback property is used directly."""
-        handler = object()
+    async def test_skips_langfuse_callback_when_provider_package_missing(
+        self, monkeypatch
+    ):
+        """LangGraph stays provider-agnostic when trace-langfuse is not installed."""
 
         # pylint: disable=too-few-public-methods,missing-class-docstring,missing-function-docstring
-        class ContextWithCallbackProperty:
+        class ContextWithoutProvider:
             session_id = "test-session"
             trace_id = "trace-ctx"
             message_id = "msg-ctx"
@@ -291,11 +264,15 @@ class TestAdapterRun:
             def __init__(self):
                 self.emit_chunk = AsyncMock()
 
-            @property
-            def langfuse_callback(self):
-                return handler
+        def fake_import_module(name):
+            if name == "by_framework_trace_langfuse":
+                raise ImportError(name)
+            raise AssertionError(f"unexpected import: {name}")
 
-        ctx = ContextWithCallbackProperty()
+        monkeypatch.setattr(
+            "by_framework_langgraph.adapter.import_module", fake_import_module
+        )
+        ctx = ContextWithoutProvider()
         graph = MagicMock()
         graph.ainvoke = AsyncMock(
             return_value={"messages": [MagicMock(content="hello")]}
@@ -310,7 +287,6 @@ class TestAdapterRun:
         assert result == "hello"
         _, kwargs = graph.ainvoke.call_args
         callbacks = kwargs["config"]["callbacks"]
-        assert handler in callbacks
         assert any(
             type(cb).__name__ == "_TokenAccumulatingCallbackHandler" for cb in callbacks
         )
@@ -335,11 +311,8 @@ class TestAdapterRun:
         monkeypatch.setitem(
             sys.modules,
             "by_framework_trace_langfuse",
-            SimpleNamespace(LangfuseConfig=MagicMock()),
+            SimpleNamespace(build_langchain_callback=MagicMock(return_value=None)),
         )
-        sys.modules[
-            "by_framework_trace_langfuse"
-        ].LangfuseConfig.from_env.return_value = None
 
         adapter = LangGraphAdapter(graph, ctx, stream=False)
 
@@ -382,11 +355,8 @@ class TestAdapterRun:
         monkeypatch.setitem(
             sys.modules,
             "by_framework_trace_langfuse",
-            SimpleNamespace(LangfuseConfig=MagicMock()),
+            SimpleNamespace(build_langchain_callback=MagicMock(return_value=None)),
         )
-        sys.modules[
-            "by_framework_trace_langfuse"
-        ].LangfuseConfig.from_env.return_value = None
 
         adapter = LangGraphAdapter(graph, ctx, stream=False)
 
@@ -530,7 +500,6 @@ class TestTokenAccumulatingCallbackHandler:
     def test_callback_injected_in_tracing_scope(self):
         """_langfuse_callback_manager injects _TokenAccumulatingCallbackHandler."""
         ctx = MagicMock()
-        ctx.langfuse_callback = None
         graph = MagicMock()
         adapter = LangGraphAdapter(graph=graph, context=ctx)
 

{by_framework-0.2.2.dev4 → by_framework-0.2.2.dev5}/libs/by-framework-trace-langfuse/src/by_framework_trace_langfuse/__init__.py

@@ -5,6 +5,7 @@ from .langfuse import (
     LangfuseConfig,
     LangfusePlugin,
     LangfuseTraceProviderFactory,
+    build_langchain_callback,
     start_client_dispatch_observation,
 )
 
@@ -13,5 +14,6 @@ __all__ = [
     "LangfuseConfig",
     "LangfusePlugin",
     "LangfuseTraceProviderFactory",
+    "build_langchain_callback",
     "start_client_dispatch_observation",
 ]

{by_framework-0.2.2.dev4 → by_framework-0.2.2.dev5}/libs/by-framework-trace-langfuse/src/by_framework_trace_langfuse/langfuse.py

@@ -13,6 +13,7 @@ from datetime import datetime, timezone
 from importlib import import_module
 from typing import Any, Optional, Protocol, runtime_checkable
 
+from by_framework.common.logger import get_logger
 from by_framework.core.extensions import (
     AgentConfig,
     Plugin,
@@ -28,6 +29,8 @@ from by_framework.trace.span_recorder import (
     str_to_uint128,
 )
 
+logger = get_logger(__name__)
+
 LANGFUSE_OBSERVATION_ATTR = "_langfuse_observation"
 LANGFUSE_CALL_PARENT_OBSERVATION_ATTR = "_langfuse_call_parent_observation"
 LANGFUSE_WORKFLOW_OBSERVATION_ATTR = "_langfuse_workflow_observation"
@@ -71,6 +74,82 @@ class LangfuseConfig:
         return value.strip().strip(_QUOTES_TO_STRIP)
 
 
+def build_langchain_callback(
+    *,
+    trace_id: str,
+    parent_observation_id: str,
+) -> Optional[Any]:
+    """Build a Langfuse LangChain CallbackHandler for an existing trace."""
+    config = LangfuseConfig.from_env()
+    if config is None:
+        return None
+
+    try:
+        callback_handler_cls = getattr(
+            import_module("langfuse.langchain"),
+            "CallbackHandler",
+        )
+        callback_handler_cls = _without_langchain_root_promotion(callback_handler_cls)
+        trace_id_hex = f"{str_to_uint128(trace_id):032x}"
+        trace_context = {
+            "trace_id": trace_id_hex,
+            "parent_span_id": parent_observation_id,
+        }
+
+        return callback_handler_cls(
+            public_key=config.public_key,
+            trace_context=trace_context,
+        )
+    except Exception:  # pylint: disable=broad-exception-caught
+        return None
+
+
+def _without_langchain_root_promotion(callback_handler_cls: Any) -> Any:
+    """Return a CallbackHandler class that keeps LangChain runs as child spans."""
+
+    # pylint: disable=too-few-public-methods
+    class ByFrameworkCallbackHandler(callback_handler_cls):
+        """Langfuse LangChain handler that does not rename the existing trace root."""
+
+        def on_chain_start(
+            self,
+            serialized: Any,
+            inputs: dict[str, Any],
+            *,
+            run_id: Any,
+            parent_run_id: Any = None,
+            **kwargs: Any,
+        ) -> Any:
+            result = super().on_chain_start(
+                serialized,
+                inputs,
+                run_id=run_id,
+                parent_run_id=parent_run_id,
+                **kwargs,
+            )
+            if parent_run_id is None:
+                runs = getattr(self, "_runs", {})
+                observation = runs.get(run_id) if isinstance(runs, dict) else None
+                _mark_observation_as_non_root(observation)
+            return result
+
+    ByFrameworkCallbackHandler.__name__ = callback_handler_cls.__name__
+    ByFrameworkCallbackHandler.__qualname__ = callback_handler_cls.__qualname__
+    ByFrameworkCallbackHandler.__module__ = callback_handler_cls.__module__
+    return ByFrameworkCallbackHandler
+
+
+def _mark_observation_as_non_root(observation: Any) -> None:
+    """Prevent Langfuse from using a child LangChain run as the trace root."""
+    otel_span = getattr(observation, "_otel_span", None)
+    if otel_span is None or not hasattr(otel_span, "set_attribute"):
+        return
+    try:
+        otel_span.set_attribute("langfuse.internal.as_root", False)
+    except Exception:  # pylint: disable=broad-exception-caught
+        pass
+
+
 @runtime_checkable
 class ObservationHandle(Protocol):
     """Minimal observation interface needed by the plugin."""
@@ -371,6 +450,8 @@ class LangfusePlugin(Plugin):
 
     async def on_task_start(self, context: Any) -> None:  # pylint: disable=too-many-locals
         tracer = self._get_tracer()
+        if tracer is None:
+            return
         observation_store = self._get_observation_store(context)
         identity = self._build_task_identity(context)
 
@@ -532,6 +613,8 @@ class LangfusePlugin(Plugin):
     async def on_call_agent_start(self, context: Any, command: Any) -> None:
         """Create a call observation and pass it as the child task parent."""
         tracer = self._get_tracer()
+        if tracer is None:
+            return
         header = getattr(command, "header", None)
         if header is None:
             return
@@ -618,6 +701,8 @@ class LangfusePlugin(Plugin):
         """Create a return observation and pass it as the resume parent."""
         del context, command
         tracer = self._get_tracer()
+        if tracer is None:
+            return
         header = getattr(callback_command, "header", None)
         if header is None:
             return
@@ -730,7 +815,7 @@ class LangfusePlugin(Plugin):
                 return parent_id
         return ""
 
-    def _get_tracer(self) -> LangfuseTracer:
+    def _get_tracer(self) -> Optional[LangfuseTracer]:
         tracer = self._tracer or self._build_default_tracer()
         self._tracer = tracer
         return tracer
@@ -744,13 +829,14 @@ class LangfusePlugin(Plugin):
         )
         return self._observation_store
 
-    def _build_default_tracer(self) -> LangfuseTracer:
+    def _build_default_tracer(self) -> Optional[LangfuseTracer]:
         config = LangfuseConfig.from_env()
         if config is None:
-            raise RuntimeError(
-                "LangfusePlugin requires LANGFUSE_SECRET_KEY, "
-                "LANGFUSE_PUBLIC_KEY, and LANGFUSE_BASE_URL to be set."
+            logger.error(
+                "LangfusePlugin: LANGFUSE_SECRET_KEY, LANGFUSE_PUBLIC_KEY, and "
+                "LANGFUSE_BASE_URL are not set — Langfuse tracing disabled."
             )
+            return None
 
         try:
             langfuse_module = import_module("langfuse")
@@ -761,18 +847,11 @@ class LangfusePlugin(Plugin):
             ) from err
         langfuse_client_cls = getattr(langfuse_module, "Langfuse")
 
-        try:
-            client = langfuse_client_cls(
-                public_key=config.public_key,
-                secret_key=config.secret_key,
-                base_url=config.base_url,
-            )
-        except TypeError:
-            client = langfuse_client_cls(
-                public_key=config.public_key,
-                secret_key=config.secret_key,
-                host=config.base_url,
-            )
+        client = langfuse_client_cls(
+            public_key=config.public_key,
+            secret_key=config.secret_key,
+            base_url=config.base_url,
+        )
 
         return _SdkLangfuseTracer(client, config)
 
@@ -1037,18 +1116,11 @@ def start_client_dispatch_observation(
     tracer = _CLIENT_DISPATCH_TRACER_CACHE.get(config)
     if tracer is None:
         langfuse_client_cls = getattr(langfuse_module, "Langfuse")
-        try:
-            client = langfuse_client_cls(
-                public_key=config.public_key,
-                secret_key=config.secret_key,
-                base_url=config.base_url,
-            )
-        except TypeError:
-            client = langfuse_client_cls(
-                public_key=config.public_key,
-                secret_key=config.secret_key,
-                host=config.base_url,
-            )
+        client = langfuse_client_cls(
+            public_key=config.public_key,
+            secret_key=config.secret_key,
+            base_url=config.base_url,
+        )
         tracer = _SdkLangfuseTracer(client, config)
         _CLIENT_DISPATCH_TRACER_CACHE[config] = tracer
 

{by_framework-0.2.2.dev4 → by_framework-0.2.2.dev5}/libs/by-framework-trace-query/tests/test_trace_query_sdk.py

@@ -891,3 +891,94 @@ async def test_dashboard_trace_endpoints_use_trace_read_sdk_shape():
     assert traces_response.status == 200
     assert traces_payload["traces"][0]["trace_id"] == "trace-dashboard"
     assert traces_payload["traces"][0]["span_count"] == trace_payload["span_count"]
+
+
+@pytest.mark.asyncio
+async def test_trace_write_client_records_trace_root_start():
+    """TraceWriteClient persists start_ts and QUEUED status for trace root."""
+    redis = QueryRedis()
+    writer = TraceWriteClient(redis)
+    await writer.record_trace(
+        TraceRecord(
+            trace_id="trace-root-start",
+            name="planner",
+            session_id="session-x",
+            root_message_id="msg-1",
+            root_agent_type="planner",
+            input={"text": "hello"},
+            status="QUEUED",
+            start_ts=1000,
+        )
+    )
+
+    meta = {
+        k.decode() if isinstance(k, bytes) else k: decode_redis_value(v)
+        for k, v in (
+            await redis.hgetall(RedisKeys.trace_meta("trace-root-start"))
+        ).items()
+    }
+    assert meta["trace_id"] == "trace-root-start"
+    assert meta["status"] == "QUEUED"
+    assert int(meta["start_ts"]) == 1000
+    assert meta["root_agent_type"] == "planner"
+    assert meta["root_message_id"] == "msg-1"
+    assert meta.get("input") == {"text": "hello"}
+
+
+@pytest.mark.asyncio
+async def test_trace_write_client_records_trace_root_end():
+    """TraceWriteClient persists end_ts, status and output when root finishes."""
+    redis = QueryRedis()
+    writer = TraceWriteClient(redis)
+    # Simulate the start record written by the client
+    await writer.record_trace(
+        TraceRecord(
+            trace_id="trace-root-end",
+            name="planner",
+            root_agent_type="planner",
+            status="QUEUED",
+            start_ts=1000,
+        )
+    )
+    # Simulate the end record written by the worker
+    await writer.record_trace(
+        TraceRecord(
+            trace_id="trace-root-end",
+            status="COMPLETED",
+            end_ts=5000,
+            output={"answer": "42"},
+        )
+    )
+
+    meta = {
+        k.decode() if isinstance(k, bytes) else k: decode_redis_value(v)
+        for k, v in (
+            await redis.hgetall(RedisKeys.trace_meta("trace-root-end"))
+        ).items()
+    }
+    assert meta["status"] == "COMPLETED"
+    assert int(meta["end_ts"]) == 5000
+    assert meta.get("output") == {"answer": "42"}
+
+
+@pytest.mark.asyncio
+async def test_trace_read_client_returns_start_ts_from_trace_record():
+    """TraceReadClient propagates start_ts written by the client into the result."""
+    redis = QueryRedis()
+    writer = TraceWriteClient(redis)
+    await writer.record_trace(
+        TraceRecord(
+            trace_id="trace-ts-check",
+            name="scheduler",
+            session_id="sess-ts",
+            root_agent_type="scheduler",
+            status="QUEUED",
+            start_ts=2000,
+        )
+    )
+    from by_framework_trace_query.client import TraceReadClient as TRC
+
+    client = TRC(redis_client=redis)
+    result = await client.get_trace("trace-ts-check", session_id="sess-ts")
+    assert result.trace.start_ts == 2000
+    assert result.trace.root_agent_type == "scheduler"

{by_framework-0.2.2.dev4 → by_framework-0.2.2.dev5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "by-framework"
-version = "0.2.2.dev4"
+version = "0.2.2.dev5"
 description = "分布式 Agent 调度框架"
 readme = "README.md"
 requires-python = ">=3.12"