alysis-code 0.13.0__py3-none-any.whl

alysis_code/llm/request_plan.py

@@ -0,0 +1,389 @@
+from __future__ import annotations
+
+import copy
+import hashlib
+import json
+from collections.abc import Mapping
+from dataclasses import dataclass, field, replace
+from typing import Any
+
+from ..request_estimation import (
+    estimate_message_tokens,
+    estimate_provider_payload_tokens,
+    estimate_request_token_breakdown,
+    estimate_tool_schema_tokens,
+    sanitize_messages_for_estimation,
+)
+from .cache_control_blocks import cacheable_prefix_message_count
+
+
+def _stable_payload_hash(value: Any) -> str:
+    serialized = json.dumps(
+        value,
+        ensure_ascii=False,
+        sort_keys=True,
+        separators=(",", ":"),
+    )
+    return hashlib.sha256(serialized.encode("utf-8", errors="surrogatepass")).hexdigest()
+
+
+def _optional_payload_token_estimate(payload: Any) -> int | None:
+    if payload is None:
+        return None
+    return estimate_provider_payload_tokens(payload)
+
+
+def _safe_int(value: Any) -> int | None:
+    try:
+        parsed = int(value)
+    except (TypeError, ValueError):
+        return None
+    if parsed < 0:
+        return None
+    return parsed
+
+
+def _safe_label(value: Any, default: str = "") -> str:
+    text = str(value or "").strip()
+    return text or default
+
+
+@dataclass(frozen=True)
+class RequestLayout:
+    schema_version: int = 1
+    input_mode: str = "full"
+    continuation_strategy: str = "full_replay"
+    cache_strategy: str = "none"
+    cache_mode: str = "manual"
+    message_count: int = 0
+    request_message_count: int = 0
+    tool_count: int = 0
+    stable_prefix_message_count: int = 0
+    dynamic_suffix_message_count: int = 0
+    provider_metadata_message_count: int = 0
+    stable_prefix_estimated_tokens: int = 0
+    dynamic_suffix_estimated_tokens: int = 0
+    tool_schema_tokens: int = 0
+    total_estimated_tokens: int = 0
+    serialized_request_estimate_tokens: int | None = None
+    sent_serialized_request_estimate_tokens: int | None = None
+    cacheable_prefix_hash: str = ""
+    request_messages_signature: str = ""
+    tool_schema_hash: str = ""
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def to_payload(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "schema_version": self.schema_version,
+            "input_mode": self.input_mode,
+            "continuation_strategy": self.continuation_strategy,
+            "cache_strategy": self.cache_strategy,
+            "cache_mode": self.cache_mode,
+            "message_count": self.message_count,
+            "request_message_count": self.request_message_count,
+            "tool_count": self.tool_count,
+            "stable_prefix_message_count": self.stable_prefix_message_count,
+            "dynamic_suffix_message_count": self.dynamic_suffix_message_count,
+            "provider_metadata_message_count": self.provider_metadata_message_count,
+            "stable_prefix_estimated_tokens": self.stable_prefix_estimated_tokens,
+            "dynamic_suffix_estimated_tokens": self.dynamic_suffix_estimated_tokens,
+            "tool_schema_tokens": self.tool_schema_tokens,
+            "total_estimated_tokens": self.total_estimated_tokens,
+            "cacheable_prefix_hash": self.cacheable_prefix_hash,
+            "request_messages_signature": self.request_messages_signature,
+            "tool_schema_hash": self.tool_schema_hash,
+        }
+        if self.serialized_request_estimate_tokens is not None:
+            payload["serialized_request_estimate_tokens"] = self.serialized_request_estimate_tokens
+        if self.sent_serialized_request_estimate_tokens is not None:
+            payload["sent_serialized_request_estimate_tokens"] = (
+                self.sent_serialized_request_estimate_tokens
+            )
+        for key, value in self.metadata.items():
+            if key in payload:
+                continue
+            if isinstance(value, bool):
+                payload[key] = value
+                continue
+            parsed_int = _safe_int(value)
+            if parsed_int is not None:
+                payload[key] = parsed_int
+                continue
+            if value is not None:
+                payload[key] = _safe_label(value)
+        return payload
+
+    @classmethod
+    def from_payload(cls, payload: Any) -> RequestLayout | None:
+        if not isinstance(payload, Mapping):
+            return None
+
+        metadata: dict[str, Any] = {}
+        known = set(cls.__dataclass_fields__)
+        for key, value in payload.items():
+            if key not in known:
+                metadata[str(key)] = copy.deepcopy(value)
+
+        return cls(
+            schema_version=_safe_int(payload.get("schema_version")) or 1,
+            input_mode=_safe_label(payload.get("input_mode"), "full"),
+            continuation_strategy=_safe_label(
+                payload.get("continuation_strategy"),
+                "full_replay",
+            ),
+            cache_strategy=_safe_label(payload.get("cache_strategy"), "none"),
+            cache_mode=_safe_label(payload.get("cache_mode"), "manual"),
+            message_count=_safe_int(payload.get("message_count")) or 0,
+            request_message_count=_safe_int(payload.get("request_message_count")) or 0,
+            tool_count=_safe_int(payload.get("tool_count")) or 0,
+            stable_prefix_message_count=(
+                _safe_int(payload.get("stable_prefix_message_count")) or 0
+            ),
+            dynamic_suffix_message_count=(
+                _safe_int(payload.get("dynamic_suffix_message_count")) or 0
+            ),
+            provider_metadata_message_count=(
+                _safe_int(payload.get("provider_metadata_message_count")) or 0
+            ),
+            stable_prefix_estimated_tokens=(
+                _safe_int(payload.get("stable_prefix_estimated_tokens")) or 0
+            ),
+            dynamic_suffix_estimated_tokens=(
+                _safe_int(payload.get("dynamic_suffix_estimated_tokens")) or 0
+            ),
+            tool_schema_tokens=_safe_int(payload.get("tool_schema_tokens")) or 0,
+            total_estimated_tokens=_safe_int(payload.get("total_estimated_tokens")) or 0,
+            serialized_request_estimate_tokens=_safe_int(
+                payload.get("serialized_request_estimate_tokens")
+            ),
+            sent_serialized_request_estimate_tokens=_safe_int(
+                payload.get("sent_serialized_request_estimate_tokens")
+            ),
+            cacheable_prefix_hash=_safe_label(payload.get("cacheable_prefix_hash")),
+            request_messages_signature=_safe_label(payload.get("request_messages_signature")),
+            tool_schema_hash=_safe_label(payload.get("tool_schema_hash")),
+            metadata=metadata,
+        )
+
+
+def _provider_metadata_message_count(messages: list[dict[str, Any]]) -> int:
+    return sum(1 for message in messages if "_alysis_provider_metadata" in message)
+
+
+def _policy_label(policy: Mapping[str, Any] | None, key: str) -> str | None:
+    if not isinstance(policy, Mapping):
+        return None
+    value = policy.get(key)
+    return str(value).strip() if value is not None else None
+
+
+def _merge_metadata(*items: Mapping[str, Any] | None) -> dict[str, Any]:
+    merged: dict[str, Any] = {}
+    for item in items:
+        if not isinstance(item, Mapping):
+            continue
+        for key, value in item.items():
+            merged[str(key)] = copy.deepcopy(value)
+    return merged
+
+
+@dataclass(frozen=True)
+class RequestCachePlan:
+    strategy: str = "none"
+    mode: str = "manual"
+    prompt_cache_key: str | None = None
+    prompt_cache_retention: str | None = None
+    anthropic_cache_control_enabled: bool = False
+    anthropic_cache_control_ttl: str = "5m"
+
+    def __post_init__(self) -> None:
+        mode = str(self.mode or "manual").strip().lower()
+        if mode not in {"manual", "automatic", "auto", "off"}:
+            mode = "manual"
+        if mode == "auto":
+            mode = "automatic"
+        ttl = str(self.anthropic_cache_control_ttl or "5m").strip().lower()
+        if ttl not in {"5m", "1h"}:
+            ttl = "5m"
+        object.__setattr__(self, "strategy", str(self.strategy or "none").strip() or "none")
+        object.__setattr__(self, "mode", mode)
+        object.__setattr__(
+            self,
+            "prompt_cache_key",
+            None if mode == "off" else str(self.prompt_cache_key or "").strip() or None,
+        )
+        object.__setattr__(
+            self,
+            "prompt_cache_retention",
+            None if mode == "off" else str(self.prompt_cache_retention or "").strip() or None,
+        )
+        object.__setattr__(
+            self,
+            "anthropic_cache_control_enabled",
+            False if mode == "off" else bool(self.anthropic_cache_control_enabled),
+        )
+        object.__setattr__(self, "anthropic_cache_control_ttl", ttl)
+
+    def anthropic_cache_control_payload(self) -> dict[str, str] | None:
+        if not self.anthropic_cache_control_enabled:
+            return None
+        payload = {"type": "ephemeral"}
+        if self.anthropic_cache_control_ttl == "1h":
+            payload["ttl"] = "1h"
+        return payload
+
+    def anthropic_cache_policy_metadata(self) -> dict[str, Any] | None:
+        if not self.anthropic_cache_control_enabled:
+            return None
+        return {
+            "strategy": "anthropic_cache_control",
+            "enabled": True,
+            "ttl": self.anthropic_cache_control_ttl,
+            "mode": self.mode if self.mode != "off" else "manual",
+        }
+
+    def openai_prompt_cache_policy_metadata(self) -> dict[str, Any] | None:
+        if (
+            self.mode == "off"
+            or self.strategy != "openai_prompt_cache"
+            or (not self.prompt_cache_key and not self.prompt_cache_retention)
+        ):
+            return None
+        metadata: dict[str, Any] = {
+            "strategy": "openai_prompt_cache",
+            "enabled": True,
+            "mode": self.mode if self.mode != "off" else "manual",
+        }
+        if self.prompt_cache_retention:
+            metadata["retention"] = self.prompt_cache_retention
+        return metadata
+
+
+@dataclass(frozen=True)
+class LLMRequestPlan:
+    messages: tuple[dict[str, Any], ...]
+    tools: tuple[dict[str, Any], ...] = ()
+    tool_choice: Any | None = None
+    response_format: dict[str, Any] | None = None
+    stream: bool = False
+    temperature: float | None = None
+    max_tokens: int | None = None
+    cache: RequestCachePlan = field(default_factory=RequestCachePlan)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_chat_args(
+        cls,
+        *,
+        messages: list[dict[str, Any]] | tuple[dict[str, Any], ...] | None,
+        tools: list[dict[str, Any]] | tuple[dict[str, Any], ...] | None = None,
+        tool_choice: Any | None = None,
+        response_format: dict[str, Any] | None = None,
+        stream: bool = False,
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+        cache: RequestCachePlan | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> LLMRequestPlan:
+        return cls(
+            messages=tuple(
+                copy.deepcopy(message) for message in (messages or []) if isinstance(message, dict)
+            ),
+            tools=tuple(copy.deepcopy(tool) for tool in (tools or []) if isinstance(tool, dict)),
+            tool_choice=copy.deepcopy(tool_choice),
+            response_format=(
+                copy.deepcopy(response_format) if isinstance(response_format, dict) else None
+            ),
+            stream=bool(stream),
+            temperature=temperature,
+            max_tokens=max_tokens,
+            cache=cache or RequestCachePlan(),
+            metadata=copy.deepcopy(metadata or {}),
+        )
+
+    def message_list(self) -> list[dict[str, Any]]:
+        return [copy.deepcopy(message) for message in self.messages]
+
+    def tool_list(self) -> list[dict[str, Any]] | None:
+        tools = [copy.deepcopy(tool) for tool in self.tools]
+        return tools or None
+
+    def with_cache(self, cache: RequestCachePlan) -> LLMRequestPlan:
+        return replace(self, cache=cache)
+
+    def layout(
+        self,
+        *,
+        input_mode: str = "full",
+        continuation_strategy: str | None = None,
+        provider_payload: Mapping[str, Any] | None = None,
+        sent_provider_payload: Mapping[str, Any] | None = None,
+        cache_policy_metadata: Mapping[str, Any] | None = None,
+        extra: Mapping[str, Any] | None = None,
+    ) -> RequestLayout:
+        messages = self.message_list()
+        tools = self.tool_list() or []
+        sanitized_messages = sanitize_messages_for_estimation(messages)
+        stable_prefix_count = min(
+            cacheable_prefix_message_count(sanitized_messages),
+            len(sanitized_messages),
+        )
+        stable_prefix = sanitized_messages[:stable_prefix_count]
+        dynamic_suffix = sanitized_messages[stable_prefix_count:]
+        tool_schema_tokens = estimate_tool_schema_tokens(tools)
+        stable_prefix_tokens = estimate_message_tokens(stable_prefix)
+        dynamic_suffix_tokens = estimate_message_tokens(dynamic_suffix)
+        breakdown = estimate_request_token_breakdown(
+            messages=messages,
+            tool_list=tools,
+            pinned_prefix_len=stable_prefix_count,
+        )
+        policy_cache_strategy = _policy_label(cache_policy_metadata, "strategy")
+        policy_cache_mode = _policy_label(cache_policy_metadata, "mode")
+        metadata = _merge_metadata(self.metadata, extra)
+        return RequestLayout(
+            input_mode=_safe_label(input_mode, "full"),
+            continuation_strategy=_safe_label(
+                continuation_strategy,
+                "previous_response_id" if input_mode == "previous_response_id" else "full_replay",
+            ),
+            cache_strategy=_safe_label(policy_cache_strategy, self.cache.strategy),
+            cache_mode=_safe_label(policy_cache_mode, self.cache.mode),
+            message_count=len(sanitized_messages),
+            request_message_count=len(sanitized_messages),
+            tool_count=len(tools),
+            stable_prefix_message_count=stable_prefix_count,
+            dynamic_suffix_message_count=len(dynamic_suffix),
+            provider_metadata_message_count=_provider_metadata_message_count(messages),
+            stable_prefix_estimated_tokens=stable_prefix_tokens,
+            dynamic_suffix_estimated_tokens=dynamic_suffix_tokens,
+            tool_schema_tokens=tool_schema_tokens,
+            total_estimated_tokens=breakdown.total_tokens,
+            serialized_request_estimate_tokens=_optional_payload_token_estimate(provider_payload),
+            sent_serialized_request_estimate_tokens=_optional_payload_token_estimate(
+                sent_provider_payload
+            ),
+            cacheable_prefix_hash=_stable_payload_hash(stable_prefix) if stable_prefix else "",
+            request_messages_signature=_stable_payload_hash(sanitized_messages),
+            tool_schema_hash=_stable_payload_hash(tools) if tools else "",
+            metadata=metadata,
+        )
+
+    def request_plan_metadata(
+        self,
+        *,
+        input_mode: str = "full",
+        continuation_strategy: str | None = None,
+        provider_payload: Mapping[str, Any] | None = None,
+        sent_provider_payload: Mapping[str, Any] | None = None,
+        cache_policy_metadata: Mapping[str, Any] | None = None,
+        extra: Mapping[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        return self.layout(
+            input_mode=input_mode,
+            continuation_strategy=continuation_strategy,
+            provider_payload=provider_payload,
+            sent_provider_payload=sent_provider_payload,
+            cache_policy_metadata=cache_policy_metadata,
+            extra=extra,
+        ).to_payload()

alysis_code/llm/request_shape.py

@@ -0,0 +1,238 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from ..request_estimation import (
+    estimate_message_tokens,
+    estimate_request_token_breakdown,
+    estimate_tool_schema_tokens,
+)
+from .cache_capabilities import (
+    CACHE_CONTROL_FIELD,
+    CACHED_CONTENT_FIELD,
+    OPENROUTER_SESSION_ID_FIELD,
+    OPENROUTER_SESSION_ID_HEADER_FIELD,
+    PROMPT_CACHE_KEY_FIELD,
+    XAI_CONVERSATION_ID_HEADER_FIELD,
+)
+from .cache_control_blocks import (
+    cacheable_prefix_message_count,
+    count_explicit_cache_control_blocks,
+)
+
+_AFFINITY_CACHE_FIELDS = frozenset(
+    {
+        PROMPT_CACHE_KEY_FIELD,
+        OPENROUTER_SESSION_ID_FIELD,
+        OPENROUTER_SESSION_ID_HEADER_FIELD,
+        XAI_CONVERSATION_ID_HEADER_FIELD,
+    }
+)
+
+
+def build_request_shape_report(
+    *,
+    messages: list[dict[str, Any]],
+    tools: list[dict[str, Any]] | None,
+    cache_policy: Mapping[str, Any] | None,
+    provider_payload: Mapping[str, Any] | None = None,
+    input_mode: str = "full",
+) -> dict[str, Any]:
+    clean_messages = [message for message in messages if isinstance(message, dict)]
+    clean_tools = [tool for tool in tools or [] if isinstance(tool, dict)]
+    prefix_count = cacheable_prefix_message_count(clean_messages)
+    prefix_messages = clean_messages[:prefix_count]
+    prefix_tokens = estimate_message_tokens(prefix_messages)
+    tool_schema_tokens = estimate_tool_schema_tokens(clean_tools)
+    breakdown = estimate_request_token_breakdown(
+        messages=clean_messages,
+        tool_list=clean_tools,
+        pinned_prefix_len=prefix_count,
+    )
+    total_tokens = breakdown.total_tokens
+    min_tokens = _policy_min_tokens(cache_policy)
+    emitted_fields = _policy_list(cache_policy, "emitted_fields")
+    cache_enabled = (
+        bool(cache_policy.get("enabled")) if isinstance(cache_policy, Mapping) else False
+    )
+    explicit_cache_control_blocks = count_explicit_cache_control_blocks(
+        provider_payload or clean_messages
+    )
+    top_level_cache_control_present = (
+        isinstance(provider_payload, Mapping) and CACHE_CONTROL_FIELD in provider_payload
+    )
+    cached_content_attached = _cached_content_attached(provider_payload)
+    affinity_field_emitted = any(field in _AFFINITY_CACHE_FIELDS for field in emitted_fields)
+    cache_material_attached = (
+        top_level_cache_control_present
+        or explicit_cache_control_blocks > 0
+        or cached_content_attached
+    )
+    cache_fields_emitted = bool(cache_material_attached or affinity_field_emitted)
+    cache_eligible = _cache_eligible(
+        cache_enabled=cache_enabled,
+        emitted_fields=emitted_fields,
+        prefix_tokens=prefix_tokens,
+        min_tokens=min_tokens,
+    )
+    token_breakdown = breakdown.to_payload()
+    token_breakdown.pop("tool_schema_budget", None)
+    return {
+        "schema_version": 1,
+        "input_mode": str(input_mode or "full").strip() or "full",
+        "message_count": len(clean_messages),
+        "tool_count": len(clean_tools),
+        "system_message_count": _role_count(clean_messages, "system"),
+        "developer_message_count": _role_count(clean_messages, "developer"),
+        "user_message_count": _role_count(clean_messages, "user"),
+        "assistant_message_count": _role_count(clean_messages, "assistant"),
+        "tool_message_count": _role_count(clean_messages, "tool"),
+        "tool_call_message_count": sum(
+            1 for message in clean_messages if bool(message.get("tool_calls"))
+        ),
+        "content_block_count": sum(
+            _content_block_count(message.get("content")) for message in clean_messages
+        ),
+        "cache_enabled": cache_enabled,
+        "cache_eligible": cache_eligible,
+        "cache_used": bool(cache_material_attached),
+        "cache_fields_emitted": cache_fields_emitted,
+        "top_level_cache_control_present": top_level_cache_control_present,
+        "cached_content_attached": cached_content_attached,
+        "affinity_field_emitted": affinity_field_emitted,
+        "cache_strategy": _policy_label(cache_policy, "strategy"),
+        "cache_status": _policy_label(cache_policy, "status"),
+        "emitted_cache_fields": emitted_fields,
+        "cache_control_block_count": explicit_cache_control_blocks,
+        "explicit_cache_control_block_count": explicit_cache_control_blocks,
+        "cacheable_prefix_present": prefix_count > 0,
+        "cacheable_prefix_message_count": prefix_count,
+        "cacheable_prefix_estimated_tokens": prefix_tokens,
+        "cacheable_surface_estimated_tokens": prefix_tokens + tool_schema_tokens,
+        "min_cacheable_tokens": min_tokens,
+        "total_estimated_tokens": total_tokens,
+        "tool_schema_share": _ratio(tool_schema_tokens, total_tokens),
+        "inline_tool_transcript_share": _ratio(
+            breakdown.inline_tool_transcript_tokens,
+            total_tokens,
+        ),
+        "token_breakdown": token_breakdown,
+        "risk_reasons": _risk_reasons(
+            cache_enabled=cache_enabled,
+            cache_eligible=cache_eligible,
+            emitted_fields=emitted_fields,
+            explicit_cache_control_blocks=explicit_cache_control_blocks,
+            top_level_cache_control_present=top_level_cache_control_present,
+            cached_content_attached=cached_content_attached,
+            prefix_count=prefix_count,
+            prefix_tokens=prefix_tokens,
+            min_tokens=min_tokens,
+            breakdown=token_breakdown,
+            total_tokens=total_tokens,
+        ),
+    }
+
+
+def _policy_label(policy: Mapping[str, Any] | None, key: str) -> str:
+    if not isinstance(policy, Mapping):
+        return ""
+    return str(policy.get(key) or "").strip()
+
+
+def _policy_list(policy: Mapping[str, Any] | None, key: str) -> list[str]:
+    if not isinstance(policy, Mapping):
+        return []
+    raw = policy.get(key)
+    if not isinstance(raw, (list, tuple)):
+        return []
+    return [str(item).strip() for item in raw if str(item).strip()]
+
+
+def _policy_min_tokens(policy: Mapping[str, Any] | None) -> int:
+    if not isinstance(policy, Mapping):
+        return 0
+    for key in ("min_tokens", "min_cacheable_tokens"):
+        try:
+            value = int(policy.get(key))
+        except (TypeError, ValueError):
+            continue
+        if value >= 0:
+            return value
+    return 0
+
+
+def _cached_content_attached(provider_payload: Mapping[str, Any] | None) -> bool:
+    if not isinstance(provider_payload, Mapping):
+        return False
+    return "cachedContent" in provider_payload or CACHED_CONTENT_FIELD in provider_payload
+
+
+def _cache_eligible(
+    *,
+    cache_enabled: bool,
+    emitted_fields: list[str],
+    prefix_tokens: int,
+    min_tokens: int,
+) -> bool:
+    if not cache_enabled:
+        return False
+    if CACHE_CONTROL_FIELD in emitted_fields or CACHED_CONTENT_FIELD in emitted_fields:
+        return prefix_tokens >= min_tokens and prefix_tokens > 0
+    return True
+
+
+def _role_count(messages: list[dict[str, Any]], role: str) -> int:
+    return sum(1 for message in messages if str(message.get("role") or "").strip().lower() == role)
+
+
+def _content_block_count(content: Any) -> int:
+    if isinstance(content, list):
+        return len(content)
+    return 1 if content is not None else 0
+
+
+def _ratio(numerator: int, denominator: int) -> float:
+    if denominator <= 0:
+        return 0.0
+    return round(max(0, numerator) / denominator, 4)
+
+
+def _risk_reasons(
+    *,
+    cache_enabled: bool,
+    cache_eligible: bool,
+    emitted_fields: list[str],
+    explicit_cache_control_blocks: int,
+    top_level_cache_control_present: bool,
+    cached_content_attached: bool,
+    prefix_count: int,
+    prefix_tokens: int,
+    min_tokens: int,
+    breakdown: Mapping[str, Any],
+    total_tokens: int,
+) -> list[str]:
+    reasons: list[str] = []
+    if not cache_enabled:
+        reasons.append("cache_disabled_or_unavailable")
+    if cache_enabled and not emitted_fields:
+        reasons.append("no_emitted_cache_fields")
+    if (
+        CACHE_CONTROL_FIELD in emitted_fields
+        and explicit_cache_control_blocks <= 0
+        and not top_level_cache_control_present
+    ):
+        reasons.append("cache_control_blocks_absent")
+    if CACHED_CONTENT_FIELD in emitted_fields and cache_eligible and not cached_content_attached:
+        reasons.append("cached_content_absent")
+    if prefix_count <= 0:
+        reasons.append("no_cacheable_prefix")
+    if prefix_tokens < min_tokens:
+        reasons.append("prefix_below_min_tokens")
+    if cache_enabled and not cache_eligible:
+        reasons.append("cache_not_eligible")
+    if _ratio(int(breakdown.get("tool_schema_tokens") or 0), total_tokens) >= 0.25:
+        reasons.append("large_tool_schema_share")
+    if _ratio(int(breakdown.get("inline_tool_transcript_tokens") or 0), total_tokens) >= 0.25:
+        reasons.append("large_inline_tool_transcript_share")
+    return list(dict.fromkeys(reasons))