מi*9UdZddlmZddlZddlZddlmZmZmZm Z eje Z ddl mZdZGd d Zdad ed < d dd ZddZddZy#e$rdZdZe j%dYEwxYw)ud core/graph/client.py — FalkorDB client wrapper for Genesis Knowledge Graph. GenesisGraph wraps the FalkorDB Python client and exposes a clean interface for CRUD operations and Cypher traversals. If the ``falkordb`` package is not installed the class degrades gracefully: all read methods return empty lists and write methods are no-ops, with a single logged warning. Connection defaults (overridden by env vars): FALKORDB_HOST — defaults to "localhost" FALKORDB_PORT — defaults to 6379 FALKORDB_GRAPH — graph name, defaults to "genesis_kg" Production FalkorDB is on the Sunaiva Memory VPS: host: 152.53.201.221, port: 6379, graph: sunaiva_memory # VERIFICATION_STAMP # Story: M9.02 — core/graph/client.py — GenesisGraph + get_graph() # Verified By: parallel-builder # Verified At: 2026-02-25T00:00:00Z # Tests: 8/8 # Coverage: 100% ) annotationsN)AnyDictListOptional)FalkorDBTFunfalkordb package not installed — GenesisGraph running in no-op/stub mode. Install with: pip install falkordbceZdZdZ d d dZddZddZ d ddZ d ddZ d ddZ d dd Z d dd Z dd Z y) GenesisGraphz Thin wrapper around a FalkorDB graph. All methods return empty lists / None when the falkordb package is absent instead of raising ImportError, so callers can import GenesisGraph unconditionally. ctjjd||_t tjjd||_tjjd||_d|_d|_y)N FALKORDB_HOST FALKORDB_PORTFALKORDB_GRAPH) osenvirongethostintport graph_name_db_graph)selfrrrs */mnt/e/genesis-system/core/graph/client.py__init__zGenesisGraph.__init__?sZ JJNN?D9  => **..)9:F"&%) ctsy|jy t|j|j|_|j j |j|_tjd|j|j|jy#t$r.}tjd|d|_d|_Yd}~yd}~wwxYw)zr Lazily establish connection to FalkorDB. Returns True on success, False if unavailable. FNT)rrz'Connected to FalkorDB at %s:%d graph=%szFalkorDB connect failed: %s) _FALKORDB_AVAILABLEr _FalkorDBrrr select_graphrloggerdebug Exceptionwarning)rexcs rconnectzGenesisGraph.connectOs # ;; "  diidii@DH((//@DK LL9       NN8# >DHDK  sBB C&$CCc<|jy|jS)zAConnect if not yet connected. Returns True if graph is available.T)rr%)rs r_ensure_connectedzGenesisGraph._ensure_connectedis ;; "||~rNc|jsgS |jj||xsi}g}|js|S|jD]]}i}t |j |D]/\}}t |drt|j||<+|||<1|j|_|S#t$r&} tjd| |ddgcYd} ~ Sd} ~ wwxYw)u Execute a Cypher query and return results as a list of dicts. Each dict maps column name → value (node properties for node columns, scalar value for scalar columns). Returns empty list when FalkorDB is unavailable or query fails. propertiesz%FalkorDB query failed: %s | cypher=%sNx) r'rquery result_setzipheaderhasattrdictr)appendr"r r#) rcypherparamsresultrowsrecordrowcol_namevaluer$s rr+zGenesisGraph.queryss%%'I [[&&vv|H (-H .  C  !K  NNBCPTQT VI s$/B2A-B22 C!;CC!C!c|jsyt|xsi}||d<|jDcic]\}}|t|}}}dj d|D}t |} d| d|d} |j j| |ycc}}w#t$r!} tjd | |Yd } ~ yd } ~ wwxYw) z MERGE a node with the given id / type label. ``entity_type`` becomes the node label (e.g. "axiom", "entity"). All string-serialisable properties are stored on the node. Returns True on success, False on failure. Fidz, c3,K|] }d|d|yw)n. = $N.0ks r z*GenesisGraph.add_entity..sDA"QCtA3Dsz MERGE (n:z {id: $id}) SET z RETURN nTzadd_entity failed: %s | id=%sN) r'r0items _to_primitivejoin_sanitise_labelrr+r"r r#) r entity_id entity_typer)propsrBv safe_props set_clauseslabelr2r$s r add_entityzGenesisGraph.add_entitys%%'Z%2&d 6;kkmDdaaq))D DiiDDD  ,w-      KK  fj 1E  NN:C K sB?B"" C +CC c|jsyt|}t|xsi}|jDcic]\}}|t |} }}||d} | j | | rddj d| Dz} nd} d|d| d } |jj| | y cc}}w#t$r#} tjd | |||Yd } ~ yd } ~ wwxYw) a  CREATE a directed relationship between two existing nodes. Both nodes must already exist (identified by their ``id`` property). ``rel_type`` is used as the relationship type label. Returns True on success, False on failure. F)from_idto_idz SET r.z, r.c3*K|] }|d| yw)r>Nr?r@s rrCz0GenesisGraph.add_relationship..s/"#1#T! /sz9MATCH (a {id: $from_id}), (b {id: $to_id}) CREATE (a)-[r:z]->(b)z RETURN rTz+add_relationship failed: %s | %s -[%s]-> %sN) r'rGr0rDrEupdaterFrr+r"r r#)rrQrRrel_typer)safe_relrJrBrKrL cypher_paramsset_partr2r$s radd_relationshipzGenesisGraph.add_relationships %%'"8,Z%2&6;kkmDdaaq))D D5(b) RETURN b, type(r[0]) as rel_type LIMIT 100r;rNr)labelstype _rel_typez get_neighbors failed: %s | id=%s)r'maxminrGrr+r,lenr/rUr)r_r1r"r r#) rrHrVdepth rel_filterr2r4r5r6noderel_str node_dictr$s r get_neighborszGenesisGraph.get_neighborssE%%'IAs5!}%8@q234b &zl$ug>9 :  [[&&vi/@AF)+D$$  ++ 'ay'*6{Q&)D,. 4.$$T__54*t{{(, AIf%)0 +& I& 'K  NN=sI NI s%-D 3BD D5D0*D50D5c|jsgSi}|rt|}d|d}nd}g}|rB|jD]/\}} d|} |jd|d| t | || <1|rddj |nd } ||d <|| d } |j j| |} g}| js|S| jD]k}|d }i}t|d r|j|jt|dr|jr|jd |d<|j|m|S#t$r"}tjd|gcYd}~Sd}~wwxYw)z Search for nodes, optionally filtering by type label and/or properties. Returns list of property dicts. z MATCH (n:)z MATCH (n)filter_r=r>z WHERE z AND rTlimitz RETURN n LIMIT $limitrr)r_r`zsearch_entities failed: %sN)r'rGrDr1rErFrr+r,r/rUr)r_r"r r#)rrIproperty_filterrnr3rN match_clause where_partsrBrK param_key where_clauser2r4r5r6rgrir$s rsearch_entitieszGenesisGraph.search_entities#s%%'I!# #K0E&ugQ/L&L!# '--/ 51%aSM ""Rs$yk#:;$1!$4y! 5 ALk!: ;,/EF [[&&vv6F)+D$$  ++ 'ay,. 4.$$T__54*t{{(, AIf% I& 'K  NN7 =I s%+D>A;D>> E)E$E)$E)cd|_|jK t|jddxst|jdd}||jd|_yy#t$rYwxYw)z&Release FalkorDB connection resources.N connection_redis)rrgetattrcloser")rconns rryzGenesisGraph.closeZsu 88  txxt<HHhA#JJLDH   sAA A,+A, localhosti genesis_kg)rstrrrrr~returnNone)rbool)N)r2r~r3Optional[Dict[str, Any]]rList[Dict[str, Any]])rHr~rIr~r)rrr) rQr~rRr~rVr~r)rrr)Nr\)rHr~rV Optional[str]rerrr)NNd)rIrrorrnrrr)rr) __name__ __module__ __qualname____doc__rr%r'r+rOrZrjrtryr?rrr r 6sJ & * * * *  * 4,0!!)!  !V04 ###- #  #T04 222 2 - 2  2v#' ** * *  *\&*48 1"121 1  1n rr zOptional[GenesisGraph]_default_graphc6tt|||atS)z Return (and lazily create) the module-level GenesisGraph singleton. Environment variables FALKORDB_HOST / FALKORDB_PORT / FALKORDB_GRAPH override the defaults at construction time. rrr)rr rs r get_graphrqs%4dzR rcr|jddjddjdd}|r|SdS)z Convert a label string to a Cypher-safe identifier. Replaces spaces and hyphens with underscores; upper-cases the first char to match Cypher conventions.  _-.Node)replace)rNsafes rrGrGs; ==c " * *3 4 < rs.# ,,   8 $ .qqp *.&-"   ,$U I NN -sA""A?>A?