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

langchain_agentx/tools/bash/observability.py

@@ -0,0 +1,148 @@
+"""
+tools/bash/observability.py — BashRuntimeTool 可观测性协议与多端投影器
+
+目标：
+    - 标准化 decision trace / execution events schema（P1）
+    - 统一 trace_context（thread/run/tool_call）
+    - 供 UI/CLI/日志消费者做稳定投影（Phase 5）
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import Any
+
+from langchain_agentx.tool_runtime.models import ToolExecutionContext
+from langchain_agentx.observability.replay.store import (
+    DECISION_LAYERS,
+    REASON_CODES,
+    sample_events,
+    sanitize_value,
+)
+
+SCHEMA_VERSION = "bash-observability/v1"
+
+
+@dataclass(frozen=True)
+class TraceContext:
+    thread_id: str | None
+    run_id: str | None
+    tool_call_id: str | None
+    tool_name: str | None
+
+    @classmethod
+    def from_ctx(cls, ctx: ToolExecutionContext) -> "TraceContext":
+        return cls(
+            thread_id=ctx.thread_id,
+            run_id=ctx.run_id,
+            tool_call_id=ctx.tool_call_id,
+            tool_name=ctx.tool_name,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "thread_id": self.thread_id,
+            "run_id": self.run_id,
+            "tool_call_id": self.tool_call_id,
+            "tool_name": self.tool_name,
+        }
+
+
+class BashEventBuffer:
+    """最小事件流缓冲：提供 seq + ts_ms + event。"""
+
+    def __init__(self, *, trace_context: TraceContext, scenario: str) -> None:
+        self._trace_context = trace_context
+        self._scenario = scenario
+        self._seq = 0
+        self._events: list[dict[str, Any]] = []
+
+    def add(self, event: str, **payload: Any) -> None:
+        self._seq += 1
+        self._events.append(
+            {
+                "seq": self._seq,
+                "ts_ms": int(time.time() * 1000),
+                "event": event,
+                **payload,
+            }
+        )
+
+    def to_observability(self) -> dict[str, Any]:
+        return {
+            "schema_version": SCHEMA_VERSION,
+            "scenario": self._scenario,
+            "trace_context": self._trace_context.to_dict(),
+            "events": self._events,
+        }
+
+
+def build_decision_observability(
+    *,
+    trace: list[dict[str, Any]],
+    trace_context: TraceContext,
+) -> dict[str, Any]:
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "decision_layer_dict": sorted(DECISION_LAYERS),
+        "trace_context": trace_context.to_dict(),
+        "decision_trace": trace,
+    }
+
+
+def finalize_observability_payload(
+    payload: dict[str, Any],
+    *,
+    sample_limit: int = 200,
+) -> dict[str, Any]:
+    cleaned = sanitize_value(payload)
+    events = cleaned.get("events")
+    if isinstance(events, list):
+        cleaned["events"] = sample_events(events, limit=sample_limit)
+    cleaned.setdefault("reason_code_dict", sorted(REASON_CODES))
+    return cleaned
+
+
+def project_for_cli(observability: dict[str, Any] | None) -> list[str]:
+    if not observability:
+        return []
+    lines: list[str] = []
+    for e in observability.get("events", []):
+        payload = {k: v for k, v in e.items() if k not in {"seq", "event", "ts_ms"}}
+        lines.append(
+            f"[{e.get('seq')}] {e.get('event')} ts={e.get('ts_ms')} payload={payload}"
+        )
+    return lines
+
+
+def project_for_ui(observability: dict[str, Any] | None) -> list[dict[str, Any]]:
+    if not observability:
+        return []
+    cards: list[dict[str, Any]] = []
+    for e in observability.get("events", []):
+        cards.append(
+            {
+                "type": "runtime_event",
+                "title": e.get("event"),
+                "seq": e.get("seq"),
+                "ts_ms": e.get("ts_ms"),
+                "payload": {k: v for k, v in e.items() if k not in {"seq", "event", "ts_ms"}},
+            }
+        )
+    return cards
+
+
+def project_for_log(
+    *,
+    observability: dict[str, Any] | None,
+    decision_trace: list[dict[str, Any]] | None = None,
+) -> dict[str, Any]:
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "trace_context": (observability or {}).get("trace_context"),
+        "scenario": (observability or {}).get("scenario"),
+        "events": (observability or {}).get("events", []),
+        "decision_trace": decision_trace or [],
+    }
+

langchain_agentx/tools/bash/output_utils.py

@@ -0,0 +1,200 @@
+"""
+tools/bash/output_utils.py — BashRuntimeTool 模块5：结果输出辅助能力
+
+职责：
+    承接 Bash 结果展示层里与“输出内容形态”相关的通用处理，避免这些细节继续堆在
+    `tool.py` 或 `result_presenter.py` 中。
+
+在整体链路中的位置：
+    - `invoke()` 之后、`present()` 之前使用
+    - 由 `result_presenter.py` 调用，负责把 stdout 中的特殊输出形态转成结构化结果
+
+当前包含：
+    1. image data URI 检测与解析
+    2. 基于 Pillow 软依赖的可选 resize/downsample
+    3. Bash 图片输出 artifact 构造
+
+与 CC 对照：
+    对应 CC `utils.ts` 中的 `isImageOutput()`、`parseDataUri()`、
+    `resizeShellImageOutput()` 等输出辅助逻辑。
+    当前为基础版：先把图片输出识别、artifact 化和可选缩放立住，不复制完整 UI 层。
+"""
+
+from __future__ import annotations
+
+import base64
+import io
+import re
+from dataclasses import dataclass
+
+from langchain_agentx.tool_runtime.models import ToolArtifact
+
+_IMAGE_DATA_URI_RE = re.compile(
+    r"^data:(image/[a-z0-9.+_-]+);base64,([A-Za-z0-9+/=\s]+)$",
+    re.IGNORECASE,
+)
+
+_MAX_IMAGE_BYTES = 5 * 1024 * 1024
+_MAX_IMAGE_DIMENSION = 2048
+
+
+@dataclass(frozen=True)
+class BashImageArtifact:
+    """图片输出的结构化表示。"""
+
+    artifact: ToolArtifact
+    media_type: str
+    width: int | None = None
+    height: int | None = None
+    size_bytes: int | None = None
+    was_resized: bool = False
+
+
+def is_image_output(content: str) -> bool:
+    """判断 stdout 是否为 image data URI。"""
+    return _IMAGE_DATA_URI_RE.match(content.strip()) is not None
+
+
+def parse_image_data_uri(content: str) -> tuple[str, str] | None:
+    """
+    解析 image data URI，返回 `(media_type, base64_payload)`。
+
+    返回 None 表示不是受支持的 image data URI。
+    """
+    match = _IMAGE_DATA_URI_RE.match(content.strip())
+    if not match:
+        return None
+    return match.group(1), re.sub(r"\s+", "", match.group(2))
+
+
+class BashOutputArtifactBuilder:
+    """
+    Bash 输出 artifact 构造器。
+
+    只负责把 stdout 中的特殊输出识别为结构化 artifact；
+    不负责 summary/hints/payload 的展示语义。
+    """
+
+    def build_image_artifact(self, stdout: str) -> BashImageArtifact | None:
+        parsed = parse_image_data_uri(stdout)
+        if parsed is None:
+            return None
+
+        media_type, payload = parsed
+        try:
+            raw = base64.b64decode(payload, validate=True)
+        except Exception:
+            return None
+
+        optimized = self._maybe_resize_image(raw=raw, media_type=media_type)
+        encoded = base64.b64encode(optimized.data).decode("ascii")
+        data_uri = f"data:{optimized.media_type};base64,{encoded}"
+        return BashImageArtifact(
+            artifact=ToolArtifact(
+                uri=data_uri,
+                media_type=optimized.media_type,
+                description="Image artifact emitted by bash command output",
+            ),
+            media_type=optimized.media_type,
+            width=optimized.width,
+            height=optimized.height,
+            size_bytes=len(optimized.data),
+            was_resized=optimized.was_resized,
+        )
+
+    def _maybe_resize_image(self, *, raw: bytes, media_type: str) -> "_ImageOptimizationResult":
+        """
+        在 Pillow 可用时对图片做轻量压缩/缩放。
+
+        目标不是强依赖图片栈，而是在环境支持时减少超大图片对上下文与后续传输的压力。
+        """
+        try:
+            from PIL import Image  # type: ignore[import]
+        except Exception:
+            return _ImageOptimizationResult(
+                data=raw,
+                media_type=media_type,
+                width=None,
+                height=None,
+                was_resized=False,
+            )
+
+        try:
+            with Image.open(io.BytesIO(raw)) as image:
+                width, height = image.size
+                needs_resize = (
+                    len(raw) > _MAX_IMAGE_BYTES
+                    or max(width, height) > _MAX_IMAGE_DIMENSION
+                )
+                if not needs_resize:
+                    return _ImageOptimizationResult(
+                        data=raw,
+                        media_type=media_type,
+                        width=width,
+                        height=height,
+                        was_resized=False,
+                    )
+
+                resized = image.copy()
+                resized.thumbnail((_MAX_IMAGE_DIMENSION, _MAX_IMAGE_DIMENSION))
+
+                buffer = io.BytesIO()
+                target_format = self._pil_format_for_media_type(media_type)
+                save_kwargs: dict[str, int | bool] = {}
+                if target_format in {"JPEG", "WEBP"}:
+                    save_kwargs = {"quality": 85, "optimize": True}
+                elif target_format == "PNG":
+                    save_kwargs = {"optimize": True}
+
+                resized.save(buffer, format=target_format, **save_kwargs)
+                resized_width, resized_height = resized.size
+                optimized_bytes = buffer.getvalue()
+                optimized_media_type = self._media_type_for_pil_format(
+                    target_format, fallback=media_type
+                )
+                return _ImageOptimizationResult(
+                    data=optimized_bytes,
+                    media_type=optimized_media_type,
+                    width=resized_width,
+                    height=resized_height,
+                    was_resized=True,
+                )
+        except Exception:
+            return _ImageOptimizationResult(
+                data=raw,
+                media_type=media_type,
+                width=None,
+                height=None,
+                was_resized=False,
+            )
+
+    @staticmethod
+    def _pil_format_for_media_type(media_type: str) -> str:
+        media_type = media_type.lower()
+        return {
+            "image/jpeg": "JPEG",
+            "image/jpg": "JPEG",
+            "image/png": "PNG",
+            "image/gif": "GIF",
+            "image/webp": "WEBP",
+        }.get(media_type, "PNG")
+
+    @staticmethod
+    def _media_type_for_pil_format(pil_format: str, *, fallback: str) -> str:
+        return {
+            "JPEG": "image/jpeg",
+            "PNG": "image/png",
+            "GIF": "image/gif",
+            "WEBP": "image/webp",
+        }.get(pil_format.upper(), fallback)
+
+
+@dataclass(frozen=True)
+class _ImageOptimizationResult:
+    """内部图片优化结果。"""
+
+    data: bytes
+    media_type: str
+    width: int | None
+    height: int | None
+    was_resized: bool