
    Q
i^              	          d Z ddlmZ ddlmZmZmZmZmZm	Z	m
Z
mZ ddlmZmZmZmZ ddlmZ ddlmZ ddlmZ ddlmZ dd	lmZ dd
lmZ ddlmZ ddlm Z m!Z!  ee"          Z#e e!ddZ$ G d de%e          Z& G d de%e          Z' G d de%e          Z( G d de%e          Z) G d de%e          Z*	 dEdedee%         de+ddfdZ, G d d e          Z- G d! d"e-          Z. G d# d$e-          Z/ G d% d&e-          Z0 G d' d(e-          Z1 G d) d*e          Z2 G d+ d,e2          Z3 G d- d.e2          Z4 G d/ d0e2          Z5 G d1 d2e          Z6 G d3 d4e6          Z G d5 d6e6          Z G d7 d8e6          Z G d9 d:e6          Z G d; d<e6          Z7 G d= d>e6          Z8 G d? d@e6          Z9eeeedAZ:e7e8e9dBZ; G dC dD          Z<dS )Fa  
RedisVL Schema Fields and Attributes

This module defines field types and their attributes for creating Redis search indices.

Field Types:
    - TextField: Full-text search with stemming, phonetic matching
    - TagField: Exact-match categorical data (tags, categories, IDs)
    - NumericField: Numeric values for range queries and sorting
    - GeoField: Geographic coordinates for location-based search
    - VectorField: Vector embeddings for semantic similarity search
        - FlatVectorField: Exact search (100% recall)
        - HNSWVectorField: Approximate nearest neighbor search (fast, high recall)
        - SVSVectorField: Compressed vector search with memory savings

Common Vector Field Attributes (all algorithms):
    - dims: Number of dimensions in the vector (e.g., 768, 1536)
    - algorithm: Indexing algorithm ('flat', 'hnsw', or 'svs-vamana')
    - datatype: Float precision ('float16', 'float32', 'float64', 'bfloat16')
        Note: SVS-VAMANA only supports 'float16' and 'float32'
    - distance_metric: Similarity metric ('COSINE', 'L2', 'IP')
    - initial_cap: Initial capacity hint for memory allocation (optional)
    - index_missing: Allow searching for documents without this field (optional)

Algorithm-Specific Parameters:
    - FLAT: block_size (memory management for dynamic indices)
    - HNSW: m, ef_construction, ef_runtime, epsilon (graph tuning)
    - SVS-VAMANA: graph_max_degree, construction_window_size, search_window_size,
                  compression, reduce, training_threshold (VAMANA graph algorithm
                  with Intel hardware optimization and vector compression)

References:
    - Redis FT.CREATE: https://redis.io/commands/ft.create/
    - Vector Search: https://redis.io/docs/interact/search-and-query/advanced-concepts/vectors/
    )Enum)AnyDictListLiteralOptionalTupleTypeUnion)	BaseModelFieldfield_validatormodel_validator)r   )GeoField)NumericField)TagField)	TextField)VectorField)
