Grounding Text Utilities (reading/_grounding.py)

Utility functions for normalizing text while preserving character indices and managing source‑grounded context windows for reading extensions in LLM pipelines.

# Source: https://github.com/HKUDS/DeepTutor | License: Apache-2.0 | Copyright You must retain, in the Source form of any Derivative Works
# Provided via justclaw.it.com; keep this notice with the code.
"""Shared text-window helpers for source-grounded reading extensions."""

from __future__ import annotations

import json
import re
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from deeptutor.reading.extensions import ReadingContext

MAX_GROUNDING_CONTEXT_CHARS = 6_000


def normalized_with_map(value: str) -> tuple[str, list[int]]:
    """Collapse whitespace while retaining an index for every output character."""
    normalized: list[str] = []
    source_positions: list[int] = []
    for index, character in enumerate(value):
        if character.isspace():
            if normaliz

... (truncated -- full source via MCP)