a
    ”˜ëjFA  ã                   @  s*  d Z ddlmZ ddlZddlmZmZ ddlmZ ddl	m
Z
mZmZ ddlmZ ddlmZmZmZ dd	lmZ dd
lmZ ddlmZmZ ddlmZ ddlmZmZmZm Z  ddl!m"Z" e
rÔddlm#Z#m$Z$ e%Z&e'e Z(ee&e(f Z)eee(f Z*G dd„ dedd�Z+G dd„ dee&e(f eƒZ,dS )a„  **Retriever** class returns Documents given a text **query**.

It is more general than a vector store. A retriever does not need to be able to
store documents, only to return (or retrieve) it. Vector stores can be used as
the backbone of a retriever, but there are other types of retrievers as well.

**Class hierarchy:**

.. code-block::

    BaseRetriever --> <name>Retriever  # Examples: ArxivRetriever, MergerRetriever

**Main helpers:**

.. code-block::

    RetrieverInput, RetrieverOutput, RetrieverLike, RetrieverOutputLike,
    Document, Serializable, Callbacks,
    CallbackManagerForRetrieverRun, AsyncCallbackManagerForRetrieverRun
é    )ÚannotationsN)ÚABCÚabstractmethod)Ú	signature)ÚTYPE_CHECKINGÚAnyÚOptional)Ú
ConfigDict)ÚSelfÚ	TypedDictÚoverride)Ú
deprecated)Ú	Callbacks)ÚAsyncCallbackManagerÚCallbackManager)ÚDocument)ÚRunnableÚRunnableConfigÚRunnableSerializableÚensure_config)Úrun_in_executor)Ú#AsyncCallbackManagerForRetrieverRunÚCallbackManagerForRetrieverRunc                   @  s2   e Zd ZU dZded< ded< ded< ded< dS )	ÚLangSmithRetrieverParamsz!LangSmith parameters for tracing.ÚstrÚls_retriever_nameúOptional[str]Zls_vector_store_providerZls_embedding_providerZls_embedding_modelN)Ú__name__Ú
__module__Ú__qualname__Ú__doc__Ú__annotations__© r"   r"   úX/mnt/bigstor/www/usecases/.venv/lib/python3.9/site-packages/langchain_core/retrievers.pyr   8   s   
r   F)Útotalc                
      s<  e Zd ZU dZedd�ZdZded< dZded< dZ	d	ed
< dZ
ded< edddœ‡ fdd„ƒZdddœdd„Zed2dddddœdd„ƒZed3dddddœdd„ƒZeddddœd d!„ƒZdd"ddœd#d$„Zed%d&d'd(�ddddd)œdd*d	dd+ddd,œd-d.„ƒZed%d/d'd(�ddddd)œdd*d	dd+ddd,œd0d1„ƒZ‡  ZS )4ÚBaseRetrieveraK	  Abstract base class for a Document retrieval system.

    A retrieval system is defined as something that can take string queries and return
    the most 'relevant' Documents from some source.

    Usage:

    A retriever follows the standard Runnable interface, and should be used
    via the standard Runnable methods of `invoke`, `ainvoke`, `batch`, `abatch`.

    Implementation:

    When implementing a custom retriever, the class should implement
    the `_get_relevant_documents` method to define the logic for retrieving documents.

    Optionally, an async native implementations can be provided by overriding the
    `_aget_relevant_documents` method.

    Example: A retriever that returns the first 5 documents from a list of documents

        .. code-block:: python

            from langchain_core.documents import Document
            from langchain_core.retrievers import BaseRetriever

            class SimpleRetriever(BaseRetriever):
                docs: list[Document]
                k: int = 5

                def _get_relevant_documents(self, query: str) -> list[Document]:
                    """Return the first k documents from the list of documents"""
                    return self.docs[:self.k]

                async def _aget_relevant_documents(self, query: str) -> list[Document]:
                    """(Optional) async native implementation."""
                    return self.docs[:self.k]

    Example: A simple retriever based on a scikit-learn vectorizer

        .. code-block:: python

            from sklearn.metrics.pairwise import cosine_similarity


            class TFIDFRetriever(BaseRetriever, BaseModel):
                vectorizer: Any
                docs: list[Document]
                tfidf_array: Any
                k: int = 4

                class Config:
                    arbitrary_types_allowed = True

                def _get_relevant_documents(self, query: str) -> list[Document]:
                    # Ip -- (n_docs,x), Op -- (n_docs,n_Feats)
                    query_vec = self.vectorizer.transform([query])
                    # Op -- (n_docs,1) -- Cosine Sim with each doc
                    results = cosine_similarity(self.tfidf_array, query_vec).reshape(
                        (-1,)
                    )
                    return [self.docs[i] for i in results.argsort()[-self.k :][::-1]]

    T)Zarbitrary_types_allowedFÚboolÚ_new_arg_supportedÚ_expects_other_argsNzOptional[list[str]]ÚtagszOptional[dict[str, Any]]Úmetadatar   ÚNone)ÚkwargsÚreturnc                   sä   t ƒ jf i |¤Ž | jtjkrBtjdtdd� | j}tj| _|| _t| dƒr|| j	tj	kr|tjdtdd� | j	}tj	| _	|| _
