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

langchain_agentx/tools/read/backend.py

@@ -0,0 +1,415 @@
+"""
+tools/read/backend.py — ReadRuntimeTool I/O 后端
+
+职责：
+    封装文件读取的底层 I/O 操作，与工具 hook 逻辑解耦。
+    根据文件扩展名分发到对应的读取方法。
+
+    FileBackend.read() 是总入口，分发规则：
+        .png / .jpg / .jpeg / .gif / .webp → _read_image()
+        .pdf                               → _read_pdf()
+        .ipynb                             → _read_notebook()
+        其他                               → _read_text()
+
+软依赖（懒加载，缺失时给出友好错误）：
+    Pillow (PIL)  — 图片尺寸读取，缺失时 width/height=None
+    pdfplumber    — PDF 文本提取，缺失时返回 error
+    nbformat      — Notebook 解析，缺失时返回 error
+
+对应 CC：
+    _read_image()    → readImageWithTokenBudget() + detectImageFormatFromBuffer()
+    _read_text()     → readFileInRange() + addLineNumbers()
+    _read_pdf()      → pdfplumber（CC 走原生 base64，我们 v1 走文本提取）
+    _read_notebook() → readNotebook()；超限错误提示含 Unix jq 与 Windows PowerShell 示例。
+"""
+
+from __future__ import annotations
+
+import base64
+import os
+import re
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .models import (
+        FileUnchangedOutput,
+        ImageFileOutput,
+        NotebookFileOutput,
+        PDFFileOutput,
+        ReadToolInput,
+        ReadToolOutput,
+        TextFileOutput,
+    )
+
+SUPPORTED_IMAGE_EXTS: frozenset[str] = frozenset({"png", "jpg", "jpeg", "gif", "webp"})
+"""支持读取的图片扩展名（对应 CC IMAGE_EXTENSIONS）。"""
+
+BINARY_EXTENSIONS: frozenset[str] = frozenset({
+    # 可执行文件
+    "exe", "dll", "so", "dylib", "bin", "elf",
+    # 归档
+    "zip", "tar", "gz", "bz2", "xz", "7z", "rar",
+    # 编译产物
+    "o", "a", "class", "pyc", "pyo", "whl",
+    # 媒体（非图片）
+    "mp3", "mp4", "avi", "mov", "mkv", "wav", "flac",
+    # 文档（非 pdf/ipynb）
+    "docx", "xlsx", "pptx", "odt",
+    # 数据库
+    "db", "sqlite", "sqlite3",
+    # 其他
+    "iso", "img", "dmg", "pkg",
+})
+"""非文本、非图片、非 PDF 的二进制扩展名，read 工具拒绝处理。"""
+
+
+# ---------------------------------------------------------------------------
+# 工具函数
+# ---------------------------------------------------------------------------
+
+
+def detect_image_format(data: bytes) -> str:
+    """
+    从文件头 magic bytes 检测图片格式，不信任文件扩展名。
+    对应 CC detectImageFormatFromBuffer()。
+    """
+    if len(data) >= 8 and data[:8] == b"\x89PNG\r\n\x1a\n":
+        return "image/png"
+    if len(data) >= 3 and data[:3] == b"\xff\xd8\xff":
+        return "image/jpeg"
+    if len(data) >= 6 and data[:6] in (b"GIF87a", b"GIF89a"):
+        return "image/gif"
+    if len(data) >= 12 and data[:4] == b"RIFF" and data[8:12] == b"WEBP":
+        return "image/webp"
+    return "image/jpeg"
+
+
+def add_line_numbers(content: str, start_line: int = 1) -> str:
+    """
+    给文本内容加行号，格式与 CC addLineNumbers() 完全一致：
+        '   1\\t<line content>'
+    行号右对齐，占 6 位。
+    """
+    lines = content.splitlines(keepends=True)
+    return "".join(
+        f"{start_line + i:6d}\t{line}"
+        for i, line in enumerate(lines)
+    )
+
+
+def parse_page_range(pages_param: str | None, total_pages: int, limits: dict) -> tuple[int, int]:
+    """
+    解析 PDF pages 参数，返回 (page_start, page_end)（均 1-indexed）。
+
+    支持格式：
+        "3"     → (3, 3)
+        "1-5"   → (1, 5)
+        None    → (1, min(total_pages, pdf_max_pages))
+
+    对应 CC parsePDFPageRange()。
+    """
+    max_pages = limits["pdf_max_pages"]
+    if pages_param is None:
+        return 1, min(total_pages, max_pages)
+
+    m = re.fullmatch(r"(\d+)(?:-(\d+))?", pages_param.strip())
+    if not m:
+        raise ValueError(
+            f'Invalid pages format: "{pages_param}". '
+            f'Use formats like "1-5", "3", or "10-20". Pages are 1-indexed.'
+        )
+
+    start = int(m.group(1))
+    end = int(m.group(2)) if m.group(2) else start
+
+    if start < 1:
+        raise ValueError(f"Page number must be >= 1, got {start}.")
+    if end > total_pages:
+        raise ValueError(
+            f"Page {end} exceeds total pages ({total_pages}) in this PDF."
+        )
+    if start > end:
+        raise ValueError(f"Invalid page range: start ({start}) > end ({end}).")
+    if end - start + 1 > max_pages:
+        raise ValueError(
+            f'Page range "{pages_param}" requests {end - start + 1} pages, '
+            f"exceeds maximum {max_pages} pages per request."
+        )
+
+    return start, end
+
+
+# ---------------------------------------------------------------------------
+# FileBackend
+# ---------------------------------------------------------------------------
+
+
+class FileBackend:
+    """
+    文件读取 I/O 后端，对应 CC imageProcessor.ts 的职责定位。
+
+    read() 是工具 invoke() 的唯一 I/O 入口，负责根据文件类型分发。
+    """
+
+    def read(
+        self,
+        path: str,
+        inp: "ReadToolInput",
+        limits: dict,
+    ) -> "ReadToolOutput":
+        """
+        总入口：根据文件扩展名分发到对应的读取方法。
+        path 已在 normalize_input 中经过 realpath 规范化。
+        """
+        ext = Path(path).suffix.lower().lstrip(".")
+        if ext in SUPPORTED_IMAGE_EXTS:
+            return self._read_image(path, limits)
+        if ext == "pdf":
+            return self._read_pdf(path, inp.pages, limits)
+        if ext == "ipynb":
+            return self._read_notebook(path, limits)
+        return self._read_text(path, inp.offset, inp.limit, limits)
+
+    # ------------------------------------------------------------------
+    # 文本读取
+    # ------------------------------------------------------------------
+
+    def _read_text(
+        self,
+        path: str,
+        offset: int,
+        limit: int | None,
+        limits: dict,
+    ) -> "TextFileOutput":
+        """
+        读取文本文件，返回带行号内容。
+
+        对应 CC readFileInRange() + addLineNumbers()。
+
+        编码策略：
+            先尝试 UTF-8，失败后 Latin-1 fallback（errors='replace'），
+            确保任何文本文件都能读取，不因编码问题崩溃。
+        """
+        from .models import TextFileOutput
+
+        # 读取全部内容（分页在应用层切片）
+        try:
+            with open(path, encoding="utf-8") as f:
+                raw = f.read()
+        except UnicodeDecodeError:
+            with open(path, encoding="latin-1", errors="replace") as f:
+                raw = f.read()
+
+        all_lines = raw.splitlines(keepends=True)
+        total_lines = len(all_lines)
+
+        # 空文件
+        if total_lines == 0:
+            return TextFileOutput(
+                file_path=path,
+                content=(
+                    "<system-reminder>Warning: the file exists but the contents are empty."
+                    "</system-reminder>"
+                ),
+                line_start=0,
+                line_end=0,
+                total_lines=0,
+            )
+
+        # offset 超出文件行数（1-indexed：offset=1 表示第1行）
+        # offset=0 等价于 offset=1
+        effective_offset = max(offset, 1)
+        if effective_offset > total_lines:
+            return TextFileOutput(
+                file_path=path,
+                content=(
+                    f"<system-reminder>Warning: the file exists but is shorter than "
+                    f"the provided offset ({effective_offset}). "
+                    f"The file has {total_lines} lines.</system-reminder>"
+                ),
+                line_start=effective_offset,
+                line_end=effective_offset,
+                total_lines=total_lines,
+            )
+
+        # 切片：offset 1-indexed → 0-indexed
+        start_idx = effective_offset - 1
+        max_lines = limits["max_lines"]
+        effective_limit = min(limit, max_lines) if limit is not None else max_lines
+        end_idx = min(start_idx + effective_limit, total_lines)
+
+        selected = all_lines[start_idx:end_idx]
+        content_raw = "".join(selected)
+
+        # Token 估算检查（chars / 4 ≈ tokens）
+        max_tokens = limits["max_tokens"]
+        estimated_tokens = len(content_raw) // 4
+        if estimated_tokens > max_tokens:
+            raise ValueError(
+                f"File content ({estimated_tokens} estimated tokens) exceeds maximum "
+                f"allowed tokens ({max_tokens}). "
+                f"Use offset and limit parameters to read specific portions of the file."
+            )
+
+        content_with_linenos = add_line_numbers(content_raw, start_line=effective_offset)
+
+        return TextFileOutput(
+            file_path=path,
+            content=content_with_linenos,
+            line_start=effective_offset,
+            line_end=effective_offset + len(selected) - 1,
+            total_lines=total_lines,
+            truncated=(end_idx < total_lines),
+        )
+
+    # ------------------------------------------------------------------
+    # 图片读取
+    # ------------------------------------------------------------------
+
+    def _read_image(self, path: str, limits: dict) -> "ImageFileOutput":
+        """
+        读取图片文件，返回 base64 编码结果。
+        v1：直接 base64，无压缩；v2 补 Pillow resize。
+
+        对应 CC readImageWithTokenBudget()（v1 不做 token 预算压缩）。
+        """
+        from .models import ImageFileOutput
+
+        size = os.path.getsize(path)
+
+        if size == 0:
+            raise ValueError(f"Image file is empty: {path}")
+
+        if size > limits["image_max_bytes"]:
+            raise ValueError(
+                f"Image too large ({size:,} bytes, "
+                f"max {limits['image_max_bytes']:,} bytes)."
+            )
+
+        with open(path, "rb") as f:
+            data = f.read()
+
+        media_type = detect_image_format(data)
+
+        # 尝试获取尺寸（Pillow 软依赖）
+        width: int | None = None
+        height: int | None = None
+        try:
+            from PIL import Image  # type: ignore[import]
+            with Image.open(path) as img:
+                width, height = img.size
+        except ImportError:
+            pass  # Pillow 不可用时跳过尺寸信息
+
+        b64 = base64.b64encode(data).decode("ascii")
+
+        return ImageFileOutput(
+            file_path=path,
+            base64=b64,
+            media_type=media_type,
+            original_size=size,
+            width=width,
+            height=height,
+        )
+
+    # ------------------------------------------------------------------
+    # PDF 读取
+    # ------------------------------------------------------------------
+
+    def _read_pdf(
+        self,
+        path: str,
+        pages_param: str | None,
+        limits: dict,
+    ) -> "PDFFileOutput":
+        """
+        读取 PDF 文件，v1 使用 pdfplumber 提取文本。
+        v2：原生 base64 发送（依赖模型多模态支持）或转图片（依赖 pdf2image）。
+
+        对应 CC extractPDFPages() + parsePDFPageRange()（文本提取路径）。
+        """
+        from .models import PDFFileOutput
+
+        try:
+            import pdfplumber  # type: ignore[import]
+        except ImportError as e:
+            raise ImportError(
+                "PDF reading requires pdfplumber. "
+                "Install with: pip install pdfplumber"
+            ) from e
+
+        with pdfplumber.open(path) as pdf:
+            total_pages = len(pdf.pages)
+
+            # 超页数阈值且未指定 pages 时，强制要求传 pages 参数
+            inline_threshold = limits["pdf_inline_threshold"]
+            if total_pages > inline_threshold and pages_param is None:
+                raise ValueError(
+                    f"This PDF has {total_pages} pages, which is too many to read at once. "
+                    f"Use the pages parameter to read specific page ranges "
+                    f'(e.g. pages="1-5"). '
+                    f"Maximum {limits['pdf_max_pages']} pages per request."
+                )
+
+            page_start, page_end = parse_page_range(pages_param, total_pages, limits)
+
+            texts: list[str] = []
+            for page in pdf.pages[page_start - 1 : page_end]:
+                text = page.extract_text() or ""
+                texts.append(text)
+
+        content = "\n\n--- Page Break ---\n\n".join(texts)
+
+        return PDFFileOutput(
+            file_path=path,
+            content=content,
+            page_start=page_start,
+            page_end=page_end,
+            total_pages=total_pages,
+            truncated=(page_end < total_pages),
+        )
+
+    # ------------------------------------------------------------------
+    # Notebook 读取
+    # ------------------------------------------------------------------
+
+    def _read_notebook(self, path: str, limits: dict) -> "NotebookFileOutput":
+        """
+        读取 Jupyter Notebook 文件，返回所有 cells。
+        对应 CC readNotebook() → cells。
+        """
+        from .models import NotebookFileOutput
+
+        try:
+            import nbformat  # type: ignore[import]
+        except ImportError as e:
+            raise ImportError(
+                "Jupyter notebook reading requires nbformat. "
+                "Install with: pip install nbformat"
+            ) from e
+
+        with open(path, encoding="utf-8") as f:
+            nb = nbformat.read(f, as_version=4)
+
+        # 大小检查（序列化后字节数）
+        json_str = nbformat.writes(nb)
+        byte_size = len(json_str.encode("utf-8"))
+        if byte_size > limits["max_size_bytes"]:
+            qpath = repr(path)
+            raise ValueError(
+                f"Notebook content ({byte_size:,} bytes) exceeds maximum allowed size "
+                f"({limits['max_size_bytes']:,} bytes). "
+                "Slice the notebook JSON with platform-appropriate tooling, for example:\n"
+                f"  Unix / Git Bash: jq '.cells[:20]' {qpath}\n"
+                f"  Windows PowerShell: "
+                f"(Get-Content -Raw -LiteralPath {qpath} | ConvertFrom-Json).cells[0..19]\n"
+                "Or use the Bash tool with jq (where available) or a short Python one-liner."
+            )
+
+        cells = [dict(cell) for cell in nb.cells]
+
+        return NotebookFileOutput(
+            file_path=path,
+            cells=cells,
+        )

