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

langchain_agentx/observability/logging/__init__.py

@@ -0,0 +1,15 @@
+"""可观测性 logging 子域：配置、上下文契约、Debug Burst。"""
+
+from .debug_burst import DebugBurstController, DebugBurstSession
+from .logging_config import LoggingConfigBuilder, configure_logging_once
+from .logging_contract import LogContext, ObservabilityLoggerAdapter, build_log_context
+
+__all__ = [
+    "DebugBurstController",
+    "DebugBurstSession",
+    "LogContext",
+    "LoggingConfigBuilder",
+    "ObservabilityLoggerAdapter",
+    "build_log_context",
+    "configure_logging_once",
+]

langchain_agentx/observability/logging/debug_burst.py

@@ -0,0 +1,95 @@
+"""
+observability/logging/debug_burst.py — 会话级调试放大控制器
+
+职责：
+    提供 Debug Burst 的短时启停能力：临时提高日志详细度、挂载专用诊断 handler，
+    到期后自动回落，避免长期日志噪音。
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+from .logging_config import LoggingDirectoryResolver
+
+
+@dataclass
+class DebugBurstSession:
+    started_at_ts: float
+    ttl_sec: float
+    level: int
+    scope: str
+    session_id: str | None = None
+    handler: logging.Handler | None = None
+
+    def is_active(self) -> bool:
+        return (time.time() - self.started_at_ts) <= self.ttl_sec
+
+
+class DebugBurstController:
+    """Debug Burst 运行期控制器。"""
+
+    def __init__(
+        self,
+        *,
+        logger_name: str = "langchain_agentx",
+        directory_resolver: LoggingDirectoryResolver | None = None,
+    ) -> None:
+        self._logger = logging.getLogger(logger_name)
+        self._resolver = directory_resolver or LoggingDirectoryResolver()
+        self._session: DebugBurstSession | None = None
+        self._original_level: int | None = None
+
+    def start(
+        self,
+        *,
+        workspace_root: str | Path | None = None,
+        ttl_sec: float = 120.0,
+        level: int = logging.DEBUG,
+        scope: str = "session",
+        session_id: str | None = None,
+    ) -> DebugBurstSession:
+        self.stop()
+        layout = self._resolver.resolve(workspace_root=workspace_root)
+        layout.diagnostics_dir.mkdir(parents=True, exist_ok=True)
+        burst_file = layout.diagnostics_dir / "debug-burst.log"
+        handler = logging.FileHandler(burst_file, encoding="utf-8")
+        handler.setLevel(level)
+        handler.setFormatter(
+            logging.Formatter(
+                "%(asctime)s %(levelname)s %(name)s run_id=%(run_id)s session_id=%(session_id)s "
+                "task_id=%(task_id)s tool_call_id=%(tool_call_id)s agent_id=%(agent_id)s %(message)s"
+            )
+        )
+        self._logger.addHandler(handler)
+        self._original_level = self._logger.level
+        self._logger.setLevel(min(self._logger.level or level, level))
+        self._session = DebugBurstSession(
+            started_at_ts=time.time(),
+            ttl_sec=ttl_sec,
+            level=level,
+            scope=scope,
+            session_id=session_id,
+            handler=handler,
+        )
+        return self._session
+
+    def stop(self) -> None:
+        if self._session is None:
+            return
+        if self._session.handler is not None:
+            self._logger.removeHandler(self._session.handler)
+            self._session.handler.close()
+        if self._original_level is not None:
+            self._logger.setLevel(self._original_level)
+        self._session = None
+        self._original_level = None
+
+    def tick(self) -> None:
+        if self._session is None:
+            return
+        if not self._session.is_active():
+            self.stop()

langchain_agentx/observability/logging/logging_config.py

@@ -0,0 +1,178 @@
+"""
+observability/logging/logging_config.py — Python logging 配置构建协作者
+
+职责：
+    提供 dictConfig 构建与应用入口，统一日志目录、级别、formatter、handler。
+    默认目录：<workspace_root>/workspace（可由 AGENTX_LOG_ROOT 覆盖）。
+
+在整体链路中的位置：
+    进程启动或测试入口
+      -> LoggingConfigBuilder.build_dict_config()
+      -> logging.config.dictConfig(...)
+"""
+
+from __future__ import annotations
+
+import logging
+import logging.config
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from langchain_agentx.workspace import resolve_agent_workspace_config
+
+
+ENV_LOG_ROOT = "AGENTX_LOG_ROOT"
+ENV_LOG_LEVEL = "AGENTX_LOG_LEVEL"
+ENV_LOG_JSON = "AGENTX_LOG_JSON"
+
+
+class _ContextDefaultsFilter(logging.Filter):
+    def filter(self, record: logging.LogRecord) -> bool:
+        for key in ("run_id", "session_id", "task_id", "tool_call_id", "agent_id"):
+            if not hasattr(record, key):
+                setattr(record, key, "-")
+        return True
+
+
+@dataclass(frozen=True)
+class LoggingDirectoryLayout:
+    workspace_root: Path
+    log_root: Path
+    runtime_dir: Path
+    diagnostics_dir: Path
+
+
+class LoggingDirectoryResolver:
+    """日志目录解析器。"""
+
+    def resolve(
+        self,
+        *,
+        workspace_root: str | Path | None = None,
+        log_root: str | Path | None = None,
+    ) -> LoggingDirectoryLayout:
+        workspace_cfg = resolve_agent_workspace_config(workspace_root=workspace_root)
+        ws_root = workspace_cfg.workspace_root
+        root = Path(log_root or os.getenv(ENV_LOG_ROOT) or (ws_root / "workspace"))
+        resolved_root = root.expanduser().resolve()
+        return LoggingDirectoryLayout(
+            workspace_root=ws_root,
+            log_root=resolved_root,
+            runtime_dir=resolved_root / "runtime",
+            diagnostics_dir=resolved_root / "diagnostics",
+        )
+
+
+class LoggingConfigBuilder:
+    """logging dictConfig 构建器。"""
+
+    def __init__(
+        self,
+        *,
+        directory_resolver: LoggingDirectoryResolver | None = None,
+    ) -> None:
+        self._resolver = directory_resolver or LoggingDirectoryResolver()
+
+    def build_dict_config(
+        self,
+        *,
+        workspace_root: str | Path | None = None,
+        log_root: str | Path | None = None,
+        level: str | None = None,
+    ) -> dict[str, Any]:
+        layout = self._resolver.resolve(workspace_root=workspace_root, log_root=log_root)
+        layout.runtime_dir.mkdir(parents=True, exist_ok=True)
+        layout.diagnostics_dir.mkdir(parents=True, exist_ok=True)
+
+        resolved_level = (level or os.getenv(ENV_LOG_LEVEL, "INFO")).upper()
+        use_json = os.getenv(ENV_LOG_JSON, "0") == "1"
+        formatter = (
+            "%(message)s"
+            if use_json
+            else (
+                "%(asctime)s %(levelname)s %(name)s "
+                "run_id=%(run_id)s session_id=%(session_id)s task_id=%(task_id)s "
+                "tool_call_id=%(tool_call_id)s agent_id=%(agent_id)s %(message)s"
+            )
+        )
+        return {
+            "version": 1,
+            "disable_existing_loggers": False,
+            "filters": {
+                "context_defaults": {
+                    "()": _ContextDefaultsFilter,
+                }
+            },
+            "formatters": {
+                "standard": {
+                    "format": formatter,
+                }
+            },
+            "handlers": {
+                "console": {
+                    "class": "logging.StreamHandler",
+                    "level": resolved_level,
+                    "formatter": "standard",
+                    "filters": ["context_defaults"],
+                },
+                "runtime_file": {
+                    "class": "logging.handlers.TimedRotatingFileHandler",
+                    "filename": str(layout.runtime_dir / "app.log"),
+                    "when": "D",
+                    "interval": 1,
+                    "backupCount": 7,
+                    "encoding": "utf-8",
+                    "level": resolved_level,
+                    "formatter": "standard",
+                    "filters": ["context_defaults"],
+                },
+                "error_file": {
+                    "class": "logging.handlers.TimedRotatingFileHandler",
+                    "filename": str(layout.runtime_dir / "error.log"),
+                    "when": "D",
+                    "interval": 1,
+                    "backupCount": 14,
+                    "encoding": "utf-8",
+                    "level": "ERROR",
+                    "formatter": "standard",
+                    "filters": ["context_defaults"],
+                },
+            },
+            "root": {
+                "handlers": ["console", "runtime_file", "error_file"],
+                "level": resolved_level,
+            },
+        }
+
+    def apply(
+        self,
+        *,
+        workspace_root: str | Path | None = None,
+        log_root: str | Path | None = None,
+        level: str | None = None,
+    ) -> None:
+        logging.config.dictConfig(
+            self.build_dict_config(
+                workspace_root=workspace_root,
+                log_root=log_root,
+                level=level,
+            )
+        )
+
+
+_CONFIGURED = False
+
+
+def configure_logging_once(
+    *,
+    workspace_root: str | Path | None = None,
+    log_root: str | Path | None = None,
+    level: str | None = None,
+) -> None:
+    global _CONFIGURED
+    if _CONFIGURED:
+        return
+    LoggingConfigBuilder().apply(workspace_root=workspace_root, log_root=log_root, level=level)
+    _CONFIGURED = True

langchain_agentx/observability/logging/logging_contract.py

@@ -0,0 +1,65 @@
+"""
+observability/logging/logging_contract.py — 日志上下文字段契约协作者
+
+职责：
+    提供统一日志上下文构建与 logger 适配器，确保 run/session/task/tool_call
+    等关联字段在日志层可用，便于与 trace/replay 互相定位。
+
+在整体链路中的位置：
+    业务入口（loop/task_runtime/tools）
+      -> build_log_context(...)
+      -> ObservabilityLoggerAdapter(logger, context)
+      -> logger.info/warning/error(...)
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class LogContext:
+    run_id: str = "-"
+    session_id: str = "-"
+    task_id: str = "-"
+    tool_call_id: str = "-"
+    agent_id: str = "-"
+
+    def as_extra(self) -> dict[str, str]:
+        return {
+            "run_id": self.run_id,
+            "session_id": self.session_id,
+            "task_id": self.task_id,
+            "tool_call_id": self.tool_call_id,
+            "agent_id": self.agent_id,
+        }
+
+
+def build_log_context(
+    *,
+    run_id: str | None = None,
+    session_id: str | None = None,
+    task_id: str | None = None,
+    tool_call_id: str | None = None,
+    agent_id: str | None = None,
+) -> LogContext:
+    return LogContext(
+        run_id=run_id or "-",
+        session_id=session_id or "-",
+        task_id=task_id or "-",
+        tool_call_id=tool_call_id or "-",
+        agent_id=agent_id or "-",
+    )
+
+
+class ObservabilityLoggerAdapter(logging.LoggerAdapter):
+    """在日志记录中注入统一上下文字段。"""
+
+    def process(self, msg: str, kwargs: dict[str, Any]) -> tuple[str, dict[str, Any]]:
+        kwargs.setdefault("extra", {})
+        merged = dict(self.extra or {})
+        merged.update(kwargs["extra"])
+        kwargs["extra"] = merged
+        return msg, kwargs