t| jƒj}| d¡d u| _| jsÂ| j
tj
krÂddd	d
œdd„}|| _
tt| ¡ ƒh d£ ƒdk| _d S )NzgRetrievers must implement abstract `_get_relevant_documents` method instead of `get_relevant_documents`é   )Ú
stacklevelÚaget_relevant_documentsziRetrievers must implement abstract `_aget_relevant_documents` method instead of `aget_relevant_documents`Úrun_managerr
   r   úlist[Document])ÚselfÚqueryr-   c                 Ó  s   t d | j|ƒI d H S )N)r   Ú_get_relevant_documents)r3   r4   r"   r"   r#   Ú_aget_relevant_documentsÂ   s    zABaseRetriever.__init_subclass__.<locals>._aget_relevant_documents>   r3   r1   r4   r   )ÚsuperÚ__init_subclass__Úget_relevant_documentsr%   ÚwarningsÚwarnÚDeprecationWarningr5   Úhasattrr0   r6   r   Ú
parametersÚgetr'   ÚlenÚsetÚkeysr(   )Úclsr,   ZswapZaswapr>   r6   ©Ú	__class__r"   r#   r8   ›   sD    üÿÿ
þüÿÿ
þÿzBaseRetriever.__init_subclass__r   )Ú_kwargsr-   c                 K  sH   |   ¡ }| d¡r |dd… }n| d¡r6|dd… }| ¡ }t|d�S )z Get standard params for tracing.Z	Retrieveré	   Ni÷ÿÿÿ)r   )Úget_nameÚ
startswithÚendswithÚlowerr   )r3   rF   Zdefault_retriever_namer"   r"   r#   Ú_get_ls_paramsÎ   s    

zBaseRetriever._get_ls_paramsr   zOptional[RunnableConfig]r2   )ÚinputÚconfigr,   r-   c           
   
   K  s  t |ƒ}i | d¡pi ¥| jf i |¤Ž¥}tj| d¡d| dd¡| d¡| j|| jd�}|jd|| d¡pr|  ¡ | 	d	d¡d
�}zB| j
rŽ|ni }| jr°| j|fd|i|¤Ž}n| j|fi |¤Ž}W n0 tyô }	 z| |	¡ ‚ W Y d}	~	nd}	~	0 0 | |¡ |S dS )aÌ  Invoke the retriever to get relevant documents.

        Main entry point for synchronous retriever invocations.

        Args:
            input: The query string.
            config: Configuration for the retriever. Defaults to None.
            kwargs: Additional arguments to pass to the retriever.

        Returns:
            List of relevant documents.

        Examples:

        .. code-block:: python

            retriever.invoke("query")

        r*   Ú	callbacksNÚverboseFr)   ©rP   Zinheritable_tagsZ
local_tagsÚinheritable_metadataZlocal_metadataÚrun_nameÚrun_id©ÚnamerT   r1   )r   r?   rL   r   Ú	configurer)   r*   Úon_retriever_startrH   Úpopr(   r'   r5   Ú	ExceptionÚon_retriever_errorÚon_retriever_end©
r3   rM   rN   r,   rR   Zcallback_managerr1   Zkwargs_ÚresultÚer"   r"   r#   ÚinvokeÙ   sN    ÿþ
ù	
üÿÿÿ
ÿzBaseRetriever.invokec           
   
   Ë  s(  t |ƒ}i | d¡pi ¥| jf i |¤Ž¥}tj| d¡d| dd¡| d¡| j|| jd�}|jd|| d¡pr|  ¡ | 	d	d¡d
