Mj.dZddlmZddlmZddlmZmZddlm Z edGdd Z edGd d Z edGd d Z edGddZ GddZgdZy)zNavigation and organization layer for the knowledge plane. Provides topic clustering, tag extraction, and a navigation index for easy orientation in the knowledgebase. ) annotations) defaultdict) dataclassfield)KnowledgeDocumentT)frozencleZdZUdZded<ded<eeZded<dZd ed <eeZ ded <y) TopicClusterzA cluster of related documents.str cluster_idlabeldefault_factory list[str] document_idsNzlist[float] | Nonecentroid_vectortags) __name__ __module__ __qualname____doc____annotations__rlistrrrM/home/oem/CyberBrain26-unified/src/cyberbrain26/knowledge_plane/navigation.pyr r s8)O J#D9L)9*.O'.D1D)1rr c:eZdZUdZded<ded<ded<ded <y ) NavigationEntryz4A navigation entry linking a topic to its documents.r topicrrint chunk_countfloat last_updatedNrrrrrrrrrrs> Jrrc:eZdZUdZded<ded<ded<ded<y) EntityEdgezAn edge in the entity relationship graph. Represents a relationship between two entities in documents. Format: (source_entity, target_entity, relationship_type, document_id) r source_entity target_entityrelationship_type document_idNr$rrrr&r&$s! rr&cfeZdZUdZeeZded<eeZded<eeZ ded<y) KnowledgeGraphzA knowledge graph built from document entity relationships. Entities: entity name -> set of related entity names Edges: (source_entity, target_entity) -> list of EntityEdge Entity documents: entity name -> set of document IDs rzdict[str, set[str]]entitieszdict[str, list[EntityEdge]]edgesentity_documentsN) rrrrrdictr-rr.r/rrrr,r,2s:%*$$?H!?).t)DE &D,1$,G)Grr,ceZdZdZddZddZddZddZddZddZ ddZ dd Z dd Z d dd Z dd Z d ddZ d dZd!dZd!dZ d d"dZ d# d$dZy )%KnowledgeNavigatorzOrganizes and navigates the knowledgebase. Provides: - Topic clustering based on document metadata - Tag-based navigation - Full-text search index - Temporal versioning view ctt|_tt|_i|_t |_yN)rr_topics_tags _clustersr, _entity_graphselfs r__init__zKnowledgeNavigator.__init__Js,-8-> +6t+< 24-;-=rc|jjd|jjdd}|j|j|j|jjd|jjdg}t |t r,|jdDcgc]}|j}}|D]*}|j|j|j,|jjd|jjdg}t |t r,|jdDcgc]}|j}}t |tr|D]c}||jvrg|j|<|j|j|vs<|j|j|jet|d kDr?t|D]0\} } || d zd D] } |j| | d |j"2y y y cc}wcc}w) z Index a document for navigation.rclassification_topic uncategorizedrclassification_tags,classification_entitiesr-N co_reference)metadatagetr5appendr* isinstancer splitstripr6rlen enumerateadd_entity_edge) r:documentrrttagr-eentityientity1entity2s r add_documentzKnowledgeNavigator.add_documentQs !!%%gx/@/@/D/DE[]l/mn U""8#7#78  $$VX->->-B-BCXZ\-]^ dC '+zz#7!AGGI7D7 9C JJsO " "8#7#7 8 9$$(()BHDUDUDYDYZdfhDij h $+3>>#+>?a ?H? h %" D+)+DJJv&''tzz&/AAJJv&--h.B.BC  D8}q "+H"5eJAw#+AEF#3e,,Wg~xOcOcdee! &8@s 8H9H>cHt|jjS)zReturn all known topics.)sortedr5keysr9s r get_topicszKnowledgeNavigator.get_topicsosdll'')**rc:|jj|gS)z Return document IDs for a topic.)r5rE)r:rs rget_documents_by_topicz)KnowledgeNavigator.get_documents_by_topicss||r**rc:|jj|gS)zReturn document IDs for a tag.)r6rE)r:rOs rget_documents_by_tagz'KnowledgeNavigator.get_documents_by_tagwszz~~c2&&rcHt|jjS)zReturn all known tags.)rWr6rXr9s r get_all_tagszKnowledgeNavigator.get_all_tags{sdjjoo'((rc g}|jjD],\}}|jt||t |d.t |dS)z'Build a navigation index of all topics.g)rrr!r#c|jSr4)r)rPs rz9KnowledgeNavigator.get_navigation_index..s QWWr)key)r5itemsrFrrJrW)r:entriesrdoc_idss rget_navigation_indexz'KnowledgeNavigator.get_navigation_indexs["ll002 NE7 NN!( #G !$   g#455rctt}|D]`}d}d|jvr0|jjddjdd}||j |j bt |S)z)Group documents by their source URI host.unknownz://rB/r)rr source_urirHrFr*r0)r: documentsclustersdochosts rcluster_by_sourcez$KnowledgeNavigator.cluster_by_sourcesw)4T): 3CD&~~++E215;;C@C TN ! !#// 2  3 H~rc|j}g}|D]}|jjD]B}t|ts||jvs'|j |j n||jjvs|j |vs|j |j |S)z-Simple keyword search over document metadata.)lowerrDvaluesrGr rFr*rk)r:keywordrl keyword_lowerresultsrnvalues rsearch_by_keywordz$KnowledgeNavigator.search_by_keywords   0C,,. eS)mu{{}.LNN3??3   4 4 663??RY;Ys/ 0rNc|jsyy)u MemStrata pattern: deterministic staleness check. Returns True if document is currently valid, False if superseded. Uses (subject, relation, object) supersedence rule — no similarity threshold, no LLM call for stale fact retirement. TF) superseded_by)r:rM current_times rcheck_temporal_validityz*KnowledgeNavigator.check_temporal_validitys%%rcP|Dcgc]}|j|s|c}Scc}w)z8Filter out superseded documents using temporal validity.)r|)r:rlds rget_valid_documentsz&KnowledgeNavigator.get_valid_documentss%%Ha(D(DQ(GHHHs##cPddlm}|ddl}|j}||||S)zMark a document as superseded (MemStrata bi-temporal ledger). Sets valid_to to current time and records the superseding document ID. r)replaceN)valid_torz) dataclassesrtime)r:rMrzr{rrs rsupersede_documentz%KnowledgeNavigator.supersede_documents1 (   99;L !'  rc||jjvr!t|jj|<||jjvr!t|jj|<||jjvr!t|jj|<||jjvr!t|jj|<|jj|j ||jj|j |t ||||}|d|}||jj vrg|jj |<|jj |j||jj|j ||jj|j |y)zAdd an edge to the entity relationship graph. Tracks co-occurrence and relationships between entities extracted from document classification metadata. )r'r(r)r*->N)r8r-setr/addr&r.rF)r:r'r(r)r*edgeedge_keys rrLz"KnowledgeNavigator.add_entity_edges  2 2 ; ; ;9<D   ' ' 6  2 2 ; ; ;9<D   ' ' 6  2 2 C C CADD   / / >  2 2 C C CADD   / / > ##M266}E ##M266}E''/#   $_B}o6 4--33 313D   $ $X .   *11$7 ++M:>>{K ++M:>>{Krcpt|jjj|t S)z5Return entities directly related to the given entity.)rWr8r-rErr:rQs rget_entity_neighborsz'KnowledgeNavigator.get_entity_neighborss(d((1155fceDEErcpt|jjj|t S)z0Return document IDs containing the given entity.)rWr8r/rErrs rget_entity_documentsz'KnowledgeNavigator.get_entity_documentss(d((99==fceLMMrcg}|jjjD]X\}}|j|ds|j d|s/|D]%}||j |k(s|j |'Z|S)zsReturn all relationship edges involving the given entity. Optionally filter by relationship type. r)r8r.rd startswithendswithr)rF)r:rQr)r.rc edge_listrs rget_entity_relationshipsz+KnowledgeNavigator.get_entity_relationshipss#%"0066<<> +NC~~m, r&]0K%+D(0D4J4JN_4_ T*+ +  rc&|dkriS|h}|g}i}d}|r}||krxg}|D]b} |j| } | D]J} | |vs|j| |j| |j|gj| Ld|}|dz }|r||krx|S)a^Return entities related to the given entity up to a traversal depth. Performs breadth-first traversal over the entity relationship graph. Returns a dict mapping distance -> list of entity names. depth=1 returns immediate neighbors (distance 1). depth=2 returns neighbors + their neighbors (distance 1 and 2). rB)rrrF setdefault) r:rQdepthr)visitedfrontierresult current_depth next_frontiercurrent_entity neighborsneighbors rget_related_entitiesz'KnowledgeNavigator.get_related_entitiess 19I#H%h') =E1')M"* N 55nE )NHw. H-%,,X6))-<CCHM N N%H Q M=E1 r)returnNone)rMrrr)rr)rr rr)rOr rr)rzlist[NavigationEntry])rllist[KnowledgeDocument]rzdict[str, list[str]])rtr rlrrrr4)rMrr{ float | Nonerbool)rlrrr)rMrrzr r{rrr) r'r r(r r)r r*r rr)rQr rr)rQr r) str | Nonerzlist[EntityEdge])rBN)rQr rr r)rrzdict[int, list[str]])rrrrr;rUrYr[r]r_rgrprxr|rrrLrrrrrrrr2r2@s?>e<++') 6  IM ) 9E   I0I I&*  #  #    8#L#L#L #L  #L  #LJFN <@  .8   $(, """& "  "rr2)r&r,r2rr N)r __future__r collectionsrrrr&cyberbrain26.knowledge_plane.contractsrr rr&r,r2__all__rrrrs ##(D $222 $ $    $ H H Hssj dr