get_logger)norm_cosine_distancenorm_l2_distanceN)COSINEL2IPc                   "    e Zd ZdZdZdZdZdZdS )
FieldTypestagtextnumericgeovectorN)__name__
__module____qualname__TAGTEXTNUMERICGEOVECTOR     C:\Users\Dell Inspiron 16\Desktop\tws\AgrotaPowerBi\back-agrota-powerbi\mcp-client-agrota\venv\Lib\site-packages\redisvl/schema/fields.pyr   r   <   s'        
CDG
CFFFr+   r   c                       e Zd ZdZdZdZdS )VectorDistanceMetricr   r   r   N)r"   r#   r$   r   r   r   r*   r+   r,   r.   r.   D   s        F	B	BBBr+   r.   c                   &    e Zd ZdZdZdZdZdZdZdS )VectorDataTypeBFLOAT16FLOAT16FLOAT32FLOAT64INT8UINT8N)	r"   r#   r$   r1   r2   r3   r4   r5   r6   r*   r+   r,   r0   r0   J   s,        HGGGDEEEr+   r0   c                       e Zd ZdZdZdZdS )VectorIndexAlgorithmFLATHNSWz
SVS-VAMANAN)r"   r#   r$   r9   r:   
SVS_VAMANAr*   r+   r,   r8   r8   S   s        DDJJJr+   r8   c                   *    e Zd ZdZdZdZdZdZdZdZ	dS )	CompressionTypez1Vector compression types for SVS-VAMANA algorithmLVQ4LVQ4x4LVQ4x8LVQ8
LeanVec4x8
LeanVec8x8N)
r"   r#   r$   __doc__r>   r?   r@   rA   rB   rC   r*   r+   r,   r=   r=   Y   s2        ;;DFFDJJJJr+   r=   Ffieldcanonical_orderwant_unfreturnc                     t          | j                  }g }|D ]<}||v r6|                    |           |dk    r|rd|vr|                    d           =|| _        dS )a  Normalize field modifier ordering for RediSearch parser.

    RediSearch has a parser limitation where INDEXEMPTY and
    INDEXMISSING must appear BEFORE SORTABLE in field definitions. This function
    reorders field.args_suffix to match the canonical order.

    Args:
        field: Redis field object whose args_suffix will be normalized
        canonical_order: List of modifiers in desired canonical order
        want_unf: Whether UNF should be added after SORTABLE (default: False)

    Time Complexity: O(n + m), where n = len(field.args_suffix), m = len(canonical_order).
        - O(n) to create the set from field.args_suffix
        - O(m) to iterate over canonical_order and perform set lookups (O(1) average case per lookup)
    Space Complexity: O(n)

    Example:
        >>> field = RedisTextField("title")
        >>> field.args_suffix = ["SORTABLE", "INDEXMISSING"]
        >>> _normalize_field_modifiers(field, ["INDEXEMPTY", "INDEXMISSING", "SORTABLE"])
        >>> field.args_suffix
        ['INDEXMISSING', 'SORTABLE']
    SORTABLEUNFN)setargs_suffixappend)rE   rF   rG   
suffix_set
new_suffixmodifiers         r,   _normalize_field_modifiersrR   g   s    4 U&''J J# ) )z!!h''':%%(%uJ7N7N!!%((("Er+   c                   ~    e Zd ZU dZ ed          Zeed<   	  ed          Zeed<   	  ed          Z	eed<   dS )BaseFieldAttributesz4Base field attributes shared by other lexical fieldsFdefaultsortableindex_missingno_indexN)
r"   r#   r$   rD   r   rW   bool__annotations__rX   rY   r*   r+   r,   rT   rT      su         >>U5)))Hd)))>%...M4...WU5)))Hd)))VVr+   rT   c                       e Zd ZU dZ ed          Zeed<   	  ed          Ze	ed<   	  ed          Z
e	ed<   	 dZee         ed	<   	  ed          Ze	ed
<   	  ed          Ze	ed<   dS )TextFieldAttributeszFull text field attributes   rU   weightFno_stemwithsuffixtrieNphonetic_matcherindex_emptyunf)r"   r#   r$   rD   r   r_   floatr[   r`   rZ   ra   rb   r   strrc   rd   r*   r+   r,   r]   r]      s         $$E!$$$FE$$$HE%(((GT(((< 5///ND///^&*hsm***9e,,,K,,,8e$$$C$$$iir+   r]   c                       e Zd ZU dZ ed          Zeed<   	  ed          Ze	ed<   	  ed          Z
e	ed<   	  ed          Ze	ed<   d	S )
TagFieldAttributeszTag field attributes,rU   	separatorFcase_sensitivera   rc   N)r"   r#   r$   rD   r   rj   rf   r[   rk   rZ   ra   rc   r*   r+   r,   rh   rh      s         U3'''Is'''X 5///ND///d 5///ND///^e,,,K,,,88r+   rh   c                   6    e Zd ZU dZ ed          Zeed<   dS )NumericFieldAttributesNumeric field attributesFrU   rd   N)r"   r#   r$   rD   r   rd   rZ   r[   r*   r+   r,   rm   rm      s5         ""e$$$C$$$iir+   rm   c                       e Zd ZdZdS )GeoFieldAttributesrn   N)r"   r#   r$   rD   r*   r+   r,   rp   rp      s        ""Dr+   rp   c                   4   e Zd ZU dZeed<   	 eed<   	  eej	                  Z
eed<   	  eej                  Zeed<   	 dZee         ed<   	  ed	          Zeed
<   	  edddd          ed                         Zedeeef         fd            ZdS )BaseVectorFieldAttributeszHBase vector field attributes shared by FLAT, HNSW, and SVS-VAMANA fieldsdims	algorithmrU   datatypedistance_metricNinitial_capFrX   beforemodec                 *    |                                 S )z3Validate that provided values are cast to uppercase)upper)clsvs     r,   uppercase_stringsz+BaseVectorFieldAttributes.uppercase_strings   s     wwyyr+   rH   c                 j    | j         | j        | j        d}| j        
| j        |d<   | j        rd|d<   |S )z+Select attributes required by the Redis API)TYPEDIMDISTANCE_METRICNINITIAL_CAPTINDEXMISSING)ru   rs   rv   rw   rX   )self
field_datas     r,   r   z$BaseVectorFieldAttributes.field_data   sS     M9#3
 


 '(,(8J}% 	.)-J~&r+   )r"   r#   r$   rD   intr[   r8   r   r0   r3   ru   r.   r   rv   rw   r   rX   rZ   r   classmethodr   propertyr   rf   r   r   r*   r+   r,   rr   rr      s        RR
