docs(cache_warming): state what a session costs over its life and when warming stops

litellm/router_strategy/complexity_router/README.md

@@ -183,6 +183,7 @@ Requirements and semantics:
 - **Warming cost is visible where the customer already looks for cost.** Warming writes no spend logs of its own, so the replay rows are the only record of warming cost that exists, and they carry the same identity block a real request on that key carries: key, team, user and end-user attribution, the key's and team's own `tags` and `spend_logs_metadata`, plus a `litellm_cache_warming` marker in `spend_logs_metadata` so warming rows are identifiable in per-tag chargeback without putting warming's own tag on `metadata.tags`, which is an input to deployment selection and which operators can forbid requests from carrying. Replays also fan out to the key-scoped and team-scoped logging callbacks, so a team pointing its traffic at its own Langfuse sees warming there too rather than only in the proxy-wide logs. A `max_tokens=1` replay of a warm prefix bills roughly 10% of the input cost. Key-level cache controls, `disable_fallbacks` and the global-guardrail opt-outs are applied the same way, which means a key that declares its own `cache` controls overrides warming's response-cache bypass exactly as it overrides a caller's.
 - **Guardrails run on replays.** Because a replay goes through `pre_call_hook`, the guardrails configured for the model group (globally and on the deployment) also run on its warming replays. A blocking guardrail costs one skipped warm; a content-rewriting guardrail makes the warm ineffective rather than wrong, because a rewritten prefix simply is not the prefix real traffic sends. Sessions on a key that declares `max_iterations` are skipped instead of warmed, because that limiter counts every request on a `session_id` and cannot be consulted without incrementing it, so warming would consume the caller's own iteration budget.
 - **Multi-deployment groups require deployment affinity.** A replay routes by group name, so with several deployments it warms one member's cache while real traffic spreads across all of them: paying the cache-write premium against 1/N routing odds is worse than not warming, so such a group is skipped (with a one-time warning naming the group and both remedies) unless `DeploymentAffinityCheck` is active for it with the session_id mode, enabled globally via `router_settings.optional_pre_call_checks: ["session_affinity"]` or per group via `router_settings.model_group_affinity_config`. When active, replays carry the session's `session_id` (and the originating key hash), so the affinity check pins warming and real traffic to the same deployment. Single-deployment groups warm regardless. More than one deployment is used as the conservative stand-in for "more than one provider cache domain"
+- **A session's cost is bounded by three timers.** Warming replays one call per touched model per `refresh_interval_seconds` while the session is active. Once a session has gone `idle_timeout_seconds` without a real request, warming stops for it, though the record stays until `session_ttl_seconds` expires it. So a user who closes their laptop stops costing anything about ten minutes later rather than for the hour their record survives. Returning within the TTL finds the record intact but the provider cache long cold, so that turn is a normal cache write and warming resumes from it; returning later simply captures fresh. Warming is therefore for the gaps inside a working session, not across long absences: the provider cache lives about five minutes and warming stops at ten.
 - **`max_sessions`** caps concurrently warmed sessions per auto-router, enforced atomically at capture; once reached, new sessions are not admitted until existing ones expire.
 - **Interplay with `session_affinity`** (default on): affinity pins a session to its first-turn model, so it only ever touches that one model and warming keeps exactly that cache alive, which is worth having for sessions with long gaps between turns but buys nothing on switching, since no switch happens. Disable `session_affinity` to let per-turn classification move a session between tiers; the first visit to each tier is a normal cache write, and every return to a tier the session has already used is a cache read.