langchain-agentx-python 0.1__py3-none-any.whl

langchain_agentx/observability/trace/trace_callback.py

@@ -0,0 +1,295 @@
+"""
+trace_callback.py — LLM/Tool 调用回调采集器（Phase 3）。
+
+职责：
+    基于 LangChain BaseCallbackHandler 采集 llm_call/tool_call latency 与错误归因。
+
+链路位置：
+    factory.compile() -> compiled.with_config({"callbacks": [TraceCallbackHandler(...)]}).
+
+当前裁剪范围：
+    单 run 级回调；不承担 session 生命周期管理。
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+from langchain_core.callbacks import BaseCallbackHandler
+
+from .collector import TraceCollector
+
+
+@dataclass
+class TraceCallbackHandler(BaseCallbackHandler):
+    """LLM/Tool 事件回调到 TraceCollector。"""
+
+    collector: TraceCollector
+    session_id: str
+    capture_llm: bool = True
+    capture_tool: bool = True
+    _llm_spans: dict[str, str] = field(default_factory=dict)
+    _tool_spans: dict[str, str] = field(default_factory=dict)
+    _llm_started_at: dict[str, float] = field(default_factory=dict)
+    _tool_started_at: dict[str, float] = field(default_factory=dict)
+
+    def _ensure_session(self) -> None:
+        if self.collector.has_session(self.session_id):
+            return
+        self.collector.start_session(session_id=self.session_id, graph_name="agent", user_query=None)
+
+    @staticmethod
+    def _llm_name(serialized: dict[str, Any]) -> str:
+        return str(serialized.get("name") or serialized.get("id") or "llm")
+
+    def _start_llm_span(self, *, run_id: Any, name: str, prompt_count: int) -> None:
+        self._ensure_session()
+        span_id = self.collector.span_start(
+            span_type="llm_call",
+            name=name,
+            session_id=self.session_id,
+            input_data={"prompt_count": prompt_count},
+        )
+        key = str(run_id)
+        self._llm_spans[key] = span_id
+        self._llm_started_at[key] = time.time()
+
+    def on_llm_start(self, serialized: dict[str, Any], prompts: list[str], *, run_id: Any, **kwargs: Any) -> None:
+        if not self.capture_llm:
+            return
+        self._start_llm_span(
+            run_id=run_id,
+            name=self._llm_name(serialized),
+            prompt_count=len(prompts),
+        )
+
+    def on_chat_model_start(
+        self,
+        serialized: dict[str, Any],
+        messages: list[list[Any]],
+        *,
+        run_id: Any,
+        **kwargs: Any,
+    ) -> None:
+        """兼容 ChatModel 回调入口，避免 provider 仅触发 chat 路径时漏采集。"""
+        if not self.capture_llm:
+            return
+        # ChatModel 的 messages 是 batch 结构（List[List[BaseMessage]]）
+        prompt_count = len(messages)
+        self._start_llm_span(
+            run_id=run_id,
+            name=self._llm_name(serialized),
+            prompt_count=prompt_count,
+        )
+
+    def on_llm_end(self, response: Any, *, run_id: Any, **kwargs: Any) -> None:
+        if not self.capture_llm:
+            return
+        key = str(run_id)
+        span_id = self._llm_spans.pop(key, None)
+        started_at = self._llm_started_at.pop(key, None)
+        if not span_id:
+            return
+        metadata: dict[str, Any] = self._extract_llm_metadata(response)
+        if started_at is not None:
+            metadata["latency_ms"] = (time.time() - started_at) * 1000
+        self.collector.span_end(span_id=span_id, session_id=self.session_id, metadata=metadata)
+
+    def on_llm_error(self, error: BaseException, *, run_id: Any, **kwargs: Any) -> None:
+        if not self.capture_llm:
+            return
+        key = str(run_id)
+        span_id = self._llm_spans.pop(key, None)
+        self._llm_started_at.pop(key, None)
+        if not span_id:
+            return
+        self.collector.span_end(span_id=span_id, session_id=self.session_id, error=str(error))
+
+    def on_tool_start(self, serialized: dict[str, Any], input_str: str, *, run_id: Any, **kwargs: Any) -> None:
+        if not self.capture_tool:
+            return
+        self._ensure_session()
+        name = str(serialized.get("name") or "tool")
+        input_data, metadata = self._extract_tool_input_and_metadata(input_str=input_str, kwargs=kwargs)
+        span_id = self.collector.span_start(
+            span_type="tool_call",
+            name=name,
+            session_id=self.session_id,
+            input_data=input_data,
+            metadata=metadata,
+        )
+        key = str(run_id)
+        self._tool_spans[key] = span_id
+        self._tool_started_at[key] = time.time()
+
+    def on_tool_end(self, output: Any, *, run_id: Any, **kwargs: Any) -> None:
+        if not self.capture_tool:
+            return
+        key = str(run_id)
+        span_id = self._tool_spans.pop(key, None)
+        started_at = self._tool_started_at.pop(key, None)
+        if not span_id:
+            return
+        metadata: dict[str, Any] = {}
+        if started_at is not None:
+            metadata["latency_ms"] = (time.time() - started_at) * 1000
+        self.collector.span_end(span_id=span_id, session_id=self.session_id, metadata=metadata)
+
+    def on_tool_error(self, error: BaseException, *, run_id: Any, **kwargs: Any) -> None:
+        if not self.capture_tool:
+            return
+        key = str(run_id)
+        span_id = self._tool_spans.pop(key, None)
+        self._tool_started_at.pop(key, None)
+        if not span_id:
+            return
+        self.collector.span_end(span_id=span_id, session_id=self.session_id, error=str(error))
+
+    @staticmethod
+    def _extract_tool_input_and_metadata(*, input_str: str, kwargs: dict[str, Any]) -> tuple[dict[str, Any], dict[str, Any]]:
+        """
+        优先使用 LangChain 回调透传的结构化 inputs，避免把 tool_runtime 等内部对象写入 trace。
+        仅当结构化输入不可用时，回退到 input_str 快照（保留上限防止极端体积）。
+        """
+        metadata: dict[str, Any] = {}
+        raw_inputs = kwargs.get("inputs")
+        if isinstance(raw_inputs, dict):
+            clean_inputs: dict[str, Any] = {}
+            for key, value in raw_inputs.items():
+                # LangGraph 注入运行时对象（ToolRuntime），不属于用户态业务参数。
+                if key == "tool_runtime":
+                    tool_call_id = getattr(value, "tool_call_id", None)
+                    if isinstance(tool_call_id, str) and tool_call_id:
+                        metadata["tool_call_id"] = tool_call_id
+                    continue
+                clean_inputs[key] = value
+
+            if clean_inputs:
+                return clean_inputs, metadata
+
+        # fallback: 历史链路仍可能只提供 input_str。
+        return {"input": input_str[:500]}, metadata
+
+    def _extract_llm_metadata(self, response: Any) -> dict[str, Any]:
+        metadata: dict[str, Any] = {}
+        finish_reason = self._extract_finish_reason(response)
+        if isinstance(finish_reason, str) and finish_reason:
+            metadata["finish_reason"] = finish_reason
+        usage = self._extract_token_usage(response)
+        metadata.update(usage)
+        return metadata
+
+    @staticmethod
+    def _extract_finish_reason(response: Any) -> str | None:
+        first_message = TraceCallbackHandler._extract_first_generation_message(response)
+        if first_message is not None:
+            response_metadata = getattr(first_message, "response_metadata", None)
+            if isinstance(response_metadata, dict):
+                value = response_metadata.get("finish_reason")
+                if isinstance(value, str) and value:
+                    return value
+
+        # ChatModel 常见结构：AIMessage.response_metadata.finish_reason
+        response_metadata = getattr(response, "response_metadata", None)
+        if isinstance(response_metadata, dict):
+            value = response_metadata.get("finish_reason")
+            if isinstance(value, str) and value:
+                return value
+
+        # LLMResult 常见结构：llm_output.finish_reason
+        llm_output = getattr(response, "llm_output", None)
+        if isinstance(llm_output, dict):
+            value = llm_output.get("finish_reason")
+            if isinstance(value, str) and value:
+                return value
+
+        return None
+
+    @staticmethod
+    def _extract_token_usage(response: Any) -> dict[str, int]:
+        first_message = TraceCallbackHandler._extract_first_generation_message(response)
+        if first_message is not None:
+            usage_metadata = getattr(first_message, "usage_metadata", None)
+            if isinstance(usage_metadata, dict):
+                input_tokens = usage_metadata.get("input_tokens")
+                output_tokens = usage_metadata.get("output_tokens")
+                total_tokens = usage_metadata.get("total_tokens")
+                result: dict[str, int] = {}
+                if isinstance(input_tokens, int):
+                    result["input_tokens"] = input_tokens
+                if isinstance(output_tokens, int):
+                    result["output_tokens"] = output_tokens
+                if isinstance(total_tokens, int):
+                    result["total_tokens"] = total_tokens
+                if result:
+                    return result
+
+        # ChatModel 常见结构：AIMessage.usage_metadata
+        usage_metadata = getattr(response, "usage_metadata", None)
+        if isinstance(usage_metadata, dict):
+            input_tokens = usage_metadata.get("input_tokens")
+            output_tokens = usage_metadata.get("output_tokens")
+            total_tokens = usage_metadata.get("total_tokens")
+            result: dict[str, int] = {}
+            if isinstance(input_tokens, int):
+                result["input_tokens"] = input_tokens
+            if isinstance(output_tokens, int):
+                result["output_tokens"] = output_tokens
+            if isinstance(total_tokens, int):
+                result["total_tokens"] = total_tokens
+            if result:
+                return result
+
+        # LLMResult/OpenAI 常见结构：response_metadata.token_usage
+        response_metadata = getattr(response, "response_metadata", None)
+        if isinstance(response_metadata, dict):
+            token_usage = response_metadata.get("token_usage")
+            if isinstance(token_usage, dict):
+                result = {}
+                prompt_tokens = token_usage.get("prompt_tokens")
+                completion_tokens = token_usage.get("completion_tokens")
+                total_tokens = token_usage.get("total_tokens")
+                if isinstance(prompt_tokens, int):
+                    result["input_tokens"] = prompt_tokens
+                if isinstance(completion_tokens, int):
+                    result["output_tokens"] = completion_tokens
+                if isinstance(total_tokens, int):
+                    result["total_tokens"] = total_tokens
+                if result:
+                    return result
+
+        # 部分 LLMResult：response.llm_output.token_usage
+        llm_output = getattr(response, "llm_output", None)
+        if isinstance(llm_output, dict):
+            token_usage = llm_output.get("token_usage")
+            if isinstance(token_usage, dict):
+                result = {}
+                prompt_tokens = token_usage.get("prompt_tokens")
+                completion_tokens = token_usage.get("completion_tokens")
+                total_tokens = token_usage.get("total_tokens")
+                if isinstance(prompt_tokens, int):
+                    result["input_tokens"] = prompt_tokens
+                if isinstance(completion_tokens, int):
+                    result["output_tokens"] = completion_tokens
+                if isinstance(total_tokens, int):
+                    result["total_tokens"] = total_tokens
+                if result:
+                    return result
+
+        return {}
+
+    @staticmethod
+    def _extract_first_generation_message(response: Any) -> Any | None:
+        generations = getattr(response, "generations", None)
+        if not isinstance(generations, list) or not generations:
+            return None
+        first_batch = generations[0]
+        if not isinstance(first_batch, list) or not first_batch:
+            return None
+        first_generation = first_batch[0]
+        return getattr(first_generation, "message", None)
+
+
+__all__ = ["TraceCallbackHandler"]

langchain_agentx/observability/trace/trace_lifecycle_collector.py

@@ -0,0 +1,114 @@
+"""
+trace_lifecycle_collector.py — Loop 图生命周期 Trace 采集（Phase 3）。
+
+职责：
+    在固定 Loop 图节点上采集 loop 生命周期事件，统一写入 TraceCollector。
+
+链路位置：
+    HookGraphWiring(loop_start/before_model/after_model/loop_end) -> TraceLifecycleCollector。
+
+当前裁剪范围：
+    仅覆盖框架内置生命周期节点采集（非 HookRegistry 用户扩展体系）；
+    llm/tool 细粒度调用由 TraceCallbackHandler 负责。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+from uuid import uuid4
+
+from .collector import TraceCollector
+
+
+@dataclass
+class TraceLifecycleCollector:
+    """框架内置生命周期 Trace 采集器，由 HookGraphWiring 调用。"""
+
+    collector: TraceCollector
+    graph_name: str = "agent"
+    default_run_id: str | None = None
+    unit_type: str = "main_loop"
+    container_type: str = "agent_session"
+    origin: str = "user"
+    visibility: str = "default"
+    parent_run_id: str | None = None
+    parent_tool_call_id: str | None = None
+    conversation_session_id: str | None = None
+
+    def loop_start_node(self, state: dict[str, Any]) -> dict[str, Any]:
+        run_id = state.get("_run_id")
+        if not isinstance(run_id, str) or not run_id:
+            run_id = self.default_run_id or uuid4().hex
+        if not self.collector.has_session(run_id):
+            user_query = self._extract_user_query(state)
+            self.collector.start_session(
+                session_id=run_id,
+                graph_name=self.graph_name,
+                user_query=user_query,
+                conversation_session_id=self.conversation_session_id or run_id,
+                parent_session_id=self.parent_run_id,
+                parent_tool_call_id=self.parent_tool_call_id,
+                unit_type=self.unit_type,
+                container_type=self.container_type,
+                origin=self.origin,
+                visibility=self.visibility,
+            )
+        return {"_trace_collector": self.collector, "_run_id": run_id}
+
+    def before_model_node(self, state: dict[str, Any]) -> dict[str, Any]:
+        run_id = state.get("_run_id")
+        if not isinstance(run_id, str) or not run_id or not self.collector.has_session(run_id):
+            return {}
+        span_id = self.collector.span_start(
+            span_type="loop_step",
+            name=f"step_{int(state.get('step', 0) or 0)}",
+            session_id=run_id,
+            metadata={"context_length": len(state.get("messages", []))},
+        )
+        return {"_trace_loop_step_span_id": span_id}
+
+    def after_model_node(self, state: dict[str, Any]) -> dict[str, Any]:
+        run_id = state.get("_run_id")
+        span_id = state.get("_trace_loop_step_span_id")
+        if (
+            not isinstance(run_id, str)
+            or not run_id
+            or not isinstance(span_id, str)
+            or not span_id
+            or not self.collector.has_session(run_id)
+        ):
+            return {}
+        self.collector.span_end(
+            span_id=span_id,
+            session_id=run_id,
+            metadata={"finish_reason": state.get("finish_reason")},
+        )
+        return {"_trace_loop_step_span_id": None}
+
+    def loop_end_node(self, state: dict[str, Any]) -> dict[str, Any]:
+        run_id = state.get("_run_id")
+        if not isinstance(run_id, str) or not run_id or not self.collector.has_session(run_id):
+            return {}
+        self.collector.end_session(
+            session_id=run_id,
+            finish_reason=state.get("finish_reason"),
+            terminal_reason=state.get("terminal_reason"),
+        )
+        return {}
+
+    # A07 文档对齐别名：保留 loop_* 原命名，避免 HookGraphWiring 接线调整。
+    session_start_node = loop_start_node
+    session_end_node = loop_end_node
+
+    @staticmethod
+    def _extract_user_query(state: dict[str, Any]) -> str | None:
+        messages = list(state.get("messages") or [])
+        if not messages:
+            return None
+        first = messages[0]
+        content = getattr(first, "content", None)
+        return str(content)[:200] if isinstance(content, str) else None
+
+
+__all__ = ["TraceLifecycleCollector"]

