langchain-agentx-python 0.8.1__tar.gz → 0.8.2__tar.gz

{langchain-agentx-python-0.8.1/langchain_agentx_python.egg-info → langchain-agentx-python-0.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: langchain-agentx-python
-Version: 0.8.1
+Version: 0.8.2
 Summary: LangChain/LangGraph-based agent utilities for CodeBaseX.
 Author-email: GoodMood2008 <GoodMood2008@users.noreply.github.com>
 License:                                  Apache License

{langchain-agentx-python-0.8.1 → langchain-agentx-python-0.8.2}/langchain_agentx/__init__.py

@@ -11,7 +11,7 @@ from langchain_agentx import create_loop_agent
 ```
 """
 
-__version__ = "0.8.1"
+__version__ = "0.8.2"
 
 from .loop import (  # noqa: F401
     create_loop_agent,

{langchain-agentx-python-0.8.1 → langchain-agentx-python-0.8.2}/langchain_agentx/loop/subagent/runner.py

@@ -407,10 +407,13 @@ async def _collect_subagent_events(
     tool_step = 0
 
     # 构建子 graph config：合并父 runnable_config 使事件自动冒泡
-    config = {"tags": run_tags, "recursion_limit": 9999}
+    config = {"tags": run_tags}
     parent_runnable_config = getattr(ctx, "runnable_config", None)
     if parent_runnable_config is not None:
         if isinstance(parent_runnable_config, dict):
+            # 从父 config 继承 recursion_limit（如果有）
+            if "recursion_limit" in parent_runnable_config:
+                config["recursion_limit"] = parent_runnable_config["recursion_limit"]
             # 合并父 config 的 configurable 字段，使子 graph 事件冒泡到父 graph
             configurable = parent_runnable_config.get("configurable", {})
             if configurable:
@@ -480,8 +483,29 @@ async def _build_subagent_result(
     transcript: SubagentTranscriptManager,
     allowed_tool_names: set[str] | None,
     trace: SubagentExecutionTrace,
+    model: Any,
 ) -> SubagentResult:
-    content = _extract_final_content(collected.collected_assistant_messages, allowed_tool_names)
+    """构建子 Agent 执行结果。
+
+    使用 ProviderSemanticsRuntime 提取最终答案，确保与主链逻辑一致。
+    """
+    from langchain_agentx.provider.semantics.runtime import (
+        create_runtime_from_messages,
+        create_runtime_from_model,
+    )
+
+    # 字符串 model 无法可靠解析 provider family；按消息形状推断 runtime
+    if isinstance(model, str):
+        runtime = create_runtime_from_messages(collected.collected_assistant_messages)
+    else:
+        runtime = create_runtime_from_model(model)
+
+    # 使用 runtime 提取最终答案
+    final_answer = runtime.extract_final_answer_from_messages(
+        collected.collected_assistant_messages,
+        allowed_tool_names=allowed_tool_names,
+    )
+    content = final_answer.text
     status = "error" if collected.terminal_reason == "error" else "completed"
     transcript.flush([_to_message_dict(m) for m in collected.collected_assistant_messages])
     if not content and status == "completed":
@@ -571,6 +595,7 @@ async def run_subagent(
             transcript=transcript,
             allowed_tool_names=allowed_tool_names,
             trace=trace,
+            model=resolved_model,
         )
 
     finally:

{langchain-agentx-python-0.8.1 → langchain-agentx-python-0.8.2}/langchain_agentx/observability/events/langchain_agentx_event_adapter.py

@@ -564,19 +564,24 @@ class LangGraphToLangchainAgentEventAdapter:
                 )
 
     def _extract_answer_from_chain_end_output(self, data: Dict[str, Any]) -> str:
-        """从 on_chain_end 的 output 中取最后一条 AIMessage.content。"""
+        """从 on_chain_end 的 output 中提取最终可见答案。
+
+        对齐 A19 visible-answer-only 规则，统一复用 ProviderSemanticsRuntime，
+        避免在 adapter 内继续直接解析 provider 原始消息形状。
+        """
         output = data.get("output") if isinstance(data, dict) else None
         if not isinstance(output, dict) or "messages" not in output:
             return ""
+
         messages = output.get("messages")
         if not isinstance(messages, (list, tuple)):
             return ""
-        for msg in reversed(messages):
-            if isinstance(msg, AIMessage):
-                content = getattr(msg, "content", None)
-                if isinstance(content, str):
-                    return content
-        return ""
+
+        from langchain_agentx.provider.semantics.runtime import create_runtime_from_messages
+
+        runtime = create_runtime_from_messages(list(messages))
+        answer = runtime.extract_final_answer_from_messages(list(messages))
+        return answer.text
 
     @staticmethod
     def _extract_text_from_message_content(content: Any) -> str:
@@ -818,10 +823,9 @@ class LangGraphToLangchainAgentEventAdapter:
                 )
                 self.state.is_step_started = False
 
-            # answer：优先 text，其次 reason（CoT 无 text 时），最后 on_chain_end 兜底
+            # answer：只输出可见文本（A19 visible-answer-only 规则）
+            # reasoning 不再作为 fallback，reasoning_content 仅用于 reasoning 事件流
             answer = self.state.accumulated_answer.strip()
-            if not answer:
-                answer = self.state.accumulated_reasoning.strip()
             if not answer:
                 answer = self._extract_answer_from_chain_end_output(data)
             loop_payload = self._build_loop_observation_payload()

langchain-agentx-python-0.8.2/langchain_agentx/provider/semantics/__init__.py

@@ -0,0 +1,74 @@
+"""
+provider/semantics — Provider Semantics Boundary
+
+本模块提供 provider 语义归一化能力：
+- contracts: 契约对象定义
+- profile: Provider profile 解析
+- registry: Family → suite 注册表
+- runtime: 业务层门面对象
+- turn_accumulator: 状态收集器
+- answer_assembler: 最终答案装配器
+- families: 各 family 特定实现
+
+使用方式：
+    from langchain_agentx.provider.semantics import create_runtime_from_model
+
+    runtime = create_runtime_from_model(model)
+    accumulator = runtime.new_accumulator()
+    # ... 使用 runtime 和 accumulator
+"""
+
+from __future__ import annotations
+
+from langchain_agentx.provider.semantics.answer_assembler import (
+    FinalAnswerAssembler,
+    get_default_assembler,
+)
+from langchain_agentx.provider.semantics.contracts import (
+    FinalAnswer,
+    NormalizedAssistantTurn,
+    NormalizedDelta,
+    NormalizedTurnLog,
+    ProviderCapabilities,
+    ProviderProfile,
+)
+from langchain_agentx.provider.semantics.profile import (
+    ProviderProfileResolver,
+    get_default_profile_resolver,
+)
+from langchain_agentx.provider.semantics.registry import (
+    ProviderSemanticsRegistry,
+    ProviderSemanticsSuite,
+    get_default_registry,
+)
+from langchain_agentx.provider.semantics.runtime import (
+    ProviderSemanticsRuntime,
+    create_runtime_from_model,
+    create_runtime_from_messages,
+)
+from langchain_agentx.provider.semantics.turn_accumulator import TurnAccumulator
+
+__all__ = [
+    # Contracts
+    "FinalAnswer",
+    "NormalizedAssistantTurn",
+    "NormalizedDelta",
+    "NormalizedTurnLog",
+    "ProviderCapabilities",
+    "ProviderProfile",
+    # Profile
+    "ProviderProfileResolver",
+    "get_default_profile_resolver",
+    # Registry
+    "ProviderSemanticsRegistry",
+    "ProviderSemanticsSuite",
+    "get_default_registry",
+    # Runtime
+    "ProviderSemanticsRuntime",
+    "create_runtime_from_model",
+    "create_runtime_from_messages",
+    # Components
+    "TurnAccumulator",
+    "FinalAnswerAssembler",
+    "get_default_assembler",
+]

langchain-agentx-python-0.8.2/langchain_agentx/provider/semantics/answer_assembler.py

@@ -0,0 +1,105 @@
+"""
+answer_assembler.py — Provider-Agnostic 最终答案装配器
+
+职责：
+    从 NormalizedTurnLog 中装配最终可见答案
+    必须对 provider 无感知，只消费统一数据结构
+
+链路位置：
+    在整体流程中的位置：TurnAccumulator → FinalAnswerAssembler → 业务层
+    主路径和子路径共享同一装配规则，确保一致性
+
+当前裁剪范围：
+    - 不直接读取原始 AIMessage
+    - 不关心 provider family
+    - 默认不允许 reasoning 充当 answer fallback
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from langchain_agentx.provider.semantics.contracts import (
+        FinalAnswer,
+        NormalizedTurnLog,
+    )
+
+logger = logging.getLogger(__name__)
+
+
+class FinalAnswerAssembler:
+    """Provider-Agnostic 最终答案装配器。
+
+    从 NormalizedTurnLog 中按优先级选择最终可见答案：
+    1. model_end 有可见文本且不是纯工具调度消息
+    2. stream 累积有可见文本
+    3. chain_end 有可见文本且不是纯工具调度消息
+    4. 返回空字符串（不拿 reasoning 顶替）
+
+    业务层（loop、observability、subagent）共享此装配器，确保一致性。
+    """
+
+    def assemble(self, log: "NormalizedTurnLog") -> "FinalAnswer":
+        """从 turn log 中装配最终可见答案。
+
+        Args:
+            log: NormalizedTurnLog 实例
+
+        Returns:
+            FinalAnswer 实例
+        """
+        from langchain_agentx.provider.semantics.contracts import FinalAnswer
+
+        # 优先：最后一条 model_end 有可见文本且不是纯工具调度
+        model_turn = log.last_model_end_turn_with_visible_text()
+        if model_turn and not model_turn.tool_dispatch_only:
+            return FinalAnswer(
+                text=model_turn.visible_text,
+                source="model_end",
+                diagnostics=[],
+            )
+
+        # 次选：stream 累积的可见文本
+        stream_text = log.visible_stream_text()
+        if stream_text:
+            return FinalAnswer(
+                text=stream_text,
+                source="stream",
+                diagnostics=["model_end_missing_visible_text"],
+            )
+
+        # 再次选：最后一条 chain_end 有可见文本且不是纯工具调度
+        chain_turn = log.last_chain_end_turn_with_visible_text()
+        if chain_turn and not chain_turn.tool_dispatch_only:
+            return FinalAnswer(
+                text=chain_turn.visible_text,
+                source="chain_end",
+                diagnostics=["model_end_missing_visible_text"],
+            )
+
+        # 最后：返回空字符串（不拿 reasoning 顶替）
+        return FinalAnswer(
+            text="",
+            source="empty",
+            diagnostics=["no_visible_answer"],
+        )
+
+
+# 单例实例
+_default_assembler: FinalAnswerAssembler | None = None
+
+
+def get_default_assembler() -> FinalAnswerAssembler:
+    """获取默认的 FinalAnswerAssembler 单例。"""
+    global _default_assembler
+    if _default_assembler is None:
+        _default_assembler = FinalAnswerAssembler()
+    return _default_assembler
+
+
+__all__ = [
+    "FinalAnswerAssembler",
+    "get_default_assembler",
+]

langchain-agentx-python-0.8.2/langchain_agentx/provider/semantics/contracts.py

@@ -0,0 +1,184 @@
+"""
+contracts.py — Provider 语义契约对象
+
+职责：
+    定义 provider 语义归一化的核心数据结构，包括：
+    - ProviderCapabilities: provider 能力画像
+    - ProviderProfile: provider 家族与能力组合
+    - NormalizedDelta: 归一化后的流式增量事件
+    - NormalizedAssistantTurn: 归一化后的 assistant 轮次表示
+    - FinalAnswer: 最终给业务层的输出
+
+链路位置：
+    在整体流程中的位置：ProviderSemanticsBoundary → 业务层
+    业务层只消费这些统一契约，不感知 provider 原始形状
+
+当前裁剪范围：
+    - 不包含 provider 特定的解析逻辑（由 family 实现）
+    - 不包含流式事件的实际解析（由 normalizer 实现）
+    - 不包含最终答案的选择算法（由 assembler 实现）
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class ProviderCapabilities:
+    """Provider 能力画像。
+
+    描述 provider 支持或常见的语义特征，用于兼容官方与网关之间的细微差异。
+    """
+
+    # content_blocks: Anthropic 使用 blocks 列表格式
+    content_blocks: bool = False
+
+    # reasoning_channel: 是否支持独立的 reasoning 通道（如 OpenAI reasoning_content）
+    reasoning_channel: bool = False
+
+    # structured_tool_calls: 是否支持结构化 tool_calls 字段
+    structured_tool_calls: bool = True
+
+    # degraded_tool_tags: 是否可能产生退化格式的工具调用（XML tag / CALL_TOOL: 前缀）
+    degraded_tool_tags: bool = False
+
+    # final_text_may_only_appear_in_model_end: 是否只在 model_end 时才有最终文本
+    #（某些 provider 的 stream 只包含 delta，不包含完整内容）
+    final_text_may_only_appear_in_model_end: bool = False
+
+
+@dataclass(frozen=True)
+class ProviderProfile:
+    """Provider 家族与能力组合。
+
+    业务层只依赖 family 字段做粗粒度分支，细粒度差异由 capabilities 处理。
+    """
+
+    # family: provider 家族标识（anthropic / openai / compatible_openai）
+    family: str
+
+    # model_name: 模型名称（可选，用于调试和日志）
+    model_name: str | None = None
+
+    # capabilities: 该 provider 的能力画像
+    capabilities: ProviderCapabilities = field(default_factory=ProviderCapabilities)
+
+
+@dataclass
+class NormalizedDelta:
+    """归一化后的流式增量事件。
+
+    将不同 provider 的 stream chunk 统一为相同格式。
+    """
+
+    # kind: 增量类型（text / reasoning / tool_call）
+    kind: str
+
+    # text: 文本内容（kind=text 或 kind=reasoning 时使用）
+    text: str = ""
+
+    # tool_calls: 工具调用列表（kind=tool_call 时使用）
+    tool_calls: list[dict] = field(default_factory=list)
+
+    # source: 数据来源标记（stream）
+    source: str = "stream"
+
+    # diagnostics: 诊断信息列表（用于调试）
+    diagnostics: list[str] = field(default_factory=list)
+
+
+@dataclass
+class NormalizedAssistantTurn:
+    """归一化后的 assistant 轮次表示。
+
+    将 model_end 或 chain_end 的 AIMessage 统一为相同格式。
+    业务层只消费此结构，不直接读取 AIMessage.content 原始形状。
+    """
+
+    # visible_text: 可见文本（用户可见的答案内容）
+    visible_text: str = ""
+
+    # reasoning_text: 推理文本（过程内容，不作为默认答案）
+    reasoning_text: str = ""
+
+    # tool_calls: 工具调用列表
+    tool_calls: list[dict] = field(default_factory=list)
+
+    # tool_dispatch_only: 是否是纯工具调度消息（无可见文本）
+    # 用于 FinalAnswerAssembler 跳过此类消息
+    tool_dispatch_only: bool = False
+
+    # source: 数据来源（model_end / chain_end）
+    source: str = "model_end"
+
+    # diagnostics: 诊断信息列表（用于调试）
+    diagnostics: list[str] = field(default_factory=list)
+
+
+@dataclass
+class FinalAnswer:
+    """最终给业务层的输出。
+
+    由 FinalAnswerAssembler 从归一化结果装配而来。
+    业务层（loop、observability、subagent）只消费此结构。
+    """
+
+    # text: 最终可见文本
+    text: str = ""
+
+    # source: 答案来源（model_end / stream / chain_end / empty）
+    source: str = "empty"
+
+    # diagnostics: 诊断信息列表（用于调试和错误追踪）
+    diagnostics: list[str] = field(default_factory=list)
+
+
+@dataclass
+class NormalizedTurnLog:
+    """单轮模型调用的归一化事实记录。
+
+    由 TurnAccumulator 收集，供 FinalAnswerAssembler 使用。
+    """
+
+    # stream_deltas: 本轮累积的流式增量列表
+    stream_deltas: list[NormalizedDelta] = field(default_factory=list)
+
+    # model_end_turns: 本轮收集的 model_end turns（可能有多个，通常只有一个）
+    model_end_turns: list[NormalizedAssistantTurn] = field(default_factory=list)
+
+    # chain_end_turns: 本轮收集的 chain_end turns（用于 fallback）
+    chain_end_turns: list[NormalizedAssistantTurn] = field(default_factory=list)
+
+    def last_model_end_turn_with_visible_text(self) -> NormalizedAssistantTurn | None:
+        """获取最后一条有可见文本且不是纯工具调度的 model_end turn。"""
+        for turn in reversed(self.model_end_turns):
+            if turn.visible_text and not turn.tool_dispatch_only:
+                return turn
+        return None
+
+    def last_chain_end_turn_with_visible_text(self) -> NormalizedAssistantTurn | None:
+        """获取最后一条有可见文本且不是纯工具调度的 chain_end turn。"""
+        for turn in reversed(self.chain_end_turns):
+            if turn.visible_text and not turn.tool_dispatch_only:
+                return turn
+        return None
+
+    def visible_stream_text(self) -> str:
+        """获取本轮 stream 累积的可见文本。"""
+        return "".join(
+            delta.text
+            for delta in self.stream_deltas
+            if delta.kind == "text"
+        )
+
+
+__all__ = [
+    "ProviderCapabilities",
+    "ProviderProfile",
+    "NormalizedDelta",
+    "NormalizedAssistantTurn",
+    "FinalAnswer",
+    "NormalizedTurnLog",
+]

langchain-agentx-python-0.8.2/langchain_agentx/provider/semantics/families/__init__.py

@@ -0,0 +1,16 @@
+"""
+families — Provider Family 特定实现
+
+本模块包含各 provider family 的语义协作者：
+- anthropic.py: Anthropic family
+- openai.py: OpenAI family
+- compatible_openai.py: Compatible OpenAI family
+
+每个 family 包含三个协作者：
+- MessageNormalizer: 归一化 model_end / chain_end 消息
+- StreamNormalizer: 归一化流式增量
+- ToolCallInterpreter: 识别工具调度
+"""
+from __future__ import annotations
+
+__all__ = []

langchain-agentx-python-0.8.2/langchain_agentx/provider/semantics/families/anthropic.py

@@ -0,0 +1,186 @@
+"""
+anthropic.py — Anthropic Family 语义协作者
+
+职责：
+    实现 Anthropic family 的语义归一化：
+    - AnthropicMessageNormalizer: 归一化 content blocks 格式
+    - AnthropicStreamNormalizer: 归一化 Anthropic 流式 chunk
+    - AnthropicToolCallInterpreter: 识别 block tool-use
+
+链路位置：
+    在整体流程中的位置：ProviderSemanticsRegistry → Anthropic Suite → Normalizer/Interpreter
+    作为 Anthropic family 的默认实现
+
+当前裁剪范围：
+    - 不处理 reasoning_content（Anthropic 不支持）
+    - 不处理退化格式（Anthropic 使用结构化 tool_use）
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from langchain_agentx.provider.semantics.contracts import (
+    NormalizedAssistantTurn,
+    NormalizedDelta,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class AnthropicMessageNormalizer:
+    """Anthropic 消息归一化器。
+
+    将 Anthropic 的 content blocks 格式归一化为 NormalizedAssistantTurn。
+    """
+
+    def normalize_model_end(self, output: Any) -> NormalizedAssistantTurn | None:
+        """归一化 model_end 输出。
+
+        Args:
+            output: on_chat_model_end.output（AIMessage 或 dict）
+
+        Returns:
+            NormalizedAssistantTurn 实例，如果无效则返回 None
+        """
+        # 如果是 dict，提取最后一条消息
+        if isinstance(output, dict):
+            messages = output.get("messages", [])
+            if not messages:
+                return None
+            msg = messages[-1]
+        else:
+            # 直接是 AIMessage
+            msg = output
+
+        # 提取 content
+        content = getattr(msg, "content", None)
+
+        visible_text = ""
+        reasoning_text = ""
+        tool_calls = []
+
+        if isinstance(content, str):
+            visible_text = content
+        elif isinstance(content, list):
+            for block in content:
+                if not isinstance(block, dict):
+                    continue
+                block_type = block.get("type")
+
+                if block_type == "text":
+                    text = block.get("text", "")
+                    visible_text += text
+                elif block_type == "thinking":
+                    # Anthropic thinking blocks（推理内容）
+                    thinking_text = block.get("thinking", "")
+                    reasoning_text += thinking_text
+                elif block_type == "tool_use":
+                    # 结构化 tool_use
+                    tool_call = {
+                        "name": block.get("name", ""),
+                        "args": block.get("input", {}),
+                        "id": block.get("id", ""),
+                        "type": "tool_call",
+                    }
+                    tool_calls.append(tool_call)
+
+        return NormalizedAssistantTurn(
+            visible_text=visible_text,
+            reasoning_text=reasoning_text,
+            tool_calls=tool_calls,
+            tool_dispatch_only=False,  # 由 interpreter 判断
+            source="model_end",
+        )
+
+    def normalize_message(self, msg: Any) -> NormalizedAssistantTurn | None:
+        """归一化单条消息。
+
+        Args:
+            msg: AIMessage 或 dict
+
+        Returns:
+            NormalizedAssistantTurn 实例，如果无效则返回 None
+        """
+        # 复用 normalize_model_end 逻辑
+        return self.normalize_model_end({"messages": [msg]})
+
+
+class AnthropicStreamNormalizer:
+    """Anthropic 流式增量归一化器。
+
+    将 Anthropic 的流式 chunk 归一化为 NormalizedDelta。
+    """
+
+    def normalize(self, chunk: Any) -> list[NormalizedDelta]:
+        """归一化流式 chunk。
+
+        Args:
+            chunk: LangGraph astream_events chunk
+
+        Returns:
+            NormalizedDelta 列表
+        """
+        deltas = []
+
+        # 提取 event 数据
+        if not isinstance(chunk, dict):
+            return deltas
+
+        event_type = chunk.get("event")
+        if event_type != "on_chat_model_stream":
+            return deltas
+
+        data = chunk.get("data", {})
+        if not isinstance(data, dict):
+            return deltas
+
+        # 提取 chunk content
+        chunk_content = data.get("chunk", {})
+        if not isinstance(chunk_content, dict):
+            return deltas
+
+        # 处理 content_block_delta
+        if "content_block" in chunk_content:
+            block = chunk_content.get("content_block", {})
+            block_type = block.get("type")
+
+            if block_type == "text_delta":
+                text = block.get("text", "")
+                if text:
+                    deltas.append(NormalizedDelta(kind="text", text=text))
+            elif block_type == "input_json_delta":
+                # tool_use 参数增量，暂不处理
+                pass
+
+        return deltas
+
+
+class AnthropicToolCallInterpreter:
+    """Anthropic 工具调用解释器。
+
+    识别 Anthropic 的 block tool-use，判断是否是纯工具调度消息。
+    """
+
+    def is_tool_dispatch_only(self, turn: NormalizedAssistantTurn) -> bool:
+        """判断是否是纯工具调度消息。
+
+        Args:
+            turn: NormalizedAssistantTurn 实例
+
+        Returns:
+            如果是纯工具调度消息返回 True
+        """
+        # Anthropic: 有 tool_calls 且无 visible text 视为纯工具调度
+        has_tool_calls = bool(turn.tool_calls)
+        has_visible_text = bool(turn.visible_text.strip())
+
+        return has_tool_calls and not has_visible_text
+
+
+__all__ = [
+    "AnthropicMessageNormalizer",
+    "AnthropicStreamNormalizer",
+    "AnthropicToolCallInterpreter",
+]