III7####I$u^-CDDDHnDDD6,1E:N:U,V,V,VO)VVV=!%K#%%%\%...M4...W_[*.?hOOO  [ PO DcN    X  r+   rr   c                   ^    e Zd ZU dZej        Zeej                 ed<   	 dZ	e
e         ed<   dS )FlatVectorFieldAttributesz?FLAT vector field attributes for exact nearest neighbor search.rt   N
block_size)r"   r#   r$   rD   r8   r9   rt   r   r[   r   r   r   r*   r+   r,   r   r      sK         II4H4MIw+01MMM2 $J$$$TTr+   r   c                       e Zd ZU dZej        Zeej                 ed<   	  e	d          Z
eed<   	  e	d          Zeed<   	  e	d          Zeed	<   	  e	d
          Zeed<   dS )HNSWVectorFieldAttributeszEHNSW vector field attributes for approximate nearest neighbor search.rt      rU   m   ef_construction
   
ef_runtime{Gz?epsilonN)r"   r#   r$   rD   r8   r:   rt   r   r[   r   r   r   r   r   r   re   r*   r+   r,   r   r      s         OO4H4MIw+01MMM2U2AsN 5---OS---NeB'''J'''SU4(((GU(((66r+   r   c                   R   e Zd ZU dZej        Zeej                 ed<   	  e	d          Z
eed<   	  e	d          Zeed<   	  e	d          Zeed	<   	  e	d
          Zeed<   	 dZee         ed<   	 dZee         ed<   	 dZee         ed<   	  ed          d             ZdS )SVSVectorFieldAttributesz<SVS-VAMANA vector field attributes with compression support.rt   (   rU   graph_max_degree   construction_window_size   search_window_sizer   r   Ncompressionreducetraining_thresholdafterry   c                     | j         t          j        t          j        fvrt	          d| j          d          | j        | j        | j        k    r t	          d| j         d| j         d          | j        t	          d          | j        j        	                    d          st	          d	| j        j         d
          | j        rL| j        j        	                    d          r-| j        s&t                              d| j        dz   d           | j        r.| j        dk     r#t                              d| j         d           | j        r.| j        dk    r#t                              d| j         d           | S )z(Validate SVS-VAMANA specific constraintsz=SVS-VAMANA only supports FLOAT16 and FLOAT32 datatypes. Got: z4. Unsupported types: BFLOAT16, FLOAT64, INT8, UINT8.Nzreduce (z) must be less than dims ()zfreduce parameter requires compression to be set. Use LeanVec4x8 or LeanVec8x8 compression with reduce.LeanVeczSreduce parameter is only supported with LeanVec compression types. Got compression=zB. Either use LeanVec4x8/LeanVec8x8 or remove the reduce parameter.zGLeanVec compression selected without 'reduce'. Consider setting reduce=   z for better performance    zgraph_max_degree=z9 is low. Consider values between 32-64 for better recall.d   zsearch_window_size=zG is high. This may impact query latency. Consider values between 20-50.)ru   r0   r2   r3   
ValueErrorr   rs   r   value
startswithloggerwarningr   r   r   s    r,   validate_svs_paramsz,SVSVectorFieldAttributes.validate_svs_params(  s    =!79O PPPFF F F   ;"{di'' Rt{RRdiRRR  
 ' L  
 #)44Y??  X'+'7'=X X X   	 &11)<<	 K	
 NNS+/9>S S S  
   	T%:R%?%?NNDD$9 D D D  
 " 	t'>'D'DNNQd&= Q Q Q  
 r+   )r"   r#   r$   rD   r8   r;   rt   r   r[   r   r   r   r   r   r   re   r   r   r=   r   r   r   r   r*   r+   r,   r   r   	  s=        FF 	' w+67    6 "E"---c---E$)E#$6$6$6c666N#eB//////DU4(((GU(((5 .2K/*111@ FHSM   E(,,,,C_'"""6 6 #"6 6 6r+   r   c                       e Zd ZU dZeed<   	 eed<   	 dZee         ed<   	 dZee	e
ef                  ed<   	 deeee         f         fdZdefd	ZdS )
	BaseFieldz
