+ iHjb3Rt^RIt^RIt^RIHtHt^RIHtHtH t H t ^RI H t ^RI HtRtRtRtR R ltR R lt!R R]4tR#)a Abstract base class for pluggable context engines. A context engine decides when/how conversation context is compacted near the token limit, tracks usage, and may expose tools. ContextCompressor is the default; ``context.engine`` selects a plugin (``plugins/context_engine//``); one is active. Lifecycle: on_session_start() -> per API response update_from_response() -> per turn should_compress() / compress() -> on_session_end() at real session boundaries only (CLI exit, /reset, gateway expiry), never per-turn. N)ABCabstractmethod)AnyDictListOptional) elide_middle)redact_sensitive_textipiic0V^8dQhR\R\/#)memory_contextreturnstr)formats"9/home/ubuntu/.hermes/hermes-agent/agent/context_engine.py __annotate__rs[[C[C[c\VP4RRR7p\V4\8:dV#\ V\ \ 4#)zBPrepare provider context for a context-engine/LLM egress boundary.T)forceredact_url_credentials)r striplenMEMORY_CONTEXT_MAX_CHARSr_MEMORY_CONTEXT_HEAD_CHARS_MEMORY_CONTEXT_TAIL_CHARS)r sanitizeds& rsanitize_memory_contextrs>%n&:&:&Fsm  c]  26  PS   d38n   rc R#)u_Compact ``messages`` into a valid OpenAI-format list that fits the budget. ``focus_topic`` comes from manual ``/compress `` (prioritise that topic); ``force`` asks to bypass an engine-owned cooldown; ``memory_context`` is provider text for the handoff prompt. Older engines may omit optional parameters — the host filters them by signature. Nr&)r4rOrPrQrr s&&&&&&rcompressContextEngine.compressar7rc <V^8dQhRS[S[S[S[3,,RS[R,RS[S[S[S[S[3,,S[3,/#)r rOrPNr )rRr;rrrCrJ)rr0s"rrr1nsM  T#s(^, >ADj  tDcN#S( ) rc V^3#)a-Deterministically trim old tool-result payloads without an LLM call. Runs on a low, cost-oriented trigger independent of ``should_compress`` so large-window engines reclaim re-sent tool output long before full compaction. Returns ``(messages, n_pruned)``; the default no-op keeps older engines safe. r&)r4rOrPs&&&rprune_tool_results_only%ContextEngine.prune_tool_results_onlyns{rconversation_messagesincoming_message budget_tokensc <V^8dQhRS[S[S[S[3,,RS[S[S[S[3,,R,RS[S[S[3,R,RS[RS[S[S[S[3,,/#)r request_messagesrZNr[r\r )rRr;rrrC)rr0s"rrr1ysv $T#s(^ 4PTUYZ]_bZbUcPdgkPksCx.4/GJ d38n rc R#)uOptionally *select* (replace) the context for THIS request, pre-generation. Runs on every provider request (also retries), independent of ``should_compress()``: ``compress()`` shrinks over-long context, this swaps in a different one (retrieval, topic routing, branch switching). Return ``None`` to leave the request unchanged. The returned list is request-only — it MUST NOT be treated as persisted transcript state (session DB history is untouched); unlike ``pre_llm_call`` it may replace the list. The host runs it before prompt cache-control and every request sanitizer, so a malformed replacement never reaches the provider and the default no-op keeps the request byte-identical; an engine that replaces the list changes its own cache prefix (breakpoints are re-derived on the selected list). ``request_messages`` is the assembled request (system prompt + history + ephemeral prefill); ``conversation_messages`` is the persisted history for reference only (do not mutate); ``budget_tokens`` is the model's context length or 0 if unknown. Nr&)r4r^rZr[r\s&&$$$rselect_contextContextEngine.select_contextys(rcz<V^8dQhRS[S[S[S[3,,RS[S[S[3,R,RS[RR/#)r rOr9Nkwargsr rRr;rr)rr0s"rrr1sG  d38n)= d3PS8nW[F[ nq vz rc R#)adObserve a finished turn (complement of ``select_context()``) to index/update routing state for the next request. Best-effort, not guaranteed: fires from the normal finalization seam only; some abnormal early returns (content-policy block, provider terminal failure) skip it. ``messages`` is a read-only shallow copy (return value ignored; never rely on transcript mutation). ``usage`` has the ``update_from_response`` shape and is ``None`` when no provider response was reached (interrupt). ``kwargs`` may include ``turn_id``, ``task_id``, ``api_call_count``, ``interrupted``, ``failed``, ``turn_exit_reason``. Nr&)r4rOr9rcs&&&,ron_turn_completeContextEngine.on_turn_completes rcL<V^8dQhRS[S[S[S[3,,RS[/#r rOr rRr;rrrD)rr0s"rrr1s($tCH~2F4rc R#)zOCheap rough check before the API call (no real token count yet); default skips.Fr&r4rOs&&rshould_compress_preflight'ContextEngine.should_compress_preflightsrc&<V^8dQhRS[RS[/#)r rough_tokensr rB)rr0s"rrr1src R#)zTrue when preflight should trust recent real usage over the noisy rough estimate (avoids re-compacting after a compressed request already fit).Fr&)r4rps&&r$should_defer_preflight_to_real_usage2ContextEngine.should_defer_preflight_to_real_usagesrc @<V^8dQhRS[RS[RS[RS[R,/#)r r r!r"r N)rr)rr0s"rrr1s7 R R R.1 R>A R t Rrc .VP'dV#R#)a"User-visible status for automatic compaction, or ``None`` to suppress it. ``phase`` is the host call site (``"preflight"`` / ``"compress"``); ``context`` carries best-effort ``approx_tokens`` / ``threshold_tokens``. Warnings, errors and manual ``/compress`` are not governed by this hook. N)r$)r4r r!r"s&$$,rr%5ContextEngine.get_automatic_compaction_status_messages#'"G"G"GQTQrcL<V^8dQhRS[S[S[S[3,,RS[/#rirj)rr0s"rrr1s(T#s(^0Drc R#)zPreflight guard for gateway ``/compress``: False reports "nothing to compress yet" without an LLM call (e.g. transcript entirely protected).Tr&rls&&rhas_content_to_compress%ContextEngine.has_content_to_compresssrc$<V^8dQhRS[RR/#)r session_idr Nr)rr0s"rrr1see3eTerc R#)zVSession begins: load persisted state. kwargs may include hermes_home, platform, model.Nr&)r4r|rcs&&,ron_session_startContextEngine.on_session_startr7rcP<V^8dQhRS[RS[S[S[S[3,,RR/#)r r|rOr N)rrRr;r)rr0s"rrr1s5[[[T#s(^8L[QU[rc R#)uLReal session boundary (CLI exit, /reset, gateway expiry) — never per-turn.Nr&)r4r|rOs&&&ron_session_endContextEngine.on_session_endr7rc<V^8dQhRR/#)r r Nr&)rr0s"rrr1s##$#rc >^Vn^Vn^Vn^VnR#)zO/new or /reset: reset per-session state (default: counters and token tracking).N)last_prompt_tokenslast_completion_tokenslast_total_tokenscompression_countr3s&ron_session_resetContextEngine.on_session_resets$#$&'#!"!"rcF<V^8dQhRS[S[S[S[3,,/#r/rd)rr0s"rrr1s!$tCH~"6rc .#)z>Tool schemas this engine exposes to the agent (default: none).r&r3s&rget_tool_schemasContextEngine.get_tool_schemass rcB<V^8dQhRS[RS[S[S[3,RS[/#)r r5argsr )rr;r)rr0s"rrr1s/MMSMS#XMSMrc 8\P!RRV 2/4#)z~Handle a call to one of this engine's tools; must return a JSON string. kwargs may include ``messages`` (live in-memory list).errorzUnknown context engine tool: )jsondumps)r4r5rrcs&&&,rhandle_tool_callContextEngine.handle_tool_calls zz7&CD6$JKLLrc6<V^8dQhRS[S[S[3,/#r/r:)rr0s"rrr1s   DcN  rc  \VP^4pRTRVPRVPRVP'd$\ ^dWP, ^d,4M^RVP /#)z:Status dict with the standard fields run_agent.py expects.rthreshold_tokenscontext_length usage_percentr)maxrrrminr)r4 last_prompts& r get_statusContextEngine.get_statusso$1115 +  5 5 d11 RVReReReSk4G4G&G#&MNkl !7!7   rc<V^8dQhRR/#)r r r-r&)rr0s"rrr1s###rc .\P!V4#)aTPer-agent instance of a plugin-registered engine (the plugin system holds ONE shared instance; every AIAgent gets its own so a child's update_model() cannot mutate the parent's). Override when the engine holds uncopyable state (locks, DB connections): return a fresh engine sharing the durable backend and copying only mutable budget state.)copydeepcopyr3s&rclone_for_agentContextEngine.clone_for_agents }}T""rcB<V^8dQhRS[RS[RS[RS[RS[RS[RR/#) r modelrbase_urlapi_keyproviderapi_moder N)rrC)rr0s"rrr1sPMMM*-M9<MLOMM&)M Mrc W n^RIHp\VR4'gVPVnV!V\ VR/4VP V4VnVPVn\W P,4Vn R#)uModel switch / fallback: recompute threshold_tokens (override for more). Per-model threshold override (longest substring match), else the raw config percent — snapshotted ONCE so repeated switches fall back to the configured value, not the previous model's override. )resolve_model_threshold_config_threshold_percentmodel_thresholdsN) ragent.context_compressorrhasattrthreshold_percentrr'_base_threshold_percentrCr)r4rrrrrrrs&&&&&&& r update_modelContextEngine.update_modelsu-Dt899-1-C-CD *'> 74!3R8$:X:XZb(d$!%!=!= #N5K5K$K Lrc<V^8dQh/S[;R&S[;R&S[;R&S[;R&S[;R&S[;R&S[;R&S[;R&S[;R &S[;R &#) r rrrrrrrprotect_first_nprotect_last_nr$)rCfloatrD)rr0s"rrr10s #(#)*+,-2'+13r) rrrrrrrrr)N)NNF)rrrr)(__name__ __module__ __qualname____firstlineno____doc__propertyrr5rrrrrrrrrr$r=rGrLrTrXr`rfrmrrr%ryr~rrrrrrr__annotate_func____static_attributes____classdictcell__)r0s@rr-r-0so8 ;; "#N $ON.2$  ???99       nr26MN,   R R ee[[##"MM   ##MMsrr-)rrrabcrrtypingrrrragent.compression_markerr agent.redactr rrrrr+r-r&rrrsP #,,1.!""[ (JMCJMr