langchain_agentx/tools/read/limits.py

@@ -0,0 +1,67 @@
+"""
+tools/read/limits.py — ReadRuntimeTool 上限配置
+
+职责：
+    集中管理 Read 工具所有数值常量和配置读取逻辑。
+    全部支持环境变量覆盖，便于测试 mock 和生产调优。
+
+两层上限设计（对应 CC limits.ts）：
+    max_size_bytes  — 读取前检查文件总大小（stat），低代价，快速 fail
+    max_tokens      — 读取后检查输出 token 数，高代价但精确
+                      v1 用字符数估算（chars / 4 ≈ tokens）
+"""
+
+from __future__ import annotations
+
+import os
+
+# ---------------------------------------------------------------------------
+# 文本读取上限
+# ---------------------------------------------------------------------------
+
+DEFAULT_MAX_LINES = int(os.getenv("READ_TOOL_MAX_LINES", "2000"))
+"""单次最多读取行数（对应 CC MAX_LINES_TO_READ=2000）。"""
+
+DEFAULT_MAX_SIZE_BYTES = int(os.getenv("READ_TOOL_MAX_SIZE_BYTES", str(256 * 1024)))
+"""文件大小上限（字节），超过此值在 validate_input 时 stat 检查拒绝（对应 CC maxSizeBytes=256KB）。"""
+
+DEFAULT_MAX_TOKENS = int(os.getenv("READ_TOOL_MAX_TOKENS", "25000"))
+"""输出 token 数上限（chars / 4 估算），超过时报 MaxFileReadTokenExceededError（对应 CC maxTokens=25000）。"""
+
+DEFAULT_MAX_RESULT_CHARS = DEFAULT_MAX_TOKENS * 4
+"""输出字符上限，约等于 max_tokens 换算。"""
+
+# ---------------------------------------------------------------------------
+# PDF 相关上限
+# ---------------------------------------------------------------------------
+
+PDF_MAX_PAGES_PER_READ = int(os.getenv("READ_TOOL_PDF_MAX_PAGES", "20"))
+"""单次最多读取 PDF 页数（对应 CC PDF_MAX_PAGES_PER_READ=20）。"""
+
+PDF_AT_MENTION_INLINE_THRESHOLD = 10
+"""超过此页数时必须提供 pages 参数（对应 CC PDF_AT_MENTION_INLINE_THRESHOLD=10）。
+不走环境变量，是产品设计决策。"""
+
+# ---------------------------------------------------------------------------
+# 图片相关上限
+# ---------------------------------------------------------------------------
+
+IMAGE_MAX_SIZE_BYTES = int(os.getenv("READ_TOOL_IMAGE_MAX_BYTES", str(20 * 1024 * 1024)))
+"""图片文件大小上限（字节，默认 20MB）。图片有独立上限，不受 max_size_bytes 约束。"""
+
+
+def get_read_limits() -> dict:
+    """
+    返回当前有效配置（支持运行时环境变量覆盖）。
+
+    对应 CC limits.ts 的 getDefaultFileReadingLimits()。
+    """
+    return {
+        "max_lines": DEFAULT_MAX_LINES,
+        "max_size_bytes": DEFAULT_MAX_SIZE_BYTES,
+        "max_tokens": DEFAULT_MAX_TOKENS,
+        "max_result_chars": DEFAULT_MAX_RESULT_CHARS,
+        "pdf_max_pages": PDF_MAX_PAGES_PER_READ,
+        "pdf_inline_threshold": PDF_AT_MENTION_INLINE_THRESHOLD,
+        "image_max_bytes": IMAGE_MAX_SIZE_BYTES,
+    }

