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

langchain_agentx/observability/__init__.py

@@ -0,0 +1,67 @@
+"""可观测性：事件适配、trace 存储与 replay 能力。"""
+
+from .events import (
+    EventAdapterState,
+    LangchainAgentEvent,
+    LangchainAgentEventType,
+    LangGraphToLangchainAgentEventAdapter,
+)
+from .replay.service import (
+    export_call_chain,
+    list_replayable_tool_calls,
+    query_replays,
+    replay_tool_call,
+    tail_tool_call_events,
+    visualize_call_chain_mermaid,
+)
+from .replay.store import (
+    DECISION_LAYERS,
+    OBS_SCHEMA_VERSION,
+    REASON_CODES,
+    get_global_trace_store,
+    sample_events,
+    sanitize_value,
+)
+from .logging import (
+    DebugBurstController,
+    DebugBurstSession,
+    LogContext,
+    LoggingConfigBuilder,
+    ObservabilityLoggerAdapter,
+    build_log_context,
+    configure_logging_once,
+)
+from .trace import (
+    TraceCollector,
+    TraceSession,
+    TraceSpan,
+)
+
+__all__ = [
+    "EventAdapterState",
+    "DECISION_LAYERS",
+    "DebugBurstController",
+    "DebugBurstSession",
+    "LogContext",
+    "LoggingConfigBuilder",
+    "OBS_SCHEMA_VERSION",
+    "ObservabilityLoggerAdapter",
+    "build_log_context",
+    "configure_logging_once",
+    "LangchainAgentEvent",
+    "LangchainAgentEventType",
+    "LangGraphToLangchainAgentEventAdapter",
+    "REASON_CODES",
+    "export_call_chain",
+    "get_global_trace_store",
+    "list_replayable_tool_calls",
+    "query_replays",
+    "replay_tool_call",
+    "sample_events",
+    "sanitize_value",
+    "tail_tool_call_events",
+    "TraceCollector",
+    "TraceSession",
+    "TraceSpan",
+    "visualize_call_chain_mermaid",
+]

langchain_agentx/observability/evaluation/__init__.py

@@ -0,0 +1,17 @@
+"""评估系统导出。"""
+
+from .checkers.base import BaseChecker, CheckResult
+from .retention_scheduler import RetentionScheduler
+from .service import EvaluationService
+from .state import AnalysisState
+from .store import DiagnosticReport, EvaluationStore
+
+__all__ = [
+    "EvaluationService",
+    "EvaluationStore",
+    "DiagnosticReport",
+    "RetentionScheduler",
+    "AnalysisState",
+    "BaseChecker",
+    "CheckResult",
+]

langchain_agentx/observability/evaluation/checkers/__init__.py

@@ -0,0 +1,18 @@
+"""内置 Checker 导出。"""
+
+from .base import BaseChecker, CheckResult
+from .compaction import CompactionChecker
+from .degradation import DegradationChecker
+from .exit_quality import ExitQualityChecker
+from .session_memory import SessionMemoryTriggerChecker
+from .tool_behavior import ToolBehaviorChecker
+
+__all__ = [
+    "BaseChecker",
+    "CheckResult",
+    "SessionMemoryTriggerChecker",
+    "CompactionChecker",
+    "ToolBehaviorChecker",
+    "ExitQualityChecker",
+    "DegradationChecker",
+]

langchain_agentx/observability/evaluation/checkers/base.py

