Function read_file_segment

functions/function_calling/file.py:447–526

Read a line range plus metadata from a workspace file.

(
    path: Annotated[str, ParamMeta(description="Workspace-relative text file path")],
    *,
    start_line: Annotated[int, ParamMeta(description="1-based line to begin the snippet")]=1,
    line_count: Annotated[int, ParamMeta(description="Number of lines to include starting from start_line")]=40,
    inline_line_numbers: Annotated[
        bool,
        ParamMeta(description="If true, prefix each snippet line with its line number inside the snippet"),
    ] = False,
    encoding: Annotated[str, ParamMeta(description="Explicit encoding or 'auto'")]="auto",
    include_line_offsets: Annotated[
        bool,
        ParamMeta(description="Include 1-based line metadata for the returned snippet"),
    ] = False,
    _context: Dict[str, Any] | None = None,
)

def read_file_segment(
    path: Annotated[str, ParamMeta(description="Workspace-relative text file path")],
    *,
    start_line: Annotated[int, ParamMeta(description="1-based line to begin the snippet")]=1,
    line_count: Annotated[int, ParamMeta(description="Number of lines to include starting from start_line")]=40,
    inline_line_numbers: Annotated[
        bool,
        ParamMeta(description="If true, prefix each snippet line with its line number inside the snippet"),
    ] = False,
    encoding: Annotated[str, ParamMeta(description="Explicit encoding or 'auto'")]="auto",
    include_line_offsets: Annotated[
        bool,
        ParamMeta(description="Include 1-based line metadata for the returned snippet"),
    ] = False,
    _context: Dict[str, Any] | None = None,
) -> Dict[str, Any]:
    """Read a line range plus metadata from a workspace file."""

    if start_line < 1:
        raise ValueError("start_line must be >= 1")
    if line_count < 1:
        raise ValueError("line_count must be >= 1")

    ctx = FileToolContext(_context)
    target = ctx.resolve_under_workspace(path)
    if not target.exists() or not target.is_file():
        raise FileNotFoundError(f"File not found: {path}")

    text, used_encoding = _read_text_content(target, encoding)
    newline_style = _detect_newline(text)
    stat = target.stat()

    lines_with_breaks = text.splitlines(keepends=True)
    if not lines_with_breaks:
        lines_with_breaks = [""]
    total_lines = len(lines_with_breaks)
    start_idx = start_line - 1
    if start_idx >= total_lines:
        raise ValueError("start_line is beyond the total number of lines in the file")

    lines_returned = min(line_count, total_lines - start_idx)
    end_idx = start_idx + lines_returned
    segment_lines = lines_with_breaks[start_idx:end_idx]
    snippet = "".join(segment_lines)
    raw_snippet = snippet

    line_starts: List[int] = [0]
    for line in lines_with_breaks:
        line_starts.append(line_starts[-1] + len(line))
    start_char = line_starts[start_idx]

    response: Dict[str, Any] = {
        "path": ctx.to_workspace_relative(target),
        "encoding": used_encoding,
        "newline": newline_style,
        "start_line": start_line,
        "end_line": start_line + lines_returned - 1,
        "line_count": line_count,