langchain_agentx/tools/read/models.py

@@ -0,0 +1,156 @@
+"""
+tools/read/models.py — ReadRuntimeTool 输入输出数据模型
+
+职责：
+    定义 Read 工具的业务级 Input / Output Pydantic 模型。
+    不引入框架级模型（tool_runtime/models.py）；不含 I/O 操作。
+
+输出模型采用 discriminated union（对应 CC outputSchema 的 z.discriminatedUnion）：
+    - TextFileOutput        文本文件读取结果
+    - ImageFileOutput       图片文件读取结果（base64 编码）
+    - PDFFileOutput         PDF 文件读取结果（v1 文本提取路径）
+    - NotebookFileOutput    Jupyter Notebook 读取结果
+    - FileUnchangedOutput   重复读取 dedup stub（对应 CC file_unchanged）
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, Field
+
+
+# ---------------------------------------------------------------------------
+# 输入模型
+# ---------------------------------------------------------------------------
+
+
+class ReadToolInput(BaseModel):
+    """
+    ReadRuntimeTool 输入参数（对应 CC inputSchema）。
+
+    字段说明：
+        file_path  — 文件绝对路径（必须）
+        offset     — 起始行（1-indexed；0 表示从文件头开始）
+        limit      — 最多读取行数（None 表示读到文件末尾或 max_lines 上限）
+        pages      — PDF 专用，页范围如 "1-5"、"3"、"10-20"；非 PDF 文件传此参数报错
+    """
+
+    file_path: str = Field(
+        ...,
+        description="The absolute path to the file to read",
+    )
+    offset: int = Field(
+        0,
+        ge=0,
+        description=(
+            "The line number to start reading from (1-indexed). "
+            "0 means start from the beginning of the file. "
+            "Only provide if the file is too large to read at once."
+        ),
+    )
+    limit: int | None = Field(
+        None,
+        gt=0,
+        description=(
+            "The number of lines to read. "
+            "Only provide if the file is too large to read at once."
+        ),
+    )
+    pages: str | None = Field(
+        None,
+        description=(
+            'Page range for PDF files (e.g. "1-5", "3", "10-20"). '
+            "Only applicable to PDF files. Maximum 20 pages per request."
+        ),
+    )
+
+
+# ---------------------------------------------------------------------------
+# 输出模型（discriminated union by type）
+# ---------------------------------------------------------------------------
+
+
+class TextFileOutput(BaseModel):
+    """文本文件读取结果（含行号格式）。"""
+
+    type: Literal["text"] = "text"
+    file_path: str
+    content: str
+    """带行号的文本内容，格式：'   N\\t<line content>'（对应 CC addLineNumbers()）。"""
+    line_start: int
+    """实际读取起始行（1-indexed）。"""
+    line_end: int
+    """实际读取结束行（1-indexed）。"""
+    total_lines: int
+    """文件总行数。"""
+    truncated: bool = False
+
+
+class ImageFileOutput(BaseModel):
+    """图片文件读取结果（base64 编码，对应 CC type='image'）。"""
+
+    type: Literal["image"] = "image"
+    file_path: str
+    base64: str
+    """base64 编码的图片数据（ASCII 字符串）。"""
+    media_type: str
+    """MIME 类型，如 'image/png'、'image/jpeg'（从 magic bytes 检测）。"""
+    original_size: int
+    """原始文件大小（字节）。"""
+    width: int | None = None
+    """图片宽度（像素，Pillow 可用时填写）。"""
+    height: int | None = None
+    """图片高度（像素，Pillow 可用时填写）。"""
+
+
+class PDFFileOutput(BaseModel):
+    """PDF 文件读取结果（v1：文本提取路径）。"""
+
+    type: Literal["pdf"] = "pdf"
+    file_path: str
+    content: str
+    """提取的文本内容，页间以 '\\n\\n--- Page Break ---\\n\\n' 分隔。"""
+    page_start: int
+    """实际读取起始页（1-indexed）。"""
+    page_end: int
+    """实际读取结束页（1-indexed）。"""
+    total_pages: int
+    """PDF 总页数。"""
+    truncated: bool = False
+    """是否因 pdf_max_pages 限制而未读完所有页。"""
+
+
+class NotebookFileOutput(BaseModel):
+    """Jupyter Notebook 读取结果（对应 CC type='notebook'）。"""
+
+    type: Literal["notebook"] = "notebook"
+    file_path: str
+    cells: list[dict]
+    """nbformat cells 列表（每个 cell 为 dict，含 cell_type / source / outputs 等字段）。"""
+
+
+class FileUnchangedOutput(BaseModel):
+    """
+    重复读取 dedup stub（对应 CC type='file_unchanged'）。
+
+    当同一文件、同 offset/limit、mtime 未变时返回。
+    model 收到此结果应引用历史 Read 结果，而非重新读取。
+    """
+
+    type: Literal["file_unchanged"] = "file_unchanged"
+    file_path: str
+
+
+# ---------------------------------------------------------------------------
+# Union 类型别名
+# ---------------------------------------------------------------------------
+
+ReadToolOutput = Annotated[
+    TextFileOutput | ImageFileOutput | PDFFileOutput | NotebookFileOutput | FileUnchangedOutput,
+    Field(discriminator="type"),
+]
+"""
+Read 工具输出的 discriminated union。
+对应 CC outputSchema 的 z.discriminatedUnion('type', [...])。
+"""