Base fieldnametypeNpathattrsrH   c                 >    | j         r| j         | j        fS | j        dfS )z/Helper to handle field naming with path supportN)r   r   r   s    r,   _handle_nameszBaseField._handle_namesq  s'    9 	(9di''y$r+   c                      t          d          )z*Convert schema field to Redis Field objectz'Must be implemented by field subclasses)NotImplementedErrorr   s    r,   as_redis_fieldzBaseField.as_redis_fieldw  s    !"KLLLr+   )r"   r#   r$   rD   rf   r[   r   r   r   r   rT   rr   r	   r   
RedisFieldr   r*   r+   r,   r   r   e  s         
III
IIID(3-)MQE8E-/HHIJQQQ$uS(3-%78    M
 M M M M M Mr+   r   c                   p    e Zd ZU dZej        Zeej                 ed<    e	e
          Ze
ed<   defdZdS )r   z.Text field supporting a full text search indexr   default_factoryr   rH   c                    |                                  \  }}| j        j        | j        j        | j        j        d}|||d<   | j        j        | j        j        |d<   | j        j        rd|d<   | j        j        rd|d<   | j        j        rd|d<   t          |fi |}g d}| j        j
        o| j        j        }t          |||           |S )	N)r_   r`   rW   as_namerb   TrX   rc   rY   )
INDEXEMPTYr   rJ   rK   NOINDEX)r   r   r_   r`   rW   rb   rX   rc   rY   RedisTextFieldrd   rR   r   r   r   kwargsrE   rF   rG   s          r,   r   zTextField.as_redis_field  s   **,,g j'z)
+"
 "
  'F9 :&2)-)DF%& :# 	+&*F?# :! 	)$(F=! : 	&!%F:t..v.. WVV:>9dj&9"5/8DDDr+   N)r"   r#   r$   rD   r   r&   r   r   r[   r   r]   r   r   r   r*   r+   r,   r   r   |  so         88%/_D'*/
"444!&7J!K!K!KEKKK%
 % % % % % %r+   r   c                   p    e Zd ZU dZej        Zeej                 ed<    e	e
          Ze
ed<   defdZdS )r   z,Tag field for simple boolean-style filteringr   r   r   rH   c                 2   |                                  \  }}| j        j        | j        j        | j        j        d}|||d<   | j        j        rd|d<   | j        j        rd|d<   | j        j        rd|d<   t          |fi |}g d}t          ||           |S )N)rj   rk   rW   r   TrX   rc   rY   )r   r   rJ   r   )
r   r   rj   rk   rW   rX   rc   rY   RedisTagFieldrR   r   r   r   r   rE   rF   s         r,   r   zTagField.as_redis_field  s    **,,g -"j7
+"
 "
  'F9 :# 	+&*F?# :! 	)$(F=! : 	&!%F:d--f-- POO"5/:::r+   N)r"   r#   r$   rD   r   r%   r   r   r[   r   rh   r   r   r   r*   r+   r,   r   r     so         66$.ND'*.
