langchain-agentx-python 1.2.3__py3-none-any.whl → 1.2.6__py3-none-any.whl

langchain_agentx/__init__.py

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

langchain_agentx/loop/config/loop_config.py

@@ -43,13 +43,13 @@ class PromptConfig:
         - QueryParams.systemPrompt → system
         - options.customSystemPrompt → override_system
         - options.appendSystemPrompt → append_system
-        - options.thinkingConfig → thinking_enabled
+        - options.thinkingConfig → thinking_generation_enabled
     """
     system: str | SystemMessage | None = None
     override_system: str | None = None
     append_system: str | None = None
     dynamic_sections: tuple[SystemPromptSection, ...] = ()
-    thinking_enabled: bool = True  # 是否启用 thinking（对齐 CC thinkingConfig）
+    thinking_generation_enabled: bool = True  # 是否启用 request-side thinking 生成（对齐 CC thinkingConfig）
 
 
 @dataclass(frozen=True)

langchain_agentx/loop/config/thinking_config.py

@@ -6,7 +6,7 @@
 
 链路位置：
     SubagentOrchestrator → ThinkingConfig.from_subagent_mode() →
-    SubagentContext.thinking_enabled → AgentLoopConfig
+    SubagentContext.thinking_generation_enabled → AgentLoopConfig
 
 当前裁剪范围：
     v1 基础实现：mode 驱动启用/禁用；预留父配置覆盖路径。
@@ -63,7 +63,7 @@ class ThinkingConfig:
         Args:
             mode: Subagent 模式 ("plain" | "fork" | "coordinate")
             parent_thinking_config: 父 ThinkingConfig 或 dict（优先于 mode 规则）
-            parent_thinking_enabled: 父 ToolExecutionContext.thinking_enabled（fork/coordinate 继承）
+            parent_thinking_enabled: 父 ToolExecutionContext.thinking_generation_enabled（fork/coordinate 继承）
 
         Returns:
             ThinkingConfig 实例

langchain_agentx/loop/config/ui_display_context.py

@@ -23,7 +23,7 @@ class UiDisplayContext:
 
     is_transcript_mode: bool = False
     verbose: bool = False
-    thinking_enabled: bool | None = None
+    show_thinking: bool | None = None
 
     @classmethod
     def from_mapping(cls, raw: Mapping[str, Any] | None) -> UiDisplayContext | None:
@@ -31,12 +31,12 @@ class UiDisplayContext:
             return None
         is_transcript = bool(raw.get("is_transcript_mode", False))
         verbose = bool(raw.get("verbose", False))
-        thinking_raw = raw.get("thinking_enabled")
-        thinking_enabled = None if thinking_raw is None else bool(thinking_raw)
+        show_thinking_raw = raw.get("show_thinking")
+        show_thinking = None if show_thinking_raw is None else bool(show_thinking_raw)
         return cls(
             is_transcript_mode=is_transcript,
             verbose=verbose,
-            thinking_enabled=thinking_enabled,
+            show_thinking=show_thinking,
         )
 
     @classmethod

langchain_agentx/loop/exit/__init__.py

@@ -1,5 +1,6 @@
 """LangChain AgentX 退出语义与状态字段。"""
 
+from .query_source import QuerySource
 from .resolution import (
     ContinueResolution,
     LoopResolution,
@@ -10,6 +11,7 @@ from .resolution import (
 from .terminal import LoopTerminal, build_loop_terminal
 
 __all__ = [
+    "QuerySource",
     "ContinueResolution",
     "LoopResolution",
     "TerminalResolution",

langchain_agentx/loop/graph/factory.py

@@ -64,6 +64,7 @@ from ..model.model_nodes import make_model_nodes
 from ..context import default_loop_context_compaction
 from ..context.settings import CompactionSettings
 from ..injection.dedup import filter_attachment_dicts_by_task_command_id
+from ..message_contract import to_record
 from ..model.tool_call_degradation_corrector import (
     ToolCallDegradationCorrector,
     _build_allowed_tool_names_for_degradation_correction,
@@ -302,7 +303,7 @@ def _flatten_config_for_runtime(config: AgentLoopConfig) -> _FlatLoopConfig:
         model_profile_registry=config.model_profile_registry,
         compact_buffer_tokens=config.compact_buffer_tokens,
         max_output_tokens_reserved=config.max_output_tokens_reserved,
-        thinking_enabled=config.prompt.thinking_enabled,
+        thinking_generation_enabled=config.prompt.thinking_generation_enabled,
     )
 
 
@@ -955,7 +956,7 @@ class LoopGraphBuilder:
         if not memory_attachments:
             return patch
         messages = list(patch.get("messages") or state.get("messages") or [])
-        messages.extend(memory_attachments)
+        messages.extend(to_record(m) for m in memory_attachments)
         patch = dict(patch)
         patch["messages"] = messages
         return patch
@@ -1545,7 +1546,7 @@ class LoopGraphBuilder:
                 # 冻结契约：task 通知附件仅经本节点注入；按 command_id 与已有 messages 去重
                 # （见 docs/design-docs/loop/agent-loop/post-tools-injection-contract.md）
                 to_attach = filter_attachment_dicts_by_task_command_id(
-                    messages, list(batch.attachment_messages)
+                    messages, [to_record(m) for m in batch.attachment_messages]
                 )
                 messages.extend(to_attach)
                 emit_task_event(

langchain_agentx/loop/message_contract.py

@@ -0,0 +1,72 @@
+"""Loop 级消息契约公开入口（re-export façade）。
+
+职责：
+    对外稳定 import 路径；内部实现位于 ``loop.messages`` 包（contract / validate /
+    langgraph_adapter / transcript_codec）。
+
+链路位置：
+    subagent · session · memory recoverable 边界 → 本模块 → loop.messages.*
+
+当前裁剪范围：
+    Phase 4 已拆包；LangGraph 为当前唯一 engine adapter；第二引擎仅预留 Protocol。
+"""
+
+from langchain_agentx.loop.messages.contract import (
+    LoopMessageContract,
+    build_engine_input,
+    from_transcript_row,
+    get_message_contract,
+    to_engine_message,
+    to_record,
+    to_transcript_row,
+    to_transcript_tool_row,
+    validate_record,
+)
+from langchain_agentx.loop.messages.engine_protocol import EngineMessageAdapter
+from langchain_agentx.loop.messages.langgraph_adapter import LangGraphMessageAdapter
+from langchain_agentx.loop.messages.normalizer import MessageRecordNormalizer
+from langchain_agentx.loop.messages.transcript_codec import TranscriptCodec
+from langchain_agentx.loop.messages.types import (
+    EngineName,
+    MessageSurface,
+    PROVIDER_EXTENSIONS_KEY,
+    REASONING_CONTENT_KEY,
+    RECORD_CLASS_KEY,
+    RecordClass,
+    SYNTHETIC_TRANSCRIPT_TOOL_ID_PREFIX,
+    ValidationResult,
+    is_observational_record,
+    is_synthetic_transcript_tool_id,
+    merge_provider_extensions,
+    normalize_role,
+)
+from langchain_agentx.loop.messages.validate import MessageRecordValidator
+
+__all__ = [
+    "EngineMessageAdapter",
+    "EngineName",
+    "LangGraphMessageAdapter",
+    "LoopMessageContract",
+    "MessageRecordNormalizer",
+    "MessageRecordValidator",
+    "MessageSurface",
+    "PROVIDER_EXTENSIONS_KEY",
+    "REASONING_CONTENT_KEY",
+    "RECORD_CLASS_KEY",
+    "RecordClass",
+    "SYNTHETIC_TRANSCRIPT_TOOL_ID_PREFIX",
+    "TranscriptCodec",
+    "ValidationResult",
+    "build_engine_input",
+    "from_transcript_row",
+    "get_message_contract",
+    "is_observational_record",
+    "is_synthetic_transcript_tool_id",
+    "merge_provider_extensions",
+    "normalize_role",
+    "to_engine_message",
+    "to_record",
+    "to_transcript_row",
+    "to_transcript_tool_row",
+    "validate_record",
+]

langchain_agentx/loop/messages/__init__.py

@@ -0,0 +1,63 @@
+"""loop.messages — Message Contract 内部分层（contract / validate / adapter / codec）。
+
+职责：
+    实现 loop 级 message contract 内部分层；对外稳定入口为 ``loop.message_contract``。
+
+链路位置：
+    subagent · session · memory · workflow recoverable 边界经 façade 间接使用本包。
+
+当前裁剪范围：
+    consumer 禁止直接 import adapter/codec；仅 contract 测试与 package 内互引用允许。
+"""
+
+from langchain_agentx.loop.messages.contract import (
+    LoopMessageContract,
+    build_engine_input,
+    from_transcript_row,
+    get_message_contract,
+    to_engine_message,
+    to_record,
+    to_transcript_row,
+    to_transcript_tool_row,
+    validate_record,
+)
+from langchain_agentx.loop.messages.langgraph_adapter import LangGraphMessageAdapter
+from langchain_agentx.loop.messages.normalizer import MessageRecordNormalizer
+from langchain_agentx.loop.messages.transcript_codec import TranscriptCodec
+from langchain_agentx.loop.messages.types import (
+    EngineName,
+    MessageSurface,
+    RECORD_CLASS_KEY,
+    RecordClass,
+    SYNTHETIC_TRANSCRIPT_TOOL_ID_PREFIX,
+    ValidationResult,
+    is_observational_record,
+    is_synthetic_transcript_tool_id,
+    normalize_role,
+)
+from langchain_agentx.loop.messages.validate import MessageRecordValidator
+
+__all__ = [
+    "EngineName",
+    "LangGraphMessageAdapter",
+    "LoopMessageContract",
+    "MessageRecordNormalizer",
+    "MessageRecordValidator",
+    "MessageSurface",
+    "RECORD_CLASS_KEY",
+    "RecordClass",
+    "SYNTHETIC_TRANSCRIPT_TOOL_ID_PREFIX",
+    "TranscriptCodec",
+    "ValidationResult",
+    "build_engine_input",
+    "from_transcript_row",
+    "get_message_contract",
+    "is_observational_record",
+    "is_synthetic_transcript_tool_id",
+    "normalize_role",
+    "to_engine_message",
+    "to_record",
+    "to_transcript_row",
+    "to_transcript_tool_row",
+    "validate_record",
+]

langchain_agentx/loop/messages/contract.py

@@ -0,0 +1,194 @@
+"""LoopMessageContract façade 与模块级便捷 API。
+
+职责：
+    组合 normalizer / validator / transcript_codec / engine adapter，对外提供 loop 级契约 API。
+
+链路位置：
+    ``loop.message_contract`` re-export 本模块；consumer 应经 façade 调用，不直接依赖 adapter。
+
+当前裁剪范围：
+    仅 LangGraph engine；``EngineMessageAdapter`` 协议预留第二引擎，本阶段不实现。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from langchain_core.messages import BaseMessage
+
+from langchain_agentx.loop.messages.langgraph_adapter import LangGraphMessageAdapter
+from langchain_agentx.loop.messages.normalizer import MessageRecordNormalizer
+from langchain_agentx.loop.messages.transcript_codec import TranscriptCodec
+from langchain_agentx.loop.messages.types import EngineName, MessageSurface, ValidationResult
+from langchain_agentx.loop.messages.validate import MessageRecordValidator
+
+
+class LoopMessageContract:
+    """Loop 级消息契约 owner（对外 façade）。"""
+
+    def __init__(self) -> None:
+        self._normalizer = MessageRecordNormalizer()
+        self._validator = MessageRecordValidator()
+        self._codec = TranscriptCodec(self._normalizer, self._validator)
+        self._adapters: dict[EngineName, LangGraphMessageAdapter] = {
+            "langgraph": LangGraphMessageAdapter(self._normalizer),
+        }
+
+    def to_record(
+        self,
+        msg: Any,
+        *,
+        surface: MessageSurface = MessageSurface.RECOVERABLE,
+    ) -> dict[str, Any]:
+        """归一化为 canonical record；surface 仅作调用方语义标记，不在此步抛错。"""
+        del surface
+        return self._normalizer.to_record(msg)
+
+    def validate(
+        self,
+        record: dict[str, Any],
+        *,
+        surface: MessageSurface,
+    ) -> ValidationResult:
+        normalized = self._normalizer.normalize_dict(record)
+        return self._validator.validate(normalized, surface=surface)
+
+    def to_engine_message(
+        self,
+        record: dict[str, Any],
+        *,
+        engine: EngineName = "langgraph",
+    ) -> BaseMessage:
+        adapter = self._adapters.get(engine)
+        if adapter is None:
+            raise ValueError(f"unsupported engine adapter: {engine!r}")
+        return adapter.to_engine_message(record)
+
+    def build_engine_input(
+        self,
+        records: list[Any],
+        *,
+        surface: MessageSurface = MessageSurface.RECOVERABLE,
+        engine: EngineName = "langgraph",
+    ) -> list[BaseMessage]:
+        messages: list[BaseMessage] = []
+        for item in records:
+            if isinstance(item, BaseMessage):
+                messages.append(item)
+                continue
+            record = (
+                item
+                if isinstance(item, dict) and item.get("role")
+                else self._normalizer.to_record(item)
+            )
+            result = self._validator.validate(record, surface=surface)
+            if not result.ok or result.record is None:
+                raise ValueError(result.error or "invalid message record")
+            messages.append(self.to_engine_message(result.record, engine=engine))
+        return messages
+
+    def to_transcript_row(self, record: dict[str, Any]) -> dict[str, Any]:
+        return self._codec.to_transcript_row(record)
+
+    def to_transcript_tool_row(
+        self,
+        *,
+        content: str,
+        tool_call_id: str,
+        name: str,
+        synthetic: bool = False,
+    ) -> dict[str, Any]:
+        return self._codec.to_transcript_tool_row(
+            content=content,
+            tool_call_id=tool_call_id,
+            name=name,
+            synthetic=synthetic,
+        )
+
+    def from_transcript_row(
+        self,
+        row: dict[str, Any],
+        *,
+        surface: MessageSurface = MessageSurface.RECOVERABLE,
+    ) -> dict[str, Any]:
+        return self._codec.from_transcript_row(row, surface=surface)
+
+
+_default_contract = LoopMessageContract()
+
+
+def get_message_contract() -> LoopMessageContract:
+    return _default_contract
+
+
+def to_record(
+    msg: Any,
+    *,
+    surface: MessageSurface = MessageSurface.RECOVERABLE,
+) -> dict[str, Any]:
+    return _default_contract.to_record(msg, surface=surface)
+
+
+def validate_record(
+    record: dict[str, Any],
+    *,
+    surface: MessageSurface,
+) -> ValidationResult:
+    return _default_contract.validate(record, surface=surface)
+
+
+def to_engine_message(
+    record: dict[str, Any],
+    *,
+    engine: EngineName = "langgraph",
+) -> BaseMessage:
+    return _default_contract.to_engine_message(record, engine=engine)
+
+
+def build_engine_input(
+    records: list[Any],
+    *,
+    surface: MessageSurface = MessageSurface.RECOVERABLE,
+    engine: EngineName = "langgraph",
+) -> list[BaseMessage]:
+    return _default_contract.build_engine_input(records, surface=surface, engine=engine)
+
+
+def from_transcript_row(
+    row: dict[str, Any],
+    *,
+    surface: MessageSurface = MessageSurface.RECOVERABLE,
+) -> dict[str, Any]:
+    return _default_contract.from_transcript_row(row, surface=surface)
+
+
+def to_transcript_tool_row(
+    *,
+    content: str,
+    tool_call_id: str,
+    name: str,
+    synthetic: bool = False,
+) -> dict[str, Any]:
+    return _default_contract.to_transcript_tool_row(
+        content=content,
+        tool_call_id=tool_call_id,
+        name=name,
+        synthetic=synthetic,
+    )
+
+
+def to_transcript_row(record: dict[str, Any]) -> dict[str, Any]:
+    return _default_contract.to_transcript_row(record)
+
+
+__all__ = [
+    "LoopMessageContract",
+    "build_engine_input",
+    "from_transcript_row",
+    "get_message_contract",
+    "to_engine_message",
+    "to_record",
+    "to_transcript_row",
+    "to_transcript_tool_row",
+    "validate_record",
+]

