D_i%SrSSKJr SSKrSSKrSSKrSSKrSSKJr SSK J r J r J r J r JrJr SSKJr SSKJr SSKJr SS KJrJr SS KJr \ (aSS KJrJrJrJrJ r J!r! \RD"S S 9r#\"S5r$S+Sjr%Sq&S\'S'S,Sjr(S-Sjr)S.Sjr*S/Sjr+S0Sjr,S1Sjr-S2Sjr."SS\5r/S3Sjr0S4Sjr1"SS5r2S5S jr3"S!S"\ 5r4S#SSS$SS%SS&.S6S'jjr5S7S(jr6S5S)jr7S#SSS$SS%SS&.S8S*jjr8g)9z@Module contains logic for indexing documents into vector stores.) annotationsN)islice) TYPE_CHECKINGAnyLiteral TypedDictTypeVarcast) BaseLoader)Document)LangChainException) DocumentIndex RecordManager) VectorStore) AsyncIterable AsyncIteratorCallableIterableIteratorSequencei)intTc[R"URS5SS9R5n[ [ R "[U55$)z3Hashes a string and returns the corresponding UUID.utf-8Fusedforsecurity)hashlibsha1encode hexdigeststruuiduuid5NAMESPACE_UUID) input_string hash_values U/home/james-whalen/.local/lib/python3.13/site-packages/langchain_core/indexing/api.py_hash_string_to_uuidr(,sBG$eik tzz.*5 66Fbool_WARNED_ABOUT_SHA1cT[(d[R"S[SS9 Sqgg)z9Emit a one-time warning about SHA-1 collision weaknesses.aUUsing SHA-1 for document hashing. SHA-1 is *not* collision-resistant; a motivated attacker can construct distinct inputs that map to the same fingerprint. If this matters in your threat model, switch to a stronger algorithm such as 'blake2b', 'sha256', or 'sha512' by specifying `key_encoder` parameter in the `index` or `aindex` function. )category stacklevelTN)r+warningswarn UserWarningr)r'_warn_about_sha1r47s1    M ! " r)cnUS:Xa [5 [X5n[R"[U5$)zKHash *input_string* to a deterministic UUID using the configured algorithm.r)r4_calculate_hashr"r#r$)r% algorithmr&s r' _hash_stringr8Is-F 9J ::nj 11r)c>[R"USS9n[X!S9$)zBHash a nested dictionary to a UUID using the configured algorithm.T sort_keysr7)jsondumpsr8)datar7serialized_datas r'_hash_nested_dictrASsjj6O  ==r)c#f# [U5n[[X 55nU(dgUv M"7fzUtility batching function.N)iterlistr)sizeiterableitchunks r'_batchrJ[s0 hB VB%&  s/1c# /nUShvN n[U5U:aURU5 [U5U:dM:U7v /nMCN> U(aU7v gg7frC)lenappend)rFrGbatchelements r'_abatchrPesXE!g u:  LL ! u: KE    s+AA A A .A A A  Ac^TcS$[T[5(aU4Sj$[T5(aT$STS[T5S3n[ U5e)z$Get the source id from the document.cgNr3)_docs r')_get_source_id_assigner..ysDr)c">URT$rS)metadata)doc source_id_keys r'rUrV{s3<< 6r)zAsource_id_key should be either None, a string or a callable. Got z of type .) isinstancer!callabletype ValueError)rZmsgs` r'_get_source_id_assignerratsc  -%%66  oYtM':&;1 > S/r)c## [5nUH>nURU;dMUR[SUR55 Uv M@ g7f)z>Deduplicate a list of hashed documents while preserving order.r!N)setidaddr )hashed_documentsseen hashed_docs r'_deduplicate_in_orderrisCUD& == $ HHT%/ 0  's A.Ac\rSrSrSrSrg)IndexingExceptionz(Raised when an indexing operation fails.r3N)__name__ __module__ __qualname____firstlineno____doc____static_attributes__r3r)r'rkrks2r)rkc0US:XaV[R"URS5SS9R5n[ [ R "[U55$US:Xa3[R"URS55R5$US:Xa3[R"URS55R5$US:Xa3[R"URS55R5$SU3n[U5e) z8Return a hexadecimal digest of *text* using *algorithm*.rrFrblake2bsha256sha512zUnsupported hashing algorithm: ) rrrr r!r"r#r$rtrurvr_)textr7digestr`s r'r6r6sFdkk'2EJTTV4::nf566It{{734>>@@H~~dkk'23==??H~~dkk'23==?? +I; 7C S/r)ct[UR=(d 05n[U5(a U"U5nO?[URUS9n[ R "USS9n[XQS9n[XH-US9n[UURURS9$![anSUS3n[U5UeSnAff=f)aCalculate a hash of the document, and assign it to the uid. When using one of the predefined hashing algorithms, the hash is calculated by hashing the content and the metadata of the document. Args: document: Document to hash. key_encoder: Hashing algorithm to use for hashing the document. If not provided, a default encoder using SHA-1 will be used. SHA-1 is not collision-resistant, and a motivated attacker could craft two different texts that hash to the same cache key. New applications should use one of the alternative encoders or provide a custom and strong key encoder function to avoid this risk. When changing the key encoder, you must change the index as well to avoid duplicated documents in the cache. Raises: ValueError: If the metadata cannot be serialized using json. Returns: Document with a unique identifier based on the hash of the content and metadata. r<Tr:zFailed to hash metadata: z6. Please use a dict that can be serialized using json.N)rd page_contentrX) dictrXr]r6rzr=r> Exceptionr_r ) document key_encoderrXhash_ content_hashserialized_metaer` metadata_hashs r'_get_document_with_hashrs> $H$5$5$;5GH n[%U5n['[)UVs/sH n[+UUS9PM sn55nUU[%U5- - nUVs/sH nU"U5PM nnUS;a[[-UUSS9H@unnUcSUR.SSS3n [U 5eUS:XdM/UR1U5 MB [3SU5nUR5[3SUVs/sHnUR6PM sn55n/n/n/n [!5n![-UUSS9Hqunn"[3SUR65n#U"(a,U(aU!R1U#5 OU R9U#5 MOUR9U#5 UR9U5 Ms U (aUR;U US9 U[%U 5- nU(a[U [5(a U R<"U4UUS.U =(d 0D6 O1[U [5(aU R>"U40U =(d 0D6 U[%U5[%U!5- - nU[%U!5- nUR;[3SUVs/sHnUR6PM sn5UUS9 US:XdGMUHnUbMSn [AU 5e [3SU5n$URCU$UUS9=n%(dGM[EU U%5 URGU%5 U[%U%5- nURCU$UUS9=n%(aMEGM US:Xd US:XawU(apSn&US:Xa ['U5n&URCU&UUS9=n%(aE[EU U%5 URGU%5 U[%U%5- nURCU&UUS9=n%(aMEUUUUS.$![a [UR55nGNf=fs snfs snfs snfs snf) a*Index data from the loader into the vector store. Indexing functionality uses a manager to keep track of which documents are in the vector store. This allows us to keep track of which documents were updated, and which documents were deleted, which documents should be skipped. For the time being, documents are indexed using their hashes, and users are not able to specify the uid of the document. !!! warning "Behavior changed in `langchain-core` 0.3.25" Added `scoped_full` cleanup mode. !!! warning * In full mode, the loader should be returning the entire dataset, and not just a subset of the dataset. Otherwise, the auto_cleanup will remove documents that it is not supposed to. * In incremental mode, if documents associated with a particular source id appear across different batches, the indexing API will do some redundant work. This will still result in the correct end state of the index, but will unfortunately not be 100% efficient. For example, if a given document is split into 15 chunks, and we index them using a batch size of 5, we'll have 3 batches all with the same source id. In general, to avoid doing too much redundant work select as big a batch size as possible. * The `scoped_full` mode is suitable if determining an appropriate batch size is challenging or if your data loader cannot return the entire dataset at once. This mode keeps track of source IDs in memory, which should be fine for most use cases. If your dataset is large (10M+ docs), you will likely need to parallelize the indexing process regardless. Args: docs_source: Data loader or iterable of documents to index. record_manager: Timestamped set to keep track of which documents were updated. vector_store: `VectorStore` or DocumentIndex to index the documents into. batch_size: Batch size to use when indexing. cleanup: How to handle clean up of documents. - incremental: Cleans up all documents that haven't been updated AND that are associated with source IDs that were seen during indexing. Clean up is done continuously during indexing helping to minimize the probability of users seeing duplicated content. - full: Delete all documents that have not been returned by the loader during this run of indexing. Clean up runs after all documents have been indexed. This means that users may see duplicated content during indexing. - scoped_full: Similar to Full, but only deletes all documents that haven't been updated AND that are associated with source IDs that were seen during indexing. - None: Do not delete any documents. source_id_key: Optional key that helps identify the original source of the document. cleanup_batch_size: Batch size to use when cleaning up documents. force_update: Force update documents even if they are present in the record manager. Useful if you are re-indexing with updated embeddings. key_encoder: Hashing algorithm to use for hashing the document content and metadata. Options include "blake2b", "sha256", and "sha512". !!! version-added "Added in `langchain-core` 0.3.66" key_encoder: Hashing algorithm to use for hashing the document. If not provided, a default encoder using SHA-1 will be used. SHA-1 is not collision-resistant, and a motivated attacker could craft two different texts that hash to the same cache key. New applications should use one of the alternative encoders or provide a custom and strong key encoder function to avoid this risk. When changing the key encoder, you must change the index as well to avoid duplicated documents in the cache. upsert_kwargs: Additional keyword arguments to pass to the add_documents method of the `VectorStore` or the upsert method of the DocumentIndex. For example, you can use this to specify a custom vector_field: upsert_kwargs={"vector_field": "embedding"} !!! version-added "Added in `langchain-core` 0.3.10" Returns: Indexing result which contains information about how many documents were added, updated, deleted, or skipped. Raises: ValueError: If cleanup mode is not one of 'incremental', 'full' or None ValueError: If cleanup mode is incremental and source_id_key is None. ValueError: If `VectorStore` does not have "delete" and "add_documents" required methods. ValueError: If source_id_key is not None, but is not a string or callable. TypeError: If `vectorstore` is not a `VectorStore` or a DocumentIndex. AssertionError: If `source_id` is None when cleanup mode is incremental. (should be unreachable code). r>Nfull incremental scoped_fullKcleanup should be one of 'incremental', 'full', 'scoped_full' or None. Got r[>rrNJSource id key is required when cleanup mode is incremental or scoped_full.r add_documents Vectorstore  does not have required method z1Vectorstore has not implemented the delete methodrrr~FstrictlSource IDs are required when cleanup mode is incremental or scoped_full. Document that starts with content: r was not assigned as source id.r Sequence[str]r! time_at_leastrr group_idsrrAsource_id cannot be None at this point. Reached unreachable code.rbeforelimitrrrrr)$r4r_r\rhasattrr^rrrr lazy_loadrrDloadraget_timercrJrLrErirziprzrer existsrdrMupdaterupsertAssertionError list_keysr delete_keys)' docs_sourcerecord_managerrrrrZrrr~rr` destinationmethodsmethod doc_iteratorsource_id_assignerindex_start_dtrrrrscoped_full_cleanup_source_ids doc_batchoriginal_batch_sizerY hashed_docsrh source_ids source_id exists_batchuids docs_to_indexuids_to_refresh seen_docs doc_exists hashed_id source_ids_uids_to_deletedelete_group_idss' r'indexr"s`fBB)1  o11}7L X oK+{++_-F;//";-/NvhW!o%    # #{'9'9 9FCS/ ! : K / /  $%Q ( n+z** 4&002LK( 0?$,,.NIKKK/2u"J5 !)n ! )(,C[I(   *S-=== >I, =Hz z *[ ,  4 4),ZU)S% :$$%/$;$;DS$A#BC9:%S/)m+266yA*Toz:J%,, ["A[c366["A B  !e &)+|E&R "J UJMM2IMM),#**95 KK "   ,'S   ! !/ ! P 3/ /K +{33))!)%*  K77""!$* ]+c)n< )K  ["A[c366["A B (   m #( $4)-- ( ;K$2$<$<%nDV%=%. ^4**>:s>22 %3$<$<%nDV%=%.Q6b&= %C15 m ##$BC  . 8 8&~EW!9!  n  K 0  & &~ 6 3~. .K!/ 8 8&~EW!9!  n """  _# 4 0 0 23L 4*, ,#B^#Bs*S-1T%T/T!/T&-#TTc(# UHnU7v M g7f)z)Convert an iterable to an async iterator.Nr3)iteratoritems r'_to_async_iteratorrYs sch# [U[5(a0URU5IShvN nUbUSLa Sn[U5egg[U[5(a7URU5IShvN nSU;aUSS:a Sn[U5eggS[ U5S3n[ U5eNN>7f)NFrrrrrr[)r\radeleterkrr^rrs r'_adeleter_s, ,,&..s33  Y%%7?C#C( (&8  L- 0 0 , 4 4S 99 ? *|/Lq/PAC#C( (0Q *  %&a ) n4 :s"*B2B.AB21B02=B20B2c  # US:Xa [5 US;aSUS3n [U 5eUS;aUc Sn [U 5eUn [U [5(aSS /n U H&n [ X5(aMS U S U 3n [U 5e [ U 5R [R :Xa4[ U 5R[R:Xa S n [U 5eO0[U [5(aOS [ U 5S3n [U 5e[U[5(aUR5nO[ US5(aUnO [U5n[U5nUR!5IShvN nSnSnSnSn[#5n[%X>5ShvN n['U5n[)[+UVs/sH n[-UUS9PM sn55nUU['U5- - nUVs/sH nU"U5PM nnUS;a[[/UUSS9H@unnUcSUR0SSS3n [U 5eUS:XdM/UR3U5 MB [5SU5nUR7[5SUVs/sHnUR8PM sn55IShvN n/n/n/n [#5n![/UUSS9Hqunn"[5SUR85n#U"(a,U(aU!R3U#5 OU R;U#5 MOUR;U#5 UR;U5 Ms U (a&UR=U US9IShvN U['U 5- nU(a[U [5(a(U R>"U4UUS.U =(d 0D6IShvN O9[U [5(a$U R@"U40U =(d 0D6IShvN U['U5['U!5- - nU['U!5- nUR=[5SUVs/sHnUR8PM sn5UUS9IShvN US:XdGMUHnUbMSn [CU 5e [5SU5n$UREU$UUS9IShvN =n%(dGM[GU U%5IShvN URIU%5IShvN U['U%5- nUREU$UUS9IShvN =n%(aM]GMZ![a [UR55nGNf=fGNGNs snfs snfs snfGNGNGNGNds snfGNNNNNi US:Xd US:XaU(aSn&US:Xa [)U5n&UREU&UUS9IShvN =n%(a`[GU U%5IShvN URIU%5IShvN U['U%5- nUREU&UUS9IShvN =n%(aM`UUUUS .$7f)!a@Async index data from the loader into the vector store. Indexing functionality uses a manager to keep track of which documents are in the vector store. This allows us to keep track of which documents were updated, and which documents were deleted, which documents should be skipped. For the time being, documents are indexed using their hashes, and users are not able to specify the uid of the document. !!! warning "Behavior changed in `langchain-core` 0.3.25" Added `scoped_full` cleanup mode. !!! warning * In full mode, the loader should be returning the entire dataset, and not just a subset of the dataset. Otherwise, the auto_cleanup will remove documents that it is not supposed to. * In incremental mode, if documents associated with a particular source id appear across different batches, the indexing API will do some redundant work. This will still result in the correct end state of the index, but will unfortunately not be 100% efficient. For example, if a given document is split into 15 chunks, and we index them using a batch size of 5, we'll have 3 batches all with the same source id. In general, to avoid doing too much redundant work select as big a batch size as possible. * The `scoped_full` mode is suitable if determining an appropriate batch size is challenging or if your data loader cannot return the entire dataset at once. This mode keeps track of source IDs in memory, which should be fine for most use cases. If your dataset is large (10M+ docs), you will likely need to parallelize the indexing process regardless. Args: docs_source: Data loader or iterable of documents to index. record_manager: Timestamped set to keep track of which documents were updated. vector_store: `VectorStore` or DocumentIndex to index the documents into. batch_size: Batch size to use when indexing. cleanup: How to handle clean up of documents. - incremental: Cleans up all documents that haven't been updated AND that are associated with source IDs that were seen during indexing. Clean up is done continuously during indexing helping to minimize the probability of users seeing duplicated content. - full: Delete all documents that have not been returned by the loader during this run of indexing. Clean up runs after all documents have been indexed. This means that users may see duplicated content during indexing. - scoped_full: Similar to Full, but only deletes all documents that haven't been updated AND that are associated with source IDs that were seen during indexing. - None: Do not delete any documents. source_id_key: Optional key that helps identify the original source of the document. cleanup_batch_size: Batch size to use when cleaning up documents. force_update: Force update documents even if they are present in the record manager. Useful if you are re-indexing with updated embeddings. key_encoder: Hashing algorithm to use for hashing the document content and metadata. Options include "blake2b", "sha256", and "sha512". !!! version-added "Added in `langchain-core` 0.3.66" key_encoder: Hashing algorithm to use for hashing the document. If not provided, a default encoder using SHA-1 will be used. SHA-1 is not collision-resistant, and a motivated attacker could craft two different texts that hash to the same cache key. New applications should use one of the alternative encoders or provide a custom and strong key encoder function to avoid this risk. When changing the key encoder, you must change the index as well to avoid duplicated documents in the cache. upsert_kwargs: Additional keyword arguments to pass to the add_documents method of the `VectorStore` or the upsert method of the DocumentIndex. For example, you can use this to specify a custom vector_field: upsert_kwargs={"vector_field": "embedding"} !!! version-added "Added in `langchain-core` 0.3.10" Returns: Indexing result which contains information about how many documents were added, updated, deleted, or skipped. Raises: ValueError: If cleanup mode is not one of 'incremental', 'full' or None ValueError: If cleanup mode is incremental and source_id_key is None. ValueError: If `VectorStore` does not have "adelete" and "aadd_documents" required methods. ValueError: If source_id_key is not None, but is not a string or callable. TypeError: If `vector_store` is not a `VectorStore` or DocumentIndex. AssertionError: If `source_id_key` is None when cleanup mode is incremental or `scoped_full` (should be unreachable). r>Nrrrrr[>rrNrraadd_documentsrrz,>>QCS/ ! K / /  $%Q ( n+z** H!,!7!7!9  k * *(/ <0?*3355NIKKK/2u"":Bp3i!)n ! )(,C[I(   *S-=== 0;, /: s #{ ,  4 4),ZU)S% :$$%/$;$;DS$A#BC9:%S/)m+266yA*Toz:J+33 ["A[c366["A B  (* !e &)+|E&R "J UJMM2IMM),#**95 KK "   ,'S  (((W W W 3/ /K +{33!00!)%*  K77!))!$* ]+c)n< )K $$ ["A[c366["A B (%    m # ( $4)-- ( ;K*8*C*C%nDV+D+%.{N;;;$11.AAAs>22 +9*C*C%nDV+D+%.# H "4K4D4D4F!G   H6p3 , ,#B , X#B .%<A %SCd&= %C15 m ##$BC &4&?&?&~EW'@' ! !  n ;7 7 7 --n= = = 3~. .K'5&?&?&~EW'@' ! !  n """  sA,W=2B6W=)S39>W=7T8!W=UT U!W=;T# W=/T(>W=6W=9T-W=T2B.W= T5 AW=T89W=T;AW=T>/W==U>W= W=/W=U W=W="U#W=;U <&W="U # W=0W=3#TW=TW= U#W=5W=8W=;W=>W=W=W= W= W=;W= V  W=%V(&W=?W'W='W*( W=6W=)r%r!rr!)rr)r%r!r7.Literal['sha1', 'sha256', 'sha512', 'blake2b']r uuid.UUID)r?zdict[Any, Any]r7rrr)rFrrG Iterable[T]rzIterator[list[T]])rFrrGzAsyncIterable[T]rzAsyncIterator[list[T]])rZ&str | Callable[[Document], str] | Nonerz Callable[[Document], str | None])rfzIterable[Document]rzIterator[Document])rwr!r7rrr!)r}r r~zJCallable[[Document], str] | Literal['sha1', 'sha256', 'sha512', 'blake2b']rr )rVectorStore | DocumentIndexrz list[str]rr)rzBaseLoader | Iterable[Document]rrrrrrr4Literal['incremental', 'full', 'scoped_full'] | NonerZrrrrr*r~JLiteral['sha1', 'sha256', 'sha512', 'blake2b'] | Callable[[Document], str]rdict[str, Any] | Nonerr)rrrzAsyncIterator[T])rz9BaseLoader | Iterable[Document] | AsyncIterator[Document]rrrrrrrrrZrrrrr*r~rrrrr)9rq __future__rrr=r"r0 itertoolsrtypingrrrrr r $langchain_core.document_loaders.baser langchain_core.documentsr langchain_core.exceptionsr langchain_core.indexing.baserrlangchain_core.vectorstoresrcollections.abcrrrrrrUUIDr$rr(r+rr4r8rArJrPrarirkr6rrrrrrrrr3r)r'r sF" <-8E3t$ CL7!D "$22%S22> >(V>> 9%" (  3*3 H$7757  7x ' '-  H LY L$DH<@#"(+/s0s!s.s  s B s:sss s)ssn  -  6DH<@#"(+/J!.   B : )r)