by-framework-langgraph 0.0.3.dev0__py3-none-any.whl → 0.0.3.dev2__py3-none-any.whl

by_framework_langgraph/adapter.py

@@ -16,7 +16,8 @@ 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 by_framework.trace.span_recorder import str_to_uint64, str_to_uint128
+from langchain_core.callbacks import BaseCallbackHandler
 from langchain_core.messages import HumanMessage
 from langgraph.types import Command
 
@@ -31,6 +32,172 @@ if TYPE_CHECKING:
 LANGFUSE_OBSERVATION_ATTR = "_langfuse_observation"
 
 
+class _TokenAccumulatingCallbackHandler(BaseCallbackHandler):
+    """LangChain callback handler that accumulates LLM token usage into AgentContext.
+
+    Extracts token usage from whichever location the provider populates:
+      - ``llm_output["token_usage"]``  (OpenAI-style via LangChain)
+      - ``llm_output["usage"]``         (Anthropic-style / raw provider mapping)
+      - ``generation.message.usage_metadata``  (LangChain >= 0.2 standard)
+      - ``generation.generation_info``  (some community integrations)
+
+    ``run_id`` deduplication prevents double-counting when both ``on_llm_end``
+    and ``on_chat_model_end`` fire for the same call (LangChain >= 0.2).
+    """
+
+    def __init__(self, context: Any) -> None:
+        super().__init__()
+        self._context = context
+        self._seen_run_ids: set = set()
+
+    # ------------------------------------------------------------------
+    # LangChain callback entry point
+    # ------------------------------------------------------------------
+
+    def on_llm_end(self, response: Any, *, run_id: Any = None, **_kwargs: Any) -> None:
+        # Guard: only mark run as seen when we actually extracted tokens so that
+        # the on_chat_model_end event path in _stream_invoke can still fire as a
+        # fallback when the callback found nothing (e.g. stream_options not set).
+        if run_id is not None and run_id in self._seen_run_ids:
+            return
+        self._handle_llm_result(response, run_id=run_id)
+
+    # ------------------------------------------------------------------
+    # Internal extraction logic
+    # ------------------------------------------------------------------
+
+    def _handle_llm_result(self, response: Any, *, run_id: Any = None) -> None:
+        context = self._context
+        if context is None:
+            return
+
+        prompt, completion = self._extract_tokens(response)
+
+        if not (prompt or completion):
+            # Log at WARNING (always visible) to help diagnose providers whose
+            # token format is not yet handled, or where stream_options is missing.
+            gens = getattr(response, "generations", []) or []
+            first = (gens[0] or [None])[0] if gens else None
+            msg_type = type(getattr(first, "message", None)).__name__
+            logger.warning(
+                "[TokenAccumulator] on_llm_end fired but extracted 0 tokens. "
+                "For OpenAI-compatible streaming APIs add "
+                "stream_options={'include_usage': True} to your ChatModel. "
+                "llm_output=%r  first_gen_message_type=%s",
+                getattr(response, "llm_output", None),
+                msg_type,
+            )
+            # Do NOT mark run_id as seen — let the on_chat_model_end event path
+            # in _stream_invoke attempt extraction from the merged message.
+            return
+
+        if run_id is not None:
+            self._seen_run_ids.add(run_id)
+        try:
+            context.record_token_usage(
+                prompt_tokens=prompt,
+                completion_tokens=completion,
+            )
+        except Exception:  # pylint: disable=broad-exception-caught
+            pass
+
+    @staticmethod
+    def _extract_tokens(response: Any) -> tuple[int, int]:
+        """Return (prompt_tokens, completion_tokens) from an LLMResult.
+
+        Checks every known location across providers:
+          1. llm_output["token_usage"]        — OpenAI via LangChain
+          2. llm_output["usage"]              — Anthropic / raw provider mapping
+          3. message.usage_metadata           — LangChain >= 0.2 standard
+          4. message.response_metadata        — some community integrations
+          5. generation.generation_info       — older / custom integrations
+        """
+        prompt, completion = 0, 0
+
+        llm_output = getattr(response, "llm_output", None) or {}
+        if isinstance(llm_output, dict):
+            for key in ("token_usage", "usage"):
+                usage = llm_output.get(key) or {}
+                if usage:
+                    prompt = int(
+                        usage.get("prompt_tokens") or usage.get("input_tokens") or 0
+                    )
+                    completion = int(
+                        usage.get("completion_tokens")
+                        or usage.get("output_tokens")
+                        or 0
+                    )
+                    break
+
+        if prompt or completion:
+            return prompt, completion
+
+        # Iterate all generations
+        for gen_list in getattr(response, "generations", []) or []:
+            for gen in (gen_list if isinstance(gen_list, list) else [gen_list]):
+                msg = getattr(gen, "message", None)
+
+                # LangChain >= 0.2: message.usage_metadata
+                meta = getattr(msg, "usage_metadata", None)
+                if meta:
+                    prompt += int(
+                        meta.get("input_tokens") or meta.get("prompt_tokens") or 0
+                    )
+                    completion += int(
+                        meta.get("output_tokens") or meta.get("completion_tokens") or 0
+                    )
+                    continue
+
+                # response_metadata (e.g. MiniMax, Qwen, some Chinese providers)
+                resp_meta = getattr(msg, "response_metadata", None) or {}
+                if isinstance(resp_meta, dict):
+                    for key in ("token_usage", "usage"):
+                        usage = resp_meta.get(key) or {}
+                        if usage:
+                            prompt += int(
+                                usage.get("prompt_tokens")
+                                or usage.get("input_tokens")
+                                or 0
+                            )
+                            completion += int(
+                                usage.get("completion_tokens")
+                                or usage.get("output_tokens")
+                                or 0
+                            )
+                            break
+                    # Flat keys at root of response_metadata
+                    if not (prompt or completion):
+                        prompt += int(
+                            resp_meta.get("prompt_tokens")
+                            or resp_meta.get("input_tokens")
+                            or 0
+                        )
+                        completion += int(
+                            resp_meta.get("completion_tokens")
+                            or resp_meta.get("output_tokens")
+                            or 0
+                        )
+                    if prompt or completion:
+                        continue
+
+                # generation_info fallback
+                info = getattr(gen, "generation_info", None) or {}
+                for key in ("token_usage", "usage"):
+                    sub = info.get(key) or {}
+                    if sub:
+                        prompt += int(
+                            sub.get("prompt_tokens") or sub.get("input_tokens") or 0
+                        )
+                        completion += int(
+                            sub.get("completion_tokens")
+                            or sub.get("output_tokens")
+                            or 0
+                        )
+                        break
+
+        return prompt, completion
+
+
 @dataclass(frozen=True)
 class _AdapterTracingConfig:
     """Tracing-related adapter config kept separate from core graph handles."""
