File Reader Tools¶

@staticmethod
def read(
    path: str,
    offset: int = 1,
    limit: int | None = None,
) -> str:
    """Read a text file with line numbers.

    Args:
        path: Path to file.
        offset: Starting line number (1-indexed). Defaults to 1.
        limit: Maximum number of lines to read. Defaults to 2000.

    Returns:
        File content with line numbers in ``"N | content"`` format.
        Includes a metadata header with file path, total lines, and
        the range actually read.

    Raises:
        FileNotFoundError: If the file does not exist.
        IsADirectoryError: If the path is a directory.
        ValueError: If offset is less than 1.
    """
    p = Path(path)
    if not p.exists():
        raise FileNotFoundError(f"File not found: {path}")
    if p.is_dir():
        raise IsADirectoryError(f"Path is a directory, not a file: {path}")
    if offset < 1:
        raise ValueError("offset must be >= 1")

    effective_limit = limit if limit is not None else _MAX_LINES_DEFAULT

    # Size guard
    file_size = p.stat().st_size
    if file_size > _MAX_FILE_SIZE_BYTES:
        return (
            f"[File too large: {file_size:,} bytes "
            f"(limit {_MAX_FILE_SIZE_BYTES:,}). "
            f"Use offset/limit to read in segments.]"
        )

    text = p.read_text(encoding="utf-8", errors="replace")
    all_lines = text.splitlines()
    total_lines = len(all_lines)

    start = offset - 1  # convert to 0-indexed
    end = min(start + effective_limit, total_lines)
    selected = all_lines[start:end]

    # Build line-numbered output
    width = len(str(end))
    numbered = [
        f"{i + offset:>{width}} | {line}" for i, line in enumerate(selected)
    ]

    # Metadata header
    range_str = f"{offset}-{start + len(selected)}"
    header = f"[{path}] lines {range_str} of {total_lines}"
    if end < total_lines:
        header += f" (use offset={end + 1} to read more)"

    return header + "\n" + "\n".join(numbered)

@staticmethod
def read_image(
    path: str,
    max_size: int = _MAX_IMAGE_SIZE_BYTES,
) -> list:
    """Read an image file and return as multimodal content blocks.

    Returns a list of content blocks (TextBlock + ImageBlock) that the
    toolregistry pipeline can expand into format-specific multimodal
    messages via ``expand_content_blocks()``.

    If the base64-encoded image exceeds ``max_size``, Pillow is used to
    downsample it. If Pillow is not installed, the original image is
    returned with a warning.

    Args:
        path: Path to image file (.png, .jpg, .jpeg, .gif, .webp).
        max_size: Maximum base64-encoded size in bytes. Defaults to 5 MB.

    Returns:
        A list of two content blocks::

            [
                {"type": "text", "text": "[Image: name (mime, size)]"},
                {"type": "image", "source": {
                    "type": "base64",
                    "media_type": "image/png",
                    "data": "iVBOR..."
                }}
            ]

    Raises:
        FileNotFoundError: If the file does not exist.
        ValueError: If the file extension is not supported.
    """
    p = Path(path)
    if not p.exists():
        raise FileNotFoundError(f"File not found: {path}")

    ext = p.suffix.lower()
    if ext not in _SUPPORTED_IMAGE_EXTENSIONS:
        raise ValueError(
            f"Unsupported image format: '{ext}'. "
            f"Supported: {', '.join(sorted(_SUPPORTED_IMAGE_EXTENSIONS))}"
        )

    media_type = _EXTENSION_TO_MIME[ext]
    img_data = p.read_bytes()
    raw_size = len(img_data)

    b64_data = base64.b64encode(img_data).decode("ascii")

    if len(b64_data) > max_size:
        img_data, media_type = FileReader._downsample_image(
            img_data, media_type, max_size
        )
        b64_data = base64.b64encode(img_data).decode("ascii")

    return [
        {
            "type": "text",
            "text": f"[Image: {p.name} ({media_type}, {raw_size} bytes)]",
        },
        {
            "type": "image",
            "source": {
                "type": "base64",
                "media_type": media_type,
                "data": b64_data,
            },
        },
    ]

@staticmethod
def read_notebook(path: str) -> str:
    """Read a Jupyter notebook and return formatted cell contents.

    Uses stdlib ``json`` only — no external dependencies.

    Args:
        path: Path to ``.ipynb`` file.

    Returns:
        All cells with type markers (code/markdown) and outputs.

    Raises:
        FileNotFoundError: If the file does not exist.
        ValueError: If the file is not a valid notebook.
    """
    p = Path(path)
    if not p.exists():
        raise FileNotFoundError(f"File not found: {path}")

    try:
        data = json.loads(p.read_text(encoding="utf-8"))
    except json.JSONDecodeError as e:
        raise ValueError(f"Invalid notebook JSON: {e}") from e

    if "cells" not in data:
        raise ValueError(f"Not a valid Jupyter notebook (no 'cells' key): {path}")

    # Detect language from kernel info
    lang = "python"
    kernel_info = data.get("metadata", {}).get("kernelspec", {})
    if kernel_info.get("language"):
        lang = kernel_info["language"]

    lines: list[str] = []
    lines.append(f"[Notebook: {path}]")

    for i, cell in enumerate(data["cells"]):
        cell_type = cell.get("cell_type", "unknown")
        source = "".join(cell.get("source", []))

        lines.append(f"\n--- Cell {i + 1} [{cell_type}] ---")

        if cell_type == "code":
            lines.append(f"```{lang}")
            lines.append(source)
            lines.append("```")

            # Process outputs
            for output in cell.get("outputs", []):
                output_text = FileReader._extract_notebook_output(output)
                if output_text:
                    lines.append(f"Output:\n{output_text}")
        else:
            lines.append(source)

    return "\n".join(lines)

@staticmethod
def read_pdf(
    path: str,
    pages: str | None = None,
) -> str:
    """Read a PDF file and extract text.

    Uses ``pypdf`` (zero-dependency, BSD) by default. If ``pdfplumber``
    is installed, uses it for better text quality.

    Args:
        path: Path to PDF file.
        pages: Page range string (e.g. ``"1-5"``, ``"3"``, ``"10-20"``).
            Max 20 pages per call. Defaults to all pages (up to cap).

    Returns:
        Extracted text content with page markers.

    Raises:
        FileNotFoundError: If the file does not exist.
        ImportError: If neither ``pypdf`` nor ``pdfplumber`` is installed.
        ValueError: If page range is invalid.
    """
    p = Path(path)
    if not p.exists():
        raise FileNotFoundError(f"File not found: {path}")

    start_page, end_page = FileReader._parse_page_range(pages)

    # Try pdfplumber first (better quality), fall back to pypdf
    try:
        return FileReader._read_pdf_pdfplumber(p, start_page, end_page)
    except ImportError:
        pass

    try:
        return FileReader._read_pdf_pypdf(p, start_page, end_page)
    except ImportError:
        raise ImportError(
            "PDF reading requires 'pypdf' or 'pdfplumber'. "
            "Install with: pip install toolregistry-hub[reader]"
        ) from None