@@ -0,0 +1,34 @@
+"""
+checkers/base.py — Checker 基类与 CheckResult 数据模型。
+
+职责：
+    定义所有 Checker 的统一接口契约和结果数据结构。
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+from ...trace.models import TraceSession, TraceSpan
+
+
+@dataclass
+class CheckResult:
+    checker_name: str
+    status: Literal["pass", "fail", "warn", "skip"]
+    message: str
+    evidence: dict[str, Any] = field(default_factory=dict)
+
+
+class BaseChecker(ABC):
+    name: str
+    description: str
+
+    @abstractmethod
+    def check(self, session: TraceSession, spans: list[TraceSpan]) -> CheckResult:
+        """执行单项检查并返回结果。"""
+
+
+__all__ = ["BaseChecker", "CheckResult"]

langchain_agentx/observability/evaluation/checkers/compaction.py

@@ -0,0 +1,38 @@
+"""CompactionChecker — 检查上下文压缩是否按预期执行。"""
+
+from __future__ import annotations
+
+from ...trace.models import SpanStatus, SpanType, TraceSession, TraceSpan
+from .base import BaseChecker, CheckResult
+
+_LOOP_COUNT_THRESHOLD = 20
+
+
+class CompactionChecker(BaseChecker):
+    name = "compaction"
+    description = "检查上下文压缩是否按预期执行"
+
+    def check(self, session: TraceSession, spans: list[TraceSpan]) -> CheckResult:
+        compaction_spans = [span for span in spans if span.span_type == SpanType.COMPACTION]
+
+        if session.loop_count > _LOOP_COUNT_THRESHOLD and not compaction_spans:
+            return CheckResult(
+                self.name,
+                "warn",
+                f"loop_count={session.loop_count} 但无 compaction span",
+                evidence={"loop_count": session.loop_count},
+            )
+
+        failed = [span for span in compaction_spans if span.status == SpanStatus.FAILED]
+        if failed:
+            return CheckResult(
+                self.name,
+                "fail",
+                "compaction 执行失败",
+                evidence={"error": failed[0].error},
+            )
+
+        return CheckResult(self.name, "pass", "compaction 正常")
+
+
+__all__ = ["CompactionChecker"]

langchain_agentx/observability/evaluation/checkers/degradation.py

@@ -0,0 +1,50 @@
+"""DegradationChecker — 检查 tool_call 退化情况。"""
+
+from __future__ import annotations
+
+from ...trace.models import SpanType, TraceSession, TraceSpan
+from .base import BaseChecker, CheckResult
+
+_DEGRADATION_RATE_THRESHOLD = 0.2
+
+
+class DegradationChecker(BaseChecker):
+    name = "degradation"
+    description = "检查 tool_call 退化率"
+
+    def check(self, session: TraceSession, spans: list[TraceSpan]) -> CheckResult:
+        del session
+        llm_spans = [span for span in spans if span.span_type == SpanType.LLM_CALL]
+        if not llm_spans:
+            return CheckResult(self.name, "skip", "无 LLM 调用记录")
+
+        degraded: list[TraceSpan] = []
+        for span in llm_spans:
+            degradation_meta = (span.metadata or {}).get("degradation")
+            if isinstance(degradation_meta, dict):
+                if bool(degradation_meta.get("detected")):
+                    degraded.append(span)
+            elif degradation_meta is True:
+                degraded.append(span)
+        rate = len(degraded) / len(llm_spans)
+
+        if rate > _DEGRADATION_RATE_THRESHOLD:
+            tool_dist: dict[str, int] = {}
+            for span in degraded:
+                raw_tools = (span.metadata or {}).get("tool_names")
+                if isinstance(raw_tools, list) and raw_tools:
+                    tool_name = str(raw_tools[0])
+                else:
+                    tool_name = str((span.metadata or {}).get("tool_name", "unknown"))
+                tool_dist[tool_name] = tool_dist.get(tool_name, 0) + 1
+            return CheckResult(
+                self.name,
+                "fail",
+                f"tool_call 退化率 {rate:.0%} 超过阈值",
+                evidence={"degradation_rate": rate, "tool_distribution": tool_dist},
+            )
+
+        return CheckResult(self.name, "pass", "退化率正常")
+
+
+__all__ = ["DegradationChecker"]

langchain_agentx/observability/evaluation/checkers/exit_quality.py

@@ -0,0 +1,42 @@
+"""ExitQualityChecker — 检查 session 退出质量。"""
+
+from __future__ import annotations
+
+from ...trace.models import TraceSession, TraceSpan
+from .base import BaseChecker, CheckResult
+
+
+class ExitQualityChecker(BaseChecker):
+    name = "exit_quality"
+    description = "检查 session 退出质量"
+
+    def check(self, session: TraceSession, spans: list[TraceSpan]) -> CheckResult:
+        del spans
+        reason = session.finish_reason
+
+        if reason == "error":
+            return CheckResult(
+                self.name,
+                "fail",
+                "session 以 error 退出",
+                evidence={"terminal_reason": session.terminal_reason},
+            )
+        if reason == "max_steps":
+            return CheckResult(
+                self.name,
+                "warn",
+                "session 触发 max_steps 退出，可能 loop 卡住",
+                evidence={"loop_count": session.loop_count},
+            )
+        if reason == "end_turn":
+            return CheckResult(self.name, "pass", "session 正常退出")
+
+        return CheckResult(
+            self.name,
+            "skip",
+            f"未知 finish_reason: {reason}",
+            evidence={"finish_reason": reason},
+        )
+
+
+__all__ = ["ExitQualityChecker"]

langchain_agentx/observability/evaluation/checkers/session_memory.py

@@ -0,0 +1,45 @@
+"""SessionMemoryTriggerChecker — 检查 session memory 是否在应触发时触发。"""
+
+from __future__ import annotations
+
+from ...trace.models import SpanStatus, SpanType, TraceSession, TraceSpan
+from .base import BaseChecker, CheckResult
+
+_FIRST_TRIGGER_TOKENS = 10_000
+
+
+class SessionMemoryTriggerChecker(BaseChecker):
+    name = "session_memory_trigger"
+    description = "检查 session memory 是否在应触发时触发"
+
+    def check(self, session: TraceSession, spans: list[TraceSpan]) -> CheckResult:
+        if session.total_input_tokens < _FIRST_TRIGGER_TOKENS:
+            return CheckResult(self.name, "skip", "token 未达首次触发阈值")
+
+        memory_spans = [
+            span
+            for span in spans
+            if span.span_type == SpanType.TASK_EVENT and span.name == "session_memory_extraction"
+        ]
+
+        if not memory_spans:
+            return CheckResult(
+                self.name,
+                "fail",
+                "应触发 session memory 但无对应 span",
+                evidence={"total_input_tokens": session.total_input_tokens},
+            )
+
+        failed = [span for span in memory_spans if span.status == SpanStatus.FAILED]
+        if failed:
+            return CheckResult(
+                self.name,
+                "warn",
+                f"{len(failed)} 次 session memory 抽取失败",
+                evidence={"failed_spans": [span.span_id for span in failed]},
+            )
+
+        return CheckResult(self.name, "pass", "session memory 触发正常")
+
+
+__all__ = ["SessionMemoryTriggerChecker"]

langchain_agentx/observability/evaluation/checkers/tool_behavior.py

@@ -0,0 +1,53 @@
+"""ToolBehaviorChecker — 检查工具调用是否符合契约。"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+
+from ...trace.models import SpanStatus, SpanType, TraceSession, TraceSpan
+from .base import BaseChecker, CheckResult
+
+_FAIL_RATE_THRESHOLD = 0.3
+_CONSECUTIVE_FAIL_THRESHOLD = 3
+
+
+class ToolBehaviorChecker(BaseChecker):
+    name = "tool_behavior"
+    description = "检查工具调用失败率与连续失败"
+
+    def check(self, session: TraceSession, spans: list[TraceSpan]) -> CheckResult:
+        del session  # 与统一签名保持一致，当前 checker 不依赖 session 聚合字段。
+        tool_spans = [span for span in spans if span.span_type == SpanType.TOOL_CALL]
+        if not tool_spans:
+            return CheckResult(self.name, "skip", "无工具调用")
+
+        failed = [span for span in tool_spans if span.status == SpanStatus.FAILED]
+        fail_rate = len(failed) / len(tool_spans)
+
+        if fail_rate > _FAIL_RATE_THRESHOLD:
+            return CheckResult(
+                self.name,
+                "fail",
+                f"工具调用失败率 {fail_rate:.0%} 超过阈值",
+                evidence={"fail_rate": fail_rate, "total": len(tool_spans), "failed": len(failed)},
+            )
+
+        consecutive: dict[str, int] = defaultdict(int)
+        for span in tool_spans:
+            tool_name = str((span.metadata or {}).get("tool_name", "unknown"))
+            if span.status == SpanStatus.FAILED:
+                consecutive[tool_name] += 1
+                if consecutive[tool_name] >= _CONSECUTIVE_FAIL_THRESHOLD:
+                    return CheckResult(
+                        self.name,
+                        "fail",
+                        f"工具 {tool_name} 连续失败 {consecutive[tool_name]} 次",
+                        evidence={"tool_name": tool_name, "consecutive_fails": consecutive[tool_name]},
+                    )
+            else:
+                consecutive[tool_name] = 0
+
+        return CheckResult(self.name, "pass", "工具调用行为正常")
+
+
+__all__ = ["ToolBehaviorChecker"]

