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

langchain_agentx/observability/trace/event_emitter.py

@@ -0,0 +1,183 @@
+"""event_emitter.py — OOP 统一事件发射器。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Optional
+
+if TYPE_CHECKING:
+    from .collector import TraceCollector
+
+
+@dataclass
+class TraceEventEmitter:
+    """Loop 节点事件发射器（面向对象）。"""
+
+    collector: "TraceCollector"
+    session_id: str
+
+    def emit_loop_decision_event(
+        self,
+        *,
+        decision: str,
+        selected_edge: str,
+        reason_code: str,
+        evidence: dict[str, Any],
+        node: str = "loop_controller",
+    ) -> str:
+        return self.collector.emit_event(
+            session_id=self.session_id,
+            event_type="loop.decision",
+            payload={
+                "node": node,
+                "decision": decision,
+                "selected_edge": selected_edge,
+                "reason_code": reason_code,
+                "reason_text": _reason_code_to_text(reason_code),
+                "evidence": evidence,
+            },
+        )
+
+    def emit_task_event(
+        self,
+        *,
+        event_type: str,
+        batch_id: str,
+        command_ids: list[str],
+        **kwargs: Any,
+    ) -> str:
+        return self.collector.emit_event(
+            session_id=self.session_id,
+            event_type=event_type,
+            payload={
+                "batch_id": batch_id,
+                "command_ids": command_ids,
+                **kwargs,
+            },
+        )
+
+    @classmethod
+    def from_state(cls, state: dict[str, Any]) -> Optional["TraceEventEmitter"]:
+        collector = _get_collector_from_state(state)
+        session_id = state.get("_run_id")
+        if not collector or not session_id:
+            return None
+        return cls(collector=collector, session_id=session_id)
+
+
+def emit_loop_decision_event(
+    state: dict[str, Any],
+    decision: str,
+    selected_edge: str,
+    reason_code: str,
+    evidence: dict[str, Any],
+) -> None:
+    """
+    采集 loop.decision 事件。
+
+    Args:
+        state: Agent state（需包含 _trace_collector 和 _run_id）
+        decision: 决策类型（continue/call_tools/terminal/task_reconcile）
+        selected_edge: 选中的下一跳节点名
+        reason_code: 机器可读原因码（枚举）
+        evidence: 决策依据（结构化字段）
+
+    Example:
+        >>> emit_loop_decision_event(
+        ...     state=state,
+        ...     decision="call_tools",
+        ...     selected_edge="tools",
+        ...     reason_code="pending_tool_calls",
+        ...     evidence={"pending_tool_calls": 2, "step": 4},
+        ... )
+    """
+    emitter = TraceEventEmitter.from_state(state)
+    if emitter is None:
+        return
+    emitter.emit_loop_decision_event(
+        decision=decision,
+        selected_edge=selected_edge,
+        reason_code=reason_code,
+        evidence=evidence,
+    )
+
+
+def emit_task_event(
+    state: dict[str, Any],
+    event_type: str,
+    batch_id: str,
+    command_ids: list[str],
+    **kwargs: Any,
+) -> None:
+    """
+    采集 task.reserve/ack 事件。
+
+    Args:
+        state: Agent state
+        event_type: 事件类型（task.reserve / task.ack）
+        batch_id: 批次 ID
+        command_ids: 命令 ID 列表
+        **kwargs: 其他字段（如 attachment_count）
+
+    Example:
+        >>> emit_task_event(
+        ...     state=state,
+        ...     event_type="task.reserve",
+        ...     batch_id="batch-123",
+        ...     command_ids=["cmd-1", "cmd-2"],
+        ...     attachment_count=2,
+        ... )
+    """
+    emitter = TraceEventEmitter.from_state(state)
+    if emitter is None:
+        return
+    emitter.emit_task_event(
+        event_type=event_type,
+        batch_id=batch_id,
+        command_ids=command_ids,
+        **kwargs,
+    )
+
+
+def _get_collector_from_state(state: dict[str, Any]) -> Optional["TraceCollector"]:
+    """
+    从 state 获取 collector。
+
+    Args:
+        state: Agent state
+
+    Returns:
+        TraceCollector 实例，如果不存在则返回 None
+
+    Note:
+        优雅降级：collector 不存在时返回 None，调用方应检查并跳过采集。
+    """
+    return state.get("_trace_collector")
+
+
+def _reason_code_to_text(reason_code: str) -> str:
+    """
+    将 reason_code 转换为人可读文本。
+
+    Args:
+        reason_code: 机器可读原因码
+
+    Returns:
+        人可读说明文本
+    """
+    reason_text_map = {
+        "middleware_jump_to": "Middleware requested jump",
+        "max_steps_force_final": "Max steps reached, forcing final response",
+        "should_end_terminal": "Loop decided to terminate",
+        "pending_tool_calls": "Tool calls pending execution",
+        "pending_task_notifications": "Task notifications pending",
+        "no_tools_and_not_continue": "No tools to call and not continuing",
+    }
+    return reason_text_map.get(reason_code, reason_code)
+
+
+__all__ = [
+    "TraceEventEmitter",
+    "emit_loop_decision_event",
+    "emit_task_event",
+]

langchain_agentx/observability/trace/hook_event_emitter.py

@@ -0,0 +1,49 @@
+"""
+hook_event_emitter.py — Hook 执行记录写入 TraceCollector（Phase 3）。
+
+职责：
+    接收 HookExecutionRecord 并写入 collector，供后续查询 hook_id/skip_reason/snapshot_id。
+
+链路位置：
+    HookEngine 执行后（或 HookGraphWiring）调用本发射器。
+
+当前裁剪范围：
+    仅处理结构化 record，不负责 Hook 执行或策略决策。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from langchain_agentx.loop.hook.types import HookExecutionRecord
+
+from .collector import TraceCollector
+
+
+@dataclass
+class HookEventEmitter:
+    """Hook 执行记录发射器。"""
+
+    collector: TraceCollector
+
+    def emit_record(self, session_id: str, record: HookExecutionRecord) -> str:
+        return self.collector.emit_event(
+            session_id=session_id,
+            event_type="hook.execution",
+            payload={
+                "hook_id": record.hook_id,
+                "hook_event": record.hook_event,
+                "hook_source": record.hook_source,
+                "matcher": record.matcher,
+                "matched": record.matched,
+                "skip_reason": record.skip_reason,
+                "snapshot_id": record.snapshot_id,
+                "policy_source": record.policy_source,
+                "outcome": record.outcome,
+                "prevent_continuation": record.prevent_continuation,
+                "duration_ms": record.duration_ms,
+            },
+        )
+
+
+__all__ = ["HookEventEmitter"]

