ei nddlmZmZddlmZmZmZmZmZm Z m Z ddl Z ddl mZddlmZmZmZmZmZmZmZmZmZmZddlmZmZmZeGddZeGd d ZeGd d eZ eGd deZ!eGddeZ"eGddeZ#eGddeZ$eGddeZ%eGddeZ&eGddeZ'eGddeZ(eGddeZ)eGdd eZ*eGd!d"eZ+eGd#d$eZ,eGd%d&eZ-Gd'd(Z.e.d)e._/e.d*e._0e.d+e._1e.d,e._2e.d-e._3e.Z4eGd.d/Z5eGd0d1Z6eGd2d3Z7eGd4d5Z8eGd6d7Z9eGd8d9e9Z:eGd:d;e9Z;eGd<d=e9Zd?e9Z=eGd@dAe9Z>eGdBdCe9Z?eGdDdEe9Z@eGdFdGe9ZAeGdHdIe9ZBeGdJdKe9ZCeGdLdMe9ZDeGdNdOe9ZEeGdPdQZFdRee e.eGfdSeeGfdTZHdRe eeeIedUffdSee e.eGffdVZJdWeGdXeeGefdSeIee e.eGfeKffdYZLeGdZd[ZMeGd\d]eMZNeGd^d_eMZOeGd`daZPy)b) dataclassfield)OptionalListDictSetAnyUnioncastN)NDArray) EmbeddingsIDsInclude OneOrMany SparseVectorTYPE_KEYSPARSE_VECTOR_TYPE_VALUEmaybe_cast_one_to_manynormalize_embeddingsvalidate_embeddings) CollectionRequestVersionContextSegmentcLeZdZUeed<eed<eed<eed<edefdZy)Scan collectionknnmetadatarecordreturnclt|jj|jjS)N)collection_version log_position)rrversionr#selfs p/home/obispo/Crisostomo_bridge/mision_env/lib/python3.12/site-packages/chromadb/execution/expression/operator.pyr$z Scan.version s)$#6655  N) __name__ __module__ __qualname__r__annotations__rpropertyrr$r(r'rrs2 L O  .  r(rcZeZdZdZdeeeffdZedeeefddfdZ d dZ d dZ y) Wherea?Base class for Where expressions (algebraic data type). Supports logical operators for combining conditions: - AND: where1 & where2 - OR: where1 | where2 Examples: # Simple conditions where1 = Key("status") == "active" where2 = Key("score") > 0.5 # Combining with AND combined_and = where1 & where2 # Combining with OR combined_or = where1 | where2 # Complex expressions complex_where = (Key("status") == "active") & ((Key("score") > 0.5) | (Key("priority") == "high")) r ctd)zCConvert the Where expression to a dictionary for JSON serialization#Subclasses must implement to_dict()NotImplementedErrorr%s r'to_dictz Where.to_dict@!"GHHr(datac$ t|ts!tdt|j|s t dd|vrt|dt s$tdt|djt|ddk(r t dt|dkDr t d|dDcgc]}tj|}}t|dk(r|dS|d}|dd D]}||z} |Sd |vrt|d t s$td t|d jt|d dk(r t d t|dkDr t d |d Dcgc]}tj|}}t|dk(r|dS|d}|dd D]}||z} |St|dk7rt dt|tt|j\}}t|ts!tdt|jt|tr|st d|dt|dk7rt d|dtt|j\}}|dk(rt||k(S|dk(rt||k7S|dk(rt||kDS|dk(rt||k\S|dk(rt||kS|dk(rt||kS|dk(rKt|t s!tdt|jt|j|S|dk(rKt|t s!tdt|jt|j!|S|dk(rKt|ts!tdt|jt|j#|S|dk(rKt|ts!td t|jt|j%|S|d!k(rKt|ts!td"t|jt|j'|S|d#k(rKt|ts!td$t|jt|j)|St d%|t||k(Scc}wcc}w)&atCreate Where expression from dictionary. Supports MongoDB-style query operators: - {"field": "value"} -> Key("field") == "value" (shorthand for equality) - {"field": {"$eq": value}} -> Key("field") == value - {"field": {"$ne": value}} -> Key("field") != value - {"field": {"$gt": value}} -> Key("field") > value - {"field": {"$gte": value}} -> Key("field") >= value - {"field": {"$lt": value}} -> Key("field") < value - {"field": {"$lte": value}} -> Key("field") <= value - {"field": {"$in": [values]}} -> Key("field").is_in([values]) - {"field": {"$nin": [values]}} -> Key("field").not_in([values]) - {"field": {"$contains": "text"}} -> Key("field").contains("text") - {"field": {"$not_contains": "text"}} -> Key("field").not_contains("text") - {"field": {"$regex": "pattern"}} -> Key("field").regex("pattern") - {"field": {"$not_regex": "pattern"}} -> Key("field").not_regex("pattern") - {"$and": [conditions]} -> condition1 & condition2 & ... - {"$or": [conditions]} -> condition1 | condition2 | ... zExpected dict for Where, got zWhere dict cannot be empty$andz$and must be a list, got rz$$and requires at least one conditionz:$and cannot be combined with other fields in the same dictN$orz$or must be a list, got z#$or requires at least one conditionz9$or cannot be combined with other fields in the same dictz/Where dict must contain exactly one field, got z!Field name must be a string, got zOperator dict for field 'z' cannot be emptyz#' must contain exactly one operator$eq$ne$gt$gte$lt$lte$inz$in requires a list, got $ninz$nin requires a list, got $containsz!$contains requires a string, got $not_containsz%$not_contains requires a string, got $regexz&$regex requires a string pattern, got $not_regexz*$not_regex requires a string pattern, got zUnknown operator: ) isinstancedict TypeErrortyper) ValueErrorlistlenr0 from_dictnextiteritemsstrKeyis_innot_incontains not_containsregex not_regex)r7c conditionsresultr conditionopvalues r'rOzWhere.from_dictDs<*$%;DJd6lD1/T&\0B0K0K/LM4< A% !GHH4y1} P7;6lC%//!,CJC:!#!!}$]F^ $! $M d]d5k40":4U ;L;U;U:V WXX4;1$ !FGG4y1} O7;5kB%//!,BJB:!#!!}$]F^ $! $M4yA~ Ec$i[Q $D$67 E9eS)7U 8L8L7MN)T* $3E7:KLy>Q&$3E7:]^!ioo&7!89 E;u:..5[u:..5[u:--6\u:..5[u:--6\u:..5[%eT2'7U 8L8L7MNu:++E226\%eT2'8e9M9M8NOu:,,U33;&%eS1'?U @T@T?UVu:..u55?*%eS1'CDKDXDXCYZu:225998^%eS1'DT%[EYEYDZ[u:++E22<'%eS1'HeI]I]H^_u://66$'9"%>??5zY..SD$Cs 6T4T c$t|trKt|tr"t|j|jzSt|j|gzSt|trt|g|jzSt||gS)zOverload & operator for AND)rHAndr\r&others r'__and__z Where.__and__sy dC %%4??U-=-==>>t%01 1 s #v 0 001 1D%=!!r(c$t|trKt|tr"t|j|jzSt|j|gzSt|trt|g|jzSt||gS)zOverload | operator for OR)rHOrr\rcs r'__or__z Where.__or__sy dB %$$//E,<,<<==doo/0 0 r "tfu///0 04-  r(N)rdr0r rb)rdr0r rg) r)r*r+__doc__rrSr r5 staticmethodrOrerhr.r(r'r0r0)sV*Ic3hIP/S#XP/7P/P/d " !r(r0c8eZdZUdZeeed<deee ffdZ y)rbz(Logical AND of multiple where conditionsr\r c`d|jDcgc]}|jc}iScc}w)Nr9r\r5r&r[s r'r5z And.to_dicts%doo>>??>+N r)r*r+rirr0r,rrSr r5r.r(r'rbrbs%2U @c3h@r(rbc8eZdZUdZeeed<deee ffdZ y)rgz'Logical OR of multiple where conditionsr\r c`d|jDcgc]}|jc}iScc}w)Nr;rmrns r'r5z Or.to_dicts%T__= =>>=roNrpr.r(r'rgrgs#1U ?c3h?r(rgc<eZdZUdZeed<eed<deeeffdZy)EqzEquality comparisonkeyr`r c6|jd|jiiS)Nr<rur`r%s r'r5z Eq.to_dict5$**-..r(N r)r*r+rirSr,r rr5r.r(r'rtrts# H J/c3h/r(rtc<eZdZUdZeed<eed<deeeffdZy)NezNot equal comparisonrur`r c6|jd|jiiS)Nr=rwr%s r'r5z Ne.to_dictrxr(Nryr.r(r'r{r{# H J/c3h/r(r{c<eZdZUdZeed<eed<deeeffdZy)GtzGreater than comparisonrur`r c6|jd|jiiS)Nr>rwr%s r'r5z Gt.to_dict%rxr(Nryr.r(r'rrs#! H J/c3h/r(rc<eZdZUdZeed<eed<deeeffdZy)Gtez Greater than or equal comparisonrur`r c6|jd|jiiS)Nr?rwr%s r'r5z Gte.to_dict064::.//r(Nryr.r(r'rr)s#* H J0c3h0r(rc<eZdZUdZeed<eed<deeeffdZy)LtzLess than comparisonrur`r c6|jd|jiiS)Nr@rwr%s r'r5z Lt.to_dict;rxr(Nryr.r(r'rr4r}r(rc<eZdZUdZeed<eed<deeeffdZy)LtezLess than or equal comparisonrur`r c6|jd|jiiS)NrArwr%s r'r5z Lte.to_dictFrr(Nryr.r(r'rr?s#' H J0c3h0r(rcBeZdZUdZeed<eeed<deeeffdZ y)Inz"In comparison - value is in a listruvaluesr c6|jd|jiiS)NrBrurr%s r'r5z In.to_dictQs5$++.//r(N r)r*r+rirSr,rr rr5r.r(r'rrJs(, H I0c3h0r(rcBeZdZUdZeed<eeed<deeeffdZ y)Ninz*Not in comparison - value is not in a listrurr c6|jd|jiiS)NrCrr%s r'r5z Nin.to_dict\s64;;/00r(Nrr.r(r'rrUs(4 H I1c3h1r(rc<eZdZUdZeed<eed<deeeffdZy)Containsz(Contains comparison for document contentrucontentr c6|jd|jiiS)NrDrurr%s r'r5zContains.to_dictgs; 566r(N r)r*r+rirSr,rr r5r.r(r'rr`s#2 H L7c3h7r(rc<eZdZUdZeed<eed<deeeffdZy) NotContainsz,Not contains comparison for document contentrurr c6|jd|jiiS)NrErr%s r'r5zNotContains.to_dictrs?DLL9::r(Nrr.r(r'rrks#6 H L;c3h;r(rc<eZdZUdZeed<eed<deeeffdZy)RegexzRegular expression matchingrupatternr c6|jd|jiiS)NrFrurr%s r'r5z Regex.to_dict}s8T\\233r(Nrr.r(r'rrvs#% H L4c3h4r(rc<eZdZUdZeed<eed<deeeffdZy)NotRegexz$Negative regular expression matchingrurr c6|jd|jiiS)NrGrr%s r'r5zNotRegex.to_dicts<677r(Nrr.r(r'rrs#. H L8c3h8r(rc(eZdZUdZded<ded<ded<ded<ded<defdZd efd Zd e d e fd Z d e d e fd Z d e d efdZd e d efdZd e d efdZd e d efdZdee d efdZdee d efdZded efdZded efdZded efdZ ded e!fdZ"y)rTaField proxy for building Where conditions with operator overloading. The Key class allows for readable field references using either: 1. Predefined constants for special fields: K.EMBEDDING, K.DOCUMENT, K.SCORE, etc. 2. String literals with # prefix for special fields: Key("#embedding") 3. Metadata field names without # prefix: Key("my_metadata_field") Predefined field constants (special fields with # prefix): Key.ID - ID field (equivalent to Key("#id")) Key.DOCUMENT - Document field (equivalent to Key("#document")) Key.EMBEDDING - Embedding field (equivalent to Key("#embedding")) Key.METADATA - Metadata field (equivalent to Key("#metadata")) Key.SCORE - Score field (equivalent to Key("#score")) Note: K is an alias for Key, so you can use K.DOCUMENT or Key.DOCUMENT interchangeably. Examples: # Using predefined keys with K alias for special fields from chromadb.execution.expression import K K.DOCUMENT.contains("search text") # Searches document field # Custom metadata field names (without # prefix) K("status") == "active" # Metadata field named "status" K("category").is_in(["science", "tech"]) # Metadata field named "category" K("sparse_embedding") # Example: metadata field (could store anything) # Using with Knn for different fields Knn(query=[0.1, 0.2]) # Default: searches "#embedding" Knn(query=[0.1, 0.2], key=K.EMBEDDING) # Explicit: searches "#embedding" Knn(query=sparse, key="sparse_embedding") # Example: searches a metadata field # Combining conditions (K("status") == "active") & (K.SCORE > 0.5) IDDOCUMENT EMBEDDINGMETADATASCOREnamec||_y)N)r)r&rs r'__init__z Key.__init__s  r(r c,t|jS)z!Make Key hashable for use in sets)hashrr%s r'__hash__z Key.__hash__sDIIr(r`c.t|j|S)zEquality: Key('field') == value)rtrr&r`s r'__eq__z Key.__eq__$))U##r(c.t|j|S)z Not equal: Key('field') != value)r{rrs r'__ne__z Key.__ne__rr(c.t|j|S)z"Greater than: Key('field') > value)rrrs r'__gt__z Key.__gt__rr(c.t|j|S)z,Greater than or equal: Key('field') >= value)rrrs r'__ge__z Key.__ge__499e$$r(c.t|j|S)zLess than: Key('field') < value)rrrs r'__lt__z Key.__lt__rr(c.t|j|S)z)Less than or equal: Key('field') <= value)rrrs r'__le__z Key.__le__rr(rc.t|j|S)z?Check if field value is in list: Key('field').is_in(['a', 'b']))rrr&rs r'rUz Key.is_ins$))V$$r(c.t|j|S)zDCheck if field value is not in list: Key('field').not_in(['a', 'b']))rrrs r'rVz Key.not_ins499f%%r(rc.t|j|S)z9Match field against regex: Key('field').regex('^pattern'))rrr&rs r'rYz Key.regexsTYY((r(c.t|j|S)z@Field should not match regex: Key('field').not_regex('^pattern'))rrrs r'rZz Key.not_regex 7++r(rc.t|j|S)z;Check if field contains text: Key('field').contains('text'))rrr&rs r'rWz Key.containsrr(c.t|j|S)zFCheck if field doesn't contain text: Key('field').not_contains('text'))rrrs r'rXzKey.not_containss499g..r(N)#r)r*r+rir,rSrintrr rtrr{rrrrrrrrrrrrUrrVrrYrrZrrWrrXr.r(r'rTrTs(!H IOO LS# $C$B$$C$B$$C$B$%C%C%$C$B$%C%C% %DI%"%&T#Y&3&)S)U),,,,,,/C/K/r(rT#id #document #embedding #metadata#scorecJeZdZUdZeeed<dZeeed<dZ eeed<y)FilterNuser_idswherewhere_document) r)r*r+rrrr,rr rr.r(r'rrs,"Hhsm"E8C=$(NHSM(r(rc"eZdZUeed<eed<y)KNN embeddingsfetchN)r)r*r+r r,rr.r(r'rrs  Jr(rcjeZdZUdZeed<dZeeed<dee e ffdZ e dee e fddfdZ y) LimitroffsetNlimitr cXd|ji}|j|j|d<|S)z8Convert the Limit to a dictionary for JSON serializationrrrrr&r]s r'r5z Limit.to_dicts,DKK( :: !"jjF7O r(r7c8t|ts!tdt|j|j dd}t|t s!tdt|j|dkrtd||j d}|Dt|t s!tdt|j|dkrtd|ddh}t|j|z }|rtd |t|| S) zCreate Limit from dictionary. Examples: - {"offset": 10} -> Limit(offset=10) - {"offset": 10, "limit": 20} -> Limit(offset=10, limit=20) - {"limit": 20} -> Limit(offset=0, limit=20) zExpected dict for Limit, got rrz%Limit offset must be an integer, got z'Limit offset must be non-negative, got rz$Limit limit must be an integer, got z"Limit limit must be positive, got zUnexpected keys in Limit dict: r) rHrIrJrKr)getrrLsetkeysr)r7rr allowed_keysunexpected_keyss r'rOzLimit.from_dicts%$%;DJ>OPQ QF%00r()r)r*r+rrr,rrrrSr r5rjrOr.r(r'rr sWFCOE8C=c3h"1S#X"17"1"1r(rcjeZdZUdZeed<dZeed<dZeed<dZeed<dZ eed<e de fdZ y ) ProjectionFdocument embeddingrrankurir c<t}|jr|jd|jr|jd|jr|jd|j r|jd|j r|jd|S)N documentsr metadatas distancesuris)rMrappendrrrr)r&includess r'includedzProjection.includedDsm6 == OOK ( >> OOL ) == OOK ( 99 OOK ( 88 OOF #r(N) r)r*r+rboolr,rrrrr-rrr.r(r'rr<sMHdItHdD$C  '  r(rceZdZdZdeeeffdZedeeefddfdZ de de e fddfdZ de e e fddfd Zde de e fdd fd Zde e e fdd fd Zde de e fdd fdZde e e fdd fdZde de e fddfdZde e e fddfdZddZddZddZddZd dZde de e fddfdZde de e fddfdZy)!RankaBase class for Rank expressions (algebraic data type). Supports arithmetic operations for combining rank expressions: - Addition: rank1 + rank2, rank + 0.5 - Subtraction: rank1 - rank2, rank - 0.5 - Multiplication: rank1 * rank2, rank * 0.8 - Division: rank1 / rank2, rank / 2.0 - Negation: -rank - Absolute value: abs(rank) Supports mathematical functions: - Exponential: rank.exp() - Logarithm: rank.log() - Maximum: rank.max(other) - Minimum: rank.min(other) Examples: # Weighted combination Knn(query=[0.1, 0.2]) * 0.8 + Val(0.5) * 0.2 # Normalization Knn(query=[0.1, 0.2]) / Val(10.0) # Clamping Knn(query=[0.1, 0.2]).min(1.0).max(0.0) r ctd)zCConvert the Score expression to a dictionary for JSON serializationr2r3r%s r'r5z Rank.to_dictrr6r(r7ct|ts!tdt|j|s t dt |dk7rt dt |tt|j}|dk(rG|d}t|ttfs!tdt|jt|S|dk(r |d}t|ts!tdt|jd |vr t d |d }t|trN|jttk(rt!j"|}nt d td td |t|t$t&t(j*fr7t-|}|rt |dkDr t dt/||d}n!tdt|j|jdd}t|t0s!tdt|j|jdd}t|ts!tdt|j|dkrt d||jdd}t|t2s!tdt|jt5||||jd|S|dk(r|d} t| t$t&fs!tdt| jt | dkrt d t | | D cgc]} t6j#| } } | d} | dd!D]} | | z} | S|d"k(r~|d"} t| ts!td#t| jd$| vsd%| vr t d&t6j#| d$}t6j#| d%}||z S|d'k(r|d'} t| t$t&fs!td(t| jt | dkrt d)t | | D cgc]} t6j#| } } | d} | dd!D]} | | z} | S|d*k(r~|d*}t|ts!td+t|jd$|vsd%|vr t d,t6j#|d$}t6j#|d%}||z S|d-k(rT|d-}t|ts!td.t|jt9t6j#|S|d/k(rY|d/}t|ts!td0t|jt6j#|j;S|d1k(rY|d1}t|ts!td2t|jt6j#|j=S|d3k(r|d3} t| t$t&fs!td4t| jt | dkrt d5t | | D cgc]} t6j#| } } | d} | dd!D]} | j?| } | S|d6k(r|d6} t| t$t&fs!td7t| jt | dkrt d8t | | D cgc]} t6j#| } } | d} | dd!D]} | jA| } | St d9|cc} wcc} wcc} wcc} w):asCreate Rank expression from dictionary. Supports operators: - {"$val": number} -> Val(number) - {"$knn": {...}} -> Knn(...) - {"$sum": [ranks]} -> rank1 + rank2 + ... - {"$sub": {"left": ..., "right": ...}} -> left - right - {"$mul": [ranks]} -> rank1 * rank2 * ... - {"$div": {"left": ..., "right": ...}} -> left / right - {"$abs": rank} -> abs(rank) - {"$exp": rank} -> rank.exp() - {"$log": rank} -> rank.log() - {"$max": [ranks]} -> rank1.max(rank2).max(rank3)... - {"$min": [ranks]} -> rank1.min(rank2).min(rank3)... zExpected dict for Rank, got zRank dict cannot be emptyr:z1Rank dict must contain exactly one operator, got $valz$val requires a number, got $knnz$knn requires a dict, got queryz$knn requires 'query' fieldzExpected dict with z='z', got z)$knn requires exactly one query embeddingrzB$knn query must be a list, numpy array, or SparseVector dict, got rurz$knn key must be a string, got rz#$knn limit must be an integer, got z!$knn limit must be positive, got return_rankFz($knn return_rank must be a boolean, got default)rrurrr$sumz$sum requires a list, got z$$sum requires at least 2 ranks, got N$subz2$sub requires a dict with 'left' and 'right', got leftrightz'$sub requires 'left' and 'right' fields$mulz$mul requires a list, got z$$mul requires at least 2 ranks, got $divz2$div requires a dict with 'left' and 'right', got z'$div requires 'left' and 'right' fields$absz$abs requires a rank dict, got $expz$exp requires a rank dict, got $logz$log requires a rank dict, got $maxz$max requires a list, got z$$max requires at least 2 ranks, got $minz$min requires a list, got z$$min requires at least 2 ranks, got zUnknown rank operator: )!rHrIrJrKr)rLrNrPrQrrfloatValrrrrrOrMtuplenpndarrayrrrSrKnnrabsexplogmaxmin)r7r_r`knn_datar normalizedrurr ranks_datarranksr]sub_datarrdiv_data child_datas r'rOzRank.from_dictvs"$%:4:;N;N:OPQ Q89 9 t9>CCI;O $tyy{# $ <LEec5\2">tE{?S?S>T UVVu:  6\F|Hh-"??W%E%&99X&*BB(2259E%-hZr:R9SSZ[`ZabED%#<=1%8 !S_q%8$%PQQ$J/"1  XY]^cYdYmYmXno,,ul3Cc3'"A$s)BTBTAU VWWLL"-EeS)9$u+:N:N9OPz #DUG!LMM",,}etK?P?Y?Y>Z[ Y/'  6\fJj4-80j1A1J1J0KL:" :3z?:KL1;;1T^^A&;E;1XF12Y $! $M 6\F|Hh-HhI`I`HabX%)@ !JKK>>(6"23DNN8G#45E%<  6\fJj4-80j1A1J1J0KL:" :3z?:KL1;;1T^^A&;E;1XF12Y $! $M 6\F|Hh-HhI`I`HabX%)@ !JKK>>(6"23DNN8G#45E%<  6\fJj$/5d:6F6O6O5PQt~~j12 2 6\fJj$/5d:6F6O6O5PQ>>*-113 3 6\fJj$/5d:6F6O6O5PQ>>*-113 3 6\fJj4-80j1A1J1J0KL:" :3z?:KL1;;1T^^A&;E;1XF12Y 'A 'M 6\fJj4-80j1A1J1J0KL:" :3z?:KL1;;1T^^A&;E;1XF12Y 'A 'M6rd;< )r rC)r rE)r)r*r+rirrSr r5rjrOr r rr"r&r*r-r1r3r6r8r;r?rrrrrr.r(r'rrUs6Ic3hIX=S#XX=6X=X=v 'U65##56 '5 '!eE3J/!E!%U65##56%5% %eE3J/%E% 'U65##56 '5 '!eE3J/!E!%vuc'9!:%u% %%s "3%%$  'vuc12 'u ' 'vuc12 'u 'r(rc2eZdZUdZeed<deeeffdZ y)r>zAbsolute value of a rankrr c:d|jjiS)Nrrr5r%s r'r5z Abs.to_dict ))+,,r(N r)r*r+rirr,rrSr r5r.r(r'r>r>" J-c3h-r(r>c<eZdZUdZeed<eed<deeeffdZ y)r4zDivision of two ranksrrr cpd|jj|jjdiS)Nrrrrr5rr%s r'r5z Div.to_dict,!2!2!4tzz?Q?Q?STUUr(NrOr.r(r'r4r4s% J KVc3hVr(r4c2eZdZUdZeed<deeeffdZ y)rCzExponentiation of a rankrr c:d|jjiS)NrrMr%s r'r5z Exp.to_dictrNr(NrOr.r(r'rCrCrPr(rCc2eZdZUdZeed<deeeffdZ y)rEzLogarithm of a rankrr c:d|jjiS)NrrMr%s r'r5z Log.to_dictrNr(NrOr.r(r'rErEs J-c3h-r(rEc8eZdZUdZeeed<deee ffdZ y)rFzMaximum of multiple ranksrr c`d|jDcgc]}|jc}iScc}w)Nr rr5r&rs r'r5z Max.to_dict%djj99::9roN r)r*r+rirrr,rrSr r5r.r(r'rFrF## :;c3h;r(rFc8eZdZUdZeeed<deee ffdZ y)rIzMinimum of multiple ranksrr c`d|jDcgc]}|jc}iScc}w)Nr r\r]s r'r5z Min.to_dictr^roNr_r.r(r'rIrIr`r(rIc8eZdZUdZeeed<deee ffdZ y)r/z Multiplication of multiple ranksrr c`d|jDcgc]}|jc}iScc}w)Nrr\r]s r'r5z Mul.to_dictr^roNr_r.r(r'r/r/s#* :;c3h;r(r/ceZdZUdZeeeeedddfe d<e jZ ee efe d<dZee d<d Zeee d <d Zee d <d eeeffdZy )raKNN-based ranking Args: query: The query for KNN search. Can be: - A string (will be automatically embedded using the collection's embedding function) - A dense vector (list or numpy array) - A sparse vector (SparseVector dict) key: The embedding key to search against. Can be: - Key.EMBEDDING (default) - searches the main embedding field - A metadata field name (e.g., "my_custom_field") - searches that metadata field limit: Maximum number of results to consider (default: 16) default: Default score for records not in KNN results (default: None) return_rank: If True, return the rank position (0, 1, 2, ...) instead of distance (default: False) Examples: # Search with string query (automatically embedded) Knn(query="hello world") # Will use collection's embedding function # Search main embeddings with vectors (equivalent forms) Knn(query=[0.1, 0.2]) # Uses default key="#embedding" Knn(query=[0.1, 0.2], key=K.EMBEDDING) Knn(query=[0.1, 0.2], key="#embedding") # Search sparse embeddings stored in metadata with string Knn(query="hello world", key="custom_embedding") # Will use schema's embedding function # Search sparse embeddings stored in metadata with vector Knn(query=my_vector, key="custom_embedding") # Example: searches a metadata field zNDArray[np.float32]zNDArray[np.float64]zNDArray[np.int32]rrurrNrFrr c|j}t|tr|j}n*t|tj r|j }|j}t|tr |j}|||jd}|j|j|d<|jr|j|d<d|iS)N)rrurrrr) rrHrr5rrtolistrurTrrrr)r& query_value key_valuer]s r'r5z Knn.to_dict(sjj k< 0%--/K  RZZ 0%,,.KHH i %!I'y4::N << # $ F9    $($4$4F= !r()r)r*r+rir rSrr rr,KrrurTrrrrrrrr r5r.r(r'rrs~<   U    ;;CsCx&E3O#GXe_#K c3h r(rc<eZdZUdZeed<eed<deeeffdZ y)r(zSubtraction of two ranksrrr cpd|jj|jjdiS)NrrSrTr%s r'r5z Sub.to_dictIrUr(NrOr.r(r'r(r(Bs%" J KVc3hVr(r(c8eZdZUdZeeed<deee ffdZ y)rzSummation of multiple ranksrr c`d|jDcgc]}|jc}iScc}w)Nrr\r]s r'r5z Sum.to_dictSr^roNr_r.r(r'rrMs#% :;c3h;r(rc2eZdZUdZeed<deeeffdZ y)r zConstant rank valuer`r cd|jiS)Nr)r`r%s r'r5z Val.to_dict]s ##r(N) r)r*r+rir r,rrSr r5r.r(r'r r Ws L$c3h$r(r cneZdZUdZeeed<dZeed<dZ e ee ed<dZ e ed<d eeeffd Zy) RrfaReciprocal Rank Fusion for combining multiple ranking strategies. RRF formula: score = -sum(weight_i / (k + rank_i)) for each ranking strategy The negative is used because RRF produces higher scores for better results, but Chroma uses ascending order (lower scores = better results). Args: ranks: List of Rank expressions to fuse (must have at least one) k: Smoothing constant (default: 60, standard in literature) weights: Optional weights for each ranking strategy. If not provided, all ranks are weighted equally (weight=1.0 each). normalize: If True, normalize weights to sum to 1.0 (default: False). When False, weights are used as-is for relative importance. When True, weights are scaled so they sum to 1.0. Examples: # Note: metadata fields (like "sparse_embedding" below) are user-defined and can store any data. # The field name is just an example - use whatever name matches your metadata structure. # Basic RRF combining KNN rankings (equal weight) Rrf([ Knn(query=[0.1, 0.2], return_rank=True), Knn(query=another_vector, key="custom_embedding", return_rank=True) # Example metadata field ]) # Weighted RRF with relative weights (not normalized) Rrf( ranks=[ Knn(query=[0.1, 0.2], return_rank=True), Knn(query=another_vector, key="custom_embedding", return_rank=True) # Example metadata field weights=[2.0, 1.0], # First ranking is 2x more important k=100 ) # Weighted RRF with normalized weights Rrf( ranks=[ Knn(query=[0.1, 0.2], return_rank=True), Knn(query=another_vector, key="custom_embedding", return_rank=True) # Example metadata field ], weights=[3.0, 1.0], # Will be normalized to [0.75, 0.25] normalize=True, k=100 ) r<kNweightsF normalizer cN|js td|jdkrtd|j|jt |jt |jk7r8tdt |jdt |jdt d|jDr td |jr |jnd gt |jz}|j r-t|}|dk(r td |Dcgc]}||z  }}t||jDcgc]\}}||j|zz }}}|d}|d dD]}||z} | jScc}wcc}}w) zConvert RRF to a composition of existing expression operators. Builds: -sum(weight_i / (k + rank_i)) for each rank Using Python's overloaded operators for cleaner code. zRRF requires at least one rankrzk must be positive, got NzNumber of weights (z) must match number of ranks ()c3&K|] }|dk yw)gNr.).0ws r' zRrf.to_dict..s1q1s71sz All weights must be non-negativeg?z3Sum of weights must be positive when normalize=Truer:) rrLrtrurNanyrvsumzipr5)r&ru weight_sumr{rtermsrrf_sumterms r'r5z Rrf.to_dictszz=> > 66Q;7x@A A << #4<< C O3 )#dll*;)<>WJQ !VWW/67!q:~7G7584LMDdfftm$MMa!"I %DnG %!!##8Ns 1 FF!)r)r*r+rirrr,rtrrurr rvrrrSr r5r.r(r'rrrrasN+Z : AsK%)GXd5k ")It($c3h($r(rrcxeZdZUdZeeZeee e fe d<de e e ffdZede e e fddfdZy) SelectaSelection configuration for search results. Fields can be: - Key.DOCUMENT - Select document key (equivalent to Key("#document")) - Key.EMBEDDING - Select embedding key (equivalent to Key("#embedding")) - Key.SCORE - Select score key (equivalent to Key("#score")) - Any other string - Select specific metadata property Note: You can use K as an alias for Key for more concise code. Examples: # Select predefined keys using K alias (K is shorthand for Key) from chromadb.execution.expression import K Select(keys={K.DOCUMENT, K.SCORE}) # Select specific metadata properties Select(keys={"title", "author", "date"}) # Mixed selection Select(keys={K.DOCUMENT, "title", "author"}) default_factoryrr cg}|jD]?}t|tr|j|j/|j|Adt t j|iS)z9Convert the Select to a dictionary for JSON serializationr)rrHrTrrrMrIfromkeys)r& key_stringsrts r'r5zSelect.to_dictsa  &A!S!""166*""1%  & T]];7899r(r7ct|ts!tdt|j|j dg}t|t ttfs!tdt|jg}|D]}t|ts!tdt|j|dk(r |jtjZ|dk(r |jtj|dk(r |jtj|dk(r |jtj|d k(r |jtj |jt| dh}t|j#|z }|rt%d |t't| S) zCreate Select from dictionary. Examples: - {"keys": ["#document", "#score"]} -> Select(keys={Key.DOCUMENT, Key.SCORE}) - {"keys": ["title", "author"]} -> Select(keys={"title", "author"}) zExpected dict for Select, got rz*Select keys must be a list/tuple/set, got z!Select key must be a string, got rrrrrz Unexpected keys in Select dict: )r)rHrIrJrKr)rrMr rrSrrTrrrrrrrLr)r7rkey_listrtrrs r'rOzSelect.from_dicts}$%AjC(CFa / >> >s$,r_r7c ||}t|ts#t|dt|jd|vrt |dd|vrt |d|d}t|t tfs#t|dt|j|st |d|d}t|ts#t|dt|j|d krt |d |t||fS) axParse common fields for MinK/MaxK from dict. Args: op: The operator name (e.g., "$min_k" or "$max_k") data: The dict containing the operator Returns: Tuple of (keys, k) where keys is List[Union[Key, str]] and k is int Raises: TypeError: If data types are invalid ValueError: If required fields are missing or invalid z requires a dict, got rz requires 'keys' fieldrtz requires 'k' fieldz keys must be a list, got z keys cannot be emptyz k must be an integer, got rz k must be positive, got ) rHrIrJrKr)rLrMr rr)r_r7agg_datarrts r'_parse_k_aggregater$s" BxH h %2$4T(^5L5L4MNOO XB45677 (B42344 F D dT5M *2$8d9L9L8MNOO B44566 A a 2$9$q':J:J9KLMMAvB48<== D !1 $$r(cJeZdZdZdeeeffdZedeeefddfdZ y) Aggregatea5Base class for aggregation expressions within groups. Aggregations determine which records to keep from each group: - MinK: Keep k records with minimum values (ascending order) - MaxK: Keep k records with maximum values (descending order) Examples: # Keep top 3 by score per group (single key) MinK(keys=Key.SCORE, k=3) # Keep top 5 by priority, then score as tiebreaker (multiple keys) MinK(keys=[Key("priority"), Key.SCORE], k=5) # Keep bottom 2 by score per group MaxK(keys=Key.SCORE, k=2) r ctd)zGConvert the Aggregate expression to a dictionary for JSON serializationr2r3r%s r'r5zAggregate.to_dict^r6r(r7ct|ts!tdt|j|s t dt |dk7rt dt |tt|j}|dk(rt||\}}t||S|dk(rt||\}}t||St d|) zCreate Aggregate expression from dictionary. Supports: - {"$min_k": {"keys": [...], "k": n}} -> MinK(keys=[...], k=n) - {"$max_k": {"keys": [...], "k": n}} -> MaxK(keys=[...], k=n) z!Expected dict for Aggregate, got zAggregate dict cannot be emptyr:z6Aggregate dict must contain exactly one operator, got $min_kr$max_kzUnknown aggregate operator: ) rHrIrJrKr)rLrNrPrQrrMinKMaxK)r7r_rrts r'rOzAggregate.from_dictbs$%?T @S@S?TUV V=> > t9>HT T $tyy{# $ >(T2GD!TQ' ' 8^(T2GD!TQ' ';B4@A Ar(N) r)r*r+rirrSr r5rjrOr.r(r'rrKsK"Ic3hIBS#XB;BBr(rcLeZdZUdZeeeefed<e ed<de ee ffdZ y)rz:Keep k records with minimum aggregate key values per grouprrtr cJdt|j|jdiS)Nrrrrrtr%s r'r5z MinK.to_dict #3DII#>TVVLMMr(N r)r*r+rirr rTrSr,rrr r5r.r(r'rr3D E#s(O $$ FNc3hNr(rcLeZdZUdZeeeefed<e ed<de ee ffdZ y)rz:Keep k records with maximum aggregate key values per grouprrtr cJdt|j|jdiS)Nrrrr%s r'r5z MaxK.to_dictrr(Nrr.r(r'rrrr(rceZdZUdZeeZeee e fe d<dZ e ee d<dee effdZedee efddfd Zy) GroupByadGroup results by metadata keys and aggregate within each group. Groups search results by one or more metadata fields, then applies an aggregation (MinK or MaxK) to select records within each group. The final output is flattened and sorted by score. Args: keys: Metadata key(s) to group by. Can be a single key or a list of keys. E.g., Key("category") or [Key("category"), Key("author")] aggregate: Aggregation to apply within each group (MinK or MaxK) Note: Both keys and aggregate must be specified together. Examples: # Top 3 documents per category (single key) GroupBy( keys=Key("category"), aggregate=MinK(keys=Key.SCORE, k=3) ) # Top 2 per (year, category) combination (multiple keys) GroupBy( keys=[Key("year"), Key("category")], aggregate=MinK(keys=Key.SCORE, k=2) ) # Top 1 per category by priority, score as tiebreaker GroupBy( keys=Key("category"), aggregate=MinK(keys=[Key("priority"), Key.SCORE], k=1) ) rrN aggregater c|jr |jiSdt|ji}|jj|d<|S)z:Convert the GroupBy to a dictionary for JSON serializationrr)rrrr5rs r'r5zGroupBy.to_dictsIyyDNN2I"(*:499*E!F"nn446{ r(r7c t|ts!tdt|j|s t Sd|vr t dd|vr t d|d}t|ttfs!tdt|j|s t d|d}t|ts!tdt|jtj|}t t|| S) zCreate GroupBy from dictionary. Examples: - {} -> GroupBy() (default, no grouping) - {"keys": ["category"], "aggregate": {"$min_k": {"keys": ["#score"], "k": 3}}} zExpected dict for GroupBy, got rzGroupBy requires 'keys' fieldrz"GroupBy requires 'aggregate' fieldz!GroupBy keys must be a list, got zGroupBy keys cannot be emptyz&GroupBy aggregate must be a dict, got )rr) rHrIrJrKr)rrLrMr rrOr)r7raggregate_datars r'rOzGroupBy.from_dicts$%=d4j>Q>Q=RST T9   <= = d "AB BF|$u .?T @S@S?TUV V;< <k*.$/8n9M9V9V8WX ''7 ,T2iHHr()r)r*r+rirrMrrr rTrSr,rrrrr r5rjrOr.r(r'rrswB(-T'BD)E#s(O $B%)Ix ")c3h!IS#X!I9!I!Ir(r)Q dataclassesrrtypingrrrrr r r numpyr numpy.typingr chromadb.api.typesr rrrrrrrrrchromadb.typesrrrrr0rbrgrtr{rrrrrrrrrrrTrrrrrrjrrrrrr>r4rCrErFrIr/rr(rr rrrrSrr rrrrrrrr.r(r'rs7(>>>            G!G! G!T @%@ @ ?? ? // / // / // / 0%0 0 // / 0%0 0 00 0 1%1 1 7u7 7 ;%; ; 4E4 4 8u8 8b/b/L U; L! ; M  )) )     .1.1 .1b  0 ['[' ['|  -$- - V$V V -$- - -$- - ;$; ; ;$; ; ;$; ; C $C  C L V$V V ;$; ; $$$ $ [$$[$ [$| R*R* R*pD9U38_5D$s)D ?5cE#s(O!;<?eCQTHoAV? $% $%S>$% 4c3h # %&$%N 2B2B 2Bj N9N N N9N N PIPI PIr(