ZǻiF ddlmZddlZddlmZmZmZmZddlZddl m Z ddl m Z ddl mZmZmZmZddlmZddlmZdd lmZmZmZmZmZmZmZmZmZm Z dd l!m"Z"ejFe$Z%Gd d eZ&Gd deZ'y)) annotationsN)AnyCallableOptionalUnion)ValidationError)Embedder)EmbeddingRequiredErrorRetrieverInitializationErrorSearchValidationErrorSearchQueryParseError)get_search_query) Retriever) EmbedderModelHybridCypherRetrieverModelHybridCypherSearchModelHybridRetrieverModelHybridSearchModelNeo4jDriverModelRawSearchResultRetrieverResultItem SearchTypeHybridSearchRanker)prettifyceZdZdZ d d fd Zd dZdddejdf d dZxZ S) HybridRetrievera Provides retrieval method using combination of vector search over embeddings and fulltext search. If an embedder is provided, it needs to have the required Embedder type. Example: .. code-block:: python import neo4j from neo4j_graphrag.retrievers import HybridRetriever driver = neo4j.GraphDatabase.driver(URI, auth=AUTH) retriever = HybridRetriever( driver, "vector-index-name", "fulltext-index-name", custom_embedder ) retriever.search(query_text="Find me a book about Fremen", top_k=5) Args: driver (neo4j.Driver): The Neo4j Python driver. vector_index_name (str): Vector index name. fulltext_index_name (str): Fulltext index name. embedder (Optional[Embedder]): Embedder object to embed query text. return_properties (Optional[list[str]]): List of node properties to return. result_formatter (Optional[Callable[[neo4j.Record], RetrieverResultItem]]): Provided custom function to transform a neo4j.Record to a RetrieverResultItem. neo4j_database (Optional[str]): The name of the Neo4j database. If not provided, this defaults to the server's default database ("neo4j" by default) (`see reference to documentation `_). Two variables are provided in the neo4j.Record: - node: Represents the node retrieved from the vector index search. - score: Denotes the similarity score. Nc B t|}|r t|nd} t|||| |||} t || jj| j| j|_ | j|_ | j|_ | jr| jjnd|_| j |_d|_d|_|j'|jy#t$r} t | j | d} ~ wwxYw)Ndriverembedder) driver_modelvector_index_namefulltext_index_nameembedder_modelreturn_propertiesresult_formatterneo4j_database)rrrrr errorssuper__init__r"rr(r#r$r&r%r!r'_embedding_node_property_embedding_dimension_fetch_index_infos) selfrr#r$r!r&r'r(r"r%validated_datae __class__s ^/opt/lhia/marcimex/agent/venv/lib/python3.12/site-packages/neo4j_graphrag/retrievers/hybrid.pyr+zHybridRetriever.__init__Ts B+6:LAI]H=tN1)"3$7-"3!1-N   ' ' . .0M0M "0!A!A#1#E#E !/!A!A,,  ) ) 2 2 !/ ? ?(,%$(!  6 67# B.qxxz: A Bs.C66 D?DDcvd|jdi}|jd}tt||S)z Best effort to guess the node-to-text method. Inherited classes can override this method to implement custom text formatting. scorenode)contentmetadata)getrstr)r/recordr8r6s r3default_record_formatterz(HybridRetriever.default_record_formatters@ VZZ( zz&!"I  c t||||||}|j d} |j | d<|j | d<|r9|s7|js td|jj|}|| d<ttj|j|j|j|j |j" \} } d | vr| d =t$j'd t)| t$j'd |  |j*j-| | |j.t0j2j4 \} } } t?| d|iS#t$r}t|j|d}~wwxYw#t0j6j8$r"}dt;|vrt=d||d}~wwxYw)aGet the top_k nearest neighbor embeddings for either provided query_vector or query_text. Both query_vector and query_text can be provided. If query_vector is provided, then it will be preferred over the embedded query_text for the vector search. See the following documentation for more details: - `Query a vector index `_ - `db.index.vector.queryNodes() `_ - `db.index.fulltext.queryNodes() `_ To query by text, an embedder must be provided when the class is instantiated. Args: query_text (str): The text to get the closest neighbors of. query_vector (Optional[list[float]], optional): The vector embeddings to get the closest neighbors of. Defaults to None. top_k (int, optional): The number of neighbors to return. Defaults to 5. effective_search_ratio (int): Controls the candidate pool size for the vector index by multiplying top_k to balance query accuracy and performance. Defaults to 1. ranker (str, HybridSearchRanker): Type of ranker to order the results from retrieval. alpha (Optional[float]): Weight for the vector score when using the linear ranker. The fulltext index score is multiplied by (1 - alpha). **Required** when using the linear ranker; must be between 0 and 1. Raises: SearchValidationError: If validation of the input arguments fail. EmbeddingRequiredError: If no embedder is provided. Returns: RawSearchResult: The results of the search query as a list of neo4j.Record and an optional metadata dict ) query_vector query_texttop_keffective_search_ratiorankeralphaNT exclude_noner#r$)Embedding method required for text query.rA) search_typer&embedding_node_propertyneo4j_version_is_5_23_or_aboverErFrE%HybridRetriever Cypher parameters: %s HybridRetriever Cypher query: %s database_routing_4org.apache.lucene.queryparser.classic.ParseException0Invalid Lucene query generated from query_text: recordsr8) rrr r) model_dumpr#r$r!r embed_queryrrHYBRIDr&r,rLrErFloggerdebugrr execute_queryr(neo4jRoutingControlREAD exceptions ClientErrorr:r r) r/rBrArCrDrErFr0r1 parameters search_query_rUs r3get_search_resultsz"HybridRetriever.get_search_resultssP ;.)%'= N$..D.A *.*@*@ &',0,D,D () l==,? ==44Z@L)5J~ &*"))"44$($A$A+/+N+N!(( &&   a z !8$ RS 7F  KK55----22 6MGQ$l3  U ;' 3 : ;H++ EQO+FzlS   s0E#AF# F ,FF G +GG )NNNN)r neo4j.Driverr#r:r$r:r!Optional[Embedder]r&zOptional[list[str]]r'7Optional[Callable[[neo4j.Record], RetrieverResultItem]]r( Optional[str]returnNone)r;z neo4j.Recordrir)rBr:rAOptional[list[float]]rCintrDrlrEUnion[str, HybridSearchRanker]rFOptional[float]rir) __name__ __module__ __qualname____doc__r+r<rNAIVErd __classcell__r2s@r3rr1s N(,15 (,)8)8)8! )8 % )8 / )8 )8&)8 )8V  "/3&'1C1I1I!%^ ^ ,^  ^ !$ ^ / ^ ^  ^ r=rceZdZdZ d dfd Zddddej df d dZxZS) HybridCypherRetrievera( Provides retrieval method using combination of vector search over embeddings and fulltext search, augmented by a Cypher query. This retriever builds on HybridRetriever. If an embedder is provided, it needs to have the required Embedder type. Note: `node` is a variable from the base query that can be used in `retrieval_query` as seen in the example below. Example: .. code-block:: python import neo4j from neo4j_graphrag.retrievers import HybridCypherRetriever driver = neo4j.GraphDatabase.driver(URI, auth=AUTH) retrieval_query = "MATCH (node)-[:AUTHORED_BY]->(author:Author)" "RETURN author.name" retriever = HybridCypherRetriever( driver, "vector-index-name", "fulltext-index-name", retrieval_query, custom_embedder ) retriever.search(query_text="Find me a book about Fremen", top_k=5) To query by text, an embedder must be provided when the class is instantiated. Args: driver (neo4j.Driver): The Neo4j Python driver. vector_index_name (str): Vector index name. fulltext_index_name (str): Fulltext index name. retrieval_query (str): Cypher query that gets appended. embedder (Optional[Embedder]): Embedder object to embed query text. result_formatter (Optional[Callable[[neo4j.Record], RetrieverResultItem]]): Provided custom function to transform a neo4j.Record to a RetrieverResultItem. neo4j_database (Optional[str]): The name of the Neo4j database. If not provided, this defaults to the server's default database ("neo4j" by default) (`see reference to documentation `_). Raises: RetrieverInitializationError: If validation of the input arguments fail. Nc  t|}|r t|nd} t||||| ||} t || jj| j| j|_ | j|_ | j|_ | jr| jjnd|_| j |_y#t$r} t | j | d} ~ wwxYw)Nrr )r"r#r$retrieval_queryr%r'r()rrrrr r)r*r+r"rr(r#r$ryr%r!r') r/rr#r$ryr!r'r(r"r%r0r1r2s r3r+zHybridCypherRetriever.__init__s B+6:LAI]H=tN7)"3$7 /-!1-N   ' ' . .0M0M "0!A!A#1#E#E -==,,  ) ) 2 2 !/ ? ? B.qxxz: A Bs.C C5C00C5r>r?c  t|||||||}|j d} |j | d<|j | d<|r9|s7|js td|jj|}|| d<|r%|jD]\} } | | vs | | | <| d =ttj|j|j|j |j" \} }d | vr| d =t$j'd t)| t$j'd |  |j*j-| | |j.t0j2j4\}}}t?|d|iS#t$r} t| j| d} ~ wwxYw#t0j6j8$r"} dt;| vrt=d|| d} ~ wwxYw)aGet the top_k nearest neighbor embeddings for either provided query_vector or query_text. Both query_vector and query_text can be provided. If query_vector is provided, then it will be preferred over the embedded query_text for the vector search. See the following documentation for more details: - `Query a vector index `_ - `db.index.vector.queryNodes() `_ - `db.index.fulltext.queryNodes() `_ Args: query_text (str): The text to get the closest neighbors of. query_vector (Optional[list[float]]): The vector embeddings to get the closest neighbors of. Defaults to None. top_k (int): The number of neighbors to return. Defaults to 5. effective_search_ratio (int): Controls the candidate pool size for the vector index by multiplying top_k to balance query accuracy and performance. Defaults to 1. query_params (Optional[dict[str, Any]]): Parameters for the Cypher query. Defaults to None. ranker (str, HybridSearchRanker): Type of ranker to order the results from retrieval. alpha (Optional[float]): Weight for the vector score when using the linear ranker. The fulltext index score is multiplied by (1 - alpha). **Required** when using the linear ranker; must be between 0 and 1. Raises: SearchValidationError: If validation of the input arguments fail. EmbeddingRequiredError: If no embedder is provided. Returns: RawSearchResult: The results of the search query as a list of neo4j.Record and an optional metadata dict )rArBrCrDrErF query_paramsNTrGr#r$rIrAr{)rJryrLrErFrErMrNrOrRrSrT) rrr r)rVr#r$r!r rWitemsrrrXryrLrErFrYrZrrr[r(r\r]r^r_r`r:r r)r/rBrArCrDr{rErFr0r1rakeyvaluerbrcrUs r3rdz(HybridCypherRetriever.get_search_results=sN ;4)%'=)N$..D.A *.*@*@ &',0,D,D () l==,? ==44Z@L)5J~ & *002 , Uj(&+JsO ,>**")) 00+/+N+N!(( &&   a z !8$ RS 7F  KK55----22 6MGQ$l3  a ;' 3 : ;T++ EQO+FzlS   s0F,AF+ F( F##F(+G*G%%G*)NNN)rrer#r:r$r:ryr:r!rfr'rgr(rhrirj)rBr:rArkrCrlrDrlr{zOptional[dict[str, Any]]rErmrFrnrir) rorprqrrr+rrsrdrtrus@r3rwrws$X(, (,&@&@&@! &@  &@ % &@ &@&&@ &@V/3&'151C1I1I!%d d ,d  d !$ d / d /d d  d r=rw)( __future__rloggingtypingrrrrr\pydanticrneo4j_graphrag.embeddings.baser neo4j_graphrag.exceptionsr r r r neo4j_graphrag.neo4j_queriesrneo4j_graphrag.retrievers.baserneo4j_graphrag.typesrrrrrrrrrrneo4j_graphrag.utils.loggingr getLoggerrorYrrwr=r3rsq#11 $3 :4   2   8 $z iz zs Is r=