langchain_agentx/plugin/__init__.py

@@ -0,0 +1,26 @@
+"""
+plugin/__init__.py — Plugin 子系统公共导出。
+
+职责：
+    暴露 Plugin 子系统第一阶段可复用的数据类型与配置读取入口。
+
+链路位置：
+    被 PluginLoader、容器集成层与测试代码统一导入。
+
+当前裁剪范围：
+    仅包含 Phase B 的数据层导出，不含 Loader/Registry 实现。
+"""
+
+from .builtin import BuiltinPluginDefinition, BuiltinPluginRegistry
+from .config import PluginConfig, PluginConfigLoader, RepositoryEntry
+from .types import LoadedPlugin, PluginLoadResult
+
+__all__ = [
+    "BuiltinPluginDefinition",
+    "BuiltinPluginRegistry",
+    "LoadedPlugin",
+    "PluginConfig",
+    "PluginConfigLoader",
+    "PluginLoadResult",
+    "RepositoryEntry",
+]

langchain_agentx/plugin/builtin.py

@@ -0,0 +1,53 @@
+"""
+plugin/builtin.py — 内置插件定义注册表。
+
+职责：
+    维护随框架发布的内置插件定义，并提供全局注册表访问。
+
+链路位置：
+    PluginLoader._discover_builtin() 通过本模块获取内置插件声明。
+
+当前裁剪范围：
+    仅做定义注册与读取，不包含 hooks 实际注册逻辑。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+
+@dataclass(frozen=True)
+class BuiltinPluginDefinition:
+    name: str
+    description: str
+    version: str = "0.1.0"
+    hooks: dict[str, Any] | None = None
+    mcp_servers: dict[str, dict[str, Any]] = field(default_factory=dict)
+    applicable_containers: list[str] = field(default_factory=list)
+    default_enabled: bool = True
+    is_available: Callable[[], bool] | None = None
+
+
+class BuiltinPluginRegistry:
+    """内置插件注册表。"""
+
+    _singleton: "BuiltinPluginRegistry | None" = None
+
+    def __init__(self) -> None:
+        self._definitions: dict[str, BuiltinPluginDefinition] = {}
+
+    def register(self, definition: BuiltinPluginDefinition) -> None:
+        self._definitions[definition.name] = definition
+
+    def all(self) -> list[BuiltinPluginDefinition]:
+        return list(self._definitions.values())
+
+    @classmethod
+    def global_instance(cls) -> "BuiltinPluginRegistry":
+        if cls._singleton is None:
+            cls._singleton = cls()
+        return cls._singleton
+
+
+__all__ = ["BuiltinPluginDefinition", "BuiltinPluginRegistry"]

langchain_agentx/plugin/config.py

@@ -0,0 +1,113 @@
+"""
+plugin/config.py — plugin_config.json 读取与内存表示。
+
+职责：
+    定义 PluginConfig/RepositoryEntry，并提供 PluginConfigLoader 读取配置文件。
+
+链路位置：
+    PluginLoader 在 Discovery 阶段通过本模块读取插件启停状态和仓库坐标。
+
+当前裁剪范围：
+    仅包含读取逻辑，不包含配置写入管理（PluginConfigManager 在后续阶段实现）。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+import json
+import logging
+
+from langchain_agentx.workspace.config import AgentWorkspaceConfig
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class RepositoryEntry:
+    url: str
+    branch: str = "main"
+    commit_sha: str | None = None
+
+
+@dataclass(frozen=True)
+class PluginConfig:
+    """plugin_config.json 的内存表示。"""
+
+    enabled_plugins: dict[str, bool] = field(default_factory=dict)
+    repositories: dict[str, RepositoryEntry] = field(default_factory=dict)
+
+    def is_enabled(self, plugin_id: str, default: bool = True) -> bool:
+        return self.enabled_plugins.get(plugin_id, default)
+
+
+class PluginConfigLoader:
+    """加载 plugin_config.json。"""
+
+    @staticmethod
+    def load(cfg: AgentWorkspaceConfig) -> PluginConfig:
+        config_path = cfg.plugin_config_path
+        if not config_path.exists():
+            return PluginConfig()
+
+        try:
+            raw = json.loads(config_path.read_text(encoding="utf-8"))
+        except json.JSONDecodeError as exc:
+            logger.warning(
+                "plugin config parse failed at %s: %s; fallback to empty config",
+                config_path,
+                exc,
+            )
+            return PluginConfig()
+        except OSError as exc:
+            logger.warning(
+                "plugin config read failed at %s: %s; fallback to empty config",
+                config_path,
+                exc,
+            )
+            return PluginConfig()
+
+        if not isinstance(raw, dict):
+            logger.warning(
+                "plugin config root must be object at %s; fallback to empty config",
+                config_path,
+            )
+            return PluginConfig()
+
+        enabled_plugins = PluginConfigLoader._parse_enabled_plugins(raw)
+        repositories = PluginConfigLoader._parse_repositories(raw)
+        return PluginConfig(enabled_plugins=enabled_plugins, repositories=repositories)
+
+    @staticmethod
+    def _parse_enabled_plugins(raw: dict[str, object]) -> dict[str, bool]:
+        payload = raw.get("enabled_plugins")
+        if not isinstance(payload, dict):
+            return {}
+        parsed: dict[str, bool] = {}
+        for plugin_id, enabled in payload.items():
+            if isinstance(plugin_id, str) and isinstance(enabled, bool):
+                parsed[plugin_id] = enabled
+        return parsed
+
+    @staticmethod
+    def _parse_repositories(raw: dict[str, object]) -> dict[str, RepositoryEntry]:
+        payload = raw.get("repositories")
+        if not isinstance(payload, dict):
+            return {}
+        parsed: dict[str, RepositoryEntry] = {}
+        for name, entry in payload.items():
+            if not isinstance(name, str) or not isinstance(entry, dict):
+                continue
+            url = entry.get("url")
+            if not isinstance(url, str) or not url:
+                continue
+            branch = entry.get("branch")
+            commit_sha = entry.get("commit_sha")
+            parsed[name] = RepositoryEntry(
+                url=url,
+                branch=branch if isinstance(branch, str) and branch else "main",
+                commit_sha=commit_sha if isinstance(commit_sha, str) else None,
+            )
+        return parsed
+
+
+__all__ = ["PluginConfig", "PluginConfigLoader", "RepositoryEntry"]