�I dH }zN| j
r”|ni }| jr¼| j|fd|i|¤ŽI dH }n| j|fi |¤ŽI dH }W n8 t�y }	 z| |	¡I dH  ‚ W Y d}	~	nd}	~	0 0 | |¡I dH  |S dS )aã  Asynchronously invoke the retriever to get relevant documents.

        Main entry point for asynchronous retriever invocations.

        Args:
            input: The query string.
            config: Configuration for the retriever. Defaults to None.
            kwargs: Additional arguments to pass to the retriever.

        Returns:
            List of relevant documents.

        Examples:

        .. code-block:: python

            await retriever.ainvoke("query")

        r*   rO   NrP   Fr)   rQ   rS   rT   rU   r1   )r   r?   rL   r   rW   r)   r*   rX   rH   rY   r(   r'   r6   rZ   r[   r\   r]   r"   r"   r#   Úainvoke  sN    ÿþ
ù	
üÿÿÿÿ
zBaseRetriever.ainvoker   )r4   r1   r-   c                C  s   dS )zäGet documents relevant to a query.

        Args:
            query: String to find relevant documents for.
            run_manager: The callback handler to use.

        Returns:
            List of relevant documents.
        Nr"   ©r3   r4   r1   r"   r"   r#   r5   T  s    z%BaseRetriever._get_relevant_documentsr   c                Ã  s   t d| j|| ¡ d�I dH S )zðAsynchronously get documents relevant to a query.

        Args:
            query: String to find relevant documents for
            run_manager: The callback handler to use

        Returns:
            List of relevant documents
        N)r1   )r   r5   Zget_syncrb   r"   r"   r#   r6   b  s    üz&BaseRetriever._aget_relevant_documentsz0.1.46r`   z1.0)ZsinceÚalternativeZremoval)rO   r)   r*   rS   r   r   )r4   rO   r)   r*   rS   r,   r-   c                K  sH   i }|r||d< |r||d< |r(||d< |r4||d< | j ||fi |¤ŽS )a  Retrieve documents relevant to a query.

        Users should favor using `.invoke` or `.batch` rather than
        `get_relevant_documents directly`.

        Args:
            query: string to find relevant documents for.
            callbacks: Callback manager or list of callbacks. Defaults to None.
            tags: Optional list of tags associated with the retriever.
                These tags will be associated with each call to this retriever,
                and passed as arguments to the handlers defined in `callbacks`.
                Defaults to None.
            metadata: Optional metadata associated with the retriever.
                This metadata will be associated with each call to this retriever,
                and passed as arguments to the handlers defined in `callbacks`.
                Defaults to None.
            run_name: Optional name for the run. Defaults to None.
            kwargs: Additional arguments to pass to the retriever.

        Returns:
            List of relevant documents.
        rO   r)   r*   rS   )r`   ©r3   r4   rO   r)   r*   rS   r,   rN   r"   r"   r#   r9   u  s    !z$BaseRetriever.get_relevant_documentsra   c                Ë  sN   i }|r||d< |r||d< |r(||d< |r4||d< | j ||fi |¤ŽI dH S )a  Asynchronously get documents relevant to a query.

        Users should favor using `.ainvoke` or `.abatch` rather than
        `aget_relevant_documents directly`.

        Args:
            query: string to find relevant documents for.
            callbacks: Callback manager or list of callbacks.
            tags: Optional list of tags associated with the retriever.
                These tags will be associated with each call to this retriever,
                and passed as arguments to the handlers defined in `callbacks`.
                Defaults to None.
            metadata: Optional metadata associated with the retriever.
                This metadata will be associated with each call to this retriever,
                and passed as arguments to the handlers defined in `callbacks`.
                Defaults to None.
            run_name: Optional name for the run. Defaults to None.
            kwargs: Additional arguments to pass to the retriever.

        Returns:
            List of relevant documents.
        rO   r)   r*   rS   N)ra   rd   r"   r"   r#   r0   ¡  s    !z%BaseRetriever.aget_relevant_documents)N)N)r   r   r   r    r	   Zmodel_configr'   r!   r(   r)   r*   r   r8   rL   r`   ra   r   r5   r6   r   r9   r0   Ú__classcell__r"   r"   rD   r#   r%   E   s@   
@ÿ2 ÿ; ý>ù +ùr%   )-r    Ú
__future__r   r:   Úabcr   r   Úinspectr   Útypingr   r   r   Zpydanticr	   Ztyping_extensionsr
   r   r   Zlangchain_core._apir   Zlangchain_core.callbacksr   Z langchain_core.callbacks.managerr   r   Zlangchain_core.documentsr   Zlangchain_core.runnablesr   r   r   r   Zlangchain_core.runnables.configr   r   r   r   ZRetrieverInputÚlistZRetrieverOutputZRetrieverLikeZRetrieverOutputLiker   r%   r"   r"   r"   r#   Ú<module>   s*   