langchain_agentx/loop/messages/engine_protocol.py

@@ -0,0 +1,29 @@
+"""Engine adapter 协议：canonical record ↔ 执行引擎消息（Phase 4 预留第二引擎）。
+
+职责：
+    ``EngineMessageAdapter`` Protocol 定义 engine 边界；当前仅 LangGraph 实现。
+
+链路位置：
+    contract 通过 ``_adapters`` 字典按 ``EngineName`` 选择 adapter。
+
+当前裁剪范围：
+    协议仅声明 ``to_engine_message``；不绑定 LangChain 具体消息类型。
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+from langchain_agentx.loop.messages.types import EngineName
+
+
+class EngineMessageAdapter(Protocol):
+    """执行引擎边界 adapter；当前仅 LangGraph 实现。"""
+
+    engine: EngineName
+
+    def to_engine_message(self, record: dict[str, Any]) -> Any:
+        """Canonical record → engine-native message object."""
+
+
+__all__ = ["EngineMessageAdapter"]

langchain_agentx/loop/messages/langgraph_adapter.py

@@ -0,0 +1,116 @@
+"""LangGraph / LangChain BaseMessage adapter（当前唯一 engine 实现）。
+
+职责：
+    canonical record → ``HumanMessage`` / ``AIMessage`` / ``ToolMessage`` 等 BaseMessage。
+
+链路位置：
+    contract.to_engine_message / build_engine_input 的 LangGraph 边界 adapter。
+
+当前裁剪范围：
+    user/assistant 多模态 content 透传；tool 使用 block-aware string 序列化（非裸 ``str(list)``）。
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from langchain_core.messages import AIMessage, BaseMessage, HumanMessage, SystemMessage, ToolMessage
+
+from langchain_agentx.loop.messages.normalizer import MessageRecordNormalizer
+from langchain_agentx.loop.messages.types import EngineName, PROVIDER_EXTENSIONS_KEY, REASONING_CONTENT_KEY
+
+
+def _engine_content(content: Any) -> str | list[Any]:
+    """LangChain BaseMessage 接受 str 或多模态 block list；其余标量转 str。"""
+    if isinstance(content, list):
+        return content
+    if isinstance(content, str):
+        return content
+    if content is None:
+        return ""
+    return str(content)
+
+
+def _tool_content_for_engine(content: Any) -> str:
+    """ToolMessage 需要 string body；list/dict 做 block-aware 序列化，避免 silent str(list) 塌缩。"""
+    if isinstance(content, str):
+        return content
+    if content is None:
+        return ""
+    if isinstance(content, list):
+        parts: list[str] = []
+        for block in content:
+            if isinstance(block, dict):
+                block_type = block.get("type")
+                if block_type == "text":
+                    text = block.get("text")
+                    if isinstance(text, str) and text:
+                        parts.append(text)
+                elif block_type == "thinking":
+                    thinking = block.get("thinking")
+                    if isinstance(thinking, str) and thinking:
+                        parts.append(thinking)
+                else:
+                    parts.append(json.dumps(block, ensure_ascii=False))
+            elif block is not None:
+                parts.append(str(block))
+        if parts:
+            return "\n".join(parts)
+        return json.dumps(content, ensure_ascii=False)
+    if isinstance(content, dict):
+        return json.dumps(content, ensure_ascii=False)
+    return str(content)
+
+
+class LangGraphMessageAdapter:
+    """Canonical record → LangChain BaseMessage。"""
+
+    engine: EngineName = "langgraph"
+
+    def __init__(self, normalizer: MessageRecordNormalizer) -> None:
+        self._normalizer = normalizer
+
+    def to_engine_message(self, record: dict[str, Any]) -> BaseMessage:
+        normalized = self._normalizer.normalize_dict(record)
+        role = normalized["role"]
+        content = _engine_content(normalized.get("content", ""))
+
+        if role == "user":
+            return HumanMessage(content=content)
+        if role == "assistant":
+            additional_kwargs: dict[str, Any] = {}
+            extensions = normalized.get(PROVIDER_EXTENSIONS_KEY)
+            if isinstance(extensions, dict):
+                rc = extensions.get(REASONING_CONTENT_KEY)
+                if isinstance(rc, str) and rc:
+                    additional_kwargs[REASONING_CONTENT_KEY] = rc
+            return AIMessage(
+                content=content,
+                tool_calls=list(normalized.get("tool_calls") or []),
+                additional_kwargs=additional_kwargs or {},
+            )
+        if role == "system":
+            return SystemMessage(content=content)
+        if role == "tool":
+            tool_call_id = normalized.get("tool_call_id")
+            if not isinstance(tool_call_id, str) or not tool_call_id:
+                raise ValueError(
+                    "tool message record missing tool_call_id; "
+                    "cannot convert to LangGraph ToolMessage / add_messages"
+                )
+            name = str(normalized.get("name") or "tool")
+            status = normalized.get("status")
+            kwargs: dict[str, Any] = {
+                "content": _tool_content_for_engine(normalized.get("content", "")),
+                "tool_call_id": tool_call_id,
+                "name": name,
+            }
+            if isinstance(status, str) and status:
+                kwargs["status"] = status
+            return ToolMessage(**kwargs)
+
+        return HumanMessage(content=content)
+
+
+__all__ = ["LangGraphMessageAdapter"]