langchain-agentx-python 0.8.0__py3-none-any.whl → 0.8.2__py3-none-any.whl

langchain_agentx/__init__.py

@@ -1,64 +1,64 @@
-"""
-LangChain-based agent utilities for CodeBaseX.
-
-This package provides:
-- LangChain-AgentX LangGraph agent factory (`loop`)
-
-Typical usage:
-
-```python
-from langchain_agentx import create_loop_agent
-```
-"""
-
-__version__ = "0.8.0"
-
-from .loop import (  # noqa: F401
-    create_loop_agent,
-)
-
-from .loop.hook import (  # noqa: F401
-    ATTACHMENT_HOOK_BLOCKING_ERROR,
-    ATTACHMENT_HOOK_CANCELLED,
-    ATTACHMENT_HOOK_NON_BLOCKING_ERROR,
-    ATTACHMENT_HOOK_STOPPED_CONTINUATION,
-    ATTACHMENT_HOOK_SUCCESS,
-)
-from .observability import (  # noqa: F401
-    EventAdapterState,
-    LangchainAgentEvent,
-    LangchainAgentEventType,
-    LangGraphToLangchainAgentEventAdapter,
-    TraceCollector,
-    TraceSession,
-    TraceSpan,
-)
-from .provider import CompatibleChatOpenAI  # noqa: F401
-from .session import AgentSession, create_agent_session  # noqa: F401
-from .health import HealthCheck, HealthReport, PreflightResult, preflight, sdk_health  # noqa: F401
-from .workflow import BaseWorkflow  # noqa: F401
-
-__all__ = [
-    "ATTACHMENT_HOOK_BLOCKING_ERROR",
-    "ATTACHMENT_HOOK_CANCELLED",
-    "ATTACHMENT_HOOK_NON_BLOCKING_ERROR",
-    "ATTACHMENT_HOOK_STOPPED_CONTINUATION",
-    "ATTACHMENT_HOOK_SUCCESS",
-    "create_loop_agent",
-    "create_agent_session",
-    "AgentSession",
-    "BaseWorkflow",
-    "EventAdapterState",
-    "LangchainAgentEvent",
-    "LangchainAgentEventType",
-    "LangGraphToLangchainAgentEventAdapter",
-    "TraceCollector",
-    "TraceSession",
-    "TraceSpan",
-    "CompatibleChatOpenAI",
-    "HealthCheck",
-    "HealthReport",
-    "PreflightResult",
-    "preflight",
-    "sdk_health",
-]
+"""
+LangChain-based agent utilities for CodeBaseX.
+
+This package provides:
+- LangChain-AgentX LangGraph agent factory (`loop`)
+
+Typical usage:
+
+```python
+from langchain_agentx import create_loop_agent
+```
+"""
+
+__version__ = "0.8.2"
+
+from .loop import (  # noqa: F401
+    create_loop_agent,
+)
+
+from .loop.hook import (  # noqa: F401
+    ATTACHMENT_HOOK_BLOCKING_ERROR,
+    ATTACHMENT_HOOK_CANCELLED,
+    ATTACHMENT_HOOK_NON_BLOCKING_ERROR,
+    ATTACHMENT_HOOK_STOPPED_CONTINUATION,
+    ATTACHMENT_HOOK_SUCCESS,
+)
+from .observability import (  # noqa: F401
+    EventAdapterState,
+    LangchainAgentEvent,
+    LangchainAgentEventType,
+    LangGraphToLangchainAgentEventAdapter,
+    TraceCollector,
+    TraceSession,
+    TraceSpan,
+)
+from .provider import CompatibleChatOpenAI  # noqa: F401
+from .session import AgentSession, create_agent_session  # noqa: F401
+from .health import HealthCheck, HealthReport, PreflightResult, preflight, sdk_health  # noqa: F401
+from .workflow import BaseWorkflow  # noqa: F401
+
+__all__ = [
+    "ATTACHMENT_HOOK_BLOCKING_ERROR",
+    "ATTACHMENT_HOOK_CANCELLED",
+    "ATTACHMENT_HOOK_NON_BLOCKING_ERROR",
+    "ATTACHMENT_HOOK_STOPPED_CONTINUATION",
+    "ATTACHMENT_HOOK_SUCCESS",
+    "create_loop_agent",
+    "create_agent_session",
+    "AgentSession",
+    "BaseWorkflow",
+    "EventAdapterState",
+    "LangchainAgentEvent",
+    "LangchainAgentEventType",
+    "LangGraphToLangchainAgentEventAdapter",
+    "TraceCollector",
+    "TraceSession",
+    "TraceSpan",
+    "CompatibleChatOpenAI",
+    "HealthCheck",
+    "HealthReport",
+    "PreflightResult",
+    "preflight",
+    "sdk_health",
+]

langchain_agentx/loop/config/agent_config.py

@@ -14,21 +14,31 @@ from __future__ import annotations
 from typing import Any
 
 
+DEFAULT_RECURSION_LIMIT = 9_999
+
+
 def merge_run_config(
     graph: Any,
     caller: dict[str, Any] | None = None,
 ) -> dict[str, Any]:
-    """合并 graph 绑定的 recursion_limit 与调用方 config。
+    """合并 graph 绑定 config 与调用方 config。
 
-    与 ``create_loop_agent(max_steps=...)`` 经 ``compute_recursion_limit`` 写入 graph 的上限对齐；
-    ``caller`` 中的同名字段可覆盖。
+    保留 graph 上通过 ``with_config`` 绑定的全部 LangGraph config（如
+    ``configurable`` / ``metadata``），同时让 ``caller`` 的同名字段覆盖。
+    对于 ``metadata`` 与 ``configurable`` 这两个嵌套 dict，采用浅合并，
+    避免调用方仅传部分字段时整体替换 graph 绑定值。
     """
     bound_raw = getattr(graph, "config", None)
-    bound: dict[str, Any] = bound_raw if isinstance(bound_raw, dict) else {}
-    limit = bound.get("recursion_limit", 9_999)
-    merged = build_agent_config(recursion_limit=limit)
-    if caller:
-        merged.update(caller)
+    bound: dict[str, Any] = dict(bound_raw) if isinstance(bound_raw, dict) else {}
+    bound.setdefault("recursion_limit", DEFAULT_RECURSION_LIMIT)
+    if not caller:
+        return bound
+    merged = dict(bound)
+    merged.update(caller)
+    if isinstance(bound.get("metadata"), dict) and isinstance(caller.get("metadata"), dict):
+        merged["metadata"] = {**bound["metadata"], **caller["metadata"]}
+    if isinstance(bound.get("configurable"), dict) and isinstance(caller.get("configurable"), dict):
+        merged["configurable"] = {**bound["configurable"], **caller["configurable"]}
     return merged
 
 

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/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/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/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/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/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__ = []