sj|).dZddlmZddlZddlmZddlmZddlm Z m Z m Z m Z ej eZdZdZed Zd Zd Zd Zd ZdZed GddZd+dZd,dZd-dZd.dZd/d Zd0d"Zd1d&Zd,d'Z d2d)Z!d3d*Z"dS)4uDeterministic-empty detection and cost-aware retry budgets (NS-503). When a provider returns an empty completion, the agent loop retries up to 3 times and then walks the fallback chain. Every attempt re-sends the full conversation input — at large context on paid routes this bills the user repeatedly for a turn that produces no text (the "charged ~$2.33 for an empty answer" incident class). Signaled refusals (``finish_reason="content_filter"``, Anthropic ``stop_reason="refusal"``, Bedrock guardrails) are already terminal and never reach the empty-retry loop. This module addresses the *unsignaled* empties: the provider reports a successful completion with zero output tokens and a generic finish reason (portal-proxied refusals commonly look like this). Two independent guards, both failing OPEN to today's behaviour: 1. **Deterministic-empty detection** — two consecutive empty attempts, both with usage present and ``output_tokens == 0``, from the same (model, provider, finish_reason), are treated as deterministic: the same prompt will keep producing the same empty. Remaining retries are skipped and the loop proceeds straight to the fallback chain (a different model may behave differently). Attempts with missing usage or ``output_tokens > 0`` (model generated *something* — think-block stripping, whitespace, flaky decoding) never classify as deterministic and keep the full retry budget. 2. **Cost-aware retry budget** — when the estimated input cost of a single empty attempt exceeds the configured threshold (default $0.25), the empty-retry budget for this streak drops from 3 to 1. Unknown pricing, missing usage, or included/subscription routes leave the budget untouched. Configured via the additive ``agent.empty_response_guard`` section in ``config.yaml`` (resolved once at agent init by ``agent_init``):: agent: empty_response_guard: enabled: true # false = legacy fixed 3-retry behaviour cost_threshold_usd: 0.25 # per-attempt cost that halves the budget Per project policy, no ``HERMES_*`` environment variables are involved — ``.env`` is reserved for credentials; behavioural settings live in ``config.yaml``. ) annotationsN) dataclass)Decimal)AnyListOptionalTuplez0.25T_empty_attempt_history_empty_streak_cost_usd_empty_guard_enabled_empty_guard_cost_threshold_usd)frozenc^eZdZUdZded<ded<ded<ded<ded<ed d Zd S) EmptyAttemptz8One observed empty completion within the current streak.strmodelprovider finish_reasonbool usage_present zero_outputreturntuplec*|j|j|jfSN)rrr)selfs >/home/agent/.hermes/hermes-agent/agent/empty_response_guard.py signaturezEmptyAttempt.signatureRs DM4+=>>N)rr)__name__ __module__ __qualname____doc____annotations__propertyr r!rrrHspBBJJJMMM ???X???r!rsectionrrTuple[bool, Decimal]cHt|tsttfS|dt}t|t r|}nEt|t r)|dv}nt}t}|d}|ft|t sQ tt |}|dkr|}n+#t$rt d|YnwxYw||fS)aaResolve ``agent.empty_response_guard`` config into (enabled, threshold). Tolerant of malformed input: anything that isn't a well-formed dict (or well-formed values within it) falls back to the schema defaults. Called once per agent at init; the resolved values are stashed on the agent object so the hot loop never re-reads config. enabled)0falsenooffcost_threshold_usdNrz9empty-guard: invalid cost_threshold_usd %r, using default) isinstancedictDEFAULT_GUARD_ENABLEDDEFAULT_COST_THRESHOLD_USDgetrrstriplowerr Exceptionloggerdebug)r) enabled_rawr, threshold threshold_raw candidates rresolve_guard_settingsr@Ws/ gt $ $C%'ABB++i)>??K+t$$( K % %(##%%++--5PP'*IKK 455M M4)H)H  M 2 233I1}}%     LLK       Y s$C55%DDagentrctt|tt}t|tr|ntS)zWhether the guard is enabled for this agent (config-resolved). Agents built before the config was threaded through (tests, embedded callers) simply get the default: enabled. )getattr _ENABLED_ATTRr4r2rrAvalues r guard_enabledrGzs0 E=*? @ @Eud++ F551FFr!rcvt|td}t|tr|dkr|StS)Nr)rC_THRESHOLD_ATTRr2rr5rEs r_cost_threshold_usdrJs8 E?D 1 1E%!!eaii %%r!List[EmptyAttempt]cft|td}|g}t|t||Sr)rC_ATTEMPTS_ATTRsetattr)rAattemptss r _attemptsrPs5und33H~x000 Or!responseOptional[Decimal]c t|dd}|sdS ddlm}m}||t|ddt|dd}|t|dd pd |t|ddt|d dt|d d }n-#t$r t d dYdSwxYwt|ddS)z NNN~~Y 6 6F ~~y/1--22~ #5q99>QI 6I%!+ ,,s2A &A43A4rrNonec t|}t|dddkr7|t|tt dt ||\}}|ttt|ddpdtt|ddpdt|pd||t||}|S|dkrOt|tt dpt d}t|t||zdSdSdS) a"Record one empty completion in the current streak. Must be called before ``_empty_content_retries`` is incremented for this attempt: a counter of 0 marks the start of a new streak and clears prior history (this transparently follows every existing counter-reset site). _empty_content_retriesrr-rrYr)rrrrrN) rPrCclearrN_STREAK_COST_ATTRrrjappendrrrc)rArrQrOrrcostpriors rrecord_empty_attemptrssGHu.22a77('#,,777!-eX!>!>M; OOgeWb117R88 B77=2>>m1r22'#     "% 2 2D D1HH0'#,,??O73<<(%$,77777HHr!ct|sdSt|tdpg}t|dkrdS|dt fd|DS)uITrue when the current streak looks deterministic. Requires >= 2 consecutive attempts, ALL with usage present, zero output tokens, and an identical (model, provider, finish_reason) signature. Any attempt with missing usage or non-zero output keeps this False (fail open — transients deserve their retries). FNrc3TK|]"}|jo|jo|jjkV#dSr)rrr ).0afirsts r z&deterministic_empty..sN  LAMLakU_.Lr!)rGrCrMlenall)rArOrys @rdeterministic_emptyr}s   uund339rH 8}}qu QKE   r!intct|stSt||}|tS|t|krtStS)zEmpty-retry budget for the current streak (3, or 1 when a single attempt is estimated to cost more than the configured threshold).)rGDEFAULT_EMPTY_RETRY_BUDGETrcrJREDUCED_EMPTY_RETRY_BUDGET)rArQrqs rempty_retry_budgetrsT   *)) !% 2 2D |)) "5)))))) %%r!cFt|td}||dkrdS|S)zAAccumulated estimated cost of the current empty streak, if known.Nr)rCro)rArqs rstreak_cost_usdr s+ 5+T 2 2D |tqyyt Kr!)r)rrr*)rArrr)rArrr)rArrrK)rArrQrrrR)rArrQrrr)rArrrrQrrrk)rArrQrrr~)rArrrR)#r% __future__rlogging dataclassesrdecimalrtypingrrrr getLoggerr"r:rrr5r4rMrorDrIrr@rGrJrPrcrjrsr}rrr(r!rrs,,\#"""""!!!!!!------------  8 $ $$WV__*,& 3 $ ? ? ? ? ? ? ? ?     FGGGG&&&&////4---->8888<( & & & &r!