j"JdZddlmZmZddlmZmZmZGddeZdS)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)AnyDictListceZdZUdZeedefdZdZe 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 dedeeeeffdZdeeeefdefdZde defdZdeeeefdefdZdeddfdZdedeeeefddfd Zd0d!Z deeeeffd"Z!d#ed$eeefdefd%Z"deeeffd&Z# d1d(ed e d)ed*ed+ed,eddfd-Z$dS)2 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)aUpdate tracked token usage from an API response. Called after every LLM call with a normalized usage dict. The legacy keys ``prompt_tokens``, ``completion_tokens``, and ``total_tokens`` are always present. Newer hosts also include canonical buckets: ``input_tokens``, ``output_tokens``, ``cache_read_tokens``, ``cache_write_tokens``, and ``reasoning_tokens``. Engines should treat those fields as optional for compatibility with older hosts. Nr )rrs rupdate_from_responsez"ContextEngine.update_from_responseFrr prompt_tokenscdS)z0Return True if compaction should fire this turn.Nr )rr!s rshould_compresszContextEngine.should_compressRrrmessagescurrent_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.compressVrrcdS)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_preflightns ur rough_tokenscdS)aReturn True when preflight should trust recent real usage instead. Built-in compression uses this to avoid re-compacting from known-noisy rough estimates after a compressed request has already fit. Third-party engines can ignore it safely. Fr )rr,s r$should_defer_preflight_to_real_usagez2ContextEngine.should_defer_preflight_to_real_usagevs 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_compresss 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 )rr1kwargss ron_session_startzContextEngine.on_session_startrrcdS)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 )rr1r$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)rrr;r3r>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_keyproviderapi_modecL||_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)rrGrrHrIrJrKs r update_modelzContextEngine.update_models*- #NT5K$K L Lr)N)NN)r N)rFrFrFrF)%__name__ __module__ __qualname____doc__propertyrstrrrrM__annotations__rrrrrrfloatrrrrr boolr#rr(r+r.r0r4r6r8r:r@rErNr rrr r s88;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  MM MMMMMMrr N) rRabcrrtypingrrrr r rrrZs6$#######""""""""""BMBMBMBMBMCBMBMBMBMBMr