ixJdZddlmZmZddlmZmZmZGddeZdS)uAbstract base class for pluggable context engines. A context engine controls how conversation context is managed when approaching the model's token limit. The built-in ContextCompressor is the default implementation. Third-party engines (e.g. LCM) can replace it via the plugin system or by being placed in the ``plugins/context_engine//`` directory. Selection is config-driven: ``context.engine`` in config.yaml. Default is ``"compressor"`` (the built-in). Only one engine is active. The engine is responsible for: - Deciding when compaction should fire - Performing compaction (summarization, DAG construction, etc.) - Optionally exposing tools the agent can call (e.g. lcm_grep) - Tracking token usage from API responses Lifecycle: 1. Engine is instantiated and registered (plugin register() or default) 2. on_session_start() called when a conversation begins 3. update_from_response() called after each API response with usage data 4. should_compress() checked after each turn 5. compress() called when should_compress() returns True 6. on_session_end() called at real session boundaries (CLI exit, /reset, gateway session expiry) — NOT per-turn )ABCabstractmethod)AnyDictListc eZdZUdZeedefdZdZe e d<dZ e e d<dZ e e d<dZ e e d<dZe e d <dZe e d <d Zee d <d Ze e d<dZe e d<edeeefddfdZed+de defdZe d,deeeefde dedeeeeffdZdeeeefdefdZdeeeefdefdZdeddfdZdedeeeefddfdZd-dZdeeeeffd Z d!ed"eeefdefd#Z!deeeffd$Z" d.d&ed e d'ed(ed)eddf d*Z#dS)/ ContextEnginez.Base class all context engines must implement.returncdS)z,Short identifier (e.g. 'compressor', 'lcm').Nselfs 9/home/ubuntu/.hermes/hermes-agent/agent/context_engine.pynamezContextEngine.name%rlast_prompt_tokenslast_completion_tokenslast_total_tokensthreshold_tokenscontext_lengthcompression_countg?threshold_percentprotect_first_nprotect_last_nusageNcdS)zUpdate tracked token usage from an API response. Called after every LLM call with the usage dict from the response. Nr )rrs rupdate_from_responsez"ContextEngine.update_from_responseArr prompt_tokenscdS)z0Return True if compaction should fire this turn.Nr )rr!s rshould_compresszContextEngine.should_compressHrrmessagescurrent_tokens focus_topiccdS)uCompact the message list and return the new message list. This is the main entry point. The engine receives the full message list and returns a (possibly shorter) list that fits within the context budget. The implementation is free to summarize, build a DAG, or do anything else — as long as the returned list is a valid OpenAI-format message sequence. Args: focus_topic: Optional topic string from manual ``/compress ``. Engines that support guided compression should prioritise preserving information related to this topic. Engines that don't support it may simply ignore this argument. Nr )rr$r%r&s rcompresszContextEngine.compressLrrcdS)zQuick rough check before the API call (no real token count yet). Default returns False (skip pre-flight). Override if your engine can do a cheap estimate. Fr rr$s rshould_compress_preflightz'ContextEngine.should_compress_preflightds urcdS)uQuick check: is there anything in ``messages`` that can be compacted? Used by the gateway ``/compress`` command as a preflight guard — returning False lets the gateway report "nothing to compress yet" without making an LLM call. Default returns True (always attempt). Engines with a cheap way to introspect their own head/tail boundaries should override this to return False when the transcript is still entirely protected. Tr r*s rhas_content_to_compressz%ContextEngine.has_content_to_compressns tr session_idc dS)zCalled when a new conversation session begins. Use this to load persisted state (DAG, store) for the session. kwargs may include hermes_home, platform, model, etc. Nr )rr.kwargss ron_session_startzContextEngine.on_session_start}rrcdS)uCalled at real session boundaries (CLI exit, /reset, gateway expiry). Use this to flush state, close DB connections, etc. NOT called per-turn — only when the session truly ends. Nr )rr.r$s ron_session_endzContextEngine.on_session_endrrc>d|_d|_d|_d|_dS)zyCalled on /new or /reset. Reset per-session state. Default resets compression_count and token tracking. rN)rrrrr s ron_session_resetzContextEngine.on_session_resets* #$&'#!"!"rcgS)zReturn tool schemas this engine provides to the agent. Default returns empty list (no tools). LCM would return schemas for lcm_grep, lcm_describe, lcm_expand here. r r s rget_tool_schemaszContextEngine.get_tool_schemass  rrargsc >ddl}|dd|iS)zHandle a tool call from the agent. Only called for tool names returned by get_tool_schemas(). Must return a JSON string. kwargs may include: messages: the current in-memory message list (for live ingestion) rNerrorzUnknown context engine tool: )jsondumps)rrr8r0r;s rhandle_tool_callzContextEngine.handle_tool_calls-  zz7$JD$J$JKLLLrc|j|j|j|jr td|j|jz dznd|jdS)zsReturn status dict for display/logging. Default returns the standard fields run_agent.py expects. dr)rrr usage_percentr)rrrminrr s r get_statuszContextEngine.get_statussZ #'"9 $ 5"1&.C043FFLMMM,-!%!7   rmodelbase_urlapi_keyprovidercL||_t||jz|_dS)aCalled when the user switches models or on fallback activation. Default updates context_length and recalculates threshold_tokens from threshold_percent. Override if your engine needs more (e.g. recalculate DAG budgets, switch summary models). N)rintrr)rrDrrErFrGs r update_modelzContextEngine.update_models*- #NT5K$K L Lr)N)NN)r N)rCrCrC)$__name__ __module__ __qualname____doc__propertyrstrrrrI__annotations__rrrrrrfloatrrrrr boolr#rr(r+r-r1r3r5r7r=rBrJr rrr r sv88;c;;;^X; "#C###scNCs $u###OSNC $sCx. T   ^ ??S?D???^?#   tCH~&    d38n     ^ .$tCH~2F4 T#s(^0D      3 T      T#s(^8L QU    ####$tCH~"6 MS MS#X MS M M M M DcN    , MMMM M  M  M MMMMMMrr N) rNabcrrtypingrrrr r rrrVs6$#######""""""""""nMnMnMnMnMCnMnMnMnMnMr