$j@dZddlmZmZddlmZddlmZmZerddlm Z ddl m Z m Z ddl mZddlmZGd d eZd S) aAbstract interface for MemoryEngine public methods. This module defines the public API that HTTP endpoints and extensions should use to interact with the memory system. All methods require a RequestContext for authentication when a TenantExtension is configured. )ABCabstractmethod)datetime) TYPE_CHECKINGAny)Budget) RecallResult ReflectResult) TagsMatch)RequestContextceZdZdZedefdZedddedeeee fdd d eedzdeee ff d Z edd d ddd dd dd dededdde de deedzde dzde de de de dd ddfdZeddd dddededddedzde d edzdd dd!fd"Zedd deeee ffd#Zed$d%dedd d&e deee fdzfd'Zeded(eee fdd ddfd)Zeded*edd deee ffd+Zeded,edd deee ffd-Zedd$d.dededzd/e dd deee ff d0Zeddd1d2d3dededzd4edzd5e d6e dd deee ffd7Zedd8d9dededzd5e dd deee ff d:Zeddd;d1d2d<ded4edzd=eedzd>d?d5e d6e dd deee ffd@ZedAededd deee fdzfdBZedAededd deee ffdCZedDedd deee fdzfdEZed1d2dFded5e d6e dd deee ff dGZededd deee ffdHZededIedd deee fdzfdJZededd deee ffdKZededLedd deee ffdMZ edddNdedOedzd,edzdd deee ff dPZ!edddedeeee fdd d eedzdeee ff dQZ"dS)RMemoryEngineInterfacez Abstract interface for the Memory Engine. This defines the public API that should be used by HTTP endpoints and extensions. All methods require a RequestContext for authentication. returnc KdS)z Check the health of the memory system. Returns: Dict with 'status' key ('healthy' or 'unhealthy') and additional info. N)selfs f/home/rurouni/.hermes/hermes-agent/venv/lib/python3.11/site-packages/hindsight_api/engine/interface.py health_checkz"MemoryEngineInterface.health_checks  N) document_tagsbank_idcontentsrequest_contextr rc KdS)a Retain a batch of memory items. Args: bank_id: The memory bank ID. contents: List of content dicts with 'content', optional 'event_date', 'context', 'metadata', 'document_id', and per-item 'tags'. request_context: Request context for authentication. document_tags: Optional tags applied to all items in the batch. Returns: Dict with processing results. Nrrrrrrs rretain_batch_asyncz(MemoryEngineInterface.retain_batch_async- , riFii ) budget max_tokens enable_trace fact_type question_dateinclude_entitiesmax_entity_tokensinclude_chunksmax_chunk_tokensqueryrz Budget | Nonerr r!r"r#r$r%r&r c  KdS)a Recall memories relevant to a query. Args: bank_id: The memory bank ID. query: The search query. budget: Search budget (LOW, MID, HIGH). max_tokens: Maximum tokens in response. enable_trace: Include trace information. fact_type: Filter by fact types. question_date: Context date for temporal relevance. include_entities: Include entity observations. max_entity_tokens: Max tokens for entity observations. include_chunks: Include raw chunks. max_chunk_tokens: Max tokens for chunks. request_context: Request context for authentication. Returns: RecallResult with matching memories. Nr) rrr'rrr r!r"r#r$r%r&rs r recall_asyncz"MemoryEngineInterface.recall_asyncEsJ r)rcontextrresponse_schemar*r+r c KdS)aB Reflect on a query and generate a thoughtful response. Args: bank_id: The memory bank ID. query: The question to reflect on. budget: Search budget for retrieving context. context: Additional context for the reflection. max_tokens: Maximum tokens for the response. response_schema: Optional JSON Schema for structured output. request_context: Request context for authentication. Returns: ReflectResult with generated response and supporting facts. Nr)rrr'rr*rr+rs r reflect_asyncz#MemoryEngineInterface.reflect_asyncl 6 rc KdS)z List all memory banks. Args: request_context: Request context for authentication. Returns: List of bank info dicts. Nr)rrs r list_banksz MemoryEngineInterface.list_bankss  rT)create_if_missingr1c KdS)uX Get bank profile including disposition and mission. Args: bank_id: The memory bank ID. request_context: Request context for authentication. create_if_missing: If True (default), the bank is auto-created with defaults if it does not exist. Pass False to make this a strict read — returns None if the bank does not exist. Returns: Bank profile dict with bank_id, name, disposition, and mission, or None when create_if_missing=False and the bank does not exist. Nr)rrrr1s rget_bank_profilez&MemoryEngineInterface.get_bank_profiles . r dispositionc KdS)z Update bank disposition traits. Args: bank_id: The memory bank ID. disposition: Dict with trait values. request_context: Request context for authentication. Nr)rrr4rs rupdate_bank_dispositionz-MemoryEngineInterface.update_bank_dispositions rnew_infoc KdS)a' Merge new mission information into bank profile. Args: bank_id: The memory bank ID. new_info: New mission information to merge. request_context: Request context for authentication. Returns: Updated mission info. Nr)rrr7rs rmerge_bank_missionz(MemoryEngineInterface.merge_bank_mission & rmissionc KdS)a Set the bank's mission (replaces existing). Args: bank_id: The memory bank ID. mission: The mission text. request_context: Request context for authentication. Returns: Dict with bank_id and mission. Nr)rrr;rs rset_bank_missionz&MemoryEngineInterface.set_bank_missionr:r)r!delete_bank_profiler>c KdS)a Delete a bank or its memories. Args: bank_id: The memory bank ID. fact_type: If specified, only delete memories of this type. delete_bank_profile: If True, also delete the bank profile row itself. If False, only delete memories/entities/documents but preserve the bank. request_context: Request context for authentication. Returns: Dict with deletion counts. Nr)rrr!r>rs r delete_bankz!MemoryEngineInterface.delete_bankrrdr)r! search_querylimitoffsetrBrCrDc KdS)a List memory units with pagination. Args: bank_id: The memory bank ID. fact_type: Filter by fact type. search_query: Full-text search query. limit: Maximum results. offset: Pagination offset. request_context: Request context for authentication. Returns: Dict with 'items', 'total', 'limit', 'offset'. Nr)rrr!rBrCrDrs rlist_memory_unitsz'MemoryEngineInterface.list_memory_unitss 2 ri)r!rCc KdS)at Get graph data for visualization. Args: bank_id: The memory bank ID. fact_type: Filter by fact type. limit: Maximum number of items to return (default: 1000). request_context: Request context for authentication. Returns: Dict with nodes, edges, table_rows, total_units, limit. Nr)rrr!rCrs rget_graph_dataz$MemoryEngineInterface.get_graph_data* * r any_strict)rBtags tags_matchrCrDrKrLr c KdS)a List documents with pagination. Args: bank_id: The memory bank ID. search_query: Case-insensitive substring filter on document ID. tags: Filter by tags. tags_match: How to match tags (any, all, any_strict, all_strict). limit: Maximum results. offset: Pagination offset. request_context: Request context for authentication. Returns: Dict with 'items', 'total', 'limit', 'offset'. Nr)rrrBrKrLrCrDrs rlist_documentsz$MemoryEngineInterface.list_documentsEr.r document_idc KdS)a Get a specific document. Args: document_id: The document ID. bank_id: The memory bank ID. request_context: Request context for authentication. Returns: Document dict or None if not found. NrrrOrrs r get_documentz"MemoryEngineInterface.get_documentbr:rc KdS)a Delete a document and its memory units. Args: document_id: The document ID. bank_id: The memory bank ID. request_context: Request context for authentication. Returns: Dict with deletion counts. NrrQs rdelete_documentz%MemoryEngineInterface.delete_documentwr:rchunk_idc KdS)z Get a specific chunk. Args: chunk_id: The chunk ID. request_context: Request context for authentication. Returns: Chunk dict or None if not found. Nr)rrUrs r get_chunkzMemoryEngineInterface.get_chunk " r)rCrDc KdS)aH List entities for a bank with pagination. Args: bank_id: The memory bank ID. limit: Maximum results. offset: Offset for pagination. request_context: Request context for authentication. Returns: Dict with items, total, limit, offset. Nr)rrrCrDrs r list_entitiesz#MemoryEngineInterface.list_entitiesrIrc KdS)aP Get statistics about memory nodes and links for a bank. Args: bank_id: The memory bank ID. request_context: Request context for authentication. Returns: Dict with node_counts, link_counts, link_counts_by_fact_type, link_breakdown, and operations stats. Nrrrrs rget_bank_statsz$MemoryEngineInterface.get_bank_statss $ r entity_idc KdS)a Get entity details including metadata and observations. Args: bank_id: The memory bank ID. entity_id: The entity ID. request_context: Request context for authentication. Returns: Entity dict with id, canonical_name, mention_count, first_seen, last_seen, metadata, and observations. None if not found. Nr)rrr^rs r get_entityz MemoryEngineInterface.get_entitys ( rc KdS)a List async operations for a bank. Args: bank_id: The memory bank ID. request_context: Request context for authentication. Returns: Dict with 'total' (int) and 'operations' (list of operation dicts). Nrr\s rlist_operationsz%MemoryEngineInterface.list_operationsrXr operation_idc KdS)ag Cancel a pending async operation. Args: bank_id: The memory bank ID. operation_id: The operation ID to cancel. request_context: Request context for authentication. Returns: Dict with success status and message. Raises: ValueError: If operation not found. Nr)rrrcrs rcancel_operationz&MemoryEngineInterface.cancel_operationrr)namer;rfc KdS)aU Update bank name and/or mission. Args: bank_id: The memory bank ID. name: New bank name (optional). mission: New mission text (optional, replaces existing). request_context: Request context for authentication. Returns: Updated bank profile dict. Nr)rrrfr;rs r update_bankz!MemoryEngineInterface.update_bankrIrc KdS)a Submit a batch retain operation to run asynchronously. Args: bank_id: The memory bank ID. contents: List of content dicts to retain. request_context: Request context for authentication. document_tags: Optional tags applied to all items in the async batch. Returns: Dict with operation_id and items_count. Nrrs rsubmit_async_retainz)MemoryEngineInterface.submit_async_retain*rIr)#__name__ __module__ __qualname____doc__rdictrstrlistrrintboolrr)r-r0r3r6r9r=r@rFrHrNrRrTrWrZr]r`rbrerhrjrrrrrs%  D   ^ +/     tCH~& *  Cy4'   c3h   ^ . #'"&*)-!&!$$ $$ $ $ $ $  $  $ $ 9t#$  $$ $ $ $ $ *$  $ $ $ ^$ L #'"'+       t    *     ^ @ *  d38n     ^  #'     *    c3h$     ^ 0  #s(^ *      ^ "   *  c3h    ^ (   *  c3h    ^ ( !%$(     :  "  *   c3h   ^ 6 !%#'    :  Dj     *  c3h   ^ 4 !%     :    *   c3h   ^ 4 $(!%".    Dj  3i$      *  c3h   ^ 8   *  c3h$     ^ (   *  c3h    ^ (  *  c3h$     ^ ,          *   c3h   ^ 4  *  c3h    ^ &   *  c3h$     ^ *  *  c3h    ^ $   *  c3h    ^ .  "     Dj  t  *   c3h   ^ ,+/     tCH~& *  Cy4'   c3h   ^   rrN)rnabcrrrtypingrr"hindsight_api.engine.memory_enginer$hindsight_api.engine.response_modelsr r hindsight_api.engine.search.tagsr hindsight_api.modelsr rrrrrzs$#######%%%%%%%%4999999PPPPPPPP::::::333333l l l l l Cl l l l l r