langchain_agentx/observability/evaluation/retention_scheduler.py

@@ -0,0 +1,67 @@
+"""
+evaluation/retention_scheduler.py — 诊断存储清理调度器。
+
+职责：
+    以固定周期执行 trace session 分层保留策略清理，避免数据库无限增长。
+
+链路位置：
+    FastAPI lifespan -> RetentionScheduler.start()。
+
+当前裁剪范围：
+    仅清理 trace_sessions/trace_spans。SDK 已提供 ``EvaluationStore.cleanup_old_reports``（OB-D10），本模块 **仍不** 调用；诊断报告时间清理仅由显式 ``TraceCleanupTask(... cleanup_diagnostic_reports=True)`` 等路径触发。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+
+from langchain_agentx.observability.trace.sqlite_store import SqliteTraceStore
+
+logger = logging.getLogger(__name__)
+
+
+class RetentionScheduler:
+    """按周期执行 session retention 清理任务。"""
+
+    def __init__(
+        self,
+        *,
+        trace_store: SqliteTraceStore,
+        interval_seconds: int = 24 * 3600,
+        failed_days: int = 180,
+        normal_days: int = 30,
+    ) -> None:
+        self._trace_store = trace_store
+        self._interval_seconds = int(interval_seconds)
+        self._failed_days = int(failed_days)
+        self._normal_days = int(normal_days)
+        self._task: asyncio.Task | None = None
+
+    def start(self) -> None:
+        if self._task is None or self._task.done():
+            self._task = asyncio.create_task(self._loop())
+
+    def stop(self) -> None:
+        if self._task is not None:
+            self._task.cancel()
+            self._task = None
+
+    async def _loop(self) -> None:
+        while True:
+            await asyncio.sleep(self._interval_seconds)
+            try:
+                deleted = self._trace_store.cleanup_sessions_by_retention(
+                    failed_days=self._failed_days,
+                    normal_days=self._normal_days,
+                )
+                logger.info(
+                    "RetentionScheduler cleanup done deleted=%s failed_days=%s normal_days=%s",
+                    deleted,
+                    self._failed_days,
+                    self._normal_days,
+                )
+            except asyncio.CancelledError:
+                raise
+            except Exception:
+                logger.exception("RetentionScheduler cleanup failed")

langchain_agentx/observability/evaluation/service.py

@@ -0,0 +1,102 @@
+"""
+evaluation/service.py — EvaluationService，评估系统入口。
+
+职责：
+    接收 session_end 信号，拉取 spans，逐个跑 Checker，并将结果写入 EvaluationStore。
+
+链路位置：
+    由 after_session_end hook 触发（fire-and-forget），不阻塞主 Loop。
+
+当前裁剪范围：
+    LlmDiagnosticAnalyzer 仅保留触发位，暂不实现诊断正文生成。
+"""
+
+from __future__ import annotations
+
+import logging
+
+from ..trace.collector import TraceCollector
+from .checkers.base import BaseChecker, CheckResult
+from .checkers.compaction import CompactionChecker
+from .checkers.degradation import DegradationChecker
+from .checkers.exit_quality import ExitQualityChecker
+from .checkers.session_memory import SessionMemoryTriggerChecker
+from .checkers.tool_behavior import ToolBehaviorChecker
+from .store import EvaluationStore
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_CHECKERS: list[BaseChecker] = [
+    SessionMemoryTriggerChecker(),
+    CompactionChecker(),
+    ToolBehaviorChecker(),
+    ExitQualityChecker(),
+    DegradationChecker(),
+]
+
+
+class EvaluationService:
+    """评估系统入口。评估失败需静默降级，不影响主 Loop。"""
+
+    def __init__(
+        self,
+        store: EvaluationStore,
+        trace_collector: TraceCollector,
+        checkers: list[BaseChecker] | None = None,
+        scheduler: object | None = None,
+    ) -> None:
+        self._store = store
+        self._collector = trace_collector
+        self._checkers = checkers if checkers is not None else list(_DEFAULT_CHECKERS)
+        self._scheduler = scheduler
+
+    async def on_session_end(self, session_id: str) -> None:
+        """after_session_end hook 回调入口。"""
+        try:
+            await self._evaluate(session_id)
+        except Exception:
+            logger.exception("EvaluationService: session %s 评估失败，静默降级", session_id)
+
+    async def _evaluate(self, session_id: str) -> None:
+        # flush() 在 on_session_end 触发前已清除内存 buffer，
+        # 改为通过 get_session/get_span_tree 读取（先查内存，再查 SQLite）。
+        session = self._collector.get_session(session_id)
+        if session is None:
+            logger.debug("EvaluationService: session %s 无 trace 数据，跳过", session_id)
+            return
+
+        spans = self._collector.get_span_tree(session_id)
+        results: list[CheckResult] = []
+        for checker in self._checkers:
+            try:
+                results.append(checker.check(session, spans))
+            except Exception:
+                logger.exception("Checker %s 执行异常，跳过", checker.name)
+
+        if session.status == "interrupted":
+            results.append(
+                CheckResult(
+                    checker_name="session_interrupted",
+                    status="fail",
+                    message=f"Session 异常中断：{session.terminal_reason or 'unknown'}",
+                    evidence={
+                        "status": session.status,
+                        "terminal_reason": session.terminal_reason,
+                    },
+                )
+            )
+
+        self._store.save_results(session_id, results)
+        fails = [result for result in results if result.status == "fail"]
+        if fails:
+            logger.debug(
+                "EvaluationService: session %s 有 %d 个 fail，待 LlmDiagnosticAnalyzer 分析",
+                session_id,
+                len(fails),
+            )
+            enqueue = getattr(self._scheduler, "enqueue_priority", None)
+            if callable(enqueue):
+                enqueue(session_id)
+
+
+__all__ = ["EvaluationService"]

langchain_agentx/observability/evaluation/state.py

@@ -0,0 +1,32 @@
+"""
+evaluation/state.py — 诊断分析共享状态。
+
+职责：
+    维护正在分析的 session 集合，协调“手动触发”和“后台轮询”避免重复分析。
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+
+class AnalysisState:
+    """手动触发与后台调度共享的分析互斥状态。"""
+
+    def __init__(self) -> None:
+        self._in_progress: set[str] = set()
+        self._lock = asyncio.Lock()
+
+    async def try_acquire(self, session_id: str) -> bool:
+        async with self._lock:
+            if session_id in self._in_progress:
+                return False
+            self._in_progress.add(session_id)
+            return True
+
+    async def release(self, session_id: str) -> None:
+        async with self._lock:
+            self._in_progress.discard(session_id)
+
+    def is_in_progress(self, session_id: str) -> bool:
+        return session_id in self._in_progress