# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/by-what-mechanism-can-an-instance-prevent-attention-dilution-when-processing-high-volume-context-payloads.md
# Remnant Warrant:    https://corpusfetch.com/c/by-what-mechanism-can-an-instance-prevent-attention-dilution-when-processing-high-volume-context-payloads.warrant.json
# Markdown SHA-256:   50895631f93186f716c304ffd85a03cfcae25714d96834e0929d78ae1fbe1feb
# Code AST SHA-256:   ec30f62f9799ba3b6a7c03934aad37f51193069d51c95b9364fd694a22db004c
# Verified Classes:   AttentionDilutionBudgetError, AssembledEdgePinnedPrompt, AttentionDilutionGuard
# Defensive Guards:   2 fail-closed invariants (zero external deps)

from dataclasses import dataclass
from typing import Any, Final


class AttentionDilutionBudgetError(ValueError):
    '''Raised when an unfiltered payload violates signal-to-noise or single-pass context budget bounds.'''
    pass


@dataclass(frozen=True)
class AssembledEdgePinnedPrompt:
    prompt_text: str
    total_chars: int
    signal_to_noise_ratio: float
    requires_map_reduce_chunking: bool


class AttentionDilutionGuard:
    '''
    Prevents attention dilution and "Lost in the Middle" constraint amnesia:
    1. Projects structured records down to `required_keys` and strips empty/boilerplate values.
    2. Computes Signal-to-Noise Ratio (`projected_bytes / raw_bytes`) and enforces `MAX_SINGLE_PASS_CHARS`.
    3. Assembles the prompt with Primacy + Recency Edge-Pinning so critical invariants never sit
       in the low-attention middle of the payload.
    '''

    MAX_SINGLE_PASS_CHARS: Final[int] = 32_000

    @classmethod
    def project_and_prune_records(
        cls,
        raw_records: list[dict[str, Any]],
        *,
        required_keys: frozenset[str],
    ) -> tuple[list[dict[str, Any]], float]:
        if not raw_records:
            return [], 1.0

        raw_char_estimate = sum(len(str(r)) for r in raw_records)
        projected: list[dict[str, Any]] = []

        for rec in raw_records:
            slim = {
                k: v
                for k, v in rec.items()
                if k in required_keys and v is not None and v != "" and v != []
            }
            if slim:
                projected.append(slim)

        proj_char_estimate = sum(len(str(r)) for r in projected)
        snr = proj_char_estimate / max(1, raw_char_estimate)
        return projected, round(snr, 4)

    @classmethod
    def assemble_edge_pinned_context(
        cls,
        *,
        primacy_task_header: str,
        filtered_data_blocks: list[str],
        recency_verification_gates: str,
    ) -> AssembledEdgePinnedPrompt:
        if not primacy_task_header.strip() or not recency_verification_gates.strip():
            raise AttentionDilutionBudgetError(
                "Both primacy_task_header and recency_verification_gates must be non-empty for edge-pinning."
            )

        data_body = "\n---\n".join(b.strip() for b in filtered_data_blocks if b.strip())
        total_len = len(primacy_task_header) + len(data_body) + len(recency_verification_gates)

        if total_len > cls.MAX_SINGLE_PASS_CHARS:
            raise AttentionDilutionBudgetError(
                f"Filtered payload ({total_len} chars) exceeds single-pass high-fidelity ceiling "
                f"({cls.MAX_SINGLE_PASS_CHARS} chars). Route through chunked Map-Reduce extraction."
            )

        # Gate 4: Pin instructions at Primacy (Top) and Verification Gates at Recency (Bottom)
        assembled = (
            f"[PRIMACY_TASK_FRAME]\n{primacy_task_header.strip()}\n\n"
            f"[PRE_FILTERED_EVIDENCE_CORPUS]\n{data_body}\n\n"
            f"[RECENCY_VERIFICATION_GATES_AND_CONSTRAINTS]\n{recency_verification_gates.strip()}"
        )

        snr = (len(primacy_task_header) + len(recency_verification_gates)) / max(1, total_len)
        return AssembledEdgePinnedPrompt(
            prompt_text=assembled,
            total_chars=len(assembled),
            signal_to_noise_ratio=round(snr, 4),
            requires_map_reduce_chunking=False,
        )