!222 %6H I I IEIII 
            r+   r   c                   p    e Zd ZU dZej        Zeej                 ed<    e	e
          Ze
ed<   defdZdS )r   z)Numeric field for numeric range filteringr   r   r   rH   c                    |                                  \  }}d| j        j        i}|||d<   | j        j        rd|d<   | j        j        rd|d<   t          |fi |}g d}| j        j        o| j        j        }t          |||           |S )NrW   r   TrX   rY   )r   rJ   rK   r   )r   r   rW   rX   rY   RedisNumericFieldrd   rR   r   s          r,   r   zNumericField.as_redis_field  s    **,,g 
+"

  'F9 :# 	+&*F?# : 	&!%F:!$11&11
 IHH:>9dj&9"5/8DDDr+   N)r"   r#   r$   rD   r   r'   r   r   r[   r   rm   r   r   r   r*   r+   r,   r   r     sq         33(2(:D'*$
%:::$)E:P$Q$Q$QE!QQQ
      r+   r   c                   p    e Zd ZU dZej        Zeej                 ed<    e	e
          Ze
ed<   defdZdS )r   z<Geo field with a geo-spatial index for location based searchr   r   r   rH   c                     |                                  \  }}d| j        j        i}|||d<   | j        j        rd|d<   | j        j        rd|d<   t          |fi |}g d}t          ||           |S )NrW   r   TrX   rY   )r   rJ   r   )r   r   rW   rX   rY   RedisGeoFieldrR   r   s         r,   r   zGeoField.as_redis_field  s    **,,g 
+"

  'F9 :# 	+&*F?# : 	&!%F:d--f--
 BAA"5/:::r+   N)r"   r#   r$   rD   r   r(   r   r   r[   r   rp   r   r   r   r*   r+   r,   r   r     so         FF$.ND'*.
!222 %6H I I IEIII
      r+   r   c                   X    e Zd ZU dZej        Zeej                 ed<   e	ed<   de
fdZdS )FlatVectorFieldzQVector field with FLAT (exact search) indexing for exact nearest neighbor search.r   r   rH   c                     |                                  \  }}| j        j        }| j        j        | j        j        |d<   t	          || j        j        ||          S )N
BLOCK_SIZEr   )r   r   r   r   RedisVectorFieldrt   r   r   r   r   s       r,   r   zFlatVectorField.as_redis_field"  sX    **,,gZ*
: ,'+z'<J|$dj&:JPWXXXXr+   N)r"   r#   r$   rD   r   r)   r   r   r[   r   r   r   r*   r+   r,   r   r     se         [['1'8D'*#
$888$$$$Y
 Y Y Y Y Y Yr+   r   c                   D    e Zd ZU dZdZed         ed<   eed<   defdZ	dS )HNSWVectorFieldzmVector field with HNSW (Hierarchical Navigable Small World) indexing for approximate nearest neighbor search.r!   r   r   rH   c                    |                                  \  }}| j        j        }|                    | j        j        | j        j        | j        j        | j        j        d           t          || j        j	        ||          S )N)MEF_CONSTRUCTION
EF_RUNTIMEEPSILONr   )
r   r   r   updater   r   r   r   r   rt   r   s       r,   r   zHNSWVectorField.as_redis_field1  s    **,,gZ*
Z\#':#="j3:-	 	
 	
 	
  dj&:JPWXXXXr+   N)
r"   r#   r$   rD   r   r   r[   r   r   r   r*   r+   r,   r   r   +  s_         ww&D'(
&&&$$$$Y
 Y Y Y Y Y Yr+   r   c                   X    e Zd ZU dZej        Zeej                 ed<   e	ed<   de
