$jK?dZddlZddlmZmZddlmZmZddlmZm Z m Z m Z m Z m Z mZmZmZmZmZmZmZmZGddZdS) z Search tracer for collecting detailed search execution traces. The SearchTracer collects comprehensive information about each step of the spreading activation search process for debugging and visualization. N)UTCdatetime)AnyLiteral) EntryPointLinkInfo NodeVisitPruningDecision QueryInfoRerankedResultRetrievalMethodResultsRetrievalResultRRFMergeResultSearchPhaseMetrics SearchSummary SearchTraceTemporalConstraintWeightComponentscdeZdZdZ d@dedededeedzdedzf dZd Zd ee fd Z d e dzd e dzfdZ dedede defdZ dededede dzdededzdeddzde dzde de de de de fd Z dAd"ed#ededde d$edzd%e dzd&ed'edzd(efd)Zded*ed+de fd,ZdBd-ed.e d/eeefdzfd0Z d@d1ed2d3eed.e d4ed5eeefdzd6edzf d7Zd8eefd9Zd:eeeefd;efd<Zd=eeeefd>efd?ZdS)C SearchTracera Tracer for collecting detailed search execution information. Usage: tracer = SearchTracer(query="Who is Alice?", budget=50, max_tokens=4096) tracer.start() # During search... tracer.record_query_embedding(embedding) tracer.add_entry_point(node_id, text, similarity, rank) tracer.visit_node(...) tracer.prune_node(...) # After search... trace = tracer.finalize(final_results) json_output = trace.to_json() Nquerybudget max_tokenstags tags_matchc6||_||_||_||_||_d|_d|_g|_g|_g|_ g|_ d|_ g|_ g|_ g|_d|_t!|_d|_d|_d|_dS)a? Initialize tracer. Args: query: Search query text budget: Maximum nodes to explore max_tokens: Maximum tokens to return in results tags: Tags filter applied to recall tags_match: Tags matching mode (any, all, any_strict, all_strict) Nr) query_textrrrrquery_embedding start_time entry_pointsvisitspruned phase_metricstemporal_constraintretrieval_results rrf_mergedreranked current_stepsetnodes_visited_settemporal_links_followedsemantic_links_followedentity_links_followed)selfrrrrrs j/home/rurouni/.hermes/hermes-agent/venv/lib/python3.11/site-packages/hindsight_api/engine/search/tracer.py__init__zSearchTracer.__init__1s$  $ $48(,.0') -/ 79?C @B02.0 !$()$'($%&"""c6tj|_dS)zStart timing the search.N)timer )r/s r0startzSearchTracer.startbs)++r2 embeddingc||_dS)zRecord the query embedding.N)r)r/r6s r0record_query_embeddingz#SearchTracer.record_query_embeddingfs(r2r5endc>||t|||_dSdS)zr?s r0add_entry_pointzSearchTracer.add_entry_pointos`c#z2233    !+         r2context event_dateis_entry_pointparent_node_id link_type)temporalsemanticentity link_weight activationsemantic_similarityrecency frequency final_weightcZ|xjdz c_|j|tdt d| } tdt d| } tdt d| } t | | | | | d| zd| zd| zd| z }t |j|||||||||gd }|j||d kr|xj dz c_ dS|d kr|xj dz c_ dS|d kr|xj dz c_ dSdS) a Record visiting a node. Args: node_id: Memory unit ID text: Memory unit text context: Memory unit context event_date: When the memory occurred is_entry_point: Whether this is an entry point parent_node_id: Node that led here (None for entry points) link_type: Type of link from parent link_weight: Weight of link from parent activation: Activation score semantic_similarity: Semantic similarity to query recency: Recency weight frequency: Frequency weight final_weight: Combined final weight rrArBg333333?g?g333333?) rQrRrSrTrUactivation_contributionsemantic_contributionrecency_contributionfrequency_contributionN) stepr<r=rHrIrJrKrLrPweightsneighbors_explored final_rankrMrNrO) r)r+addrDrErr r"rFr,r-r.)r/r<r=rHrIrJrKrLrPrQrRrSrTrUr\visits r0 visit_nodezSearchTracer.visit_nodesD Q ""7+++"#s30C'D'DEEc3sG,,--Si0011 #! 3%$'*$4"%(;";!%#')#3    "!))#!     5!!!  " "  ( (A - ( ( ( ( * $ $  ( (A - ( ( ( ( ( " "  & &! + & & & &# "r2F from_node_id to_node_id entity_idnew_activationfollowed prune_reasonis_supplementaryc d} |jD]} | j|kr| } n| dSt|||||||| } | j| dS)aO Record a link to a neighbor (whether followed or not). Args: from_node_id: Source node to_node_id: Target node link_type: Type of link link_weight: Weight of link entity_id: Entity ID if link is entity-based new_activation: Activation passed to neighbor (None for supplementary links) followed: Whether link was followed prune_reason: Why link was not followed (if not followed) is_supplementary: Whether this is a supplementary link (multiple connections) N)rcrLrPrdrerfrgrh)r"r<r r]rF) r/rbrcrLrPrdrerfrgrhr`v link_infos r0add_neighbor_linkzSearchTracer.add_neighbor_links6  AyL(() = F!#)%-      '' 22222r2reason)already_visitedactivation_too_lowbudget_exhaustedc l|jt||||jdzdS)z Record a node being pruned (not visited). Args: node_id: Node that was pruned reason: Why it was pruned activation: Activation value when pruned r)r<rmrQwould_have_been_stepN)r#rFr r))r/r<rmrQs r0 prune_nodezSearchTracer.prune_nodesN  %%)%6%:         r2 phase_nameduration_secondsdetailsc^|jt|||pidS)z Record metrics for a search phase. Args: phase_name: Name of the phase duration_seconds: Time taken details: Additional phase-specific details )rtrurvN)r$rFr)r/rtrurvs r0add_phase_metriczSearchTracer.add_phase_metricsH !! %!1 2        r2 method_name)rNbm25graphrMresults score_fieldmetadata fact_typec g}t|dD]\}\} } | |} | d} |t|| | dpd| dpd| d| d p|| | |jt |||||pi dS) a Record results from a single retrieval method. Args: method_name: Name of the retrieval method results: List of (doc_id, data) tuples from retrieval duration_seconds: Time taken for this retrieval score_field: Field name containing the score in data dict metadata: Optional metadata about this retrieval method fact_type: Fact type this retrieval was for (world, experience) rr5NrBr=rHrIr)r?r<r=rHrIrscore score_name)ryrr|rur~) enumerategetrFrr&r) r/ryr|rur}r~rr&r?doc_iddatars r0add_retrieval_resultsz"SearchTracer.add_retrieval_results0s($-gQ$?$?$?   D.64HH[))E}  $ $"&))/R HHY//52#xx 55"hh{33@y*        %% "'#)!1!R         r2merged_resultsc g|_t|dD]q\}\}}}|jt||dd|dd|di|rd S) z Record RRF merged results. Args: merged_results: List of (doc_id, data, rrf_meta) tuples from RRF merge rrr=r rrf_scorerB source_ranks)r<r=rrfinal_rrf_rankN)r'rrFrr)r/rr?rrrrf_metas r0add_rrf_mergedzSearchTracer.add_rrf_merged`s.7a.P.P.P   *D*64 O " ""&"--≪<&:?{??????r2r)rr4rrtypingrrrrr r r r r rrrrrrrrrrr2r0rs& """"""""$CCCCCCCCCCr2