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

by_framework_langgraph/adapter.py

@@ -18,7 +18,7 @@ from by_framework.core.protocol.commands import ResumeCommand
 from by_framework.core.protocol.events import StreamChunkEvent
 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 langchain_core.messages import AIMessage, HumanMessage
 from langgraph.types import Command
 
 from ._utils import extract_content_text, extract_resume_data
@@ -32,6 +32,26 @@ if TYPE_CHECKING:
 LANGFUSE_OBSERVATION_ATTR = "_langfuse_observation"
 
 
+def _last_ai_message_text(messages: list[Any]) -> str:
+    """Find the last AIMessage's text content — not just messages[-1].
+
+    A correctly-terminating ReAct graph routes back to the agent node after
+    every tool call, so the state's last message should already be an
+    AIMessage. But a misconfigured graph (e.g. a routing function that
+    returns the string "end" instead of the END constant) can terminate
+    right after a tool call instead, leaving a ToolMessage as messages[-1].
+    Blindly using messages[-1].content would then surface a tool's raw
+    result as the "final answer" instead of the model's actual reply, so
+    this scans backwards for the last real AIMessage rather than trusting
+    positional order.
+    """
+    for msg in reversed(messages):
+        if isinstance(msg, AIMessage):
+            content = msg.content
+            return content if isinstance(content, str) else str(content)
+    return ""
+
+
 class _TokenAccumulatingCallbackHandler(BaseCallbackHandler):
     """LangChain callback handler that accumulates LLM token usage into AgentContext.
 
@@ -445,12 +465,38 @@ class LangGraphAdapter:
             )
             return {"status": AgentState.QUEUED.value}
 
+        # The checkpointed graph state's last message — not the streamed
+        # text — is the authoritative final answer, and takes priority
+        # whenever it's available (not just when full_response is empty).
+        # on_chat_model_stream isn't guaranteed to fire for every LLM call a
+        # graph makes: a model that narrates before calling a tool (e.g.
+        # "好的,我来帮你计算这个表达式!" + a tool_calls delta) can populate
+        # full_response with that preamble via a round that DID stream,
+        # while the actual final answer's round — after the tool
+        # executes — doesn't stream at all. full_response would then be
+        # non-empty but wrong (just the preamble), so an empty-only check
+        # can't catch it; graph state's messages[-1] is what the graph
+        # actually decided the final answer is, regardless of what
+        # streaming happened to capture.
+        state_text = self._extract_final_text_from_state()
+        if state_text:
+            full_response = state_text
+
         # Emit final answer if using custom output handler
         if self._output_handler and full_response:
             await self._output_handler(self._context, full_response)
 
         return full_response
 
+    def _extract_final_text_from_state(self) -> str:
+        """Read the last AIMessage's text straight from the checkpointed
+        graph state — see the fallback's call site for why this exists."""
+        try:
+            snapshot = self._graph.get_state(self._state_config)
+        except Exception:  # pylint: disable=broad-exception-caught
+            return ""
+        return _last_ai_message_text((snapshot.values or {}).get("messages", []))
+
     async def _process_result(self, result: dict) -> Any:
         """Analyze graph result and determine suspended vs completed."""
         if self._is_graph_suspended():
@@ -460,13 +506,12 @@ class LangGraphAdapter:
             )
             return {"status": AgentState.QUEUED.value}
 
-        # Extract final answer from last message
+        # Extract final answer from the last AIMessage
         messages = result.get("messages", [])
         if not messages:
             return result
 
-        last_msg = messages[-1]
-        answer = last_msg.content if hasattr(last_msg, "content") else str(last_msg)
+        answer = _last_ai_message_text(messages)
 
         # Emit output
         if self._output_handler:
@@ -525,6 +570,7 @@ class LangGraphAdapter:
                 self._context, "parent_message_id", ""
             ),
             "by_framework_agent_id": getattr(self._context, "current_agent_id", ""),