langchain_agentx/observability/trace/models.py

@@ -0,0 +1,144 @@
+"""
+Trace 数据模型。
+
+职责：
+- 定义 TraceSession（一次 Agent 运行）
+- 定义 TraceSpan（一次操作）
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+from enum import Enum
+
+
+class SpanType(str, Enum):
+    """Span 类型枚举"""
+    AGENT_RUN = "agent_run"
+    LOOP_STEP = "loop_step"
+    LLM_CALL = "llm_call"
+    TOOL_CALL = "tool_call"
+    HOOK_EXEC = "hook_exec"
+    EXIT_LOGIC = "exit_logic"
+    COMPACTION = "compaction"
+    LOOP_DECISION = "loop_decision"
+    TASK_EVENT = "task_event"
+
+
+class SpanStatus(str, Enum):
+    """Span 状态"""
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+
+@dataclass
+class TraceSpan:
+    """一次操作的 trace span"""
+    
+    span_id: str
+    session_id: str
+    parent_span_id: Optional[str]
+    span_type: SpanType
+    name: str
+    start_time: float
+    end_time: Optional[float] = None
+    latency_ms: Optional[float] = None
+    status: SpanStatus = SpanStatus.RUNNING
+    input_data: Optional[Dict[str, Any]] = None
+    output_data: Optional[Dict[str, Any]] = None
+    error: Optional[str] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """转换为字典（用于 JSON 序列化）"""
+        return {
+            "span_id": self.span_id,
+            "session_id": self.session_id,
+            "parent_span_id": self.parent_span_id,
+            "span_type": self.span_type.value if isinstance(self.span_type, SpanType) else self.span_type,
+            "name": self.name,
+            "start_time": self.start_time,
+            "end_time": self.end_time,
+            "latency_ms": self.latency_ms,
+            "status": self.status.value if isinstance(self.status, SpanStatus) else self.status,
+            "input_data": self.input_data,
+            "output_data": self.output_data,
+            "error": self.error,
+            "metadata": self.metadata,
+        }
+
+
+@dataclass
+class TraceSession:
+    """一次 Agent 运行的 trace session"""
+    
+    session_id: str
+    user_query: Optional[str]
+    graph_name: str
+    start_time: float
+    conversation_session_id: str = ""
+    parent_session_id: Optional[str] = None       # 父 run 的 session_id（子 Agent 场景）
+    parent_tool_call_id: Optional[str] = None     # 触发本子 Agent 的 tool_call_id
+    workflow_id: Optional[str] = None             # Workflow 聚合标识
+    unit_type: str = "main_loop"                  # main_loop / subagent / background
+    container_type: str = "agent_session"         # agent_session / conversation / workflow / background
+    origin: str = "user"                          # user / tool / system
+    visibility: str = "default"                   # default / hidden / summary_only
+    end_time: Optional[float] = None
+    status: str = "running"
+    finish_reason: Optional[str] = None
+    exit_code: Optional[str] = None
+    terminal_reason: Optional[str] = None
+    loop_count: int = 0
+    total_input_tokens: int = 0
+    total_output_tokens: int = 0
+    total_latency_ms: float = 0.0
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """转换为字典（用于 JSON 序列化）"""
+        return {
+            "session_id": self.session_id,
+            "conversation_session_id": self.conversation_session_id,
+            "parent_session_id": self.parent_session_id,
+            "parent_tool_call_id": self.parent_tool_call_id,
+            "workflow_id": self.workflow_id,
+            "unit_type": self.unit_type,
+            "container_type": self.container_type,
+            "origin": self.origin,
+            "visibility": self.visibility,
+            "user_query": self.user_query,
+            "graph_name": self.graph_name,
+            "start_time": self.start_time,
+            "end_time": self.end_time,
+            "status": self.status,
+            "finish_reason": self.finish_reason,
+            "exit_code": self.exit_code,
+            "terminal_reason": self.terminal_reason,
+            "loop_count": self.loop_count,
+            "total_input_tokens": self.total_input_tokens,
+            "total_output_tokens": self.total_output_tokens,
+            "total_latency_ms": self.total_latency_ms,
+            "metadata": self.metadata,
+        }
+
+
+@dataclass
+class SessionBuffer:
+    """Session 的内存缓冲区（flush 前暂存）"""
+    
+    session: TraceSession
+    spans: List[TraceSpan] = field(default_factory=list)
+    span_stack: List[str] = field(default_factory=list)  # 用于追踪当前 span 栈
+    next_seq_no: int = 1  # run 内事件顺序号（单调递增）
+    
+    def add_span(self, span: TraceSpan) -> None:
+        """添加 span"""
+        self.spans.append(span)
+    
+    def get_span(self, span_id: str) -> Optional[TraceSpan]:
+        """根据 span_id 获取 span"""
+        for span in self.spans:
+            if span.span_id == span_id:
+                return span
+        return None