@@ -167,6 +334,47 @@ class LangGraphAdapter:
                         await self._context.emit_chunk(
                             chunk.content, content_type="text"
                         )
+                elif kind == "on_chat_model_end":
+                    # Fallback: capture token usage from the event's merged output
+                    # message when the on_llm_end callback found nothing (e.g. the
+                    # provider requires stream_options but it was not set).
+                    # _TokenAccumulatingCallbackHandler marks run_id as seen only
+                    # after a successful extraction, so this path fires only when
+                    # the callback got 0 tokens.
+                    run_id = event.get("run_id")
+                    token_handler = next(
+                        (
+                            cb
+                            for cb in scoped_callbacks
+                            if isinstance(cb, _TokenAccumulatingCallbackHandler)
+                        ),
+                        None,
+                    )
+                    if token_handler is not None and run_id not in (
+                        token_handler._seen_run_ids  # pylint: disable=protected-access
+                    ):
+                        output = event["data"].get("output")
+                        meta = getattr(output, "usage_metadata", None)
+                        if meta:
+                            prompt = int(
+                                meta.get("input_tokens")
+                                or meta.get("prompt_tokens")
+                                or 0
+                            )
+                            completion = int(
+                                meta.get("output_tokens")
+                                or meta.get("completion_tokens")
+                                or 0
+                            )
+                            if prompt or completion:
+                                token_handler._seen_run_ids.add(run_id)  # pylint: disable=protected-access
+                                try:
+                                    self._context.record_token_usage(
+                                        prompt_tokens=prompt,
+                                        completion_tokens=completion,
+                                    )
+                                except Exception:  # pylint: disable=broad-exception-caught
+                                    pass
                 elif kind == "on_tool_start":
                     tool_name = event["name"]
                     tool_input = event["data"].get("input")
@@ -184,7 +392,7 @@ class LangGraphAdapter:
                         ),
                     )
 
