`gj5)rdZddlmZmZddlmZmZmZmZddl m Z dZ dZ dZ dZd ed efd ZGd d eZy)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)AnyDictListOptional)redact_sensitive_textipiiz+ ...[memory provider context truncated]... memory_contextreturnct|jdd}t|tkr|S|dtt z|t dzS)zBPrepare provider context for a context-engine/LLM egress boundary.T)forceredact_url_credentialsN)r striplenMEMORY_CONTEXT_MAX_CHARS_MEMORY_CONTEXT_HEAD_CHARS!_MEMORY_CONTEXT_TRUNCATION_MARKER_MEMORY_CONTEXT_TAIL_CHARS)r sanitizeds G/root/.hermes/venv/lib/python3.12/site-packages/agent/context_engine.pysanitize_memory_contextr(s`%#I  9~11--. + , //0 1 2cZeZdZUdZeedefdZdZe 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 d0deeeefdee deedededeeeeff dZdeeeefdefdZde defdZdeeeefdefdZd eddfd!Zd edeeeefddfd"Z d1d#Z!deeeeffd$Z"d%ed&eeefdefd'Z#deeeffd(Z$ d2d)ed e d*ed+ed,ed-eddfd.Z%y)3 ContextEnginez.Base class all context engines must implement.r cy)z,Short identifier (e.g. 'compressor', 'lcm').Nselfs rnamezContextEngine.name=rrlast_prompt_tokenslast_completion_tokenslast_total_tokensthreshold_tokenscontext_lengthcompression_countg?threshold_percentprotect_first_nprotect_last_nusageNcy)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)rr,s rupdate_from_responsez"ContextEngine.update_from_response^r r prompt_tokenscy)z0Return True if compaction should fire this turn.Nr)rr/s rshould_compresszContextEngine.should_compressjr rmessagescurrent_tokens focus_topicr r cy)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. force: Whether a user-requested compression should bypass an engine-owned cooldown. Engines without cooldowns may ignore it. memory_context: Text returned by memory providers immediately before compaction. Summarizing engines should include non-empty text in their handoff prompt. Older engines may omit this parameter; the host filters unsupported optional arguments by signature. Nr)rr2r3r4r r s rcompresszContextEngine.compressnr rcy)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. Frrr2s rshould_compress_preflightz'ContextEngine.should_compress_preflights r rough_tokenscy)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_usagesrcy)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. Trr8s rhas_content_to_compressz%ContextEngine.has_content_to_compresssr session_idc y)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_startr rcy)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?r2s ron_session_endzContextEngine.on_session_endr rc<d|_d|_d|_d|_y)zyCalled on /new or /reset. Reset per-session state. Default resets compression_count and token tracking. rN)r!r"r#r&rs 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. rrs rget_tool_schemaszContextEngine.get_tool_schemass  rrargsc 6ddl}|jdd|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)rrrIrArLs rhandle_tool_callzContextEngine.handle_tool_calls# zz7&CD6$JKLLrc|jdkDr |jnd}||j|j|jrtd||jz dznd|jdS)zsReturn status dict for display/logging. Default returns the standard fields run_agent.py expects. rd)r!r$r% usage_percentr&)r!r$r%minr&)r last_prompts r get_statuszContextEngine.get_statussq261H1H11Ld--RS "- $ 5 5"11&&Ct':'::S@A,-!%!7!7  rmodelbase_urlapi_keyproviderapi_modecL||_t||jz|_y)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)r%intr'r$)rrUr%rVrWrXrYs r update_modelzContextEngine.update_models$- #NT5K5K$K Lr)N)NNF)r N)r]r]r]r])&__name__ __module__ __qualname____doc__propertyrstrrr!r[__annotations__r"r#r$r%r&r'floatr)r+rrr.boolr1rrr6r9r<r>rBrDrFrHrNrTr\rrrrr8s8;c;; "#C#scNCs $u#OSNC  $sCx.  T    ?S?D??)-%)  tCH~& !  c]       d38n   >$tCH~2F4 T#s(^0D   3 T   T#s(^8L QU #$tCH~"6 MS MS#X MS M DcN 6MMM M  M  MM MrrN)raabcrrtypingrrrr agent.redactr rrrrrcrrrrrrjsU6$,,.!""$S! C C  OMCOMr