langchain_agentx/observability/replay/__init__.py

@@ -0,0 +1,35 @@
+"""
+Replay：trace 存储、查询 façade、CLI、UI 投影。
+"""
+
+from .service import (
+    export_call_chain,
+    list_replayable_tool_calls,
+    query_replays,
+    replay_tool_call,
+    tail_tool_call_events,
+    visualize_call_chain_mermaid,
+)
+from .store import (
+    DECISION_LAYERS,
+    OBS_SCHEMA_VERSION,
+    REASON_CODES,
+    get_global_trace_store,
+    sample_events,
+    sanitize_value,
+)
+
+__all__ = [
+    "DECISION_LAYERS",
+    "OBS_SCHEMA_VERSION",
+    "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",
+    "visualize_call_chain_mermaid",
+]

langchain_agentx/observability/replay/cli.py

@@ -0,0 +1,91 @@
+"""
+runtime/observability_cli.py — 可观测性 CLI 适配入口
+
+职责：
+    为命令行场景提供统一回放/查询接口，作为 runtime replay 服务的
+    交互层适配器，支持 list/replay/query 等子命令。
+
+OOP 边界：
+    - CLI 仅负责参数解析与输出渲染；
+    - 业务逻辑委托 `runtime/replay.py`；
+    - 不直接操作存储层（JSONL/gzip）。
+
+与 CC 对比：
+    对齐 CC 在交互排障中的“可查询、可导出、可回放”路径，
+    以标准命令形式提供给运维与开发流程。
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+from pprint import pprint
+
+from .service import (
+    export_call_chain,
+    list_replayable_tool_calls,
+    query_replays,
+    visualize_call_chain_mermaid,
+)
+from ..logging import ObservabilityLoggerAdapter, build_log_context
+
+logger = logging.getLogger(__name__)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="AgentX observability CLI")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    sub.add_parser("list")
+
+    replay_p = sub.add_parser("replay")
+    replay_p.add_argument("--tool-call-id", required=True)
+    replay_p.add_argument("--mermaid", action="store_true")
+
+    query_p = sub.add_parser("query")
+    query_p.add_argument("--tool-name")
+    query_p.add_argument("--status")
+    query_p.add_argument("--start-ts", type=int)
+    query_p.add_argument("--end-ts", type=int)
+    query_p.add_argument("--limit", type=int, default=50)
+
+    args = parser.parse_args()
+    log = ObservabilityLoggerAdapter(logger, build_log_context().as_extra())
+    log.info("replay cli command=%s", args.cmd)
+    if args.cmd == "list":
+        rows = list_replayable_tool_calls()
+        log.info("replay cli list rows=%s", len(rows))
+        pprint(rows)
+        return
+    if args.cmd == "replay":
+        replay_log = ObservabilityLoggerAdapter(
+            logger,
+            build_log_context(tool_call_id=args.tool_call_id).as_extra(),
+        )
+        if args.mermaid:
+            replay_log.info("replay cli export mermaid")
+            print(visualize_call_chain_mermaid(args.tool_call_id))
+        else:
+            replay_log.info("replay cli export call chain")
+            pprint(export_call_chain(args.tool_call_id))
+        return
+    if args.cmd == "query":
+        rows = query_replays(
+            tool_name=args.tool_name,
+            status=args.status,
+            start_ts=args.start_ts,
+            end_ts=args.end_ts,
+            limit=args.limit,
+        )
+        log.info(
+            "replay cli query rows=%s tool_name=%s status=%s",
+            len(rows),
+            args.tool_name or "-",
+            args.status or "-",
+        )
+        pprint(rows)
+
+
+if __name__ == "__main__":
+    main()
+

langchain_agentx/observability/replay/service.py

@@ -0,0 +1,83 @@
+"""
+runtime/replay.py — 运行时观测回放服务接口
+
+职责：
+    提供基于 `tool_call_id` 的回放能力，对外暴露：
+    - 单次调用链查询
+    - 可回放列表
+    - 增量事件 tail（实时轮询）
+    - 条件过滤查询
+    - 导出与可视化（mermaid）
+
+OOP 边界：
+    该模块是 `ObservabilityTraceStore` 的 façade 层，
+    统一封装调用入口，避免业务侧直接依赖底层存储实现。
+
+与 CC 对比：
+    对齐 CC “问题复盘/归因追踪”的使用方式，先提供稳定 API，
+    再逐步演进为更强的可视化与外部系统集成。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .store import get_global_trace_store
+
+
+def replay_tool_call(tool_call_id: str) -> dict[str, Any] | None:
+    """按 tool_call_id 获取最近一次观测记录。"""
+    return get_global_trace_store().get(tool_call_id)
+
+
+def list_replayable_tool_calls() -> list[str]:
+    """列出可回放的 tool_call_id。"""
+    return get_global_trace_store().all_keys()
+
+
+def tail_tool_call_events(tool_call_id: str, offset: int = 0) -> tuple[list[dict[str, Any]], int]:
+    """
+    获取事件增量（用于 UI/CLI 轮询实时展示）。
+    返回 (events, next_offset)。
+    """
+    return get_global_trace_store().tail_events(tool_call_id, offset=offset)
+
+
+def query_replays(
+    *,
+    tool_name: str | None = None,
+    status: str | None = None,
+    start_ts: int | None = None,
+    end_ts: int | None = None,
+    limit: int = 200,
+) -> list[dict[str, Any]]:
+    """按条件查询回放记录。"""
+    return get_global_trace_store().query(
+        tool_name=tool_name,
+        status=status,
+        start_ts=start_ts,
+        end_ts=end_ts,
+        limit=limit,
+    )
+
+
+def export_call_chain(tool_call_id: str) -> dict[str, Any] | None:
+    """一键导出完整调用链（decision_trace + observability events）。"""
+    return replay_tool_call(tool_call_id)
+
+
+def visualize_call_chain_mermaid(tool_call_id: str) -> str:
+    """将调用链导出为简易 mermaid 时序图文本。"""
+    record = replay_tool_call(tool_call_id)
+    if not record:
+        return "sequenceDiagram\n  participant U as User\n  participant T as Tool\n  U->>T: no replay record"
+    lines = ["sequenceDiagram", "  participant U as User", "  participant T as Tool"]
+    for step in record.get("decision_trace", []):
+        lines.append(
+            f"  U->>T: decision {step.get('layer')} / {step.get('behavior')} / {step.get('policy_id')}"
+        )
+    events = (((record.get("observability") or {}).get("events")) or [])
+    for ev in events:
+        lines.append(f"  T-->>U: {ev.get('event')}")
+    return "\n".join(lines)
+