-                    # Use a stable logical ID from metadata if available, fallback to run_id
+                    # Use stable metadata when available, otherwise fall back.
                     stable_id = (
                         event.get("metadata", {}).get("tool_call_id")
                         or event.get("metadata", {}).get("checkpoint_ns")
@@ -379,69 +587,50 @@ 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
+        # Always inject token accumulator — works regardless of Langfuse config.
+        callbacks.append(_TokenAccumulatingCallbackHandler(self._context))
 
-        # 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_langgraph/tools.py

@@ -7,7 +7,7 @@ mechanism.
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Annotated
+from typing import TYPE_CHECKING, Annotated, Any
 
 from langchain_core.tools import BaseTool, InjectedToolCallId, tool
 from langgraph.types import interrupt
@@ -16,6 +16,31 @@ if TYPE_CHECKING:
     from by_framework.worker.context import AgentContext
 
 
+def _langfuse_observation_id_from_callbacks(callbacks: Any) -> str:
+    """Return the Langfuse observation id for the active LangChain tool run."""
+    run_id = getattr(callbacks, "run_id", None) or getattr(
+        callbacks,
+        "parent_run_id",
+        None,
+    )
+    if not run_id:
+        return ""
+
+    handlers = [
+        *list(getattr(callbacks, "handlers", []) or []),
+        *list(getattr(callbacks, "inheritable_handlers", []) or []),
+    ]
+    for handler in handlers:
+        runs = getattr(handler, "_runs", None)
+        if not isinstance(runs, dict):
+            continue
+        observation = runs.get(run_id)
+        observation_id = getattr(observation, "id", None)
+        if observation_id:
+            return str(observation_id)
+    return ""
+
+
 def make_remote_agent_tool(
     context: AgentContext,
     tool_name: str,
@@ -50,6 +75,7 @@ def make_remote_agent_tool(
     async def remote_agent_tool(
         topic: str,
         tool_call_id: Annotated[str, InjectedToolCallId],
+        callbacks: Any = None,
     ) -> str:
         # Idempotency guard: checkpoint restore replays tool execution,
         # but we must not re-dispatch the command.
@@ -57,9 +83,19 @@ def make_remote_agent_tool(
         is_dispatched = await context.redis.exists(redis_key)
 
         if not is_dispatched:
+            metadata = {}
+            langfuse_parent_observation_id = _langfuse_observation_id_from_callbacks(
+                callbacks
+            )
+            if langfuse_parent_observation_id:
+                metadata["langfuse_parent_observation_id"] = (
+                    langfuse_parent_observation_id
+                )
+
             await context.call_agent(
                 target_agent_type=target_agent_type,
                 content=topic,
+                metadata=metadata,
             )
             await context.redis.set(redis_key, "1", ex=idempotency_ttl)
 

{by_framework_langgraph-0.0.3.dev0.dist-info → by_framework_langgraph-0.0.3.dev2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: by-framework-langgraph
-Version: 0.0.3.dev0
+Version: 0.0.3.dev2
 Summary: LangGraph integration for by-framework
 Requires-Python: >=3.12
 Requires-Dist: by-framework>=0.2.1

by_framework_langgraph-0.0.3.dev2.dist-info/RECORD

@@ -0,0 +1,8 @@
+by_framework_langgraph/__init__.py,sha256=x08wIaK4VRnUnUD_mbBxVgI2Zf7CvwAVbr3syP2NQps,1046
+by_framework_langgraph/_utils.py,sha256=A8eQ19YqyBiMKcPIlzmwggN_mK5iQvNJPTaTmsywWsw,1605
+by_framework_langgraph/adapter.py,sha256=b4WcK6R3B0Y7a52lIY6kMLtpp9mjXOkp4p6HcALAzbA,26689
+by_framework_langgraph/tools.py,sha256=l7LurtKKXA1Z4fyj15ffFWyWpt8drNCJ-mkGmlS7EVo,5561
+by_framework_langgraph/worker.py,sha256=wFalpBQLqFm-YzJugzAzkA3ciI9lUzxRTv4GmqVCv78,6156
+by_framework_langgraph-0.0.3.dev2.dist-info/METADATA,sha256=lzuVDa2l8CUp_af7-VnadrCq-wJgXCWJ2ldcuEwHKRw,2334
+by_framework_langgraph-0.0.3.dev2.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+by_framework_langgraph-0.0.3.dev2.dist-info/RECORD,,

by_framework_langgraph-0.0.3.dev0.dist-info/RECORD

@@ -1,8 +0,0 @@
-by_framework_langgraph/__init__.py,sha256=x08wIaK4VRnUnUD_mbBxVgI2Zf7CvwAVbr3syP2NQps,1046
-by_framework_langgraph/_utils.py,sha256=A8eQ19YqyBiMKcPIlzmwggN_mK5iQvNJPTaTmsywWsw,1605
-by_framework_langgraph/adapter.py,sha256=TmCU0gniDZxAXwnm-hA0M6wLaNThZ3CX3UznfG1g9-w,18051
-by_framework_langgraph/tools.py,sha256=T7OoNKMPuJT3t6bR5G8KVGSjrSnLP0tiCEzCnBGesMY,4384
-by_framework_langgraph/worker.py,sha256=wFalpBQLqFm-YzJugzAzkA3ciI9lUzxRTv4GmqVCv78,6156
-by_framework_langgraph-0.0.3.dev0.dist-info/METADATA,sha256=UI2zpgc9eB1ZBqy5BdNNqtonWWc-8QkmkpiE2dpE9MU,2334
-by_framework_langgraph-0.0.3.dev0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-by_framework_langgraph-0.0.3.dev0.dist-info/RECORD,,