fdZdS )SVSVectorFieldzoVector field with SVS-VAMANA indexing and compression for memory-efficient approximate nearest neighbor search.r   r   rH   c                    |                                  \  }}| j        j        }|                    | j        j        | j        j        | j        j        | j        j        d           | j        j        | j        j        |d<   | j        j	        | j        j	        |d<   | j        j
        | j        j
        |d<   t          || j        j        ||          S )N)GRAPH_MAX_DEGREECONSTRUCTION_WINDOW_SIZESEARCH_WINDOW_SIZEr   COMPRESSIONREDUCETRAINING_THRESHOLDr   )r   r   r   r   r   r   r   r   r   r   r   r   rt   r   s       r,   r   zSVSVectorField.as_redis_fieldF  s    **,,gZ*
$(J$?,0J,O&*j&C:-	 	
 	
 	
 :!-(,
(>J}%:(#':#4Jx :(4/3z/LJ+,dj&:JPWXXXXr+   N)r"   r#   r$   rD   r   r)   r   r   r[   r   r   r   r*   r+   r,   r   r   @  se         yy'1'8D'*#
$888####Y
 Y Y Y Y Y Yr+   r   )r   r   r   r    )flathnswz
svs-vamanac                       e Zd ZdZedeeef         dee	         fd            Z
ei dfdededeeef         dee         de	f
d	            ZdS )
FieldFactoryz;Factory class to create fields from client data and kwargs.r   rH   c                     d|vrt          d          d|vrt          d          |d                                         }|t          vrt          d|           t          |         S )z.Get the vector field type from the field data.rt   z2Must provide algorithm param for the vector field.rs   z-Must provide dims param for the vector field.z Unknown vector field algorithm: )r   lowerVECTOR_FIELD_TYPE_MAP)r}   r   rt   s      r,   pick_vector_field_typez#FieldFactory.pick_vector_field_typel  s|     e##QRRRLMMM+&,,..	111K	KKLLL$Y//r+   Nr   r   r   c                     |dk    r|                      |          }n(|t          vrt          d|           t          |         }|                    |||d          S )z8Create a field of a given type with provided attributes.r!   zUnknown field type: )r   r   r   )r   FIELD_TYPE_MAPr   model_validate)r}   r   r   r   r   field_classs         r,   create_fieldzFieldFactory.create_field{  s{     844U;;KK>)) !>!>!>???(.K)) 
 
 	
r+   )r"   r#   r$   rD   r   r   rf   r   r
   r   r   r   r   r*   r+   r,   r   r   i  s        EE04S> 0d9o 0 0 0 [0 
 !#"
 

 
 CH~	

 sm
 

 
 
 [
 
 
r+   r   )F)=rD   enumr   typingr   r   r   r   r   r	   r
   r   pydanticr   r   r   r   redis.commands.search.fieldr   r   r   r   r   r   r   r   r   r   r   redisvl.utils.logr   redisvl.utils.utilsr   r   r"   r   VECTOR_NORM_MAPrf   r   r.   r0   r8   r=   rZ   rR   rT   r]   rh   rm   rp   rr   r   r   r   r   r   r   r   r   r   r   r*   r+   r,   <module>r      s  " "H       I I I I I I I I I I I I I I I I I I I I G G G G G G G G G G G G ; ; ; ; ; ; A A A A A A I I I I I I A A A A A A C C C C C C G G G G G G ( ( ( ( ( ( F F F F F F F F	H		 #

     d       3       S$       3       c4    EJ%# %#%#(,S	%#=A%#	%# %# %# %#VW W W W W) W W Wj j j j j- j j j"
9 
9 
9 
9 
9, 
9 
9 
9j j j j j0 j j j	 	 	 	 	, 	 	 	" " " " "	 " " "JU U U U U 9 U U U7 7 7 7 7 9 7 7 7$V V V V V8 V V VxM M M M M	 M M M.+ + + + +	 + + +\& & & & &y & & &R" " " " "9 " " "J! ! ! ! !y ! ! !HY Y Y Y Yi Y Y YY Y Y Y Yi Y Y Y*Y Y Y Y YY Y Y Y8 	     )
 )
 )
 )
 )
 )
 )
 )
 )
 )
r+   