+            "worker_id": getattr(self._context, "worker_id", ""),
             "langgraph_thread_id": self._thread_id,
         }
         return {
@@ -538,10 +584,31 @@ class LangGraphAdapter:
 
         with (
             self._phoenix_context_manager(),
+            self._langfuse_attribute_propagation_context_manager(),
             self._langfuse_callback_manager(callbacks),
         ):
             yield callbacks
 
+    @contextmanager
+    def _langfuse_attribute_propagation_context_manager(self) -> Iterator[None]:
+        """Propagate stable framework metadata to Langfuse child observations."""
+        worker_id = str(getattr(self._context, "worker_id", "") or "")
+        if not worker_id:
+            yield
+            return
+
+        try:
+            propagate_attributes = getattr(
+                import_module("langfuse"),
+                "propagate_attributes",
+            )
+        except (ImportError, AttributeError):
+            yield
+            return
+
+        with propagate_attributes(metadata={"worker_id": worker_id}):
+            yield
+
     @contextmanager
     def _phoenix_context_manager(self) -> Iterator[None]:
         """Prepare OpenTelemetry context for Phoenix tracing."""

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: by-framework-langgraph
-Version: 0.0.3.dev2
+Version: 0.0.3.dev4
 Summary: LangGraph integration for by-framework
 Requires-Python: >=3.12
 Requires-Dist: by-framework>=0.2.1
@@ -67,3 +67,46 @@ class OrchestratorWorker(LangGraphWorker):
         llm = ChatOpenAI(model="gpt-4o").bind_tools([poet, ask])
         # ... build and return compiled graph
 ```
+
+## Common Pitfalls
+
+Both of these fail **silently** — no exception, just wrong or empty results — so they're easy to lose time to.
+
+### `add_messages` must be imported as a function, not written as a string
+
+```python
+from langgraph.graph.message import add_messages
+
+# Correct — the reducer actually runs; messages accumulate across nodes.
+messages: Annotated[list, add_messages]
+
+# Wrong — looks plausible (some older LangGraph docs used this form), but
+# the reducer silently does nothing: each node only sees its own output,
+# not the accumulated history. Your agent node ends up calling the model
+# with just the latest ToolMessage and no prior context, and typically
+# returns an empty or confused reply.
+messages: Annotated[list, "add_messages"]
+```
+
+### A routing function must return the `END` constant, not the string `"end"`
+
+```python
+from langgraph.graph import END
+
+# Correct — the graph terminates properly; the agent node's final
+# AIMessage is saved to state before the graph stops.
+def should_continue(state):
+    ...
+    return END
+
+# Wrong — "end" looks like it should work as a node name, but LangGraph
+# only recognizes the END constant (whose actual value is "__end__").
+# LangGraph logs "wrote to unknown channel branch:to:end, ignoring it."
+# and the graph doesn't route there — the agent's last turn is dropped,
+# and `state["messages"][-1]` after execution can end up being something
+# other than the model's real final answer (e.g. a stale ToolMessage from
+# an earlier step), not the reply you expected.
+def should_continue(state):
+    ...
+    return "end"
+```

{by_framework_langgraph-0.0.3.dev2.dist-info → by_framework_langgraph-0.0.3.dev4.dist-info}/RECORD

@@ -1,8 +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/adapter.py,sha256=3ZYzpcbWAo_-EmQ9QzxYE7e_dxnfThiHk0wDqsF5OiA,29859
 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.dev4.dist-info/METADATA,sha256=48vOtcoLYGH-XS9TT6Jg5D1CzxX7ro6auzAi8TlhGHk,3939
+by_framework_langgraph-0.0.3.dev4.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+by_framework_langgraph-0.0.3.dev4.dist-info/RECORD,,

{by_framework_langgraph-0.0.3.dev2.dist-info → by_framework_langgraph-0.0.3.dev4.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.30.1
+Generator: hatchling 1.32.0
 Root-Is-Purelib: true
 Tag: py3-none-any